Skip to content

Update Documentation for Emscripten Builds #1621

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

Update Documentation for Emscripten Builds #1621

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
150a271
update documentation for emscripten builds
adqm Aug 2, 2025
7a7c32a
remove emsdk version suggestion for cpython 3.13
adqm Aug 3, 2025
144a72f
add make-mpdec step to the broken-out build commands
adqm Aug 3, 2025
703a7a5
suggest python3 for Tools/wasm/emscripten commands
adqm Aug 3, 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
41 changes: 29 additions & 12 deletions getting-started/setup-building.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -493,13 +493,26 @@ 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 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):
Comment on lines +508 to +511
Copy link
Contributor

Choose a reason for hiding this comment

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

@hoodmane This was the historical guidance for ccache... is it still required now that the --config-cache option is part of the emscripten build script?


.. 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
Expand All @@ -508,8 +521,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
Copy link
Contributor

Choose a reason for hiding this comment

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

I can't comment on he code block below - but there's now one more build step - make-mpdec (same general structure as the make-libffi call).

As a longer term maintenance issue, this list of subcommands is likely to change over time; the dev guide should always have the instructions for the current state of main, but it might be worth flagging that some of the steps might not exist on older Python versions.

Copy link
Author

Choose a reason for hiding this comment

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

Ah, right. I missed that change. I'll update the code block to match the current steps.

That addition looks like it was backported to 3.14, so maybe not an urgent question, but I do agree that it's worth thinking through how best to label version-specific steps.

It would be great to have this generated automatically, but I'm not sure how best to do that (you could imagine adding a command to Tools/wasm/emscripten that outputs these steps rather than hard-coding them in the dev guide, but that doesn't feel particularly great). For now I'll just update the list of commands here.


Expand All @@ -524,11 +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 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::

Expand All @@ -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
Expand Down
Loading