gh-156780: Emscripten: support building CPython with static linking

CPython's Emscripten glue was written for the -sMAIN_MODULE configuration it
is built and tested in upstream, and reaches for helpers that only exist
there. Because EM_JS bodies are emitted verbatim, Emscripten's dependency
tracker cannot see those references: a static link silently emits JS referring
to helpers it never included, and dies with a ReferenceError during
initRuntime rather than failing at link time.

Four such references:

* emscripten_syscalls.c hooks resolveGlobalSymbol() to wrap main() in
  WebAssembly.promising(). That helper lives in libdylink.js, which
  src/modules.mjs only links in for MAIN_MODULE builds. It sits below a
  WebAssembly.promising check, so the break is invisible until a runtime
  exposes JSPI.

* emscripten_trampoline.c uses wasmTable and addFunction(), neither of which
  is included by default; MAIN_MODULE pulls them in via libdylink.js.

* The promising-main wrapper calls emscripten_exit_with_live_runtime(), which
  is likewise dropped from a static link.

* The trampoline's preRun hook reads _PyRuntime, which is bound into the JS
  glue only because configure lists it in -sEXPORTED_FUNCTIONS. An embedder
  linking libpython gets no such flag, so this one fails on every runtime.

Declare the library symbols with EM_JS_DEPS, export _PyRuntime's address from
the trampoline itself so it needs no link flags, define
Py_EMSCRIPTEN_DYNAMIC_LINKING from configure so the entry-point hook can be
written for whichever configuration is in use, and pass -sALLOW_TABLE_GROWTH
when not linking with MAIN_MODULE, as addFunction() requires a growable table.

Statically, Emscripten calls the `_main` binding directly instead of resolving
main through libdylink, so that is what the hook rebinds. It must wrap the raw
wasm export: WebAssembly.promising() rejects the createExportWrapper() shim
that `_main` normally holds. A static libpython is usually embedded in a host
application whose main() is not Python's, where wrapping the entry point would
be wrong, so this now requires the embedder to set
Module.Py_EmscriptenPromisingMain.

The async stdin device is needed in every configuration, so it moves to its
own constructor instead of riding along with the entry-point hook.

Verified by embedding a static libpython in a small browser app: an
interactive console runs under Chrome with JSPI available, where the same app
built against unpatched sources fails at startup.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: clementperon

Misc/NEWS.d/next/Build/2026-09-01-16-26-22.gh-issue-156780.Kz8vQr.rst

@@ -0,0 +1,9 @@
+Emscripten: allow CPython to be linked statically. The platform glue reached
+from :c:macro:`EM_JS` bodies for ``resolveGlobalSymbol()``, ``wasmTable`` and
+``addFunction()``, which exist only in ``-sMAIN_MODULE`` builds, and for
+``_PyRuntime``, which only CPython's own link exports. Emscripten cannot see
+inside an ``EM_JS`` body, so without ``--enable-wasm-dynamic-linking`` these
+were silently omitted and startup failed with a ``ReferenceError``. Embedders
+linking a static ``libpython`` must now opt in to wrapping the program entry
+point with ``WebAssembly.promising()`` by setting
+``Module.Py_EmscriptenPromisingMain``.

Python/emscripten_syscalls.c

@@ -1,5 +1,7 @@
 #include "emscripten.h"
 #include "stdio.h"
+// for Py_EMSCRIPTEN_DYNAMIC_LINKING
+#include "pyconfig.h"
 
 // All system calls: return nonnegative number on success, return -errno on
 // failure. Negative results get stored back into errno here:
@@ -54,7 +56,7 @@ __attribute__((constructor)) void __syscall_init_umask(void) {
 #define EM_JS_MACROS(ret, func_name, args, body...)                            \
   EM_JS(ret, func_name, args, body)
 
-EM_JS_MACROS(void, _emscripten_promising_main_js, (void), {
+EM_JS_MACROS(void, _emscripten_setup_async_input_device_js, (void), {
     // Define FS.createAsyncInputDevice(), This is quite similar to
     // FS.createDevice() defined here:
     // https://github.com/emscripten-core/emscripten/blob/4.0.11/src/lib/libfs.js?plain=1#L1642
@@ -103,34 +105,83 @@ EM_JS_MACROS(void, _emscripten_promising_main_js, (void), {
         FS.registerDevice(dev, ops);
         return FS.mkdev(path, mode, dev);
     };
+})
+
+EM_JS_DEPS(_emscripten_setup_async_input_device, "$FS,$PATH,$FS_getMode");
+
+__attribute__((constructor)) void _emscripten_setup_async_input_device(void) {
+    _emscripten_setup_async_input_device_js();
+}
+
+// Wrapping the program entry point with WebAssembly.promising() is what lets
+// main() suspend, so that a blocking read() can await the input device
+// installed above. How Emscripten hands us that entry point depends on how we
+// were linked; see getEntryFunction() in Emscripten's src/parseTools.mjs.
+//
+// * With -sMAIN_MODULE, Emscripten looks main up through resolveGlobalSymbol(),
+//   so we hook the lookup. resolveGlobalSymbol() is defined in libdylink.js,
+//   which is only linked in for MAIN_MODULE builds.
+//
+// * Statically linked, Emscripten calls the `_main` binding directly. We rebind
+//   it to a wrapper around the raw export, because WebAssembly.promising()
+//   rejects the createExportWrapper() shim that `_main` normally holds. A
+//   static libpython is usually embedded in a host application whose main() is
+//   not Python's, so an embedder has to opt in by setting
+//   Module.Py_EmscriptenPromisingMain before the runtime starts.
+#ifdef Py_EMSCRIPTEN_DYNAMIC_LINKING
+#define _Py_EM_INSTALL_PROMISING_MAIN                                          \
+    const origResolveGlobalSymbol = resolveGlobalSymbol;                       \
+    resolveGlobalSymbol = function (name, direct = false) {                    \
+        const orig = origResolveGlobalSymbol(name, direct);                    \
+        if (name === "main") {                                                 \
+            orig.sym = _PyEM_promisingEntryPoint(orig.sym);                    \
+        }                                                                      \
+        return orig;                                                           \
+    };
+#else
+#define _Py_EM_INSTALL_PROMISING_MAIN                                          \
+    if (!Module.Py_EmscriptenPromisingMain) {                                  \
+        return;                                                                \
+    }                                                                          \
+    _main = _PyEM_promisingEntryPoint(wasmExports["main"]);
+#endif
+
+EM_JS_MACROS(void, _emscripten_promising_main_js, (void), {
     if (!WebAssembly.promising) {
         // No stack switching support =(
         return;
     }
-    const origResolveGlobalSymbol = resolveGlobalSymbol;
+    _Py_EM_INSTALL_PROMISING_MAIN
+}
+// * wrap the entry point with WebAssembly.promising,
+// * call exit_with_live_runtime() to prevent emscripten from shutting down
+//   the runtime before the promise resolves,
+// * call onExit / process.exit ourselves, since exit_with_live_runtime()
+//   prevented Emscripten from calling it normally.
+function _PyEM_promisingEntryPoint(orig) {
     if (ENVIRONMENT_IS_NODE && !Module.onExit) {
         Module.onExit = (code) => process.exit(code);
     }
-    // * wrap the main symbol with WebAssembly.promising,
-    // * call exit_with_live_runtime() to prevent emscripten from shutting down
-    //   the runtime before the promise resolves,
-    // * call onExit / process.exit ourselves, since exit_with_live_runtime()
-    //   prevented Emscripten from calling it normally.
-    resolveGlobalSymbol = function (name, direct = false) {
-        const orig = origResolveGlobalSymbol(name, direct);
-        if (name === "main") {
-            const main = WebAssembly.promising(orig.sym);
-            orig.sym = (...args) => {
-                (async () => {
-                    const ret = await main(...args);
-                    Module.onExit?.(ret);
-                })();
-                _emscripten_exit_with_live_runtime();
-            };
-        }
-        return orig;
+    const main = WebAssembly.promising(orig);
+    return (...args) => {
+        (async () => {
+            const ret = await main(...args);
+            Module.onExit?.(ret);
+        })();
+        _emscripten_exit_with_live_runtime();
     };
-})
+}
+)
+
+// EM_JS bodies are emitted verbatim, so Emscripten's dependency tracker cannot
+// see what they reference. Undeclared, these are dropped from the JS glue
+// without a diagnostic and the body throws a ReferenceError at initRuntime.
+#ifdef Py_EMSCRIPTEN_DYNAMIC_LINKING
+EM_JS_DEPS(_emscripten_promising_main,
+           "$resolveGlobalSymbol,emscripten_exit_with_live_runtime");
+#else
+EM_JS_DEPS(_emscripten_promising_main, "emscripten_exit_with_live_runtime");
+#endif
 
 __attribute__((constructor)) void _emscripten_promising_main(void) {
     _emscripten_promising_main_js();

Python/emscripten_trampoline.c

@@ -47,6 +47,12 @@ typedef PyObject* (*TrampolineFunc)(int* success,
                                     PyObject* args,
                                     PyObject* kw);
 
+// Emscripten binds a C global into the JS glue only when it is exported, and an
+// embedder linking libpython statically does not get CPython's own
+// -sEXPORTED_FUNCTIONS. Export the address from here so the setup code below
+// needs no link flags of its own.
+EMSCRIPTEN_KEEPALIVE _PyRuntimeState *const _PyEM_runtime = &_PyRuntime;
+
 /**
  * Backwards compatible trampoline works with all JS runtimes
  */
@@ -90,10 +96,15 @@ function getPyEMTrampolinePtr() {
 addOnPreRun(function setEmscriptenTrampoline() {
     const ptr = getPyEMTrampolinePtr();
     const offset = HEAP32[__PyEM_EMSCRIPTEN_TRAMPOLINE_OFFSET / 4];
-    HEAP32[(__PyRuntime + offset) / 4] = ptr;
+    HEAP32[(HEAPU32[__PyEM_runtime / 4] + offset) / 4] = ptr;
 });
 );
 
+// Emscripten cannot see what an EM_JS body references. Under -sMAIN_MODULE
+// libdylink.js happens to pull these in; a static link needs them declared, and
+// addFunction() additionally needs configure's -sALLOW_TABLE_GROWTH.
+EM_JS_DEPS(_PyEM_TrampolineCall, "$wasmTable,$addFunction,$addOnPreRun");
+
 PyObject*
 _PyEM_TrampolineCall(PyCFunctionWithKeywords func,
                      PyObject* self,

configure

@@ -2446,6 +2446,12 @@ AS_CASE([$ac_sys_system],
 
     AS_VAR_IF([enable_wasm_dynamic_linking], [yes], [
       AS_VAR_APPEND([LINKFORSHARED], [" -sMAIN_MODULE"])
+      AC_DEFINE([Py_EMSCRIPTEN_DYNAMIC_LINKING], [1],
+                [Define if the Emscripten build is linked with -sMAIN_MODULE.])
+    ], [
+      dnl Without MAIN_MODULE the call trampoline's addFunction() needs the
+      dnl function table to be growable; MAIN_MODULE implies this.
+      AS_VAR_APPEND([LINKFORSHARED], [" -sALLOW_TABLE_GROWTH"])
     ])
 
     AS_VAR_IF([enable_wasm_pthreads], [yes], [

configure.ac

@@ -1898,6 +1898,9 @@
 /* Define if you want to build an interpreter with many run-time checks. */
 #undef Py_DEBUG
 
+/* Define if the Emscripten build is linked with -sMAIN_MODULE. */
+#undef Py_EMSCRIPTEN_DYNAMIC_LINKING
+
 /* Defined if Python is built as a shared library. */
 #undef Py_ENABLE_SHARED