Emscripten

Emscripten_ is a complete open-source compiler toolchain. It compiles C/C++ code

into WebAssembly_/JavaScript executables, for use in JavaScript runtimes,

including browsers and Node.js.

.. note::

The instructions below assume a Unix-based OS due to cross-compilation for

CPython being designed for ``./configure`` / ``make``.

To build for Emscripten, you will need to cross-compile CPython. This requires a

C compiler just like building for :ref:`Unix <unix-compiling>` as well as:

* The Emscripten compiler

* Node.js

The simplest way to install the Emscripten compiler is:

.. code-block:: 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``.

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

CPython twice: once to have a version of Python for the build system to use and

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):

.. code-block:: shell

That single command will configure and build both the build Python and the

Emscripten build in ``cross-build/build`` and

``cross-build/wasm32-emscripten/build/python/``, respectively.

You can also do each configuration and build step separately; the command above

is a convenience wrapper around the following commands:

.. code-block:: shell

.. note::

The ``configure-host`` command infers the use of ``--with-pydebug`` from the

build Python.

Running the separate commands after ``emscripten build`` is useful if you, for

example, only want to run the ``make-host`` step after making code changes.

Once everything is complete, there will be a

``cross-build/wasm32-emscripten/build/python/python.sh`` helper file which you

can use to run the ``python.mjs`` file:

.. code-block:: shell

You can also use ``Makefile`` targets and they will work as expected thanks to

the ``HOSTRUNNER`` environment variable having been set to a similar value as

used in ``python.sh``:

.. code-block:: shell

.. _Emscripten: https://emscripten.org/

.. _WebAssembly: https://webassembly.org