Don't build MAIN_MODULE as RELOCATABLE (#25522)

The main advantage here is that main module no longer requires
relocation entries for symbols defined locally.

To show the benefits of this approach I build binaryan_wasm
with `-sMAIN_MODULE=1` both before and after this change.

Before:

Wasm Size: 22.6M
__wasm_apply_data_relocs size: 123k

After:

Wasm Size: 16.6M
__wasm_apply_data_relocs size: 0 (no longer exists)

Since this is quite a major change, I've kept the `-sRELOCATABLE`
option available so folks that use this to get the old behaviour when
linking their main module.  In order to tests this path too now run
all the `@needs_dylink` tests in test_core.py with and without
`-sRELOCTABLE`.  Hopefully we can remove this configuration
completely at some point in the future.

Fixes: #12682

Author: sbc100

ChangeLog.md

@@ -26,6 +26,11 @@ See docs/process.md for more on how version tagging works.
   exception here for `EMSCRIPTEN_VERSION` which is the only internal setting
   where we could find usage of `emscripten_get_compiler_setting` (in a global
   GitHub search). (#25667)
+- When using dynamic linking the main module is no longer built as a relocatable
+  binary.  This will significantly reduce the overhead of dynamic linking for
+  the main program, for example, eliminating all internal relocations. If you
+  encounter any issues with new default it is possible to revert to the old
+  behaviour by adding `-sRELOCATABLE` when linking the main module. (#25522)
 
 4.0.18 - 10/24/25
 -----------------

embuilder.py

@@ -120,6 +120,7 @@
     'crtbegin',
     'libsanitizer_common_rt',
     'libubsan_rt',
+    'libwasm_workers-debug',
     'libwasm_workers-debug-stub',
     'libfetch',
     'libfetch-mt',

emcc.py

@@ -410,7 +410,7 @@ def phase_setup(options, state):
             'unused-command-line-argument',
             "linker flag ignored during compilation: '%s'" % arg)
 
-  if settings.MAIN_MODULE or settings.SIDE_MODULE:
+  if settings.SIDE_MODULE:
     settings.RELOCATABLE = 1
 
   if 'USE_PTHREADS' in user_settings:

src/jsifier.mjs

@@ -121,7 +121,7 @@ function isDefined(symName) {
   }
   // 'invoke_' symbols are created at runtime in library_dylink.py so can
   // always be considered as defined.
-  if (RELOCATABLE && symName.startsWith('invoke_')) {
+  if ((MAIN_MODULE || RELOCATABLE) && symName.startsWith('invoke_')) {
     return true;
   }
   return false;
@@ -572,7 +572,7 @@ function(${args}) {
       if (!LibraryManager.library.hasOwnProperty(symbol)) {
         const isWeakImport = WEAK_IMPORTS.has(symbol);
         if (!isDefined(symbol) && !isWeakImport) {
-          if (PROXY_TO_PTHREAD && !MAIN_MODULE && symbol == '__main_argc_argv') {
+          if (PROXY_TO_PTHREAD && !(MAIN_MODULE || RELOCATABLE) && symbol == '__main_argc_argv') {
             error('PROXY_TO_PTHREAD proxies main() for you, but no main exists');
             return;
           }
@@ -603,7 +603,7 @@ function(${args}) {
 
         // emit a stub that will fail at runtime
         var stubFunctionBody = `abort('missing function: ${symbol}');`
-        if (RELOCATABLE) {
+        if (RELOCATABLE || MAIN_MODULE) {
           // Create a stub for this symbol which can later be replaced by the
           // dynamic linker.  If this stub is called before the symbol is
           // resolved assert in debug builds or trap in release builds.
@@ -762,8 +762,8 @@ function(${args}) {
         contentText = 'export ' + contentText;
       }
 
-      // Relocatable code needs signatures to create proper wrappers.
-      if (sig && RELOCATABLE) {
+      // Dynamic linking needs signatures to create proper wrappers.
+      if (sig && (MAIN_MODULE || RELOCATABLE)) {
         if (!WASM_BIGINT) {
           sig = sig[0].replace('j', 'i') + sig.slice(1).replace(/j/g, 'ii');
         }
@@ -774,7 +774,7 @@ function(${args}) {
       }
       if (isStub) {
         contentText += `\n${mangled}.stub = true;`;
-        if (ASYNCIFY && MAIN_MODULE) {
+        if (ASYNCIFY && (MAIN_MODULE || RELOCATABLE)) {
           contentText += `\nasyncifyStubs['${symbol}'] = undefined;`;
         }
       }

src/lib/libcore.js

@@ -2213,11 +2213,12 @@ addToLibrary({
   __stack_high: '{{{ STACK_HIGH }}}',
   __stack_low: '{{{ STACK_LOW }}}',
   __global_base: '{{{ GLOBAL_BASE }}}',
-#if ASYNCIFY == 1
+#endif // RELOCATABLE
+
+#if (MAIN_MODULE || RELOCATABLE) && ASYNCIFY == 1
   __asyncify_state: "new WebAssembly.Global({'value': 'i32', 'mutable': true}, 0)",
   __asyncify_data: "new WebAssembly.Global({'value': '{{{ POINTER_WASM_TYPE }}}', 'mutable': true}, {{{ to64(0) }}})",
 #endif
-#endif // RELOCATABLE
 
   _emscripten_fs_load_embedded_files__deps: ['$FS', '$PATH'],
   _emscripten_fs_load_embedded_files: (ptr) => {

src/lib/libdylink.js

@@ -6,10 +6,14 @@
  * Dynamic library loading
  */
 
-#if !RELOCATABLE
-#error "library_dylink.js requires RELOCATABLE"
+#if !MAIN_MODULE && !RELOCATABLE
+#error "library_dylink.js requires MAIN_MODULE or RELOCATABLE"
 #endif
 
+{{{
+const UNDEFINED_ADDR = to64(-1);
+}}}
+
 var LibraryDylink = {
 #if FILESYSTEM
   $registerWasmPlugin__deps: ['$preloadPlugins'],
@@ -170,10 +174,10 @@ var LibraryDylink = {
     get(obj, symName) {
       var rtn = GOT[symName];
       if (!rtn) {
-        rtn = GOT[symName] = new WebAssembly.Global({'value': '{{{ POINTER_WASM_TYPE }}}', 'mutable': true});
 #if DYLINK_DEBUG == 2
-        dbg("new GOT entry: " + symName);
+        dbg(`new GOT entry: ${symName}`);
 #endif
+        rtn = GOT[symName] = new WebAssembly.Global({'value': '{{{ POINTER_WASM_TYPE }}}', 'mutable': true}, {{{ UNDEFINED_ADDR }}});
       }
       if (!currentModuleWeakSymbols.has(symName)) {
         // Any non-weak reference to a symbol marks it as `required`, which
@@ -189,6 +193,11 @@ var LibraryDylink = {
   $isInternalSym: (symName) => {
     // TODO: find a way to mark these in the binary or avoid exporting them.
     return [
+      'memory',
+      '__memory_base',
+      '__table_base',
+      '__stack_pointer',
+      '__indirect_function_table',
       '__cpp_exception',
       '__c_longjmp',
       '__wasm_apply_data_relocs',
@@ -213,6 +222,7 @@ var LibraryDylink = {
 
   $updateGOT__internal: true,
   $updateGOT__deps: ['$GOT', '$isInternalSym', '$addFunction'],
+  $updateGOT__docs: '/** @param {boolean=} replace */',
   $updateGOT: (exports, replace) => {
 #if DYLINK_DEBUG
     dbg(`updateGOT: adding ${Object.keys(exports).length} symbols`);
@@ -230,8 +240,7 @@ var LibraryDylink = {
       }
 #endif
 
-
-      var existingEntry = GOT[symName] && GOT[symName].value != 0;
+      var existingEntry = GOT[symName] && GOT[symName].value != {{{ UNDEFINED_ADDR }}};
       if (replace || !existingEntry) {
 #if DYLINK_DEBUG == 2
         dbg(`updateGOT: before: ${symName} : ${GOT[symName]?.value}`);
@@ -252,7 +261,7 @@ var LibraryDylink = {
 #if DYLINK_DEBUG == 2
         dbg(`updateGOT:  after: ${symName} : ${newValue} (${value})`);
 #endif
-        GOT[symName] ||= new WebAssembly.Global({'value': '{{{ POINTER_WASM_TYPE }}}', 'mutable': true});
+        GOT[symName] ??= new WebAssembly.Global({'value': '{{{ POINTER_WASM_TYPE }}}', 'mutable': true});
         GOT[symName].value = newValue;
       }
 #if DYLINK_DEBUG
@@ -280,9 +289,12 @@ var LibraryDylink = {
 
   // Applies relocations to exported things.
   $relocateExports__internal: true,
-  $relocateExports__deps: ['$updateGOT', '$isImmutableGlobal'],
-  $relocateExports__docs: '/** @param {boolean=} replace */',
-  $relocateExports: (exports, memoryBase, replace) => {
+  $relocateExports__deps: ['$isImmutableGlobal'],
+  $relocateExports: (exports, memoryBase = 0) => {
+#if DYLINK_DEBUG
+    dbg(`relocateExports memoryBase=${memoryBase} count=${Object.keys(exports).length}`);
+#endif
+
     function relocateExport(name, value) {
 #if SPLIT_MODULE
       // Do not modify exports synthesized by wasm-split
@@ -304,7 +316,6 @@ var LibraryDylink = {
     for (var e in exports) {
       relocated[e] = relocateExport(e, exports[e])
     }
-    updateGOT(relocated, replace);
     return relocated;
   },
 
@@ -315,13 +326,17 @@ var LibraryDylink = {
     dbg('reportUndefinedSymbols');
 #endif
     for (var [symName, entry] of Object.entries(GOT)) {
-      if (entry.value == 0) {
+      if (entry.value == {{{ UNDEFINED_ADDR }}}) {
+#if DYLINK_DEBUG
+        dbg(`undef GOT entry: ${symName}`);
+#endif
         var value = resolveGlobalSymbol(symName, true).sym;
         if (!value && !entry.required) {
           // Ignore undefined symbols that are imported as weak.
 #if DYLINK_DEBUG
           dbg('ignoring undefined weak symbol:', symName);
 #endif
+          entry.value = {{{ to64(0) }}};
           continue;
         }
 #if ASSERTIONS
@@ -343,7 +358,7 @@ var LibraryDylink = {
           entry.value = value;
 #endif
         } else {
-          throw new Error(`bad export type for '${symName}': ${typeof value}`);
+          throw new Error(`bad export type for '${symName}': ${typeof value} (${value})`);
         }
       }
     }
@@ -390,7 +405,7 @@ var LibraryDylink = {
   // Allocate memory even if malloc isn't ready yet.  The allocated memory here
   // must be zero initialized since its used for all static data, including bss.
   $getMemory__noleakcheck: true,
-  $getMemory__deps: ['$GOT', '__heap_base', '$alignMemory', 'calloc'],
+  $getMemory__deps: ['$GOT', 'emscripten_get_sbrk_ptr', '__heap_base', '$alignMemory', 'calloc'],
   $getMemory: (size) => {
     // After the runtime is initialized, we must only use sbrk() normally.
 #if DYLINK_DEBUG
@@ -409,7 +424,27 @@ var LibraryDylink = {
     assert(end <= HEAP8.length, 'failure to getMemory - memory growth etc. is not supported there, call malloc/sbrk directly or increase INITIAL_MEMORY');
 #endif
     ___heap_base = end;
+
+    // After allocating the memory from the start of the heap we need to ensure
+    // that once the program starts it doesn't use this region.  In relocatable
+    // mode we can just update the __heap_base symbol that we are exporting to
+    // the main module.
+    // When not relocatable `__heap_base` is fixed and exported by the main
+    // module, but we can update the `sbrk_ptr` value instead.  We call
+    // `_emscripten_get_sbrk_ptr` knowing that it is safe to call prior to
+    // runtime initialization (unlike, the higher level sbrk function)
+#if RELOCATABLE
     GOT['__heap_base'].value = {{{ to64('end') }}};
+#else
+#if PTHREADS
+    if (!ENVIRONMENT_IS_PTHREAD) {
+#endif
+      var sbrk_ptr = _emscripten_get_sbrk_ptr();
+      {{{ makeSetValue('sbrk_ptr', 0, 'end', '*') }}}
+#if PTHREADS
+    }
+#endif
+#endif
     return ret;
   },
 
@@ -622,7 +657,7 @@ var LibraryDylink = {
     * @param {number=} handle
     */`,
   $loadWebAssemblyModule__deps: [
-    '$loadDynamicLibrary', '$getMemory',
+    '$loadDynamicLibrary', '$getMemory', '$updateGOT',
     '$relocateExports', '$resolveGlobalSymbol', '$GOTHandler',
     '$getDylinkMetadata', '$alignMemory',
     '$currentModuleWeakSymbols',
@@ -632,7 +667,7 @@ var LibraryDylink = {
   ],
   $loadWebAssemblyModule: (binary, flags, libName, localScope, handle) => {
 #if DYLINK_DEBUG
-    dbg('loadWebAssemblyModule:', libName);
+    dbg('loadWebAssemblyModule:', libName, handle);
 #endif
     var metadata = getDylinkMetadata(binary);
 
@@ -651,6 +686,9 @@ var LibraryDylink = {
       // exclusive access to it for the duration of this function.  See the
       // locking in `dynlink.c`.
       var firstLoad = !handle || !{{{ makeGetValue('handle', C_STRUCTS.dso.mem_allocated, 'i8') }}};
+#if DYLINK_DEBUG
+      dbg('firstLoad:', firstLoad);
+#endif
       if (firstLoad) {
 #endif
         // alignments are powers of 2
@@ -787,6 +825,7 @@ var LibraryDylink = {
         // add new entries to functionsInTableMap
         updateTableMap(tableBase, metadata.tableSize);
         moduleExports = relocateExports(instance.exports, memoryBase);
+        updateGOT(moduleExports);
 #if ASYNCIFY
         moduleExports = Asyncify.instrumentWasmExports(moduleExports);
 #endif
@@ -875,18 +914,27 @@ var LibraryDylink = {
           if (applyRelocs) {
             if (runtimeInitialized) {
 #if DYLINK_DEBUG
-              dbg('applyRelocs');
+              dbg('running __wasm_apply_data_relocs');
 #endif
               applyRelocs();
             } else {
+#if DYLINK_DEBUG
+              dbg('delaying __wasm_apply_data_relocs');
+#endif
               __RELOC_FUNCS__.push(applyRelocs);
             }
           }
           var init = moduleExports['__wasm_call_ctors'];
           if (init) {
             if (runtimeInitialized) {
+#if DYLINK_DEBUG
+              dbg('running __wasm_call_ctors');
+#endif
               init();
             } else {
+#if DYLINK_DEBUG
+              dbg('delaying __wasm_call_ctors');
+#endif
               // we aren't ready to run compiled code yet
               addOnPostCtor(init);
             }

src/lib/libglemu.js

@@ -10,7 +10,7 @@ assert(!FULL_ES3, 'cannot emulate both ES3 and legacy GL');
 
 {{{
   const copySigs = (func) => {
-    if (!RELOCATABLE) return '';
+    if (!MAIN_MODULE && !RELOCATABLE) return '';
     return ` _${func}.sig = _emscripten_${func}.sig = orig_${func}.sig;`;
   };
   const fromPtr = (arg) => {

src/lib/libpthread.js

@@ -594,7 +594,7 @@ var LibraryPThread = {
 #if MAIN_MODULE
   $registerTLSInit: (tlsInitFunc, moduleExports, metadata) => {
 #if DYLINK_DEBUG
-    dbg("registerTLSInit: " + tlsInitFunc);
+    dbg('registerTLSInit:', tlsInitFunc, metadata?.tlsExports);
 #endif
     // In relocatable builds, we use the result of calling tlsInitFunc
     // (`_emscripten_tls_init`) to relocate the TLS exports of the module
@@ -613,7 +613,7 @@ var LibraryPThread = {
       }
       var tlsExports = {};
       metadata.tlsExports.forEach((s) => tlsExports[s] = moduleExports[s]);
-      relocateExports(tlsExports, __tls_base, /*replace=*/true);
+      updateGOT(relocateExports(tlsExports, __tls_base), /*replace=*/true);
     }
 
     // Register this function so that its gets called for each thread on

src/lib/libwasm_worker.js

@@ -15,7 +15,7 @@
 #if LINKABLE
 #error "-sLINKABLE is not supported with -sWASM_WORKERS"
 #endif
-#if RELOCATABLE
+#if RELOCATABLE || MAIN_MODULE
 #error "dynamic linking is not supported with -sWASM_WORKERS"
 #endif
 #if PROXY_TO_WORKER

src/modules.mjs

@@ -93,7 +93,7 @@ function calculateLibraries() {
     libraries.push('libsyscall.js');
   }
 
-  if (RELOCATABLE) {
+  if (MAIN_MODULE || RELOCATABLE) {
     libraries.push('libdylink.js');
   }