MODULARIZE followups after #10697 (#11116)

Get MINIMAL_RUNTIME + MODULARIZE code size back to
where it was before that PR, when emitting HTML: the HTML in that
mode will create a single instance of the app and run it automatically.
It does so without needing the Promise, so we don't need to emit it.
Diffing the output JS to before #10697 shows essentially no difference.

Also move the changelog entry to the right place (we had a release
meanwhile), expand it a little, and ifdef some logging in postamble.js
(if we reject the Promise on an error, we log it out that way anyhow).

Author: kripken

ChangeLog.md

@@ -17,6 +17,13 @@ See docs/process.md for how version tagging works.
 
 Current Trunk
 -------------
+- Change the factory function created by using the `MODULARIZE` build option to
+  return a Promise instead of the module instance. If you use `MODULARIZE` you
+  will need to wait on the returned Promise, using `await` or its `then`
+  callback, to get the module instance (#10697). This fixes some long-standing
+  bugs with that option which have been reported multiple times, but is a
+  breaking change - sorry about that. See detailed examples for the
+  current usage in `src/settings.js` on `MODULARIZE`.
 - A new `PRINTF_LONG_DOUBLE` option allows printf to print long doubles at full
   float128 precision. (#11130)
 - `emscripten_async_queue_on_thread` has been renamed to
@@ -43,10 +50,6 @@ Current Trunk
 
 1.39.15: 05/06/2020
 -------------------
-- Change the factory function created by using the `MODULARIZE` build option to
-  return a Promise instead of the module instance. If you use `MODULARIZE` you
-  will need to wait on the returned Promise, using `await` or its `then`
-  callback, to get the module instance (#10697).
 - Add `--extern-pre-js` and `--extern-post-js` emcc flags. Files provided there
   are prepended/appended to the final JavaScript output, *after* all other
   work has been done, including optimization, optional `MODULARIZE`-ation,

emcc.py

@@ -1329,6 +1329,13 @@ def has_c_source(args):
 
     if shared.Settings.MODULARIZE:
       assert not options.proxy_to_worker, '-s MODULARIZE=1 is not compatible with --proxy-to-worker (if you want to run in a worker with -s MODULARIZE=1, you likely want to do the worker side setup manually)'
+      # in MINIMAL_RUNTIME we may not need to emit the Promise code, as the
+      # HTML output creates a singleton instance, and it does so without the
+      # Promise. However, in Pthreads mode the Promise is used for worker
+      # creation.
+      if shared.Settings.MINIMAL_RUNTIME and final_suffix == '.html' and \
+         not shared.Settings.USE_PTHREADS:
+        shared.Settings.EXPORT_READY_PROMISE = 0
 
     if shared.Settings.EMULATE_FUNCTION_POINTER_CASTS:
       shared.Settings.ALIASING_FUNCTION_POINTERS = 0
@@ -3423,17 +3430,22 @@ def modularize():
   logger.debug('Modularizing, assigning to var ' + shared.Settings.EXPORT_NAME)
   src = open(final).read()
 
+  return_value = shared.Settings.EXPORT_NAME + '.ready'
+  if not shared.Settings.EXPORT_READY_PROMISE:
+    return_value = '{}'
+
   src = '''
 function(%(EXPORT_NAME)s) {
   %(EXPORT_NAME)s = %(EXPORT_NAME)s || {};
 
 %(src)s
 
-  return %(EXPORT_NAME)s.ready;
+  return %(return_value)s
 }
 ''' % {
     'EXPORT_NAME': shared.Settings.EXPORT_NAME,
     'src': src,
+    'return_value': return_value
   }
 
   if shared.Settings.MINIMAL_RUNTIME and not shared.Settings.USE_PTHREADS:

src/postamble.js

@@ -408,15 +408,17 @@ function exit(status, implicit) {
     if (!implicit) {
 #if EXIT_RUNTIME == 0
       var msg = 'program exited (with status: ' + status + '), but EXIT_RUNTIME is not set, so halting execution but not exiting the runtime or preventing further async execution (build with EXIT_RUNTIME=1, if you want a true shutdown)';
-      err(msg);
 #if MODULARIZE
       readyPromiseReject(msg);
+#else
+      err(msg);
 #endif // MODULARIZE
 #else
       var msg = 'program exited (with status: ' + status + '), but noExitRuntime is set due to an async operation, so halting execution but not exiting the runtime or preventing further async execution (you can use emscripten_force_exit, if you want to force a true shutdown)';
-      err(msg);
 #if MODULARIZE
       readyPromiseReject(msg);
+#else
+      err(msg);
 #endif // MODULARIZE
 #endif // EXIT_RUNTIME
     }

src/settings.js

@@ -1064,8 +1064,11 @@ var DETERMINISTIC = 0;
 // for default values. Default values must be passed as a parameter to the
 // factory function.
 //
-// The default .html shell file provided in MINIMAL_RUNTIME mode shows
-// an example to how the module is instantiated from within the html file.
+// The default .html shell file provided in MINIMAL_RUNTIME mode will create
+// a singleton instance automatically, to run the application on the page.
+// (Note that it does so without using the Promise API mentioned earlier, and
+// so code for the Promise is not even emitted in the .js file if you tell
+// emcc to emit an .html output.)
 // The default .html shell file provided by traditional runtime mode is only
 // compatible with MODULARIZE=0 mode, so when building with traditional
 // runtime, you should provided your own html shell file to perform the

src/settings_internal.js

@@ -209,3 +209,7 @@ var STACK_BASE = 0;
 // enabled, but if `--no-entry` is passed, or if `_main` is not part of 
 // EXPORTED_FUNCTIONS then this gets set to 0.
 var EXPECT_MAIN = 1;
+
+// Provide and export a .ready() Promise. This is currently used by default with
+// MODULARIZE, and returned from the factory function.
+var EXPORT_READY_PROMISE = 1;

src/shell_minimal.js

@@ -15,7 +15,7 @@ var Module = {{{ EXPORT_NAME }}};
 #endif // USE_CLOSURE_COMPILER
 #endif // SIDE_MODULE
 
-#if MODULARIZE
+#if MODULARIZE && EXPORT_READY_PROMISE
 // Set up the promise that indicates the Module is initialized
 var readyPromiseResolve, readyPromiseReject;
 Module['ready'] = new Promise(function(resolve, reject) {
@@ -140,7 +140,7 @@ function err(text) {
 // compilation is ready. In that callback, call the function run() to start
 // the program.
 function ready() {
-#if MODULARIZE
+#if MODULARIZE && EXPORT_READY_PROMISE
   readyPromiseResolve(Module);
 #endif // MODULARIZE
 #if INVOKE_RUN && hasExportedFunction('_main')

tests/code_size/hello_webgl2_fastcomp_asmjs.json

@@ -1,12 +1,12 @@
 {
   "a.html": 580,
   "a.html.gz": 382,
-  "a.js": 5388,
-  "a.js.gz": 2546,
+  "a.js": 5326,
+  "a.js.gz": 2510,
   "a.mem": 321,
   "a.mem.gz": 219,
-  "a.asm.js": 9846,
-  "a.asm.js.gz": 3535,
-  "total": 16135,
-  "total_gz": 6682
+  "a.asm.js": 9814,
+  "a.asm.js.gz": 3544,
+  "total": 16042,
+  "total_gz": 6655
 }

tests/code_size/hello_webgl2_fastcomp_wasm.json

@@ -1,10 +1,10 @@
 {
   "a.html": 563,
   "a.html.gz": 377,
-  "a.js": 5353,
-  "a.js.gz": 2570,
-  "a.wasm": 8007,
-  "a.wasm.gz": 4421,
-  "total": 13923,
-  "total_gz": 7368
+  "a.js": 5293,
+  "a.js.gz": 2537,
+  "a.wasm": 8004,
+  "a.wasm.gz": 4376,
+  "total": 13861,
+  "total_gz": 7290
 }

tests/code_size/hello_webgl2_wasm.json

@@ -1,10 +1,10 @@
 {
   "a.html": 563,
   "a.html.gz": 377,
-  "a.js": 5133,
-  "a.js.gz": 2460,
+  "a.js": 5073,
+  "a.js.gz": 2423,
   "a.wasm": 10912,
   "a.wasm.gz": 6940,
-  "total": 16608,
-  "total_gz": 9777
+  "total": 16549,
+  "total_gz": 9740
 }

tests/code_size/hello_webgl2_wasm2js.json

@@ -1,10 +1,10 @@
 {
   "a.html": 588,
   "a.html.gz": 386,
-  "a.js": 23765,
-  "a.js.gz": 8937,
+  "a.js": 23705,
+  "a.js.gz": 8895,
   "a.mem": 3168,
   "a.mem.gz": 2711,
-  "total": 27521,
-  "total_gz": 12034
+  "total": 27462,
+  "total_gz": 11992
 }