[MODULARIZE=instance] Document lack of global Module object (#24326)

Also, disabled tests that use the `Module` object internally.

Because of this ccall/cwrap also don't work. It is conceivable that we
could make this work in the future.

Author: sbc100

.circleci/config.yml

@@ -811,6 +811,8 @@ jobs:
             instance.test_iostream_and_determinism
             instance.test_fannkuch
             instance.test_fasta
+            instance.test_EXPORTED_RUNTIME_METHODS
+            instance.test_ccall
             esm_integration.test_fs_js_api*
             esm_integration.test_inlinejs3
             esm_integration.test_embind_val_basics

site/source/docs/compiling/Modularized-Output.rst

@@ -95,7 +95,8 @@ modularization, and not the ability to create multiple instances.  In this
 mode a module is created that exports a single instance of the program rather
 than a factory function.
 
-This setting only works when :ref:`export_es6` is enabled.
+This setting implicitly enables :ref:`export_es6` and will not work when
+:ref:`export_es6` is explictly disabled.
 
 In this mode the default export of the module is an initializer function which
 allows input parameters to be passed to the instance.  Other elements normally
@@ -108,6 +109,19 @@ found on the module object are instead exported directly.  For example:
   await init({ print: myPrint });
   _nativeMethod();
 
+Limitations
+-----------
+
+Some major features still do not work in this mode.  Many of these we hope to
+fix in future releses.  Current limitations include:
+
+* Internal usage (e.g. usage within EM_JS / JS libary code) of the `Module`
+  object does not work.  This is because symbols are exported directly using
+  ES6 module syntax rathar than using a global `Module` object.
+
+* `ccall`/`cwrap`, these depend on the internal `Module` object.
+
+
 Source Phase Imports (experimental)
 ===================================
 
@@ -117,7 +131,8 @@ the auto-generated code for finding and fetching the Wasm binary.
 
 See :ref:`source_phase_imports`.
 
-This setting only works when :ref:`export_es6` is enabled.
+This setting implicitly enables :ref:`export_es6` and will not work when
+:ref:`export_es6` is explictly disabled.
 
 
 ES Module Integration (experimental)
@@ -129,7 +144,12 @@ boilerplate code for linking up Wasm and JavaScript.
 
 See :ref:`wasm_esm_integration`.
 
-This setting only works when :ref:`export_es6` is enabled.
+Limitations
+-----------
+
+This setting implicitly enables :ref:`export_es6` and sets :ref:`MODULARIZE` to
+``instance``.  Because of this all the same limitations mentioned above for
+``-sMODULARIZE=intance`` apply.
 
 .. _Source phase imports: https://github.com/tc39/proposal-source-phase-imports
 .. _Wasm ESM integration: https://github.com/WebAssembly/esm-integration

src/modules.mjs

@@ -416,15 +416,16 @@ function exportSymbol(name) {
 // export parts of the JS runtime that the user asked for
 function exportRuntimeSymbols() {
   // optionally export something.
-  function maybeExport(name) {
+  function shouldExport(name) {
     // If requested to be exported, export it.
     if (EXPORTED_RUNTIME_METHODS.has(name)) {
       // Unless we are in MODULARIZE=instance mode then HEAP objects are
       // exported separately in updateMemoryViews
       if (MODULARIZE == 'instance' || !name.startsWith('HEAP')) {
-        return exportSymbol(name);
+        return true;
       }
     }
+    return false;
   }
 
   // All possible runtime elements that can be exported
@@ -521,8 +522,8 @@ function exportRuntimeSymbols() {
     }
   }
 
-  const exports = runtimeElements.map(maybeExport);
-  const results = exports.filter((name) => name);
+  const exports = runtimeElements.filter(shouldExport);
+  const results = exports.map(exportSymbol);
 
   if (MODULARIZE == 'instance') {
     if (results.length == 0) return '';

test/core/EXPORTED_RUNTIME_METHODS.c

@@ -17,8 +17,8 @@ int main() {
   EM_ASM({
 #if EXPORTED
     // test for additional things being exported
-    assert(Module['addFunction']);
-    assert(Module['lengthBytesUTF8']);
+    assert(Module['addFunction'], 'missing addFunction export');
+    assert(Module['lengthBytesUTF8'], 'missing lengthBytesUTF8 export');
     Module['setTempRet0'](42);
     assert(Module['getTempRet0']() == 42);
     // the main test here
@@ -28,9 +28,9 @@ int main() {
     // stubs that show a useful error if called. So it is only meaningful
     // to check they don't exist when assertions are disabled.
     if (!ASSERTIONS) {
-      assert(!Module['addFunction']);
-      assert(!Module['lengthBytesUTF8']);
-      assert(!Module['dynCall']);
+      assert(!Module['addFunction'], 'missing addFunction export');
+      assert(!Module['lengthBytesUTF8'], 'missing lengthBytesUTF8 export');
+      assert(!Module['dynCall'], 'missing dynCall export');
     }
     dynCall('viii', $0, [1, 4, 9]);
 #endif

test/test_core.py

@@ -51,6 +51,22 @@ def decorated(self, *args, **kwargs):
   return decorated
 
 
+def no_modularize_instance(note):
+  assert not callable(note)
+
+  def decorator(f):
+    assert callable(f)
+
+    @wraps(f)
+    def decorated(self, *args, **kwargs):
+      if self.get_setting('MODULARIZE') == 'instance' or self.get_setting('WASM_ESM_INTEGRATION'):
+        self.skipTest(note)
+      f(self, *args, **kwargs)
+    return decorated
+
+  return decorator
+
+
 def wasm_simd(f):
   assert callable(f)
 
@@ -1745,6 +1761,7 @@ def test_mod_globalstruct(self):
   def test_sizeof(self):
     self.do_core_test('test_sizeof.c')
 
+  @no_modularize_instance('uses Module object directly')
   def test_llvm_used(self):
     self.do_core_test('test_llvm_used.c')
 
@@ -1754,6 +1771,7 @@ def test_set_align(self):
 
     self.do_core_test('test_set_align.c')
 
+  @no_modularize_instance('uses Module object directly')
   def test_emscripten_api(self):
     self.set_setting('EXPORTED_FUNCTIONS', ['_main', '_save_me_aimee'])
     self.do_core_test('test_emscripten_api.c')
@@ -5347,6 +5365,7 @@ def test_sscanf_float(self):
   def test_langinfo(self):
     self.do_core_test('test_langinfo.c')
 
+  @no_modularize_instance('uses Module object directly')
   def test_files(self):
     # Use closure here, to test we don't break FS stuff
     if '-O3' in self.emcc_args and self.is_wasm2js():
@@ -6217,6 +6236,7 @@ def test_jslib(self):
 
   @with_env_modify({'LC_ALL': 'latin-1', 'PYTHONUTF8': '0', 'PYTHONCOERCECLOCALE': '0'})
   @crossplatform
+  @no_modularize_instance('uses MODULARIZE')
   def test_unicode_js_library(self):
     # First verify that we have correct overridden the default python file encoding.
     # The follow program should fail, assuming the above LC_CTYPE + PYTHONUTF8
@@ -6890,6 +6910,7 @@ def test_autodebug_wasm(self):
   ### Integration tests
 
   @crossplatform
+  @no_modularize_instance('ccall is not compatible with WASM_ESM_INTEGRATION')
   def test_ccall(self):
     self.emcc_args.append('-Wno-return-stack-address')
     self.set_setting('EXPORTED_RUNTIME_METHODS', ['ccall', 'cwrap', 'STACK_SIZE'])
@@ -6934,6 +6955,7 @@ def test_ccall(self):
     if self.maybe_closure():
       self.do_core_test('test_ccall.cpp')
 
+  @no_modularize_instance('ccall is not compatible with WASM_ESM_INTEGRATION')
   def test_ccall_cwrap_fast_path(self):
     self.emcc_args.append('-Wno-return-stack-address')
     self.set_setting('EXPORTED_RUNTIME_METHODS', ['ccall', 'cwrap'])
@@ -6948,6 +6970,7 @@ def test_ccall_cwrap_fast_path(self):
     self.set_setting('EXPORTED_FUNCTIONS', ['_print_bool'])
     self.do_runf('core/test_ccall.cpp', 'true')
 
+  @no_modularize_instance('uses Module object directly')
   def test_EXPORTED_RUNTIME_METHODS(self):
     self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', ['$dynCall', '$ASSERTIONS'])
     self.do_core_test('EXPORTED_RUNTIME_METHODS.c')
@@ -6985,9 +7008,12 @@ def test_dyncall_specific(self):
     'legacy': (['-sDYNCALLS'],),
   })
   def test_dyncall_pointers(self, args):
+    if args:
+      self.skipTest('dynCallLegacy is not yet comatible with WASM_ESM_INTEGRATION')
     self.do_core_test('test_dyncall_pointers.c', emcc_args=args)
 
   @also_with_wasm_bigint
+  @no_modularize_instance('uses Module object directly')
   def test_getValue_setValue(self):
     # these used to be exported, but no longer are by default
     def test(args=None, asserts=False):
@@ -7030,6 +7056,7 @@ def test(args=None, asserts=False):
     '': ([],),
     'files': (['-DUSE_FILES'],),
   })
+  @no_modularize_instance('uses Module object directly')
   def test_FS_exports(self, extra_args):
     # these used to be exported, but no longer are by default
     def test(output_prefix='', args=None, assert_returncode=0):
@@ -7052,6 +7079,7 @@ def test(output_prefix='', args=None, assert_returncode=0):
     self.set_setting('EXPORTED_RUNTIME_METHODS', ['FS_createDataFile'])
     test(args=['-sFORCE_FILESYSTEM'])
 
+  @no_modularize_instance('uses Module object directly')
   def test_legacy_exported_runtime_numbers(self):
     # these used to be exported, but no longer are by default
     def test(expected, args=None, assert_returncode=0):
@@ -7101,6 +7129,7 @@ def test_linker_response_file(self):
     self.run_process([EMCC, "-Wl,@rsp_file", '-o', 'response_file.o.js'] + self.get_emcc_args())
     self.do_run('response_file.o.js', 'hello, world', no_build=True)
 
+  @no_modularize_instance('uses Module object directly')
   def test_exported_response(self):
     src = r'''
       #include <stdio.h>
@@ -7124,6 +7153,7 @@ def test_exported_response(self):
     self.do_run(src, '''waka 5!''')
     assert 'other_function' in read_file('src.js')
 
+  @no_modularize_instance('uses Module object directly')
   def test_large_exported_response(self):
     src = r'''
       #include <stdio.h>
@@ -7899,6 +7929,7 @@ def get_wat_addr(call_index):
       self.assertLessEqual(start_wat_addr, dwarf_addr)
       self.assertLessEqual(dwarf_addr, end_wat_addr)
 
+  @no_modularize_instance('uses -sMODULARIZE')
   def test_modularize_closure_pre(self):
     # test that the combination of modularize + closure + pre-js works. in that mode,
     # closure should not minify the Module object in a way that the pre-js cannot use it.
@@ -8049,6 +8080,7 @@ def test_async_loop(self):
   def test_async_hello_v8(self):
     self.test_async_hello()
 
+  @no_modularize_instance('ccall is not compatible with WASM_ESM_INTEGRATION')
   def test_async_ccall_bad(self):
     # check bad ccall use
     # needs to flush stdio streams
@@ -8080,6 +8112,7 @@ def test_async_ccall_bad(self):
     self.do_runf('main.c', 'The call to main is running asynchronously.')
 
   @with_asyncify_and_jspi
+  @no_modularize_instance('ccall is not compatible with WASM_ESM_INTEGRATION')
   def test_async_ccall_good(self):
     # check reasonable ccall use
     self.set_setting('ASYNCIFY')
@@ -8108,6 +8141,7 @@ def test_async_ccall_good(self):
     'exit_runtime': (True,),
   })
   @with_asyncify_and_jspi
+  @no_modularize_instance('ccall is not compatible with WASM_ESM_INTEGRATION')
   def test_async_ccall_promise(self, exit_runtime):
     if self.get_setting('ASYNCIFY') == 2:
       self.set_setting('JSPI_EXPORTS', ['stringf', 'floatf'])
@@ -9550,6 +9584,7 @@ def test_promise_await_error(self):
     self.do_runf('core/test_promise_await.c', 'Aborted(emscripten_promise_await is only available with ASYNCIFY)',
                  assert_returncode=NON_ZERO)
 
+  @no_modularize_instance('uses Module object directly')
   def test_emscripten_async_load_script(self):
     create_file('script1.js', 'Module._set(456);''')
     create_file('file1.txt', 'first')