Add section on building for Emscripten

getting-started/setup-building.rst

@@ -458,6 +458,97 @@ used in ``python.sh``:
 .. _wasmtime: https://wasmtime.dev
 .. _WebAssembly: https://webassembly.org
 
+
+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
+
+    # Install Emscripten
+    git clone https://github.com/emscripten-core/emsdk
+    ./emsdk/emsdk install 4.0.5
+    ./emsdk/emsdk activate 4.0.5
+    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``.
+
+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
+
+   python3 Tools/wasm/emscripten build --quiet -- --config-cache --with-pydebug
+
+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
+
+   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
+
+.. 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
+
+   cross-build/wasm32-emscripten/build/python/python.sh --version
+
+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
+
+   make -C cross-build/wasm32-emscripten/build/python/ test
+
+
+.. _Emscripten: https://emscripten.org/
+.. _WebAssembly: https://webassembly.org
+
+
 Android
 -------