Allow user JS libraries to be specified via -lfoo.js (#23345)

We already allowed this for system JS libraries but it is now also
possible for user libraries.

Fixes: #23338

Author: sbc100

ChangeLog.md

@@ -58,6 +58,9 @@ See docs/process.md for more on how version tagging works.
 - The `POLYFILL_OLD_MATH_FUNCTIONS` setting was removed.  The browser versions
   that require these polyfills are no longer supported by emscripten so the
   polyfills should never be needed. (#23262)
+- JavaScript libraries can now be specified via `-lfoo.js`.  This works like the
+  existing `--js-library` flag but will search the library path (all paths
+  specified with `-L`) for `libfoo.js`. (#23338)
 
 3.1.74 - 12/14/24
 -----------------

site/source/docs/tools_reference/settings_reference.rst

@@ -1417,7 +1417,7 @@ A list of imported module functions that will potentially do asynchronous
 work. The imported function should return a ``Promise`` when doing
 asynchronous work.
 
-Note when using ``--js-library``, the function can be marked with
+Note when using JS library files, the function can be marked with
 ``<function_name>_async:: true`` in the library instead of this setting.
 
 Default value: []

src/modules.mjs

@@ -205,7 +205,7 @@ export const LibraryManager = {
       libraries.push('library_little_endian_heap.js');
     }
 
-    // Add all user specified --js-library files to the link.
+    // Add all user specified JS library files to the link.
     // These must be added last after all Emscripten-provided system libraries
     // above, so that users can override built-in JS library symbols in their
     // own code.

src/settings.js

@@ -953,7 +953,7 @@ var JSPI_EXPORTS = [];
 // work. The imported function should return a ``Promise`` when doing
 // asynchronous work.
 //
-// Note when using ``--js-library``, the function can be marked with
+// Note when using JS library files, the function can be marked with
 // ``<function_name>_async:: true`` in the library instead of this setting.
 // [link]
 var JSPI_IMPORTS = [];

src/settings_internal.js

@@ -97,10 +97,9 @@ var MAIN_READS_PARAMS = true;
 
 var WASI_MODULE_NAME = "wasi_snapshot_preview1";
 
-// List of JS libraries explicitly linked against.  This includes JS system
-// libraries (specified via -lfoo or -lfoo.js) in addition to user libraries
-// passed via `--js-library`.  It does not include implicitly linked libraries
-// added by the JS compiler.
+// List of JS libraries explicitly linked against.  This includes JS specified
+// on the command line via `-lfoo.js` / `--js-library`.  It does not include
+// implicitly linked libraries added by the JS compiler.
 var JS_LIBRARIES = [];
 
 // This will contain the emscripten version. This can be useful in combination

test/test_other.py

@@ -4886,6 +4886,25 @@ def test_jslib_exported_functions(self):
     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_jslib_search_path(self):
+    create_file('libfoo.js', '''
+      addToLibrary({
+        foo: () => 42,
+      });
+      ''')
+    create_file('main.c', r'''
+      #include <stdio.h>
+      int foo();
+      int main() {
+        printf("%d\n", foo());
+        return 0;
+      }''')
+    self.do_runf('main.c', '42\n', emcc_args=['-L.', '-lfoo.js'])
+
+    # If the library path is not included with `-L` we expect the command to fail
+    err = self.expect_fail([EMCC, 'main.c', '-lfoo.js'])
+    self.assertContained('emcc: error: unable to find library -lfoo.js', err)
+
   def test_EMCC_BUILD_DIR(self):
     # EMCC_BUILD_DIR env var contains the dir we were building in, when running the js compiler (e.g. when
     # running a js library). We force the cwd to be src/ for technical reasons, so this lets you find out

tools/link.py

@@ -2804,6 +2804,9 @@ def map_to_js_libs(library_name):
     logger.debug('Mapping library `%s` to JS libraries: %s' % (library_name, libs))
     return libs
 
+  # TODO(sbc): Remove this special handling for system libraries by renaming
+  # the system libraries from `library_foo.js` to `libfoo.js` (the latter is
+  # the more standard name by which `-l` flags resolve libraries).
   if library_name.endswith('.js') and os.path.isfile(utils.path_from_root('src', f'library_{library_name}')):
     return [f'library_{library_name}']
 
@@ -2842,6 +2845,14 @@ def process_libraries(state):
     if js_libs is not None:
       continue
 
+    if lib.endswith('.js'):
+      name = 'lib' + lib
+      path = find_library(name, state.lib_dirs)
+      if not path:
+        exit_with_error(f'unable to find library {flag}')
+      settings.JS_LIBRARIES.append(os.path.abspath(path))
+      continue
+
     if not settings.RELOCATABLE:
       # Normally we can rely on the native linker to expand `-l` args.
       # However, emscripten also supports `.so` files that are actually just