From 7bb29f6d3292d18a7dee9f7bdb329fb3374c4dc7 Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Thu, 20 Mar 2025 11:00:20 +0100 Subject: [PATCH 1/8] Add section on building for Emscripten Heavily copied from Brett's WASI guide. --- getting-started/setup-building.rst | 77 ++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 03b2777b8e..49ce33425c 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -458,6 +458,83 @@ 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 ` as well as: + +1. The Emscripten compiler +2. Node.js + +Building for Emscripten requires doing a cross-build where you have a *build* +Python to help produce a 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://wasi.dev +.. _WebAssembly: https://webassembly.org + + Android ------- From 186867ed29a18bb7e1716701f21eb35cc57cddd1 Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Thu, 20 Mar 2025 11:09:54 +0100 Subject: [PATCH 2/8] Add info on installing emcc --- getting-started/setup-building.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 49ce33425c..6443ccc97e 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -477,6 +477,16 @@ C compiler just like building for :ref:`Unix ` as well as: 1. The Emscripten compiler 2. Node.js +To install the Emscripten compiler we recommend: + +.. code-block:: sh + + # Install Emscripten + git clone emscripten/emsdk + ./emsdk/emsdk install 4.0.5 + ./emsdk/emsdk activate 4.0.5 + source ./emsdk/emsdk_env.sh + Building for Emscripten requires doing a cross-build where you have a *build* Python to help produce a Emscripten build of CPython. This means you build CPython twice: once to have a version of Python for the build system to use and From 6ebe80ccd5af852ec1fadcb139707d372cf77bd6 Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Thu, 20 Mar 2025 11:12:33 +0100 Subject: [PATCH 3/8] Adjust wording --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 6443ccc97e..5fefbc9377 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -477,7 +477,7 @@ C compiler just like building for :ref:`Unix ` as well as: 1. The Emscripten compiler 2. Node.js -To install the Emscripten compiler we recommend: +The simplest way to install the Emscripten compiler is as follows: .. code-block:: sh From 44e36fe2c7d1ab15b4cb04d3e3580e99818670ba Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Thu, 20 Mar 2025 11:23:02 +0100 Subject: [PATCH 4/8] Fix link --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 5fefbc9377..85bc049f77 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -541,7 +541,7 @@ used in ``python.sh``: $ make -C cross-build/wasm32-emscripten/build/python/ test -.. _Emscripten: https://wasi.dev +.. _Emscripten: https://emscripten.org/ .. _WebAssembly: https://webassembly.org From 553c85681ab4cee8d6a22d22f137ec8893b4d738 Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Sat, 22 Mar 2025 16:19:15 +0100 Subject: [PATCH 5/8] Apply hugovk's edits Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- getting-started/setup-building.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 85bc049f77..bdcf5db266 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -462,7 +462,7 @@ used in ``python.sh``: Emscripten ---------- -Emscripten_ is a complete open source compiler toolchain. It compiles C/C++ code +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. @@ -474,10 +474,10 @@ including browsers and Node.js. To build for Emscripten, you will need to cross-compile CPython. This requires a C compiler just like building for :ref:`Unix ` as well as: -1. The Emscripten compiler -2. Node.js +* The Emscripten compiler +* Node.js -The simplest way to install the Emscripten compiler is as follows: +The simplest way to install the Emscripten compiler is: .. code-block:: sh @@ -488,7 +488,7 @@ The simplest way to install the Emscripten compiler is as follows: source ./emsdk/emsdk_env.sh Building for Emscripten requires doing a cross-build where you have a *build* -Python to help produce a Emscripten build of CPython. This means you 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). @@ -499,7 +499,7 @@ version of Python you have installed on your machine): .. code-block:: shell - $ python3 Tools/wasm/emscripten build --quiet -- --config-cache --with-pydebug + 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 @@ -510,19 +510,19 @@ 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 + 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. +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 @@ -530,7 +530,7 @@ can use to run the ``python.mjs`` file: .. code-block:: shell - $ cross-build/wasm32-emscripten/build/python/python.sh --version + 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 @@ -538,7 +538,7 @@ used in ``python.sh``: .. code-block:: shell - $ make -C cross-build/wasm32-emscripten/build/python/ test + make -C cross-build/wasm32-emscripten/build/python/ test .. _Emscripten: https://emscripten.org/ From 68bdf8de62f1221b409784bcb9010e615a6e3ca2 Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Mon, 24 Mar 2025 10:17:13 +0100 Subject: [PATCH 6/8] Fix clone step Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index bdcf5db266..5eb8347b55 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -482,7 +482,7 @@ The simplest way to install the Emscripten compiler is: .. code-block:: sh # Install Emscripten - git clone emscripten/emsdk + 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 From a15600f614fffe2a72863813c790f1bad03f0330 Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Wed, 26 Mar 2025 12:22:54 +0100 Subject: [PATCH 7/8] Add note on Emscripten version --- getting-started/setup-building.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 5eb8347b55..50527d17bd 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -487,6 +487,10 @@ The simplest way to install the Emscripten compiler is: ./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 From 490bfa4a87785ede36114c2a20fd991e5d946d9b Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Wed, 26 Mar 2025 12:24:21 +0100 Subject: [PATCH 8/8] Double backticks --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 50527d17bd..73754aa34b 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -489,7 +489,7 @@ The simplest way to install the Emscripten compiler is: 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`. +``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