Merge branch 'main' into ports-deferred

Author: dschuff

Diff for: ChangeLog.md

@@ -23,6 +23,16 @@ See docs/process.md for more on how version tagging works.
 - Added experimental support for Wasm ESM integration with
   `-sWASM_ESM_INTEGRATION`. This is currently only supported in node behind a
   flag and not in any browsers. (#23985)
+- Runtime callbacks registered in `Module['preRun']` or `Module['postRun']`, or
+  using `addOnPreRun()`, `addOnInit()`, `addOnPostCtor()`, `addOnPreMain()`,
+  `addOnExit()`, or `addOnPostRun()`, are now enqueued and executed following
+  the order of registration (i.e. `Module['preRun'] = [a, b]`, or equivalently
+  `addOnPreRun(a); addOnPreRun(b);` will run `a` then `b`; the previous behavior
+  was to run `b` then `a`). While this might be a breaking change for some users,
+  the intention is to be more consistent by making those callbacks match the
+  behavior of `Module['preInit']` and compile time callbacks (rather than the
+  contrary, as we generally expect an array of functions to be executed left to
+  right). (#24012)
 
 4.0.6 - 03/26/25
 ----------------

Diff for: cmake/Modules/FindOpenGL.cmake

@@ -31,14 +31,18 @@ mark_as_advanced(
   OPENGL_gl_LIBRARY
 )
 
-add_library(OpenGL::GL INTERFACE IMPORTED)
-set_target_properties(OpenGL::GL PROPERTIES
-  IMPORTED_LIBNAME "${OPENGL_gl_LIBRARY}"
-  INTERFACE_INCLUDE_DIRECTORIES "${OPENGL_INCLUDE_DIR}"
-)
-
-add_library(OpenGL::GLU INTERFACE IMPORTED)
-set_target_properties(OpenGL::GLU PROPERTIES
-  IMPORTED_LIBNAME "${OPENGL_glu_LIBRARY}"
-  INTERFACE_LINK_LIBRARIES OpenGL::GL
-)
+if (NOT TARGET OpenGL::GL)
+  add_library(OpenGL::GL INTERFACE IMPORTED)
+  set_target_properties(OpenGL::GL PROPERTIES
+    IMPORTED_LIBNAME "${OPENGL_gl_LIBRARY}"
+    INTERFACE_INCLUDE_DIRECTORIES "${OPENGL_INCLUDE_DIR}"
+  )
+endif()
+
+if (NOT TARGET OpenGL::GLU)
+  add_library(OpenGL::GLU INTERFACE IMPORTED)
+  set_target_properties(OpenGL::GLU PROPERTIES
+    IMPORTED_LIBNAME "${OPENGL_glu_LIBRARY}"
+    INTERFACE_LINK_LIBRARIES OpenGL::GL
+  )
+endif()

Diff for: pyproject.toml

@@ -80,13 +80,13 @@ conf\.py |
 emrun\.py |
 site/source/_themes/ |
 tools/scons/site_scons/site_tools/emscripten/__init__\.py |
+tools/maint/create_dom_pk_codes.py |
 site/source/get_wiki\.py |
 test/parse_benchmark_output\.py
 )'''
 
 [[tool.mypy.overrides]]
 module = [
-  "tools.create_dom_pk_codes",
   "tools.webidl_binder",
   "tools.toolchain_profiler",
   "tools.filelock",

Diff for: site/source/docs/getting_started/FAQ.rst

@@ -18,7 +18,7 @@ Why do I get errors building basic code and the tests?
 
 All the tests in the :ref:`Emscripten test suite <emscripten-test-suite>` are
 known to build and pass on our test infrastructure, so if you see failures
-locally it is likely that there is some problem with your environment. (Rarely,
+locally, it is likely that there is some problem with your environment. (Rarely,
 there may be temporary breakage, but never on a tagged release version.)
 
 First call ``emcc --check``, which runs basic sanity checks and prints out
@@ -105,13 +105,13 @@ compilation time).
 Why is my compiled code big?
 ============================
 
-Make sure you build with ``-O3`` or ``-Os`` so code is fully optimized and
+Make sure you build with ``-O3`` or ``-Os``, so the code is fully optimized and
 minified. You should use the closure compiler, gzip compression on your
 webserver, etc., see the :ref:`section on code size in Optimizing code
 <optimizing-code-size>`.
 
 
-Why does compiling code that works on another machine gives me errors?
+Why does compiling code that works on another machine give me errors?
 ======================================================================
 
 Make sure you are using the Emscripten bundled system headers. Using :ref:`emcc
@@ -207,11 +207,11 @@ JavaScript that does not complete and return control to the browser.
 Graphical C++ apps typically have an infinite main loop in which event handling,
 processing and rendering is done, followed by a delay to keep the frame-rate
 right (``SDL_DELAY`` in :term:`SDL` apps). As the main loop does not complete
-(is infinite) it cannot return control to the browser, and the app will hang.
+(is infinite), it cannot return control to the browser, and the app will hang.
 
 Apps that use an infinite main loop should be re-coded to put the actions for a
 single iteration of the loop into a single "finite" function. In the native
-build this function can be run in an infinite loop as before. In the Emscripten
+build, this function can be run in an infinite loop as before. In the Emscripten
 build it is set as the :ref:`main loop function <faq-how-run-event-loop>` and
 will be called by the browser at a specified frequency.
 

Diff for: site/source/docs/getting_started/Tutorial.rst

@@ -28,18 +28,18 @@ using ``./emcc`` or ``./em++``.
 For the next section you will need to open a command prompt:
 
 - On Linux or macOS, open a *Terminal*.
-- On Windows open the :ref:`Emscripten Command Prompt <emcmdprompt>`, a command
+- On Windows, open the :ref:`Emscripten Command Prompt <emcmdprompt>`, a command
   prompt that has been pre-configured with the correct system paths and settings
   to point to the :term:`active <Active Tool/SDK>` Emscripten tools. To access
-  this prompt, type **Emscripten** in the Windows 8 start screen, and then
+  this prompt, type **Emscripten** in the Windows start menu, and then
   select the **Emscripten Command Prompt** option.
 
 Navigate with the command prompt to the emscripten directory under the SDK. This
 is a folder below the :term:`emsdk root directory`, typically
 **<emsdk root directory>/upstream/emscripten/**.
 The examples below will depend on finding files relative to that location.
 
-.. note:: In older emscripten versions the directory structure was different:
+.. note:: In older emscripten versions, the directory structure was different:
    the version number appeared, and the backend (fastcomp/upstream) did not, so
    you would use something like **<emsdk root directory>/emscripten/1.20.0/**.
 
@@ -52,7 +52,7 @@ If you haven't run Emscripten before, run it now with: ::
     ./emcc -v
 
 If the output contains warnings about missing tools, see
-:ref:`verifying-the-emscripten-environment` for debugging help. Otherwise
+:ref:`verifying-the-emscripten-environment` for debugging help. Otherwise,
 continue to the next sections where we'll build some code.
 
 
@@ -61,7 +61,7 @@ Running Emscripten
 
 You can now compile your first C/C++ file to JavaScript.
 
-First, lets have a look at the file to be compiled: **hello_world.c**. This is
+First, let's have a look at the file to be compiled: **hello_world.c**. This is
 the simplest test code in the SDK, and as you can see, all it does is print
 "hello, world!" to the console and then exit.
 
@@ -86,15 +86,6 @@ execute it. You can run them using :term:`node.js`:
 
 This prints "hello, world!" to the console, as expected.
 
-.. note:: Older node.js versions do not have WebAssembly support yet. In that
-   case you will see an error message suggesting that you build with
-   ``-sWASM=0`` to disable WebAssembly, and then emscripten will emit the compiled
-   code as JavaScript. In general, WebAssembly is recommended as it has
-   widespread browser support and is more efficient both to execute and to
-   download (and therefore emscripten emits it by default), but sometimes you
-   may need your code to run in an environment where it is not yet present and
-   so should disable it.
-
 .. tip:: If an error occurs when calling *emcc*, run it with the ``-v`` option
    to print out a lot of useful debug information.
 
@@ -116,11 +107,11 @@ file as the target file: ::
 
 You can now open ``hello.html`` in a web browser.
 
-.. note:: Unfortunately several browsers (including *Chrome*, *Safari*, and
-   *Internet Explorer*) do not support ``file://`` :term:`XHR` requests, and
-   can't load extra files needed by the HTML (like a ``.wasm`` file, or packaged
-   file data as mentioned lower down). For these browsers you'll need to serve
-   the files using a :ref:`local webserver <faq-local-webserver>` and then open
+.. note:: Unfortunately, several browsers (including *Chrome* and *Safari*) do
+   not support ``file://`` :term:`XHR` requests, and can't load extra files
+   needed by the HTML (like a ``.wasm`` file, or packaged file data as mentioned
+   lower down). For these browsers, you'll need to serve the files using a
+   :ref:`local webserver <faq-local-webserver>` and then open
    ``http://localhost:8000/hello.html``).
 
 Once you have the HTML loaded in your browser, you'll see a text area for

Diff for: site/source/docs/getting_started/downloads.rst

@@ -8,20 +8,20 @@ Download and install
    <installing-from-source>` if you prefer that to downloading binaries using
    the emsdk.
 
-.. tip:: if you'd like to install emscripten using the **unofficial** packages
+.. tip:: If you'd like to install emscripten using the **unofficial** packages
    instead of the **officially supported** emsdk, see the bottom of the page.
 
 .. _sdk-installation-instructions:
 
 Installation instructions using the emsdk (recommended)
 =======================================================
 
-First check the :ref:`Platform-specific notes
+First, check the :ref:`Platform-specific notes
 <platform-notes-installation_instructions-SDK>` below and install any
 prerequisites.
 
 The core Emscripten SDK (emsdk) driver is a Python script. You can get it for
-the first time with
+the first time with:
 
   ::
 
@@ -52,7 +52,7 @@ GitHub and set them as :term:`active <Active Tool/SDK>`:
     # Activate PATH and other environment variables in the current terminal
     source ./emsdk_env.sh
 
-  .. tip:: If you want to avoid executing `source ./emsdk_env.sh` every time you open a new terminal you can follow the instructions given by the `emsdk activate` command above to add this command to your startup scripts.
+  .. tip:: If you want to avoid executing `source ./emsdk_env.sh` every time you open a new terminal, you can follow the instructions given by the `emsdk activate` command above to add this command to your startup scripts.
 
   .. note:: On Windows, run ``emsdk.bat`` instead of ``./emsdk``, and ``emsdk_env.bat`` instead of ``source ./emsdk_env.sh``.
 
@@ -67,7 +67,7 @@ commands.
 Emsdk install targets
 ---------------------
 
-In the description above we asked the emsdk to install and activate ``latest``,
+In the description above, we asked the emsdk to install and activate ``latest``,
 which is the latest tagged release. That is often what you want.
 
 You can also install a specific version by specifying it, for example,
@@ -101,7 +101,7 @@ target, and note that you must specify the backend explicitly,
     # Get a tip-of-tree 
     ./emsdk install tot
 
-(In the above examples we installed the various targets; remember to also
+(In the above examples, we installed the various targets; remember to also
 ``activate`` them as in the full example from earlier.)
 
 .. _platform-notes-installation_instructions-SDK:
@@ -122,8 +122,8 @@ macOS
 
 .. note:: Emscripten requires macOS 10.14 Mojave or above.
 
-If you use the Emscripten SDK it includes a bundled version of Python 3.
-Otherwise you will need to manually install and use Python 3.6 or newer.
+If you use the Emscripten SDK, it includes a bundled version of Python 3.
+Otherwise, you will need to manually install and use Python 3.6 or newer.
 
 These instructions explain how to install **all** the :ref:`required tools
 <toolchain-what-you-need>`. You can :ref:`test whether some of these are already

Diff for: site/source/docs/getting_started/test-suite.rst

@@ -99,7 +99,7 @@ the first failure.
    that are normally run in parallel you can force them to run serially using
    ``-j1``.
 
-One a test is fixed you continue where you left off using ``--start-at`` option:
+Once a test is fixed, you continue where you left off using ``--start-at`` option:
 
 .. code-block:: bash
 

Diff for: src/jsifier.mjs

@@ -734,15 +734,6 @@ function(${args}) {
         }
         contentText = `var ${mangled} = ${snippet};`;
       }
-      // 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) {
-        if (MODULARIZE === 'instance') {
-          contentText += `\n__exp_${mangled} = ${mangled};`;
-        } else {
-          contentText += `\nModule['${mangled}'] = ${mangled};`;
-        }
-      }
       // Relocatable code needs signatures to create proper wrappers.
       if (sig && RELOCATABLE) {
         if (!WASM_BIGINT) {

Diff for: src/lib/libcore.js

@@ -2300,7 +2300,7 @@ addToLibrary({
     ATPRERUNS.unshift('callRuntimeCallbacks(onPreRuns);');
   },
   $addOnPreRun__deps: ['$onPreRuns'],
-  $addOnPreRun: (cb) => onPreRuns.unshift(cb),
+  $addOnPreRun: (cb) => onPreRuns.push(cb),
   // See ATINITS in parseTools.mjs for more information.
   $onInits: [],
   $onInits__internal: true,
@@ -2309,7 +2309,7 @@ addToLibrary({
     ATINITS.unshift('callRuntimeCallbacks(onInits);');
   },
   $addOnInit__deps: ['$onInits'],
-  $addOnInit: (cb) => onInits.unshift(cb),
+  $addOnInit: (cb) => onInits.push(cb),
   // See ATPOSTCTORS in parseTools.mjs for more information.
   $onPostCtors: [],
   $onPostCtors__internal: true,
@@ -2318,7 +2318,7 @@ addToLibrary({
     ATPOSTCTORS.unshift('callRuntimeCallbacks(onPostCtors);');
   },
   $addOnPostCtor__deps: ['$onPostCtors'],
-  $addOnPostCtor: (cb) => onPostCtors.unshift(cb),
+  $addOnPostCtor: (cb) => onPostCtors.push(cb),
   // See ATMAINS in parseTools.mjs for more information.
   $onMains: [],
   $onMains__internal: true,
@@ -2327,7 +2327,7 @@ addToLibrary({
     ATMAINS.unshift('callRuntimeCallbacks(onMains);');
   },
   $addOnPreMain__deps: ['$onMains'],
-  $addOnPreMain: (cb) => onMains.unshift(cb),
+  $addOnPreMain: (cb) => onMains.push(cb),
   // See ATEXITS in parseTools.mjs for more information.
   $onExits: [],
   $onExits__internal: true,
@@ -2336,7 +2336,7 @@ addToLibrary({
     ATEXITS.unshift('callRuntimeCallbacks(onExits);');
   },
   $addOnExit__deps: ['$onExits'],
-  $addOnExit: (cb) => onExits.unshift(cb),
+  $addOnExit: (cb) => onExits.push(cb),
   // See ATPOSTRUNS in parseTools.mjs for more information.
   $onPostRuns: [],
   $onPostRuns__internal: true,
@@ -2345,7 +2345,7 @@ addToLibrary({
     ATPOSTRUNS.unshift('callRuntimeCallbacks(onPostRuns);');
   },
   $addOnPostRun__deps: ['$onPostRuns'],
-  $addOnPostRun: (cb) => onPostRuns.unshift(cb),
+  $addOnPostRun: (cb) => onPostRuns.push(cb),
 
   // We used to define these globals unconditionally in support code.
   // Instead, we now define them here so folks can pull it in explicitly, on

Diff for: src/lib/libdylink.js

@@ -871,13 +871,18 @@ var LibraryDylink = {
       }
 
       if (flags.loadAsync) {
-        if (binary instanceof WebAssembly.Module) {
-          var instance = new WebAssembly.Instance(binary, info);
-          return Promise.resolve(postInstantiation(binary, instance));
-        }
-        return WebAssembly.instantiate(binary, info).then(
-          (result) => postInstantiation(result.module, result.instance)
-        );
+        return (async () => {
+          var instance;
+          if (binary instanceof WebAssembly.Module) {
+            instance = new WebAssembly.Instance(binary, info);
+          } else {
+            // Destructuring assignment without declaration has to be wrapped
+            // with parens or parser will treat the l-value as an object
+            // literal instead.
+            ({ module: binary, instance } = await WebAssembly.instantiate(binary, info));
+          }
+          return postInstantiation(binary, instance);
+        })();
       }
 
       var module = binary instanceof WebAssembly.Module ? binary : new WebAssembly.Module(binary);

Diff for: src/lib/libegl.js

@@ -22,7 +22,6 @@ const eglDefaultDisplay = 62000;
 const eglDefaultConfig = 62002;
 // Magic ID for Emscripten EGLContext
 const eglDefaultContext = 62004;
-null;
 }}}
 
 var LibraryEGL = {

Diff for: src/lib/libemval.js

@@ -19,7 +19,6 @@
 {{{
   const EMVAL_RESERVED_HANDLES = 5;
   const EMVAL_LAST_RESERVED_HANDLE = EMVAL_RESERVED_HANDLES * 2 - 1;
-  null;
 }}}
 var LibraryEmVal = {
   // Stack of handles available for reuse.

Diff for: src/lib/libglemu.js

@@ -21,7 +21,6 @@ assert(!FULL_ES3, 'cannot emulate both ES3 and legacy GL');
     }
     return '';
   };
-  null;
 }}}
 
 var LibraryGLEmulation = {

Diff for: src/lib/libhtml5_webgpu.js

@@ -1,18 +1,17 @@
 {{{
   // Helper functions for code generation
-  globalThis.html5_gpu = {
-    makeImportExport: (snake_case, CamelCase) => {
-      return `
+const html5_gpu = {
+  makeImportExport: (snake_case, CamelCase) => {
+    return `
 LibraryHTML5WebGPU.emscripten_webgpu_import_${snake_case}__deps = ['$WebGPU', '$JsValStore'];
 LibraryHTML5WebGPU.emscripten_webgpu_import_${snake_case} = (handle) =>
   WebGPU.mgr${CamelCase}.create(JsValStore.get(handle));
 
 LibraryHTML5WebGPU.emscripten_webgpu_export_${snake_case}__deps = ['$WebGPU', '$JsValStore'];
 LibraryHTML5WebGPU.emscripten_webgpu_export_${snake_case} = (handle) =>
   JsValStore.add(WebGPU.mgr${CamelCase}.get(handle));`
-    },
-  };
-  null;
+  },
+};
 }}}
 
 

Diff for: src/lib/libpthread.js

@@ -52,7 +52,6 @@ const pthreadWorkerOptions = `{
 #endif
 #endif
 }`;
-null
 }}}
 
 var LibraryPThread = {