gh-156780: Emscripten: support static linking

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: clementperon

Misc/NEWS.d/next/Build/2026-09-01-23-32-22.gh-issue-156780.Qw3nRt.rst

@@ -0,0 +1 @@
+Emscripten: ``libpython.a`` can now be linked into a program statically.

Python/emscripten_trampoline.c

@@ -47,6 +47,20 @@ typedef PyObject* (*TrampolineFunc)(int* success,
                                     PyObject* args,
                                     PyObject* kw);
 
+// The JS glue only binds _PyRuntime if it is exported, which an embedder
+// linking libpython does not do.
+EMSCRIPTEN_KEEPALIVE _PyRuntimeState *const _PyEM_runtime = &_PyRuntime;
+
+// Placeholder whose function table slot the wasm-gc trampoline takes over,
+// so that the table never needs to grow.
+static PyObject*
+trampoline_placeholder(int* success, PyCFunctionWithKeywords func,
+                       PyObject* self, PyObject* args, PyObject* kw)
+{
+    Py_FatalError("Emscripten trampoline slot was not set up");
+}
+EMSCRIPTEN_KEEPALIVE const TrampolineFunc _PyEM_trampoline_slot = trampoline_placeholder;
+
 /**
  * Backwards compatible trampoline works with all JS runtimes
  */
@@ -79,7 +93,9 @@ function getPyEMTrampolinePtr() {
     const trampolineInstance = new WebAssembly.Instance(trampolineModule, {
         env: { __indirect_function_table: wasmTable, memory: wasmMemory },
     });
-    return addFunction(trampolineInstance.exports.trampoline_call);
+    const slot = HEAPU32[__PyEM_trampoline_slot / 4];
+    wasmTable.set(slot, trampolineInstance.exports.trampoline_call);
+    return slot;
 }
 // We have to be careful to work correctly with memory snapshots -- the value of
 // _PyRuntimeState.emscripten_trampoline needs to reflect whether wasm-gc is
@@ -90,12 +106,12 @@ 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;
 });
 );
 
 EM_JS_DEPS(_PyEM_TrampolineCall,
-           "$wasmTable,$wasmMemory,$addFunction,$addOnPreRun");
+           "$wasmTable,$wasmMemory,$addOnPreRun");
 
 PyObject*
 _PyEM_TrampolineCall(PyCFunctionWithKeywords func,

configure

@@ -2440,7 +2440,7 @@ AS_CASE([$ac_sys_system],
     dnl Include file system support
     AS_VAR_APPEND([LINKFORSHARED], [" -sFORCE_FILESYSTEM -lidbfs.js -lnodefs.js -lproxyfs.js -lworkerfs.js"])
     AS_VAR_APPEND([LINKFORSHARED], [" -sEXPORTED_RUNTIME_METHODS=FS,callMain,ENV,HEAPU32,TTY,ERRNO_CODES"])
-    AS_VAR_APPEND([LINKFORSHARED], [" -sEXPORTED_FUNCTIONS=_main,_Py_Version,__PyRuntime,_PyGILState_GetThisThreadState,__PyEM_EMSCRIPTEN_TRAMPOLINE_OFFSET"])
+    AS_VAR_APPEND([LINKFORSHARED], [" -sEXPORTED_FUNCTIONS=_main,_Py_Version,_PyGILState_GetThisThreadState,__PyEM_EMSCRIPTEN_TRAMPOLINE_OFFSET"])
     AS_VAR_APPEND([LINKFORSHARED], [" -sSTACK_SIZE=5MB"])
     dnl Avoid bugs in JS fallback string decoding path
     AS_VAR_APPEND([LINKFORSHARED], [" -sTEXTDECODER=2"])