Skip to content

gh-137025: Update Emscripten Build Docs #137312

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

gh-137025: Update Emscripten Build Docs #137312

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bed7f8a
news blurb for removal of wasm_build.py
adqm Aug 1, 2025
05c12ce
reference dev guide for building emscripten
adqm Aug 1, 2025
5f31272
small wording changes
adqm Aug 1, 2025
243fe71
remove unnecessary paragraph about build tools
adqm Aug 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions Misc/NEWS.d/next/Tools-Demos/2025-08-01-13-27-43.gh-issue-137025.ubuhQC.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
The ``wasm_build.py`` script has been removed. ``Tools/wasm/emscripten``
and ``Tools/wasm/wasi`` should be used instead, as described in the `Dev
Guide <https://devguide.python.org/contrib/workflows/compile/>`__.
66 changes: 6 additions & 60 deletions Tools/wasm/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,68 +9,14 @@ compilation of CPython to WebAssembly (WASM). Python supports Emscripten
run in modern browsers and JavaScript runtimes like *Node.js*. WASI builds
use WASM runtimes such as *wasmtime*.

Users and developers are encouraged to use the script
`Tools/wasm/wasm_build.py`. The tool automates the build process and provides
assistance with installation of SDKs, running tests, etc.
**NOTE**: If you are looking for general information about WebAssembly that is
not directly related to CPython, please see https://github.com/psf/webassembly.

**NOTE**: If you are looking for information that is not directly related to
building CPython for WebAssembly (or the resulting build), please see
https://github.com/psf/webassembly for more information.

## wasm32-emscripten
## Emscripten (wasm32-emscripten)

### Build

To cross compile to the ``wasm32-emscripten`` platform you need
[the Emscripten compiler toolchain](https://emscripten.org/),
a Python interpreter, and an installation of Node version 18 or newer.
Emscripten version 4.0.2 is recommended; newer versions may also work, but all
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The devguide currently states:

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.

Therefore this should be either kept or moved.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed - and it should also reflect 4.0.11 as the version as the Emscripten version being used for Python 3.14 compatibility.

official testing is performed with that version. All commands below are relative
to a checkout of the Python repository.

#### Install [the Emscripten compiler toolchain](https://emscripten.org/docs/getting_started/downloads.html)

You can install the Emscripten toolchain as follows:
```shell
git clone https://github.com/emscripten-core/emsdk.git --depth 1
./emsdk/emsdk install latest
./emsdk/emsdk activate latest
```
To add the Emscripten compiler to your path:
```shell
source ./emsdk/emsdk_env.sh
```
This adds `emcc` and `emconfigure` to your path.

##### Optionally: enable ccache for EMSDK

The ``EM_COMPILER_WRAPPER`` must be set after the EMSDK environment is
sourced. Otherwise the source script removes the environment variable.

```shell
export EM_COMPILER_WRAPPER=ccache
```

#### Compile and build Python interpreter

You can use `python Tools/wasm/emscripten` to compile and build targeting
Emscripten. You can do everything at once with:
```shell
python Tools/wasm/emscripten build
```
or you can break it out into four separate steps:
```shell
python Tools/wasm/emscripten configure-build-python
python Tools/wasm/emscripten make-build-python
python Tools/wasm/emscripten make-libffi
python Tools/wasm/emscripten configure-host
python Tools/wasm/emscripten make-host
```
Extra arguments to the configure steps are passed along to configure. For
instance, to do a debug build, you can use:
```shell
python Tools/wasm/emscripten build --with-py-debug
```
See [the devguide instructions for building for Emscripten](https://devguide.python.org/getting-started/setup-building/#emscripten).

### Running from node

Expand All @@ -97,8 +43,8 @@ You can run the browser smoke test with:

### The Web Example

When building for Emscripten, the web example will be built automatically. It
is in the ``web_example`` directory. To run the web example, ``cd`` into the
When building for Emscripten, a small web example will be built automatically
in the ``web_example`` directory. To run the web example, ``cd`` into the
``web_example`` directory, then run ``python server.py``. This will start a web
server; you can then visit ``http://localhost:8000/`` in a browser to see a
simple REPL example.
Expand Down
Loading