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

[clementperon]

Fixes #156780.

Allow Emscripten libpython.a to be embedded without -sMAIN_MODULE or wrapping the application's main(). The wrapper no longer depends on resolveGlobalSymbol().

Keep the JavaScript setup in Python/emscripten_syscalls.c and invoke it from a constructor in Programs/emscripten_beforemain.c, linked only into the interpreter and _testembed. Preserve the existing _emscripten_exit_with_live_runtime() and Module.onExit behavior. Omit the constructor when Emscripten syscall overrides are disabled.

fd_read and poll suspend only when Module.Py_EmscriptenStackSwitching is set. The interpreter sets this flag when entering its promising main(); embedders can opt in when providing their own promising entry point.

Add CI smoke tests for static embedding and for an Emscripten callback completing while main() is suspended. The latter checks that main() resumes and its exit status is preserved.

Validation with Emscripten 6.0.9 and Node 26.8.1:

• Rebuilt the dynamic-linking interpreter; test_capi.test_emscripten, test_builtin, test_json, test_sys, and test_functools passed. test_select was skipped because socket support was unavailable.
• Static embedding and suspended-main smoke tests passed. Also checked the suspended-main test with -sMAIN_MODULE; it fails against the previous wrapper and passes with this change.
• Verified that --disable-emscripten-syscalls omits the constructor and syscall objects from the configuration.
• Regenerated configure with CPython's regeneration script.

• Issue: Emscripten: static (non-MAIN_MODULE) builds fail at startup on dynamic-linking-only JS helpers #156780

[clementperon]

@hoodmane 👀 maybe ?

[hoodmane]

Maybe let's start with a PR that adds the EM_JS_DEPS() everywhere? That seems like an easy improvement.

I think rather than using Module.Py_EmscriptenPromisingMain as a runtime flag, it would be more morally upstanding to move that logic into python.o or some other object file we only link into the interpreter program, that way embedders wouldn't get it at all. Maybe we can rename _emscripten_promising_main_js to _PyEmscripten_BeforeMain() or something and move the following to python.c or to its own object file next to it:

#ifdef __EMSCRIPTEN__
__attribute__((constructor)) void _PyEmscripten_Constructor(void) {
   _PyEmscripten_BeforeMain();
}

python.c is currently very short, so I'm not sure how people will feel about adding this there but we should find out.

And of course as traditional we need much less prose since Claude is as rambly as usual. Please rewrite all the comments and the commit message by hand. I find that helps cut them down to a more reasonable length.

Of course, it's likely that any of this will bit rot without test coverage.

cc @freakboy3742 WDYT?

[clementperon]

@hoodmane as you suggest move to a dedicated object file + reword commit + add a test

[freakboy3742]

Maybe let's start with a PR that adds the EM_JS_DEPS() everywhere? That seems like an easy improvement.

+1 to this as an approach to landing the changes.

I think rather than using Module.Py_EmscriptenPromisingMain as a runtime flag, it would be more morally upstanding to move that logic into python.o
...
python.c is currently very short, so I'm not sure how people will feel about adding this there but we should find out.

I agree that linking into the mainline is a preferable approach to a runtime flag.

As for where to put it - I can definitely see the argument for using python.c, but the fact that it is so minimal at present is at least a cause for a raised eyebrow. Is Modules/main.c perhaps a better candidate?

And of course as traditional we need much less prose since Claude is as rambly as usual. Please rewrite all the comments and the commit message by hand. I find that helps cut them down to a more reasonable length.

+1 to this as well. Claude's predilection for extraneous verbositude is usually contrary to the underlying goals of effective communication :-)

[clementperon]

@hoodmane EM_JS_DEPS has been merged thanks to @freakboy3742.

I will rework a bit this PR + clean commit message & comment.

[clementperon]

@hoodmane new version after discussion with AI

• No more Py_EMSCRIPTEN_DYNAMIC_LINKING or -sALLOW_TABLE_GROWTH. The wrapper rebinds _main and, when present, wasmImports.main, so a single code path covers both configurations. The trampoline now takes over a placeholder's table slot instead of calling addFunction(), so the table never grows. The previous static branch also wrapped wasmExports["main"], which does not exist (the export is __main_argc_argv); fixed.
• Cleaner exit. After main() completes the wrapper goes through exitJS() instead of Module.onExit directly, so atexit handlers run and trailing output is flushed.
• Module.Py_EmscriptenStackSwitching is set when main() is actually entered rather than in the constructor, has its own commit, and is documented in emscripten_syscalls.c for embedders.
• FS.createAsyncInputDevice() stays in libpython, so _testinternalcapi keeps working for any libpython consumer.
• Build fixes: emscripten_beforemain.o depends on the headers, is linked into _testembed, and is installed by libainstall.
• Embed test links libpython.a directly, is built by run_test.sh instead of every make, checks node's exit status, and is linked with -O2 -g0 (wasm went from 41 MB to 8 MB).

Tested with the CI configuration, a --disable-wasm-dynamic-linking interpreter, and the embed test. PR description updated.

[hoodmane]

The changes to Python/emscripten_trampoline.c look good to me, let's next split out those into a separate PR.

[clementperon]

Rebase on top of #157238

[clementperon]

@hoodmane can I have again your feedback on this PR please 🙏

Thanks

[clementperon]

@freakboy3742 what do you think of this PR ? Do you want me to update something ?

[clementperon]

@hoodmane thanks for your review, I hope i understand correctly what you wanted