gh-156780: Emscripten: add an embedding smoke test

Link libpython.a into a program whose main() is not Python's, without
-sMAIN_MODULE or the interpreter's link flags, and run a script that
imports from the stdlib, calls through the trampoline and polls.
Platforms/emscripten/web_embed_test/run_test.sh builds and runs it in CI.

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

Author: clementperon

.github/workflows/reusable-emscripten.yml

@@ -79,3 +79,5 @@ jobs:
       run: python3 Platforms/emscripten run --test
     - name: "Test Repl"
       run: Platforms/emscripten/browser_test/run_test.sh
+    - name: "Test embedding"
+      run: Platforms/emscripten/web_embed_test/run_test.sh

Makefile.pre.in

@@ -1122,6 +1122,20 @@ web_example/python.mjs web_example/python.wasm: $(BUILDPYTHON)
 	cp python.mjs web_example/python.mjs
 	cp python.wasm web_example/python.wasm
 
+WEB_EMBED_TEST_DIR=$(EMSCRIPTEN_DIR)/web_embed_test
+
+# Linked like an embedder would: against libpython.a, without $(LINKFORSHARED)
+# and so without -sMAIN_MODULE or the interpreter's -sEXPORTED_FUNCTIONS.
+web_embed_test/main.js: $(WEB_EMBED_TEST_DIR)/main.c $(LIBRARY) $(ZIP_STDLIB)
+	@mkdir -p web_embed_test
+	$(LINKCC) $(PY_STDMODULE_CFLAGS) $(PY_CORE_EXE_LDFLAGS) -O2 -g0 -o $@ \
+		$(WEB_EMBED_TEST_DIR)/main.c $(LIBRARY) $(LIBS) $(MODLIBS) $(SYSLIBS) \
+		-sALLOW_MEMORY_GROWTH -sSTACK_SIZE=5MB \
+		--preload-file $(ZIP_STDLIB)@/lib/stdlib.zip
+
+.PHONY: web_embed_test
+web_embed_test: web_embed_test/main.js
+
 .PHONY: web_example
 web_example: web_example/python.mjs web_example/python.worker.mjs web_example/index.html web_example/server.py web_example/$(ZIP_STDLIB)
 
@@ -3288,7 +3302,7 @@ clean-retain-profile: pycremoval
 	find build -name '*.py[co]' -exec rm -f {} ';' || true
 	-rm -f pybuilddir.txt
 	-rm -f _bootstrap_python
-	-rm -rf web_example python.mjs python.wasm python*.symbols python*.map
+	-rm -rf web_example web_embed_test python.mjs python.wasm python*.symbols python*.map
 	-rm -f Programs/_testembed Programs/_freeze_module
 	-rm -rf Python/deepfreeze
 	-rm -f Python/frozen_modules/*.h

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.

Platforms/emscripten/web_embed_test/main.c

@@ -0,0 +1,50 @@
+/* Smoke test for libpython linked into a program whose main() is not Python's. */
+
+#include <Python.h>
+#include <stdio.h>
+
+// Imports come from the preloaded zip, len() goes through the call trampoline
+// and poll() through the syscall overrides.
+static const char *SCRIPT =
+    "import json, select\n"
+    "select.poll().poll(0)\n"
+    "print(json.dumps({'embedded': len('ok')}))\n";
+
+int main(void)
+{
+    PyStatus status;
+    PyConfig config;
+
+    PyConfig_InitIsolatedConfig(&config);
+    config.write_bytecode = 0;
+    config.module_search_paths_set = 1;
+    status = PyWideStringList_Append(&config.module_search_paths,
+                                     L"/lib/stdlib.zip");
+    if (PyStatus_Exception(status)) {
+        goto exception;
+    }
+    status = PyConfig_SetBytesString(&config, &config.executable, "/embed");
+    if (PyStatus_Exception(status)) {
+        goto exception;
+    }
+    status = Py_InitializeFromConfig(&config);
+    if (PyStatus_Exception(status)) {
+        goto exception;
+    }
+    PyConfig_Clear(&config);
+
+    if (PyRun_SimpleString(SCRIPT) != 0) {
+        puts("web_embed_test: script failed");
+        return 1;
+    }
+    if (Py_FinalizeEx() < 0) {
+        puts("web_embed_test: Py_FinalizeEx failed");
+        return 1;
+    }
+    puts("web_embed_test: ok");
+    return 0;
+
+exception:
+    PyConfig_Clear(&config);
+    Py_ExitStatusException(status);
+}

Platforms/emscripten/web_embed_test/run_test.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Build and run the libpython embedding smoke test.
+set -euo pipefail
+cd "$(dirname "$0")/../../.."
+
+BUILD_DIR=${CROSS_BUILD_DIR:-cross-build}/wasm32-emscripten/build/python
+make -C "$BUILD_DIR" web_embed_test
+
+# Node 24 needs JSPI enabled explicitly; it is on by default afterwards.
+NODE=${NODE:-node}
+NODE_FLAGS=
+if [ "$("$NODE" -p 'process.versions.node.split(".")[0]')" = 24 ]; then
+    NODE_FLAGS=--experimental-wasm-jspi
+fi
+
+# Run from the build directory: Emscripten resolves main.data relative to cwd.
+cd "$BUILD_DIR/web_embed_test"
+rc=0
+out=$("$NODE" $NODE_FLAGS main.js 2>&1) || rc=$?
+echo "$out"
+[ "$rc" -eq 0 ] && grep -q "web_embed_test: ok" <<<"$out"