Bug description:

CPython's Emscripten platform code is written for the -sMAIN_MODULE dynamic-linking configuration it is built and tested in. Several EM_JS bodies reference JS helpers that only exist in that configuration. Because EM_JS bodies are emitted verbatim into the output, Emscripten's dependency tracker cannot see those references, so a static link silently emits JS calling helpers it never included and fails at runtime instead of at link time.

Four such references, each confirmed against Emscripten 6.0.9:

1. Python/emscripten_syscalls.c:110 hooks resolveGlobalSymbol() to wrap main() in WebAssembly.promising(). That helper is defined in src/lib/libdylink.js, which src/modules.mjs:99 links in only if (MAIN_MODULE); the file itself #errors otherwise, and the symbol is marked __internal: true. The read sits below the if (!WebAssembly.promising) return; guard on line 106, so this only fires once a runtime exposes JSPI.
2. Python/emscripten_trampoline.c:54 and :82 use wasmTable and addFunction(). Neither is included by default; MAIN_MODULE happens to pull both in through libdylink's own __deps.
3. The promising-main wrapper calls _emscripten_exit_with_live_runtime() (emscripten_syscalls.c:128), which is likewise dropped from a static link.
4. Python/emscripten_trampoline.c:93 reads __PyRuntime, which is bound into the JS glue only because configure lists it in -sEXPORTED_FUNCTIONS for CPython's own python.mjs link. An embedder linking libpython into their own application gets no such flag. Unlike the others, this one fails on every runtime, JSPI or not.

Minimal reproducer

This is the shape of (1) with no CPython involved:

#include <emscripten.h>
EM_JS(void, probe, (void), {
    if (!WebAssembly.promising) return;
    const orig = resolveGlobalSymbol;
})
__attribute__((constructor)) void c(void) { probe(); }
int main(void) { return 0; }

$ emcc t.c -o t.js          # links clean, no diagnostic at all
$ node t.js                 # fine, the guard returns early
$ node --experimental-wasm-jspi t.js
ReferenceError: resolveGlobalSymbol is not defined
    at probe (t.js:1513:136)
    at initRuntime (t.js:540:35)

Emscripten does warn for library symbols it knows about — referencing addFunction the same way produces "addFunction is a library symbol and not included by default". resolveGlobalSymbol gets nothing, because without MAIN_MODULE libdylink.js is never loaded and the name is not in the symbol set to warn about.

Full reproduction

I built libpython3.14.a for wasm32-emscripten with --disable-wasm-dynamic-linking MODULE_BUILDTYPE=static CFLAGS=-DPY_CALL_TRAMPOLINE and linked it into a small C application that runs an interactive Python console in the browser. It aborts during startup on __PyRuntime; with that symbol exported by hand it then aborts on resolveGlobalSymbol as soon as JSPI is enabled, and works with JSPI off.

Note on the fix

EM_JS_DEPS (emscripten/em_macros.h) exists precisely to declare these, and emscripten_syscalls.c:43 already uses it for $SYSCALLS. Declaring $resolveGlobalSymbol converts the silent breakage into a link-time error: undefined symbol: $resolveGlobalSymbol, which is the behaviour you would want in a configuration that genuinely cannot support it.

Why this is not caught today

Every wasm test builds through Platforms/emscripten/__main__.py, which hard-codes --enable-wasm-dynamic-linking at line 510. web_example, web_example_pyrepl_jspi and browser_test therefore all exercise MAIN_MODULE only; the static configuration has no coverage.

Context for the report: this blocks embedding CPython in Kodi's WebAssembly port, which links statically.

CPython versions tested on:

3.14, CPython main branch

Operating systems tested on:

Other

Linked PRs

• gh-156780: Emscripten: support building CPython with static linking #156781
• gh-156780: Emscripten: add missing EM_JS_DEPS #156798
• gh-156780: Emscripten: drop the trampoline's dependence on exports #157238