Support JS libraries self-registering their exports with visibility attributes

ChangeLog.md

@@ -21,6 +21,9 @@ See docs/process.md for more on how version tagging works.
 6.0.7 (in development)
 ----------------------
 
+- JavaScript library symbols can now use the `__force` and `__export`
+  decorators to control inclusion and export visibility. (#27436)
+
 6.0.6 - 08/05/26
 ----------------
 - `DEFAULT_TO_CXX` is now disabled by default. This means that `em++` is now

site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst

@@ -598,6 +598,9 @@ See the `library_*.js`_ files for other examples.
      by ``_``. In other words ``my_func: function() {},`` becomes
      ``function _my_func() {}``, as all C methods in emscripten have a ``_`` prefix. Keys starting with ``$`` have the ``$``
      stripped and no underscore added.
+   - A library symbol can use ``__force: true`` to be included even when it is
+     not referenced, and ``__export: true`` to be exported when included. Use
+     both decorators to unconditionally include and export a symbol.
 
 
 .. _interacting-with-code-call-function-pointers-from-c:

src/jsifier.mjs

@@ -30,6 +30,7 @@ import {
   debugLog,
   error,
   errorOccured,
+  extraLibraryFuncs,
   isDecorator,
   isJsOnlySymbol,
   compileTimeContext,
@@ -41,12 +42,10 @@ import {
   localFile,
   timer,
 } from './utility.mjs';
-import {LibraryManager, librarySymbols, nativeAliases} from './modules.mjs';
+import {extraExports, LibraryManager, librarySymbols, nativeAliases} from './modules.mjs';
 
 const addedLibraryItems = {};
 
-const extraLibraryFuncs = [];
-
 // Experimental feature to check for invalid __deps entries.
 // See `EMCC_CHECK_DEPS` in in the environment to try it out.
 const CHECK_DEPS = process.env.EMCC_CHECK_DEPS;
@@ -700,6 +699,10 @@ function(${args}) {
 
       librarySymbols.push(mangled);
 
+      if (!isStub && LibraryManager.library[symbol + '__export']) {
+        extraExports.add(mangled);
+      }
+
       const original = LibraryManager.library[symbol];
       let snippet = original;
       const isUserSymbol = LibraryManager.library[symbol + '__user'];
@@ -838,7 +841,7 @@ function(${args}) {
         contentText = `var ${mangled} = ${snippet};`;
       }
 
-      if (contentText && MODULARIZE == 'instance' && (EXPORT_ALL || EXPORTED_FUNCTIONS.has(mangled)) && !isStub) {
+      if (contentText && MODULARIZE == 'instance' && (EXPORT_ALL || EXPORTED_FUNCTIONS.has(mangled) || extraExports.has(mangled)) && !isStub) {
         // In MODULARIZE=instance mode mark JS library symbols are exported at
         // the point of declaration.
         contentText = 'export ' + contentText;
@@ -973,6 +976,7 @@ var proxiedFunctionTable = [
       '//FORWARDED_DATA:' +
         JSON.stringify({
           librarySymbols,
+          extraExports: Array.from(extraExports),
           nativeAliases,
           warnings: warningOccured(),
           asyncFuncs,

src/lib/libasync.js

@@ -20,6 +20,7 @@ addToLibrary({
   },
 
 #if ASYNCIFY
+  $Asyncify__force: true,
   $Asyncify__deps: ['$runAndAbortIfError', '$callUserCallback',
 #if ASSERTIONS
     '$createNamedFunction',
@@ -627,7 +628,3 @@ addToLibrary({
   },
 #endif // ASYNCIFY
 });
-
-if (ASYNCIFY) {
-  extraLibraryFuncs.push('$Asyncify');
-}

src/lib/libautodebug.js

@@ -9,7 +9,7 @@
 #error "Should only be included in AUTODEBUG mode"
 #endif
 
-addToLibrary({
+const LibraryAutodebug = {
   $log_execution: (loc) => dbg('log_execution ' + loc),
   $get_i32: (loc, index, value) => {
     dbg('get_i32 ' + [loc, index, value]);
@@ -131,36 +131,12 @@ addToLibrary({
     dbg('memory_grow_post ' + [loc, result]);
     return result;
   },
-});
+};
 
-extraLibraryFuncs.push(
-  '$log_execution',
-  '$get_i32',
-  '$get_i64',
-  '$get_f32',
-  '$get_f64',
-  '$get_funcref',
-  '$get_externref',
-  '$get_anyref',
-  '$get_exnref',
-  '$set_i32',
-  '$set_i64',
-  '$set_f32',
-  '$set_f64',
-  '$set_funcref',
-  '$set_externref',
-  '$set_anyref',
-  '$set_exnref',
-  '$load_ptr',
-  '$load_val_i32',
-  '$load_val_i64',
-  '$load_val_f32',
-  '$load_val_f64',
-  '$store_ptr',
-  '$store_val_i32',
-  '$store_val_i64',
-  '$store_val_f32',
-  '$store_val_f64',
-  '$memory_grow_pre',
-  '$memory_grow_post',
-);
+for (const symbol of Object.keys(LibraryAutodebug)) {
+  if (!isDecorator(symbol)) {
+    LibraryAutodebug[symbol + '__force'] = true;
+  }
+}
+
+addToLibrary(LibraryAutodebug);

src/lib/libcore.js

@@ -2517,7 +2517,7 @@ function autoAddDeps(lib, name) {
 #if LEGACY_RUNTIME
 // Library functions that were previously included as runtime functions are
 // automatically included when `LEGACY_RUNTIME` is set.
-extraLibraryFuncs.push(
+for (const symbol of [
   '$addFunction',
   '$removeFunction',
   '$AsciiToString',
@@ -2544,7 +2544,9 @@ extraLibraryFuncs.push(
   '$stringToUTF8Array',
   '$stringToUTF8',
   '$lengthBytesUTF8',
-);
+]) {
+  addToLibrary({[symbol + '__force']: true}, {allowMissing: true});
+}
 #endif
 
 function wrapSyscallFunction(x, library, isWasi) {

src/lib/libembind_gen.js

@@ -914,6 +914,7 @@ var LibraryEmbind = {
 #endif
   ],
   $emitOutput__postset: () => { addAtPostCtor('emitOutput()'); },
+  $emitOutput__force: true,
   $emitOutput: () => {
     for (const typeId in awaitingDependencies) {
       throwBindingError(`Missing binding for type: '${getTypeName(typeId)}' typeId: ${typeId}`);
@@ -936,6 +937,4 @@ var LibraryEmbind = {
   $PureVirtualError: () => { throw new Error('stub function should not be called'); },
 };
 
-extraLibraryFuncs.push('$emitOutput');
-
 addToLibrary(LibraryEmbind);

src/lib/libfs.js

@@ -5,6 +5,10 @@
  */
 
 var LibraryFS = {
+#if FORCE_FILESYSTEM
+  // Include FS even when it is not referenced by compiled code.
+  $FS__force: true,
+#endif
   $FS__deps: ['$randomFill', '$PATH', '$PATH_FS', '$TTY', '$MEMFS',
     '$FS_modeStringToFlags',
     '$FS_fileDataToTypedArray',

src/lib/libfs_shared.js

@@ -200,10 +200,3 @@ addToLibrary({
   $FS_readFile__deps: ['$FS'],
   $FS_readFile: 'FS.readFile',
 });
-
-// Normally only the FS things that the compiler sees are needed are included.
-// FORCE_FILESYSTEM makes us always include the FS object, which lets the user
-// call APIs on it from JS freely.
-if (FORCE_FILESYSTEM) {
-  extraLibraryFuncs.push('$FS');
-}

src/lib/libglemu.js

@@ -34,6 +34,7 @@ var LibraryGLEmulation = {
     'glVertexAttribPointer', 'glActiveTexture', '$stringToNewUTF8',
     '$ptrToString', '$getEmscriptenSupportedExtensions',
   ],
+  $GLEmulation__force: true,
   $GLEmulation__postset: `
     // Forward declare GL functions that are overridden by GLEmulation.
     /**@suppress {duplicate, undefinedVars}*/var _emscripten_glDrawArrays;
@@ -3942,8 +3943,6 @@ var LibraryGLEmulation = {
   gluOrtho2D: (left, right, bottom, top) => _glOrtho(left, right, bottom, top, -1, 1),
 };
 
-extraLibraryFuncs.push('$GLEmulation');
-
 recordGLProcAddressGet(LibraryGLEmulation);
 
 addToLibrary(LibraryGLEmulation);

src/lib/libwasmfs.js

@@ -5,6 +5,10 @@
  */
 
 addToLibrary({
+#if FORCE_FILESYSTEM
+  // Include FS even when it is not referenced by compiled code.
+  $FS__force: true,
+#endif
   $MEMFS__deps: ['wasmfs_create_memory_backend'],
   $MEMFS: {
     createBackend(opts) {

src/modules.mjs

@@ -30,6 +30,8 @@ import {preprocess, processMacros} from './parseTools.mjs';
 
 // List of symbols that were added from the library.
 export const librarySymbols = [];
+// Library symbols exported via the `__export` decorator.
+export const extraExports = new Set();
 // Map of library symbols which are aliases for native symbols
 // e.g. `wasmTable` -> `__indirect_function_table`
 export const nativeAliases = {};
@@ -575,6 +577,7 @@ function exportRuntimeSymbols() {
       if (
         !EXPORTED_RUNTIME_METHODS.has(name) &&
         !EXPORTED_FUNCTIONS.has(name) &&
+        !extraExports.has(name) &&
         !unusedLibSymbols.has(name)
       ) {
         unexported.push(name);
@@ -601,7 +604,7 @@ function exportLibrarySymbols() {
   assert(MODULARIZE != 'instance');
   const results = ['// Begin JS library exports'];
   for (const ident of librarySymbols) {
-    if ((EXPORT_ALL || EXPORTED_FUNCTIONS.has(ident)) && !nativeAliases[ident]) {
+    if ((EXPORT_ALL || EXPORTED_FUNCTIONS.has(ident) || extraExports.has(ident)) && !nativeAliases[ident]) {
       results.push(exportSymbol(ident));
     }
   }
@@ -621,6 +624,7 @@ addToCompileTimeContext({
   loadStructInfo,
   LibraryManager,
   librarySymbols,
+  extraExports,
   addToLibrary,
   cDefs,
   cDefine,

src/utility.mjs

@@ -96,6 +96,8 @@ function range(size) {
   return Array.from(Array(size).keys());
 }
 
+export const extraLibraryFuncs = [];
+
 export function mergeInto(obj, other, options = null) {
   if (options) {
     // check for unintended symbol redefinition
@@ -148,11 +150,11 @@ export function mergeInto(obj, other, options = null) {
       }
 
       const index = key.lastIndexOf('__');
+      const decorated = key.slice(0, index);
       const decoratorName = key.slice(index);
       const type = typeof other[key];
 
       if (decoratorName == '__async') {
-        const decorated = key.slice(0, index);
         if (isJsOnlySymbol(decorated)) {
           error(`__async decorator applied to JS symbol: ${decorated}`);
         }
@@ -188,12 +190,18 @@ export function mergeInto(obj, other, options = null) {
           __user: 'boolean',
           __async: ['string', 'boolean'],
           __i53abi: 'boolean',
+          __export: 'boolean',
+          __force: 'boolean',
         };
         const expected = decoratorTypes[decoratorName];
         if (type !== expected && !expected.includes(type)) {
           error(`Decorator (${key}) has wrong type. Expected '${expected}' not '${type}'`);
         }
       }
+
+      if (decoratorName === '__force' && other[key]) {
+        extraLibraryFuncs.push(decorated);
+      }
     }
   }
 
@@ -219,6 +227,8 @@ export const decoratorSuffixes = [
   '__user',
   '__async',
   '__i53abi',
+  '__export',
+  '__force',
 ];
 
 export function isDecorator(ident) {