Allow JS library dependencies to be added in source code.

This change introduces a new EM_JS_DEPS macros that can be used to
specific the JS library dependencies of user code in EM_JS and/or EM_ASM
blocks.

This is especially important for library authors who don't want to have
their users maintain link-time list of required symbols.

See #14729

Author: sbc100

emscripten.py

@@ -165,6 +165,9 @@ def update_settings_glue(wasm_file, metadata):
     # exported.  In theory it should always be present since its defined in compiler-rt.
     assert 'emscripten_stack_get_end' in metadata['exports']
 
+  for deps in metadata['jsDeps']:
+    settings.DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.extend(deps.split(','))
+
 
 def apply_static_code_hooks(forwarded_json, code):
   code = shared.do_replace(code, '<<< ATINITS >>>', str(forwarded_json['ATINITS']))

src/settings_internal.js

@@ -38,6 +38,7 @@ var SIDE_MODULE_IMPORTS = [];
 // programs contains EM_JS or EM_ASM data section, in which case these symbols
 // won't exist.
 var EXPORT_IF_DEFINED = ['__start_em_asm', '__stop_em_asm',
+                         '__start_em_lib_deps', '__stop_em_lib_deps',
                          '__start_em_js', '__stop_em_js'];
 
 // Like EXPORTED_FUNCTIONS, but symbol is required to exist in native code.

system/include/emscripten/em_macros.h

@@ -14,3 +14,9 @@
 #else
 #define EM_IMPORT(NAME)
 #endif
+
+#define EM_JS_DEPS(deps)                  \
+  __attribute__((section("em_lib_deps"))) \
+  __attribute__((used))                   \
+  __attribute__((aligned(1)))             \
+  static char __em_lib_deps[] = deps;

test/core/test_asan_js_stack_op.c

@@ -5,6 +5,8 @@ EMSCRIPTEN_KEEPALIVE void c_func(char *str) {
   printf("%s\n", str);
 }
 
+EM_JS_DEPS("$allocateUTF8OnStack");
+
 EM_JS(void, js_func, (void), {
   _c_func(allocateUTF8OnStack('Hello, World!'));
 });

test/core/test_convertI32PairToI53Checked.cpp

@@ -10,6 +10,8 @@
 // Uncomment to compute the expected results without testing:
 //#define GENERATE_ANSWERS
 
+EM_JS_DEPS("$convertI32PairToI53Checked");
+
 double test(int64_t val) {
   int32_t lo = (uint32_t)val;
   int32_t hi = (uint64_t)val >> 32;

test/interop/test_add_function.cpp

@@ -20,6 +20,8 @@ extern "C" int baz() {
   return 3;
 }
 
+EM_JS_DEPS("$addFunction,$removeFunction");
+
 int main(int argc, char **argv) {
 #if defined(GROWTH)
   EM_ASM({

test/other/test_offset_converter.c

@@ -33,3 +33,5 @@ int main(void) {
   magic_test_function();
   return 0;
 }
+
+EM_JS_DEPS("$ptrToString");

test/other/test_runtime_keepalive.cpp

@@ -1,6 +1,8 @@
 #include <emscripten.h>
 #include <stdio.h>
 
+EM_JS_DEPS("$runtimeKeepalivePush,$runtimeKeepalivePop,$callUserCallback");
+
 int main() {
   EM_ASM({
     Module["onExit"] = () => { out("onExit"); };

test/stack_overflow.cpp

@@ -5,10 +5,13 @@
 
 #include <stdio.h>
 #include <string.h>
-#include <emscripten.h>
 
-void __attribute__((noinline)) InteropString(char *staticBuffer)
-{
+#include <emscripten/em_asm.h>
+#include <emscripten/em_macros.h>
+
+EM_JS_DEPS("$allocateUTF8OnStack");
+
+void __attribute__((noinline)) InteropString(char *staticBuffer) {
   char *string = (char*)EM_ASM_PTR({
     var str = "hello, this is a string! ";
 #if ONE_BIG_STRING
@@ -27,12 +30,12 @@ void __attribute__((noinline)) InteropString(char *staticBuffer)
   });
 }
 
-int main()
-{
+int main() {
   // Make C side consume a large portion of the stack, before bumping the rest with C++<->JS interop.
   char staticBuffer[512288] = {};
   InteropString(staticBuffer);
   int stringLength = strlen(staticBuffer);
   printf("Got string: %s\n", staticBuffer);
   printf("Received a string of length %d.\n", stringLength);
+  return 0;
 }

test/test_core.py

@@ -482,7 +482,6 @@ def test_int53(self):
       self.do_core_test('test_int53.c', interleaved_output=False)
 
   def test_int53_convertI32PairToI53Checked(self):
-    self.emcc_args += ['-sDEFAULT_LIBRARY_FUNCS_TO_INCLUDE=[$convertI32PairToI53Checked]']
     if common.EMTEST_REBASELINE:
       self.run_process([EMCC, test_file('core/test_convertI32PairToI53Checked.cpp'), '-o', 'a.js', '-DGENERATE_ANSWERS'] + self.emcc_args)
       ret = self.run_process(config.NODE_JS + ['a.js'], stdout=PIPE).stdout
@@ -6099,7 +6098,6 @@ def test_unistd_symlink_on_nodefs(self):
 
   @also_with_wasm_bigint
   def test_unistd_io(self):
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', ['$ERRNO_CODES'])
     orig_compiler_opts = self.emcc_args.copy()
     for fs in ['MEMFS', 'NODEFS']:
       self.clear()
@@ -7243,7 +7241,6 @@ def test_add_function(self):
     self.set_setting('WASM_ASYNC_COMPILATION', 0)
     self.set_setting('RESERVED_FUNCTION_POINTERS')
     self.set_setting('EXPORTED_RUNTIME_METHODS', ['callMain'])
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', ['$addFunction', '$removeFunction'])
     src = test_file('interop/test_add_function.cpp')
     post_js = test_file('interop/test_add_function_post.js')
     self.emcc_args += ['--post-js', post_js]
@@ -7641,7 +7638,6 @@ def test_webidl(self, mode, allow_memory_growth):
     # TODO(): Remove once we make webidl output closure-warning free.
     self.ldflags.remove('-sCLOSURE_WARNINGS=error')
     self.set_setting('WASM_ASYNC_COMPILATION', 0)
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', ['$intArrayFromString'])
     if self.maybe_closure():
       # avoid closure minified names competing with our test code in the global name space
       self.set_setting('MODULARIZE')
@@ -8529,7 +8525,6 @@ def test_fs_dict_none(self):
   def test_stack_overflow_check(self):
     self.set_setting('TOTAL_STACK', 1048576)
     self.set_setting('STACK_OVERFLOW_CHECK', 2)
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', '$allocateUTF8OnStack')
     self.do_runf(test_file('stack_overflow.cpp'), 'Aborted(stack overflow', assert_returncode=NON_ZERO)
 
     self.emcc_args += ['-DONE_BIG_STRING']
@@ -8946,7 +8941,6 @@ def test_asan_js_stack_op(self):
     self.emcc_args.append('-fsanitize=address')
     self.set_setting('ALLOW_MEMORY_GROWTH')
     self.set_setting('INITIAL_MEMORY', '300mb')
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', ['$allocateUTF8OnStack'])
     self.do_runf(test_file('core/test_asan_js_stack_op.c'),
                  expected_output='Hello, World!')
 

test/test_other.py

@@ -9982,7 +9982,6 @@ def test_proxy_to_pthread_stack(self):
   })
   def test_offset_converter(self, *args):
     self.set_setting('USE_OFFSET_CONVERTER')
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', ['$ptrToString'])
     self.emcc_args += ['--profiling-funcs']
     self.do_runf(test_file('other/test_offset_converter.c'), 'ok', emcc_args=list(args))
 
@@ -9993,7 +9992,6 @@ def test_offset_converter(self, *args):
   def test_offset_converter_source_map(self, *args):
     self.set_setting('USE_OFFSET_CONVERTER')
     self.set_setting('LOAD_SOURCE_MAP')
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', ['$ptrToString'])
     self.emcc_args += ['-gsource-map', '-DUSE_SOURCE_MAP']
     self.do_runf(test_file('other/test_offset_converter.c'), 'ok', emcc_args=list(args))
 
@@ -11000,9 +10998,9 @@ def test_missing_malloc_export_indirect(self):
     # we used to include malloc by default. show a clear error in builds with
     # ASSERTIONS to help with any confusion when the user calls a JS API that
     # requires malloc
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', '$allocateUTF8')
     create_file('unincluded_malloc.c', r'''
       #include <emscripten.h>
+      EM_JS_DEPS("$allocateUTF8");
       int main() {
         EM_ASM({
           try {
@@ -11437,7 +11435,6 @@ def test_shell_Oz(self):
 
   def test_runtime_keepalive(self):
     self.uses_es6 = True
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', ['$runtimeKeepalivePush', '$runtimeKeepalivePop', '$callUserCallback'])
     self.set_setting('EXIT_RUNTIME')
     self.do_other_test('test_runtime_keepalive.cpp')
 
@@ -12440,11 +12437,12 @@ def test_bigint64array_polyfill(self):
       self.assertEqual(v1, v2, msg=m)
 
   def test_warn_once(self):
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', ['$warnOnce'])
     create_file('main.c', r'''\
       #include <stdio.h>
       #include <emscripten.h>
 
+      EM_JS_DEPS("$warnOnce");
+
       int main() {
         EM_ASM({
           warnOnce("foo");
@@ -12477,3 +12475,28 @@ def test_recursive_cache_lock(self):
     with shared.Cache.lock('testing'):
       err = self.expect_fail([EMBUILDER, 'build', 'libc', '--force'], expect_traceback=True)
     self.assertContained('AssertionError: attempt to lock the cache while a parent process is holding the lock', err)
+
+  def test_em_js_deps(self):
+    # Check that EM_JS_DEPS works. Specifically, multiple different instances in different
+    # object files.
+    create_file('f1.c', '''
+    #include <emscripten.h>
+
+    EM_JS_DEPS("$allocateUTF8OnStack");
+    ''')
+    create_file('f2.c', '''
+    #include <emscripten.h>
+
+    EM_JS_DEPS("$getHeapMax");
+
+    int main() {
+      EM_ASM({
+        err(getHeapMax());
+        var x = stackSave();
+        allocateUTF8OnStack("hello");
+        stackRestore(x);
+      });
+      return 0;
+    }
+    ''')
+    self.do_runf('f2.c', emcc_args=['f1.c'])

test/unistd/io.c

@@ -13,6 +13,8 @@
 #include <sys/uio.h>
 #include <emscripten.h>
 
+EM_ASM_DEPS("$ERRNO_CODES");
+
 int main() {
   EM_ASM(
     FS.mkdir('/working');

tools/extract_metadata.py

@@ -3,11 +3,15 @@
 # University of Illinois/NCSA Open Source License.  Both these licenses can be
 # found in the LICENSE file.
 
+import logging
+
 from . import webassembly
 from .webassembly import OpCode, AtomicOpCode, MemoryOpCode
 from .shared import exit_with_error
 from .settings import settings
 
+logger = logging.getLogger('emcc')
+
 
 def skip_function_header(module):
   num_local_decls = module.read_uleb()
@@ -177,20 +181,23 @@ def data_to_string(data):
   return data
 
 
-def get_asm_strings(module, export_map):
-  if '__start_em_asm' not in export_map or '__stop_em_asm' not in export_map:
+def get_section_strings(module, export_map, section_name):
+  start_name = f'__start_{section_name}'
+  stop_name = f'__stop_{section_name}'
+  if start_name not in export_map or stop_name not in export_map:
+    logger.debug(f'no start/stop symbols found for section: {section_name}')
     return {}
 
-  start = export_map['__start_em_asm']
-  end = export_map['__stop_em_asm']
+  start = export_map[start_name]
+  end = export_map[stop_name]
   start_global = module.get_global(start.index)
   end_global = module.get_global(end.index)
   start_addr = get_global_value(start_global)
   end_addr = get_global_value(end_global)
 
   seg = find_segment_with_address(module, start_addr)
   if not seg:
-    exit_with_error('unable to find segment starting at __start_em_asm: %s' % start_addr)
+    exit_with_error(f'unable to find segment starting at __start_{section_name}: {start_addr}')
   seg, seg_offset = seg
 
   asm_strings = {}
@@ -225,9 +232,12 @@ def get_main_reads_params(module, export_map):
 
 def get_named_globals(module, exports):
   named_globals = {}
+  internal_start_stop_symbols = ('__start_em_asm', '__stop_em_asm',
+                                 '__start_em_lib_deps', '__stop_em_lib_deps',
+                                 '__em_lib_deps')
   for export in exports:
     if export.kind == webassembly.ExternType.GLOBAL:
-      if export.name in ('__start_em_asm', '__stop_em_asm') or export.name.startswith('__em_js__'):
+      if export.name in internal_start_stop_symbols or export.name.startswith('__em_js__'):
         continue
       g = module.get_global(export.index)
       named_globals[export.name] = str(get_global_value(g))
@@ -300,7 +310,8 @@ def extract_metadata(filename):
     # If main does not read its parameters, it will just be a stub that
     # calls __original_main (which has no parameters).
     metadata = {}
-    metadata['asmConsts'] = get_asm_strings(module, export_map)
+    metadata['asmConsts'] = get_section_strings(module, export_map, 'em_asm')
+    metadata['jsDeps'] = get_section_strings(module, export_map, 'em_lib_deps').values()
     metadata['declares'] = declares
     metadata['emJsFuncs'] = em_js_funcs
     metadata['exports'] = export_names
@@ -309,5 +320,4 @@ def extract_metadata(filename):
     metadata['invokeFuncs'] = invoke_funcs
     metadata['mainReadsParams'] = get_main_reads_params(module, export_map)
     metadata['namedGlobals'] = get_named_globals(module, exports)
-    # print("Metadata parsed: " + pprint.pformat(metadata))
     return metadata

tools/webidl_binder.py

@@ -81,6 +81,8 @@ def getExtendedAttribute(self, name): # noqa: U100
 
 pre_c += [r'''
 #include <emscripten.h>
+
+EM_JS_DEPS("$intArrayFromString");
 ''']
 
 mid_c += [r'''