From 150a271e33d992c8bcfb6fa577b2b9b48b2cfe59 Mon Sep 17 00:00:00 2001 From: adam j hartz Date: Sat, 2 Aug 2025 18:09:29 -0400 Subject: [PATCH 1/4] update documentation for emscripten builds * update emsdk version information * link to `Tools/wasm/README.md` for usage instructions beyond what's shown here * add note about ccache * add note about minimum Python version for `Tools/wasm/emscripten build` --- getting-started/setup-building.rst | 31 +++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index bd026ea71..3ad386d37 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -493,13 +493,27 @@ The simplest way to install the Emscripten compiler is: # Install Emscripten git clone https://github.com/emscripten-core/emsdk - ./emsdk/emsdk install 4.0.5 - ./emsdk/emsdk activate 4.0.5 + ./emsdk/emsdk install 4.0.11 + ./emsdk/emsdk activate 4.0.11 source ./emsdk/emsdk_env.sh -Updating the Emscripten compiler version often causes breakages. For the best -compatibility, use the Emscripten version suggested in the cpython repository in -``Tools/wasm/README.md``. +Updating the Emscripten compiler version can cause breakages. For the best +compatibility, use the appropriate Emscripten version based on the version of +CPython you're building: + +* For building CPython 3.14, use ``emsdk`` version ``4.0.11``. +* For building CPython 3.13, use ``emsdk`` version ``4.0.5``. +* For building the main branch of the CPython repository, you may wish to use + ``latest`` instead of a specific version. + +It is possible (but not necessary) to enable ``ccache`` for Emscripten builds +by setting the ``EM_COMPILER_WRAPPER`` environment, but this step will only +take effect if it is done **after** ``emsdk_env.sh`` is sourced (otherwise, the +sourced script removes the environment variable): + +.. code-block:: sh + + export EM_COMPILER_WRAPPER=ccache Building for Emscripten requires doing a cross-build where you have a *build* Python to help produce an Emscripten build of CPython. This means you build @@ -508,8 +522,8 @@ another that's the build you ultimately care about (that is, the build Python is not meant for use by you directly, only the build system). The easiest way to get a debug build of CPython for Emscripten is to use the -``Tools/wasm/emscripten build`` command (which should be run with a recent -version of Python you have installed on your machine): +``Tools/wasm/emscripten build`` command, which should be run with a recent +version of Python (3.13 or newer) already installed on your machine: .. code-block:: shell @@ -554,6 +568,9 @@ used in ``python.sh``: make -C cross-build/wasm32-emscripten/build/python/ test +Additional instructions for running the resulting builds (through Node.js and/or +through web browsers) are available in the CPython repository at +:cpy-file:`Tools/wasm/README.md`. .. _Emscripten: https://emscripten.org/ .. _WebAssembly: https://webassembly.org From 7a7c32aa379bf5335bcf97705dc6ec89a225f54f Mon Sep 17 00:00:00 2001 From: adam j hartz Date: Sat, 2 Aug 2025 20:00:28 -0400 Subject: [PATCH 2/4] remove emsdk version suggestion for cpython 3.13 --- getting-started/setup-building.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 3ad386d37..5e421a0ac 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -502,7 +502,6 @@ compatibility, use the appropriate Emscripten version based on the version of CPython you're building: * For building CPython 3.14, use ``emsdk`` version ``4.0.11``. -* For building CPython 3.13, use ``emsdk`` version ``4.0.5``. * For building the main branch of the CPython repository, you may wish to use ``latest`` instead of a specific version. From 144a72fee4a0b3a56165c5c4d126e9fafcbe3cff Mon Sep 17 00:00:00 2001 From: adam j hartz Date: Sat, 2 Aug 2025 20:05:08 -0400 Subject: [PATCH 3/4] add make-mpdec step to the broken-out build commands --- getting-started/setup-building.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 5e421a0ac..d0907fadb 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -540,6 +540,7 @@ is a convenience wrapper around the following commands: python Tools/wasm/emscripten configure-build-python --quiet -- --config-cache --with-pydebug python Tools/wasm/emscripten make-build-python --quiet python Tools/wasm/emscripten make-libffi --quiet + python Tools/wasm/emscripten make-mpdec --quiet python Tools/wasm/emscripten configure-host --quiet -- --config-cache python Tools/wasm/emscripten make-host --quiet From 703a7a589e42405f3875d0f5a82a22522b850335 Mon Sep 17 00:00:00 2001 From: adam j hartz Date: Sat, 2 Aug 2025 20:13:54 -0400 Subject: [PATCH 4/4] suggest python3 for Tools/wasm/emscripten commands --- getting-started/setup-building.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index d0907fadb..c4e9579d3 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -537,12 +537,12 @@ is a convenience wrapper around the following commands: .. code-block:: shell - python Tools/wasm/emscripten configure-build-python --quiet -- --config-cache --with-pydebug - python Tools/wasm/emscripten make-build-python --quiet - python Tools/wasm/emscripten make-libffi --quiet - python Tools/wasm/emscripten make-mpdec --quiet - python Tools/wasm/emscripten configure-host --quiet -- --config-cache - python Tools/wasm/emscripten make-host --quiet + python3 Tools/wasm/emscripten configure-build-python --quiet -- --config-cache --with-pydebug + python3 Tools/wasm/emscripten make-build-python --quiet + python3 Tools/wasm/emscripten make-libffi --quiet + python3 Tools/wasm/emscripten make-mpdec --quiet + python3 Tools/wasm/emscripten configure-host --quiet -- --config-cache + python3 Tools/wasm/emscripten make-host --quiet .. note::