From 07b10cc3397e9aa280800a80df7c99cf8c999977 Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Wed, 22 Apr 2026 16:28:16 -0700 Subject: [PATCH 1/6] Minor improvements to the Emscripten instructions --- getting-started/setup-building.rst | 51 ++++++++++++++++++------------ 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 6acc7ee57..38db75acf 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -522,34 +522,44 @@ The simplest way to build Emscripten is to run: .. code-block:: sh - python3 Platforms/emscripten build all --emsdk-cache=./cross-build/emsdk + export EMSDK_CACHE=$PWD/cross-build/emsdk + python3 Platforms/emscripten install-emscripten + python3 Platforms/emscripten build all -This will: +`install-emscripten` downloads and installs the version of the Emscripten SDK +required, placing it in the `EMSDK_CACHE` directory. +`build all` will: 1. Build a copy of Python that can run on the host machine (the "build" python); -2. Download a copy of the Emscripten SDK matching the version required by the - version of Python being compiled; -3. Ensure that a required version of Node is installed; -4. Download the code for all the binary dependencies of Python (such as - ``libFFI`` and ``xz``), and compile them for Emscripten; and -5. Build a copy of Python that can run on Emscripten (the "host" python). - -If you omit the ``--emsdk-cache`` environment variable, the build script will +2. Ensure that a required version of Node is installed; +3. Download the code for all the binary dependencies of Python (such as + ``libffi`` and ``mpdecimal``), and compile them for Emscripten; and +4. Build a copy of Python that can run on Emscripten (the "host" python). + +The built binary dependencies are cached inside the Emscripten cache directory. +Once built for a given Emscripten version, they will not be rebuilt on +subsequent runs unless there is a change in the version or build script for the +dependency. + +If you omit the ``EMSDK_CACHE`` environment variable, the build script will assume that the current environment has the Emscripten tools available. You are responsible for downloading and activating those tools in your environment. The version of Emscripten and Node that is required to build Python is defined in the :cpy-file:`Platforms/emscripten/config.toml` configuration file. -There are three environment variables that can be used to control the operation of +There are two environment variables that can be used to control the operation of the ``Platforms/emscripten`` build script: -* ``EMSDK_CACHE`` controls the location of the emscripten SDK. You can use this instead - environment variable instead of passing the ``--emsdk-cache`` flag. -* ``CACHE_DIR`` defines the location where downloaded artefacts, such - as precompiled ``libFFI`` and ``xz`` binaries, will be stored. -* ``CROSS_BUILD_DIR`` defines the name of the ``cross-build`` directory - that will be used for builds. This can be useful if you need to maintain - builds of multiple versions of Python. +* ``EMSDK_CACHE`` (or the ``--emsdk-cache`` flag) controls the location of the + Emscripten SDK cache directory. You can use this environment variable instead + of passing the ``--emsdk-cache`` flag. When set, the build script will + validate that the required Emscripten version is present in the cache and will + exit with an error if it is not; run ``install-emscripten`` to populate the + cache. +* ``CROSS_BUILD_DIR`` (or the ``--cross-build-dir`` flag) defines the location + of the ``cross-build`` directory that will be used for builds. This can be + useful if you need to maintain builds of multiple versions of Python + side by side. It is possible (but not necessary) to enable ``ccache`` for Emscripten builds by setting the ``EM_COMPILER_WRAPPER`` environment, but this step will only @@ -571,8 +581,9 @@ Emscripten build in ``cross-build/build`` and ``cross-build/wasm32-emscripten/build/python/``, respectively. The ``Platforms/emscripten`` script has a number of other entry points that allow for -fine-grained execution of each part of an iOS build; run ``python3 -Platforms/emscripten --help`` for more details. +fine-grained execution of each part of an Emscripten build; run +``python3 Platforms/emscripten --help`` for more details. + Once the build is complete, you can run Python code using: From 3118b20fe2b75c9ecb74b0399c8a004975900bdd Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Wed, 22 Apr 2026 16:49:07 -0700 Subject: [PATCH 2/6] Remove incorrect statement about ccache --- getting-started/setup-building.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 38db75acf..07132e85a 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -562,9 +562,7 @@ the ``Platforms/emscripten`` build script: side by side. 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): +by setting the ``EM_COMPILER_WRAPPER`` environment variable: .. code-block:: sh From 8138eed9687b78e9108ae3284ebe727dbf4f3e0c Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Wed, 22 Apr 2026 16:57:09 -0700 Subject: [PATCH 3/6] Add note about nvm --- getting-started/setup-building.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 07132e85a..98ba8ec81 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -531,7 +531,7 @@ required, placing it in the `EMSDK_CACHE` directory. `build all` will: 1. Build a copy of Python that can run on the host machine (the "build" python); -2. Ensure that a required version of Node is installed; +2. Use nvm_ to ensure that the needed version of Node is installed; 3. Download the code for all the binary dependencies of Python (such as ``libffi`` and ``mpdecimal``), and compile them for Emscripten; and 4. Build a copy of Python that can run on Emscripten (the "host" python). @@ -541,6 +541,8 @@ Once built for a given Emscripten version, they will not be rebuilt on subsequent runs unless there is a change in the version or build script for the dependency. +It is assumed that nvm is installed in `${HOME}/.nvm`. + If you omit the ``EMSDK_CACHE`` environment variable, the build script will assume that the current environment has the Emscripten tools available. You are responsible for downloading and activating those tools in your environment. The @@ -601,6 +603,7 @@ through web browsers) are available in the CPython repository at .. _Emscripten: https://emscripten.org/ .. _WebAssembly: https://webassembly.org +.. _nvm: https://github.com/nvm-sh/nvm#intro Android ------- From 48e1eb2a24a1bb26842bf364cdf2943d16e37f0a Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Wed, 22 Apr 2026 16:57:56 -0700 Subject: [PATCH 4/6] link to nvm --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 98ba8ec81..a46083b59 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -541,7 +541,7 @@ Once built for a given Emscripten version, they will not be rebuilt on subsequent runs unless there is a change in the version or build script for the dependency. -It is assumed that nvm is installed in `${HOME}/.nvm`. +It is assumed that nvm_ is installed in `${HOME}/.nvm`. If you omit the ``EMSDK_CACHE`` environment variable, the build script will assume that the current environment has the Emscripten tools available. You are From f5faa0223cef43148aca2d172be02bd2c71a3a8b Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Wed, 22 Apr 2026 17:04:02 -0700 Subject: [PATCH 5/6] Document `--host-runner` argument as alternative to nvm --- getting-started/setup-building.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index a46083b59..48556a44b 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -541,7 +541,10 @@ Once built for a given Emscripten version, they will not be rebuilt on subsequent runs unless there is a change in the version or build script for the dependency. -It is assumed that nvm_ is installed in `${HOME}/.nvm`. +It is assumed that nvm_ is installed in ``${HOME}/.nvm``. If you don't have nvm +installed or don't want to use it, you can pass ``--host-runner node`` to the +``build`` command. The argument should either be the name of an executable that +can be found on the ``PATH`` or a relative or absolute path to an executable. If you omit the ``EMSDK_CACHE`` environment variable, the build script will assume that the current environment has the Emscripten tools available. You are From a8df476168148401af26145e7cf10c1e754ad43b Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Wed, 22 Apr 2026 17:05:38 -0700 Subject: [PATCH 6/6] lint --- getting-started/setup-building.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 48556a44b..f1a309f58 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -526,9 +526,9 @@ The simplest way to build Emscripten is to run: python3 Platforms/emscripten install-emscripten python3 Platforms/emscripten build all -`install-emscripten` downloads and installs the version of the Emscripten SDK -required, placing it in the `EMSDK_CACHE` directory. -`build all` will: +``install-emscripten`` downloads and installs the version of the Emscripten SDK +required, placing it in the ``EMSDK_CACHE`` directory. +``build all`` will: 1. Build a copy of Python that can run on the host machine (the "build" python); 2. Use nvm_ to ensure that the needed version of Node is installed;