Add an experimental way to export a "static" ES module.

Adds a new mode -sMODULARIZE=static which will change the output to be more of
a static ES module. As mentioned in the docs, there will be a default async
init function exported and named exports that correspond to Wasm and runtime
exports. See the docs and test for an example.

Internally, the module will now have an init function that wraps nearly all
of the code except some top level variables that will be exported. When the
init function is run, the top level variables are then updated which will
in turn update the module exports. E.g.

```
async function init(moduleArgs) {
  function foo() {};
  x_foo = foo;
  x_bar = wasmExports['bar'];
}
var x_foo, x_bar;
export {x_foo as foo, x_bar as bar};
```

Note: I alternatively tried to keep everything at the top level scope and move
only the code that reads from moduleArg into an init function. This would make
it possible to get rid of the `x_func` vars and directly add `export` to
vars/functions we want to export. However, there are lots of things that read
from moduleArg in many different spots and ways which makes this challenging.

Author: brendandahl

site/source/docs/tools_reference/settings_reference.rst

@@ -1947,7 +1947,23 @@ factory function, you can use --extern-pre-js or --extern-post-js. While
 intended usage is to add code that is optimized with the rest of the emitted
 code, allowing better dead code elimination and minification.
 
-Default value: false
+Experimental Feature - Static ES Modules:
+
+Note this feature is still under active development and is subject to change!
+
+To enable this feature use -sMODULARIZE=static. Enabling this mode will
+produce an ES module that is a singleton with static ES module exports. The
+module will export a default value that is an async init function and will
+also export named values that correspond to the Wasm exports and runtime
+exports. The init function must be called before any of the exports can be
+used. An example of using the module is below.
+
+  import init, { foo, bar } from "./my_module.mjs"
+  await init(optionalArguments);
+  foo();
+  bar();
+
+Default value: ''
 
 .. _export_es6:
 

src/jsifier.mjs

@@ -644,6 +644,7 @@ function(${args}) {
       // asm module exports are done in emscripten.py, after the asm module is ready. Here
       // we also export library methods as necessary.
       if ((EXPORT_ALL || EXPORTED_FUNCTIONS.has(mangled)) && !isStub) {
+        assert(MODULARIZE !== 'static', 'Exports in jsifier not currently supported with static modules.');
         contentText += `\nModule['${mangled}'] = ${mangled};`;
       }
       // Relocatable code needs signatures to create proper wrappers.

src/modules.mjs

@@ -384,6 +384,9 @@ function exportRuntime() {
     // If requested to be exported, export it.  HEAP objects are exported
     // separately in updateMemoryViews
     if (EXPORTED_RUNTIME_METHODS.has(name) && !name.startsWith('HEAP')) {
+      if (MODULARIZE === 'static') {
+        return `x_${name} = ${name};`;
+      }
       return `Module['${name}'] = ${name};`;
     }
   }

src/postamble_modularize.js

@@ -18,7 +18,7 @@ moduleRtn = Module;
 
 #endif // WASM_ASYNC_COMPILATION
 
-#if ASSERTIONS
+#if ASSERTIONS && MODULARIZE != 'static'
 // Assertion for attempting to access module properties on the incoming
 // moduleArg.  In the past we used this object as the prototype of the module
 // and assigned properties to it, but now we return a distinct object.  This

src/runtime_shared.js

@@ -22,8 +22,13 @@
         shouldExport = true;
       }
     }
-
-    return shouldExport ? `Module['${x}'] = ` : '';
+    if (shouldExport) {
+      if (MODULARIZE === 'static') {
+        return `x_${x} = `
+      }
+      return `Module['${x}'] = `;
+    }
+    return '';
   };
   null;
 }}}

src/settings.js

@@ -1325,8 +1325,25 @@ var DETERMINISTIC = false;
 // --pre-js and --post-js happen to do that in non-MODULARIZE mode, their
 // intended usage is to add code that is optimized with the rest of the emitted
 // code, allowing better dead code elimination and minification.
+//
+// Experimental Feature - Static ES Modules:
+//
+// Note this feature is still under active development and is subject to change!
+//
+// To enable this feature use -sMODULARIZE=static. Enabling this mode will
+// produce an ES module that is a singleton with static ES module exports. The
+// module will export a default value that is an async init function and will
+// also export named values that correspond to the Wasm exports and runtime
+// exports. The init function must be called before any of the exports can be
+// used. An example of using the module is below.
+//
+//   import init, { foo, bar } from "./my_module.mjs"
+//   await init(optionalArguments);
+//   foo();
+//   bar();
+//
 // [link]
-var MODULARIZE = false;
+var MODULARIZE = '';
 
 // Export using an ES6 Module export rather than a UMD export.  MODULARIZE must
 // be enabled for ES6 exports and is implicitly enabled if not already set.

test/test_other.py

@@ -442,6 +442,35 @@ def test_export_es6(self, package_json, args):
 
     self.assertContained('hello, world!', self.run_js('runner.mjs'))
 
+  @parameterized({
+    '': ([],),
+    'pthreads': (['-pthread'],),
+  })
+  def test_modularize_static(self, args):
+    create_file('library.js', '''\
+    addToLibrary({
+      $baz: function() { console.log('baz'); }
+    });''')
+    self.run_process([EMCC, test_file('modularize_static.cpp'),
+                      '-sMODULARIZE=static',
+                      '-sEXPORTED_RUNTIME_METHODS=baz,addOnExit',
+                      '-sEXPORTED_FUNCTIONS=_bar,_main',
+                      '--js-library', 'library.js',
+                      '-o', 'modularize_static.mjs'] + args)
+
+    create_file('runner.mjs', '''
+      import { strict as assert } from 'assert';
+      import init, { _foo as foo, _bar as bar, baz, addOnExit, HEAP32 } from "./modularize_static.mjs";
+      await init();
+      foo(); // exported with EMSCRIPTEN_KEEPALIVE
+      bar(); // exported with EXPORTED_FUNCTIONS
+      baz(); // exported library function with EXPORTED_RUNTIME_METHODS
+      assert(typeof addOnExit === 'function'); // exported runtime function with EXPORTED_RUNTIME_METHODS
+      assert(typeof HEAP32 === 'object'); // exported runtime value by default
+    ''')
+
+    self.assertContained('main1\nmain2\nfoo\nbar\nbaz\n', self.run_js('runner.mjs'))
+
   def test_emcc_out_file(self):
     # Verify that "-ofile" works in addition to "-o" "file"
     self.run_process([EMCC, '-c', '-ofoo.o', test_file('hello_world.c')])

tools/emscripten.py

@@ -912,8 +912,12 @@ def install_wrapper(sym):
 
     # TODO(sbc): Can we avoid exporting the dynCall_ functions on the module.
     should_export = settings.EXPORT_KEEPALIVE and mangled in settings.EXPORTED_FUNCTIONS
-    if name.startswith('dynCall_') or should_export:
-      exported = "Module['%s'] = " % mangled
+    if (name.startswith('dynCall_') and settings.MODULARIZE != 'static') or should_export:
+      if settings.MODULARIZE == 'static':
+        # Update the export declared at the top level.
+        wrapper += f" x_{mangled} = "
+      else:
+        exported = "Module['%s'] = " % mangled
     else:
       exported = ''
     wrapper += exported

tools/link.py

@@ -757,7 +757,13 @@ def phase_linker_setup(options, state, newargs):
 
   if options.oformat == OFormat.MJS:
     settings.EXPORT_ES6 = 1
-    settings.MODULARIZE = 1
+    if not settings.MODULARIZE:
+      settings.MODULARIZE = 1
+
+  if settings.MODULARIZE == 'static':
+    diagnostics.warning('experimental', '-sMODULARIZE=static is still experimental. Many features may not work or will change.')
+    if options.oformat != OFormat.MJS:
+      exit_with_error('emcc: MODULARIZE static is only compatible with .mjs output files')
 
   if options.oformat in (OFormat.WASM, OFormat.BARE):
     if options.emit_tsd:
@@ -2394,7 +2400,20 @@ def modularize():
   if async_emit != '' and settings.EXPORT_NAME == 'config':
     diagnostics.warning('emcc', 'EXPORT_NAME should not be named "config" when targeting Safari')
 
-  src = '''
+  if settings.MODULARIZE == 'static':
+    src = '''
+export default async function init(moduleArg = {}) {
+  var moduleRtn;
+
+%(src)s
+
+  return await moduleRtn;
+}
+''' % {
+      'src': src,
+    }
+  else:
+    src = '''
 %(maybe_async)sfunction(moduleArg = {}) {
   var moduleRtn;
 
@@ -2403,9 +2422,9 @@ def modularize():
   return moduleRtn;
 }
 ''' % {
-    'maybe_async': async_emit,
-    'src': src,
-  }
+      'maybe_async': async_emit,
+      'src': src,
+    }
 
   if settings.MINIMAL_RUNTIME and not settings.PTHREADS:
     # Single threaded MINIMAL_RUNTIME programs do not need access to
@@ -2424,19 +2443,31 @@ def modularize():
       script_url = "typeof document != 'undefined' ? document.currentScript?.src : undefined"
       if shared.target_environment_may_be('node'):
         script_url_node = "if (typeof __filename != 'undefined') _scriptName = _scriptName || __filename;"
-    src = '''%(node_imports)s
+    if settings.MODULARIZE == 'static':
+      src = '''%(node_imports)s
+  var _scriptName = %(script_url)s;
+  %(script_url_node)s
+  %(src)s
+''' % {
+        'node_imports': node_es6_imports(),
+        'script_url': script_url,
+        'script_url_node': script_url_node,
+        'src': src,
+      }
+    else:
+      src = '''%(node_imports)s
 var %(EXPORT_NAME)s = (() => {
   var _scriptName = %(script_url)s;
   %(script_url_node)s
   return (%(src)s);
 })();
 ''' % {
-      'node_imports': node_es6_imports(),
-      'EXPORT_NAME': settings.EXPORT_NAME,
-      'script_url': script_url,
-      'script_url_node': script_url_node,
-      'src': src,
-    }
+        'node_imports': node_es6_imports(),
+        'EXPORT_NAME': settings.EXPORT_NAME,
+        'script_url': script_url,
+        'script_url_node': script_url_node,
+        'src': src,
+      }
 
   # Given the async nature of how the Module function and Module object
   # come into existence in AudioWorkletGlobalScope, store the Module
@@ -2448,9 +2479,18 @@ def modularize():
     src += f'globalThis.AudioWorkletModule = {settings.EXPORT_NAME};\n'
 
   # Export using a UMD style export, or ES6 exports if selected
-  if settings.EXPORT_ES6:
+  if settings.EXPORT_ES6 and settings.MODULARIZE != 'static':
     src += 'export default %s;\n' % settings.EXPORT_NAME
 
+  if settings.MODULARIZE == 'static':
+    exports = settings.EXPORTED_FUNCTIONS + settings.EXPORTED_RUNTIME_METHODS
+    # Declare a top level var for each export so that code in the init function
+    # can assign to it and update the live module bindings.
+    src += "var " + ", ".join(['x_' + export for export in exports]) + ";\n"
+    # Export the functions with their original name.
+    exports = ['x_' + export + ' as ' + export for export in exports]
+    src += "export {" + ", ".join(exports) + "};\n"
+
   elif not settings.MINIMAL_RUNTIME:
     src += '''\
 if (typeof exports === 'object' && typeof module === 'object')
@@ -2473,7 +2513,10 @@ def modularize():
     elif settings.ENVIRONMENT_MAY_BE_NODE:
       src += f'var isPthread = {node_pthread_detection()}\n'
     src += '// When running as a pthread, construct a new instance on startup\n'
-    src += 'isPthread && %s();\n' % settings.EXPORT_NAME
+    if settings.MODULARIZE == 'static':
+      src += 'isPthread && init();\n'
+    else:
+      src += 'isPthread && %s();\n' % settings.EXPORT_NAME
 
   final_js += '.modular.js'
   write_file(final_js, src)

tools/settings.py

@@ -267,7 +267,7 @@ def __setattr__(self, name, value):
     self.attrs[name] = value
 
   def check_type(self, name, value):
-    if name in ('SUPPORT_LONGJMP', 'PTHREAD_POOL_SIZE', 'SEPARATE_DWARF', 'LTO'):
+    if name in ('SUPPORT_LONGJMP', 'PTHREAD_POOL_SIZE', 'SEPARATE_DWARF', 'LTO', 'MODULARIZE'):
       return
     expected_type = self.types.get(name)
     if not expected_type: