Allow EXPORTED_FUNCTIONS to include and export JS library symbols (#21867)

Prior to this change one would need to add JS library symbols to both
`DEFAULT_LIBRARY_FUNCS_TO_INCLUDE` and `EXPORTED_FUNCTIONS` to achieve
this (confusingly with different name mangling for each).

Author: sbc100

ChangeLog.md

@@ -20,6 +20,9 @@ See docs/process.md for more on how version tagging works.
 
 3.1.60 (in development)
 -----------------------
+- The `EXPORTED_FUNCTIONS` list can now include JS library symbols even if they
+  have not been otherwise included (e.g. via `DEFAULT_LIBRARY_FUNCS_TO_INCLUDE`).
+  (#21867)
 
 3.1.59 - 04/30/24
 -----------------

site/source/docs/tools_reference/settings_reference.rst

@@ -956,8 +956,7 @@ EXPORT_EXCEPTION_HANDLING_HELPERS
 =================================
 
 Make the exception message printing function, 'getExceptionMessage' available
-in the JS library for use, by adding necessary symbols to EXPORTED_FUNCTIONS
-and DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.
+in the JS library for use, by adding necessary symbols to EXPORTED_FUNCTIONS.
 
 This works with both Emscripten EH and Wasm EH. When you catch an exception
 from JS, that gives you a user-thrown value in case of Emscripten EH, and a
@@ -1313,15 +1312,17 @@ to load ok, but we do actually recompile).
 EXPORTED_FUNCTIONS
 ==================
 
-Functions that are explicitly exported. These functions are kept alive
-through LLVM dead code elimination, and also made accessible outside of the
-generated code even after running closure compiler (on "Module").  The
+Symbols that are explicitly exported. These symbols are kept alive through
+LLVM dead code elimination, and also made accessible outside of the
+generated code even after running closure compiler (on "Module").  Native
 symbols listed here require an ``_`` prefix.
 
 By default if this setting is not specified on the command line the
 ``_main`` function will be implicitly exported.  In STANDALONE_WASM mode the
 default export is ``__start`` (or ``__initialize`` if --no-entry is specified).
 
+JS Library symbols can also be added to this list (without the leading `$`).
+
 .. _export_all:
 
 EXPORT_ALL
@@ -1358,13 +1359,16 @@ DEFAULT_LIBRARY_FUNCS_TO_INCLUDE
 ================================
 
 JS library elements (C functions implemented in JS) that we include by
-default. If you want to make sure something is included by the JS compiler,
+default.  If you want to make sure something is included by the JS compiler,
 add it here.  For example, if you do not use some ``emscripten_*`` C API call
-from C, but you want to call it from JS, add it here (and in EXPORTED
-FUNCTIONS with prefix "_", if you use closure compiler).  Note that the name
-may be slightly misleading, as this is for any JS library element, and not
-just functions. For example, you can include the Browser object by adding
-"$Browser" to this list.
+from C, but you want to call it from JS, add it here.
+Note that the name may be slightly misleading, as this is for any JS
+library element, and not just functions. For example, you can include the
+Browser object by adding "$Browser" to this list.
+
+If you want to both include and export a JS library symbol, it is enough to
+simply add it to EXPORTED_FUNCTIONS, without also adding it to
+DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.
 
 .. _include_full_library:
 

src/jsifier.mjs

@@ -172,9 +172,10 @@ export function runJSify(symbolsOnly) {
       symbolsNeeded.push('$' + sym);
     }
   }
-  if (INCLUDE_FULL_LIBRARY) {
-    for (const key of Object.keys(LibraryManager.library)) {
-      if (!isDecorator(key)) {
+
+  for (const key of Object.keys(LibraryManager.library)) {
+    if (!isDecorator(key)) {
+      if (INCLUDE_FULL_LIBRARY || EXPORTED_FUNCTIONS.has(mangleCSymbolName(key))) {
         symbolsNeeded.push(key);
       }
     }

src/settings.js

@@ -743,8 +743,7 @@ var EXCEPTION_CATCHING_ALLOWED = [];
 var DISABLE_EXCEPTION_THROWING = false;
 
 // Make the exception message printing function, 'getExceptionMessage' available
-// in the JS library for use, by adding necessary symbols to EXPORTED_FUNCTIONS
-// and DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.
+// in the JS library for use, by adding necessary symbols to EXPORTED_FUNCTIONS.
 //
 // This works with both Emscripten EH and Wasm EH. When you catch an exception
 // from JS, that gives you a user-thrown value in case of Emscripten EH, and a
@@ -1042,14 +1041,16 @@ var NODERAWFS = false;
 // [link]
 var NODE_CODE_CACHING = false;
 
-// Functions that are explicitly exported. These functions are kept alive
-// through LLVM dead code elimination, and also made accessible outside of the
-// generated code even after running closure compiler (on "Module").  The
+// Symbols that are explicitly exported. These symbols are kept alive through
+// LLVM dead code elimination, and also made accessible outside of the
+// generated code even after running closure compiler (on "Module").  Native
 // symbols listed here require an ``_`` prefix.
 //
 // By default if this setting is not specified on the command line the
 // ``_main`` function will be implicitly exported.  In STANDALONE_WASM mode the
 // default export is ``__start`` (or ``__initialize`` if --no-entry is specified).
+//
+// JS Library symbols can also be added to this list (without the leading `$`).
 // [link]
 var EXPORTED_FUNCTIONS = [];
 
@@ -1074,13 +1075,16 @@ var EXPORT_KEEPALIVE = true;
 var RETAIN_COMPILER_SETTINGS = false;
 
 // JS library elements (C functions implemented in JS) that we include by
-// default. If you want to make sure something is included by the JS compiler,
+// default.  If you want to make sure something is included by the JS compiler,
 // add it here.  For example, if you do not use some ``emscripten_*`` C API call
-// from C, but you want to call it from JS, add it here (and in EXPORTED
-// FUNCTIONS with prefix "_", if you use closure compiler).  Note that the name
-// may be slightly misleading, as this is for any JS library element, and not
-// just functions. For example, you can include the Browser object by adding
-// "$Browser" to this list.
+// from C, but you want to call it from JS, add it here.
+// Note that the name may be slightly misleading, as this is for any JS
+// library element, and not just functions. For example, you can include the
+// Browser object by adding "$Browser" to this list.
+//
+// If you want to both include and export a JS library symbol, it is enough to
+// simply add it to EXPORTED_FUNCTIONS, without also adding it to
+// DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.
 // [link]
 var DEFAULT_LIBRARY_FUNCS_TO_INCLUDE = [];
 

test/test_other.py

@@ -7234,7 +7234,6 @@ def test_dlsym_rtld_default_js_symbol(self):
     self.run_process([EMCC, 'main.c',
                       '--js-library=lib.js',
                       '-sMAIN_MODULE=2',
-                      '-sDEFAULT_LIBRARY_FUNCS_TO_INCLUDE=foo,bar',
                       '-sEXPORTED_FUNCTIONS=_main,_foo,_bar'])
 
     # Fist test the successful use of a JS function with dlsym
@@ -7382,7 +7381,6 @@ def test_emscripten_scan_stack(self):
 
   def test_no_warn_exported_jslibfunc(self):
     self.run_process([EMCC, test_file('hello_world.c'),
-                      '-sDEFAULT_LIBRARY_FUNCS_TO_INCLUDE=alGetError',
                       '-sEXPORTED_FUNCTIONS=_main,_alGetError'])
 
     # Same again but with `_alGet` wich does not exist.  This is a regression
@@ -12411,6 +12409,15 @@ def test_jslib_mangling(self):
       ''')
     self.run_process([EMCC, test_file('hello_world.c'), '--js-library=lib.js', '-sDEFAULT_LIBRARY_FUNCS_TO_INCLUDE=$__foo'])
 
+  def test_jslib_exported_functions(self):
+    create_file('lib.js', '''
+      addToLibrary({
+        $Foo: () => 43,
+      });
+      ''')
+    self.run_process([EMCC, test_file('hello_world.c'), '--js-library=lib.js', '-sEXPORTED_FUNCTIONS=Foo,_main'])
+    self.assertContained("Module['Foo'] = ", read_file('a.out.js'))
+
   def test_wasm2js_no_dylink(self):
     for arg in ['-sMAIN_MODULE', '-sSIDE_MODULE', '-sRELOCATABLE']:
       print(arg)

tools/link.py

@@ -1792,8 +1792,7 @@ def get_full_import_name(name):
     # JS, you may need to manipulate the refcount manually not to leak memory.
     # What you need to do is different depending on the kind of EH you use
     # (https://github.com/emscripten-core/emscripten/issues/17115).
-    settings.DEFAULT_LIBRARY_FUNCS_TO_INCLUDE += ['$getExceptionMessage', '$incrementExceptionRefcount', '$decrementExceptionRefcount']
-    settings.EXPORTED_FUNCTIONS += ['getExceptionMessage', '$incrementExceptionRefcount', '$decrementExceptionRefcount']
+    settings.EXPORTED_FUNCTIONS += ['getExceptionMessage', 'incrementExceptionRefcount', 'decrementExceptionRefcount']
     if settings.WASM_EXCEPTIONS:
       settings.REQUIRED_EXPORTS += ['__cpp_exception']
 
@@ -3103,6 +3102,8 @@ def add_js_deps(sym):
           add_js_deps(sym)
         for sym in settings.EXPORTED_RUNTIME_METHODS:
           add_js_deps(shared.demangle_c_symbol_name(sym))
+        for sym in settings.EXPORTED_FUNCTIONS:
+          add_js_deps(shared.demangle_c_symbol_name(sym))
     if settings.ASYNCIFY:
       settings.ASYNCIFY_IMPORTS_EXCEPT_JS_LIBS = settings.ASYNCIFY_IMPORTS[:]
       settings.ASYNCIFY_IMPORTS += ['*.' + x for x in js_info['asyncFuncs']]