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

Merged
merged 7 commits into from
Sep 17, 2025
Merged

Update Documentation for Emscripten Builds #1621

Changes from 1 commit
Commits
Show all changes
7 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
9fee316
bump EMSDK version for v3.14
adqm Aug 13, 2025
6da06b4
Update getting-started/setup-building.rst
AA-Turner Sep 17, 2025
c59906e
Update getting-started/setup-building.rst
AA-Turner Sep 17, 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
31 changes: 24 additions & 7 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,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``.
Copy link
Contributor

Choose a reason for hiding this comment

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

I know this isn't correct... but I don't know what is correct. I'm fairly certian it's 3.something...

However, it might be better to leave this line off entirely. Emscripten isn't Tier 3 for 3.13. Having specific build instructions implies (to me) that it should work, and that definitely won't be the case.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That sounds good to me; sorry for the error! Makes sense only to include it for 3.14+.

* 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
Expand All @@ -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:
Copy link
Contributor

Choose a reason for hiding this comment

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

I've been running it with 3.12 but it's harmless to say 3.13 here.


.. code-block:: shell

Expand Down Expand Up @@ -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