Include heap views only when needed by brendandahl · Pull Request #27269 · emscripten-core/emscripten

brendandahl · 2026-07-07T23:12:06Z

Previously, all standard heap views (HEAP8 through HEAPF64) were
always included in the JS bundle and initialized, even when unused.
Closure Compiler could not eliminate the new TypedArray(a)
expressions because in JavaScript and Closure Compiler's standard
externs, TypedArray constructors are not considered pure (side-effect-free).

Remove heap view symbols from default library inclusions. Only
include and initialize heap views that are required by runtime
features, exported, or referenced in user code and snippets.

sbc100

Nice!

I guess the reason this has an impact on codesize even closure build is that somehow these are not been detected and removed as dead code by closure?

sbc100 · 2026-07-07T23:21:29Z

+      return `${maybeExportHeap(x)}${x} = new ${type}(b);`;
+    }
+    return '';
+  };


I think this is almost enough complexity to just move the whole updateMemoryViews into a generator / helper. But I guess it makes sense for this incremental change to do it this way for now.

sbc100 · 2026-07-07T23:28:11Z

  feature_matrix.auto_enable_features()

-  if settings.WASM_BIGINT:
-    settings.DEFAULT_LIBRARY_FUNCS_TO_INCLUDE += ['$HEAP64', '$HEAPU64']


Have you basically moved the encoding of this information from here to hardcoding it in getRequiredHeapSymbols? Why is that better?

brendandahl · 2026-07-09T23:46:44Z

Nice!

I guess the reason this has an impact on codesize even closure build is that somehow these are not been detected and removed as dead code by closure?

We discussed in person, but for posterity...

Closure Compiler cannot eliminate those remaining new TypedArray(a) expressions because in JavaScript and Closure Compiler's standard externs, TypedArray constructors are not considered pure (side-effect-free) for three main reasons: 1) runtime exceptions, 2) property accessor traps, 3) no @nosideeffects in the externs defined by closure.

sbc100 · 2026-07-09T23:48:29Z

    'runtimeKeepalivePop',
    'UTF8ToString',
+    'getValue',
+    'setValue',


I wonder if these are actually used much. Maybe add a TODO to remove them from this list?

sbc100 · 2026-07-09T23:49:45Z

    }
  }
+  // If the snippet contains eval(), it may dynamically evaluate strings that reference any
+  // heap view (e.g., eval('HEAP8[0]')). Since static string matching cannot detect which


But wouldn't eval('HEAP8[0]') also work for check below? i.e. we would still see the HEAP8 reference below wouldn't we?

Not always. This was for fixing emscripten_run_script which loads a string from memory to eval.

I should update that comment.

I think if anyone is doing this it should be on them to explictly add these deps.

If you don't want to break such folks with this PR, then you can maybe include this code now and then remove it later (i.e. delay the breakage)?

sbc100 · 2026-07-09T23:51:12Z

Nice!
I guess the reason this has an impact on codesize even closure build is that somehow these are not been detected and removed as dead code by closure?

We discussed in person, but for posterity...

Closure Compiler cannot eliminate those remaining new TypedArray(a) expressions because in JavaScript and Closure Compiler's standard externs, TypedArray constructors are not considered pure (side-effect-free) for three main reasons: 1) runtime exceptions, 2) property accessor traps, 3) no @nosideeffects in the externs defined by closure.

Can you include this in the commit message in come form?

sbc100 · 2026-07-10T00:45:03Z

+// Because addImplicitDeps only scans library functions and user code (pre-js/post-js/EM_JS),
+// runtime scaffolding files that access linear memory directly must have their heap views
+// explicitly declared here so they are emitted in the final JS bundle.
+function getRequiredHeapSymbols() {


I'm still not sure why we would prefer to implement this function rather than in link.py (where these symbols would be added to DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.

For other cases there a build config implies a library symbol we do it in link.py, why should this be different?

Not sure what's happening, my comment didn't post....

I was trying to put all the heap handling code in one place. I've added new commit with it moved to python.

It's called twice because it's not fully known if the HEAP symbols are needed until after link. We can figure out most pre link (e.g. if MAIN_MODULE, SAFE_HEAP, etc are set), but we don't know if (settings.HAS_MAIN and settings.MAIN_READS_PARAMS) until later. I suppose we could call it in compile_javascript. It will still be called twice, but from one place.

That is kind of sad.. perhaps just the settings.HAS_MAIN and settings.MAIN_READS_PARAMS could be done in emscripten.py and the rest can stay in link.py

i.e. we do the things we can do in phase_linker_setup.py and we then update the list once we know about settings.HAS_MAIN and settings.MAIN_READS_PARAMS?

I'm not sure if its even good idea to group all this stuff together either.. i.e. sometimes is nice to see the side effects of a given setting all in one place (i.e. to see the effects of MEMORY64), but its also nice to group things like by the effect (i.e. to see all the things the effect HEAP requirments). Is not clear to me the that latter grouping is any better than the former grouping.

sbc100

lgtm % final comment

sbc100 · 2026-07-10T20:56:22Z

@@ -806,6 +806,49 @@ def setup_cross_origin_storage():
      exit_with_error(f"CROSS_ORIGIN_STORAGE_ORIGINS: {o!r} is not a valid HTTPS origin (expected 'https://host' or 'https://host:port')")


+def add_required_heap_symbols():


Why can't this be called from phase_linker_setup below (where most of it lived before) instead of moving to emcc.py

sbc100 · 2026-07-10T20:57:52Z

@@ -155,6 +156,8 @@ def update_settings_glue(wasm_file, metadata, base_metadata):
  for deps in metadata.js_deps:
    settings.DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.extend(deps.split(','))

+  link.add_required_heap_symbols()


This seems rather odd that we could need to call it twice.

sbc100 · 2026-07-15T00:23:21Z

+  if settings.HAS_MAIN and settings.MAIN_READS_PARAMS:
+    heaps = ['$HEAP32', '$HEAPU32']
+    if settings.WASM_BIGINT or settings.MEMORY64:
+      heaps += ['$HEAP64', '$HEAPU64']


Out of interest do you know why MAIN_READS_PARAMS means that we need both signed and unsigned versions of these heaps?

The signed heaps were not actually needed. That was an extraneous copy from the previous code where this also handled stack overflow check.

sbc100

lgtm with a few final comments.

sbc100 · 2026-07-15T22:21:08Z

+    if settings.AUDIO_WORKLET:
+      heaps += ['$HEAP32', '$HEAPU32', '$HEAPF32']
+      if settings.WASM_BIGINT or settings.MEMORY64:
+        heaps += ['$HEAP64', '$HEAPU64']


These two lines are duplicates on both branches of the if condition.

This is under AUDIO_WORKLET so it's not added in all cases. Alternatively, I could flatten out this bigger if/else so it's less clever and just always add certain HEAP deps if a setting is set.

Ah yes, fair enough. I wonder if the AUDIO_WORKLET code can add these via __deps maybe?

Most of the audio worklet code is #included directly in runtime_common. It could maybe benefit from becoming a library, but probably a bigger change.

The code in libwebaudio.js already has some indirect deps like that:

// _emscripten_create_audio_worklet() doesn't use stackAlloc, // etc., but the created worklet does.

That seems like a very round about way to include a dep.

Yes, its is kind of roundabout. But its also the exist approach we have today.

Do you think this approach of hardcoding stuff into the .py files is better?

Surely having two hacky solutions is worse than just one?

Do we inject fake deps in other JS libs? It seems to me that the lib audio is the oddball one, most of the non-lib deps are added in link.py.

I don't really care what approach we do here, it seems in the end we should move more of the audio code to a library and add the deps where they're actually used.

sbc100 · 2026-07-15T22:22:14Z

+    deps.push('$HEAP8', '$HEAPU8', '$HEAP16', '$HEAPU16', '$HEAP32', '$HEAPU32', '$HEAPF32', '$HEAPF64');
+    if (WASM_BIGINT || MEMORY64) {
+      deps.push('$HEAP64', '$HEAPU64');
+    }


If think this should not be needed because these get added by link.py if WASM_BIGINT or MEMORY64?

sbc100

lgtm

Previously, all standard heap views (HEAP8 through HEAPF64) were always included in the JS bundle and initialized, even when unused. This increased bundle size and memory overhead. Remove heap view symbols from default library inclusions. Only include and initialize heap views that are required by runtime features, exported, or referenced in user code and snippets.

sbc100 · 2026-07-21T21:33:48Z

-  {{{ maybeExportHeap('HEAP64')  }}}HEAP64 = new BigInt64Array(b);
-  {{{ maybeExportHeap('HEAPU64') }}}HEAPU64 = new BigUint64Array(b);
+  {{{ updateHeap('HEAP64',  'BigInt64Array') }}}
+  {{{ updateHeap('HEAPU64', 'BigUint64Array') }}}


It looks like this land line is not visually aligned like the others?

This is an automatic change generated by tools/maint/rebaseline_tests.py. The following (64) test expectation files were updated by running the tests with `--rebaseline`: ``` test/codesize/audio_worklet_wasm.expected.js updated test/codesize/hello_wasm_worker_wasm.expected.js updated test/codesize/hello_world_wasm.expected.js updated test/codesize/hello_world_wasm2js.expected.js updated codesize/test_codesize_cxx_ctors1.json: 151884 => 151784 [-100 bytes / -0.07%] codesize/test_codesize_cxx_ctors2.json: 151287 => 151187 [-100 bytes / -0.07%] codesize/test_codesize_cxx_except.json: 195773 => 195674 [-99 bytes / -0.05%] codesize/test_codesize_cxx_except_wasm.json: 167008 => 166908 [-100 bytes / -0.06%] codesize/test_codesize_cxx_except_wasm_legacy.json: 164892 => 164792 [-100 bytes / -0.06%] codesize/test_codesize_cxx_lto.json: 120735 => 120635 [-100 bytes / -0.08%] codesize/test_codesize_cxx_mangle.json: 262144 => 262045 [-99 bytes / -0.04%] codesize/test_codesize_cxx_noexcept.json: 153884 => 153784 [-100 bytes / -0.06%] codesize/test_codesize_cxx_wasmfs.json: 179507 => 179386 [-121 bytes / -0.07%] test/codesize/test_codesize_file_preload.expected.js updated codesize/test_codesize_file_preload.json: 23969 => 23870 [-99 bytes / -0.41%] codesize/test_codesize_files_js_fs.json: 18352 => 18253 [-99 bytes / -0.54%] codesize/test_codesize_files_wasmfs.json: 63764 => 63585 [-179 bytes / -0.28%] codesize/test_codesize_hello_O0.json: 38742 => 38592 [-150 bytes / -0.39%] codesize/test_codesize_hello_O1.json: 8261 => 8066 [-195 bytes / -2.36%] codesize/test_codesize_hello_O2.json: 5927 => 5771 [-156 bytes / -2.63%] codesize/test_codesize_hello_O3.json: 5622 => 5467 [-155 bytes / -2.76%] codesize/test_codesize_hello_Os.json: 5610 => 5455 [-155 bytes / -2.76%] codesize/test_codesize_hello_Oz.json: 4781 => 4626 [-155 bytes / -3.24%] codesize/test_codesize_hello_dylink_all.json: 856323 => 856386 [+63 bytes / +0.01%] codesize/test_codesize_hello_esm_integration.json: 8756 => 8451 [-305 bytes / -3.48%] codesize/test_codesize_hello_export_nothing.json: 2899 => 2685 [-214 bytes / -7.38%] codesize/test_codesize_hello_single_file.json: 5008 => 4853 [-155 bytes / -3.10%] codesize/test_codesize_hello_wasmfs.json: 5622 => 5467 [-155 bytes / -2.76%] codesize/test_codesize_libcxxabi_message_O3.json: 3312 => 3099 [-213 bytes / -6.43%] codesize/test_codesize_libcxxabi_message_O3_standalone.json: 3493 => 3315 [-178 bytes / -5.10%] codesize/test_codesize_mem_O3.json: 9290 => 9135 [-155 bytes / -1.67%] codesize/test_codesize_mem_O3_grow.json: 9608 => 9470 [-138 bytes / -1.44%] codesize/test_codesize_mem_O3_grow_standalone.json: 9454 => 9298 [-156 bytes / -1.65%] codesize/test_codesize_mem_O3_standalone.json: 9289 => 9132 [-157 bytes / -1.69%] codesize/test_codesize_mem_O3_standalone_lib.json: 8503 => 8325 [-178 bytes / -2.09%] codesize/test_codesize_mem_O3_standalone_narg.json: 8625 => 8447 [-178 bytes / -2.06%] codesize/test_codesize_mem_O3_standalone_narg_flto.json: 7556 => 7378 [-178 bytes / -2.36%] codesize/test_codesize_minimal_64.json: 2600 => 2388 [-212 bytes / -8.15%] test/codesize/test_codesize_minimal_O0.expected.js updated codesize/test_codesize_minimal_O0.json: 19854 => 19695 [-159 bytes / -0.80%] codesize/test_codesize_minimal_O1.json: 3376 => 3119 [-257 bytes / -7.61%] codesize/test_codesize_minimal_O2.json: 2549 => 2332 [-217 bytes / -8.51%] codesize/test_codesize_minimal_O3.json: 2285 => 2073 [-212 bytes / -9.28%] codesize/test_codesize_minimal_Os.json: 2285 => 2073 [-212 bytes / -9.28%] codesize/test_codesize_minimal_Os_mr.json: 577 => 353 [-224 bytes / -38.82%] codesize/test_codesize_minimal_Oz-ctors.json: 2256 => 2044 [-212 bytes / -9.40%] codesize/test_codesize_minimal_Oz.json: 2285 => 2073 [-212 bytes / -9.28%] codesize/test_codesize_minimal_esm.json: 2423 => 2212 [-211 bytes / -8.71%] codesize/test_codesize_minimal_esm_integration.json: 4101 => 3721 [-380 bytes / -9.27%] codesize/test_codesize_minimal_pthreads.json: 26063 => 25967 [-96 bytes / -0.37%] codesize/test_codesize_minimal_pthreads_memgrowth.json: 26498 => 26419 [-79 bytes / -0.30%] codesize/test_codesize_minimal_wasmfs.json: 2285 => 2073 [-212 bytes / -9.28%] codesize/test_minimal_runtime_code_size_hello_embind.json: 14911 => 14911 [+0 bytes / +0.00%] codesize/test_minimal_runtime_code_size_hello_embind_val.json: 11638 => 11638 [+0 bytes / +0.00%] codesize/test_minimal_runtime_code_size_hello_wasm_worker.json: 4121 => 4099 [-22 bytes / -0.53%] codesize/test_minimal_runtime_code_size_hello_webgl2_wasm2js.json: 18559 => 18559 [+0 bytes / +0.00%] codesize/test_minimal_runtime_code_size_hello_webgl2_wasm_singlefile.json: 15040 => 15040 [+0 bytes / +0.00%] codesize/test_minimal_runtime_code_size_hello_webgl_wasm.json: 12724 => 12724 [+0 bytes / +0.00%] codesize/test_minimal_runtime_code_size_hello_world_wasm.json: 927 => 927 [+0 bytes / +0.00%] codesize/test_minimal_runtime_code_size_random_printf_wasm.json: 11054 => 11054 [+0 bytes / +0.00%] codesize/test_minimal_runtime_code_size_random_printf_wasm2js.json: 17417 => 17417 [+0 bytes / +0.00%] test/codesize/test_small_js_flags.expected.js updated codesize/test_small_js_flags.json: 3888 => 3732 [-156 bytes / -4.01%] codesize/test_unoptimized_code_size.json: 177707 => 172354 [-5353 bytes / -3.01%] Average change: -3.40% (-38.82% - +0.01%) ```

sbc100 · 2026-07-21T23:23:41Z

+  if settings.MAIN_MODULE or settings.EXPORT_ALL or settings.SAFE_HEAP:
+    # Dynamic linking side modules, full symbol exports, or safe heap instrumentation
+    # require all standard heap views and value helpers to be available.
+    heaps += ['$getValue', '$setValue']


Technically these are not "heaps", but maybe not and important distinction?

What do you want to call them?

I'm not sure, maybe this function should be called something more like add_implicit_library_deps?

Then the local could be called deps or syms or js_syms?

sbc100

Thanks for your persistence with this!

sbc100 reviewed Jul 7, 2026

View reviewed changes

sbc100 reviewed Jul 9, 2026

View reviewed changes

Comment thread tools/link.py Outdated

sbc100 reviewed Jul 9, 2026

View reviewed changes

Comment thread tools/emscripten.py Outdated

sbc100 reviewed Jul 9, 2026

View reviewed changes

brendandahl force-pushed the heap-vars branch from d38e273 to a65bcda Compare July 10, 2026 00:07

sbc100 reviewed Jul 10, 2026

View reviewed changes

sbc100 approved these changes Jul 10, 2026

View reviewed changes

sbc100 reviewed Jul 10, 2026

View reviewed changes

brendandahl force-pushed the heap-vars branch from f8e2d97 to a26ce32 Compare July 14, 2026 22:02

sbc100 reviewed Jul 15, 2026

View reviewed changes

Comment thread tools/emscripten.py Outdated

sbc100 reviewed Jul 15, 2026

View reviewed changes

brendandahl force-pushed the heap-vars branch from a26ce32 to 1fbaf43 Compare July 15, 2026 18:33

sbc100 reviewed Jul 15, 2026

View reviewed changes

sbc100 approved these changes Jul 15, 2026

View reviewed changes

brendandahl added 7 commits July 21, 2026 21:27

docs

a7f92a0

review comments

9f66d19

review comments

805e08d

move to python

a30fa8b

review comments

62f2243

review comments

263eb73

brendandahl force-pushed the heap-vars branch from 1fbaf43 to 3fdd6c7 Compare July 21, 2026 21:28

brendandahl enabled auto-merge (squash) July 21, 2026 21:28

sbc100 reviewed Jul 21, 2026

View reviewed changes

brendandahl added 2 commits July 21, 2026 23:09

rc

d5e085a

brendandahl force-pushed the heap-vars branch from 3fdd6c7 to 2400f59 Compare July 21, 2026 23:12

sbc100 reviewed Jul 21, 2026

View reviewed changes

sbc100 approved these changes Jul 21, 2026

View reviewed changes

brendandahl merged commit dad92aa into emscripten-core:main Jul 22, 2026
38 of 40 checks passed

		@@ -806,6 +806,49 @@ def setup_cross_origin_storage():
		exit_with_error(f"CROSS_ORIGIN_STORAGE_ORIGINS: {o!r} is not a valid HTTPS origin (expected 'https://host' or 'https://host:port')")


		def add_required_heap_symbols():

Uh oh!

Conversation

brendandahl commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

brendandahl commented Jul 9, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbc100 Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbc100 commented Jul 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbc100 Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brendandahl commented Jul 7, 2026 •

edited

Loading

sbc100 Jul 9, 2026 •

edited

Loading

sbc100 Jul 10, 2026 •

edited

Loading