From fa156f26fd714d459b3cb1579b68c949d9628dc9 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 3 Mar 2026 10:04:40 -0800 Subject: [PATCH 01/10] Update WASI build instructions --- getting-started/setup-building.rst | 77 ++++++++++++++++++++++++++---- 1 file changed, 67 insertions(+), 10 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index d86800f67..0e0bf3c95 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -377,14 +377,15 @@ host/runtime as a *guest*. .. note:: - The instructions below assume a Unix-based OS due to cross-compilation for - CPython being designed for ``./configure`` / ``make``. + The instructions below assume a Unix-based OS (including macOS) due to + cross-compilation for CPython being designed for ``./configure`` / ``make``. To build for WASI, you will need to cross-compile CPython. This requires a C compiler just like building for :ref:`Unix ` as well as: 1. A C compiler that can target WebAssembly (for example, `WASI SDK`_) 2. A WASI host/runtime (for example, Wasmtime_) +3. Python 3.11 or newer to run the build script (``tomllib`` is required) All of this is provided in the WASI :ref:`dev container ` (which you can select as an alternative container when using a @@ -399,6 +400,49 @@ known to work. and their versions specified in the container and build scripts are tested via a :ref:`buildbot `. +Installing prerequisites (Linux) +''''''''''''''''''''''''''''''''' + +Install Wasmtime via the `official installer `__ or your +system package manager. Download the `WASI SDK`_ release archive for your +platform, extract it, and set the ``WASI_SDK_PATH`` environment variable: + +.. code-block:: shell + + export WASI_SDK_PATH=/path/to/wasi-sdk + +Installing prerequisites (macOS) +''''''''''''''''''''''''''''''''' + +Install Wasmtime via Homebrew: + +.. code-block:: shell + + brew install wasmtime + +Download the `WASI SDK`_ release archive for macOS (``arm64-macos`` for Apple +Silicon, ``x86_64-macos`` for Intel). Before extracting, remove the macOS +quarantine attribute to prevent Gatekeeper from blocking the compiler binaries: + +.. code-block:: shell + + xattr -d com.apple.quarantine wasi-sdk-*.tar.gz + sudo tar -xzf wasi-sdk-*.tar.gz -C /opt + sudo mv /opt/wasi-sdk-*-macos /opt/wasi-sdk + +Then add to your shell profile (e.g. ``~/.zshrc``): + +.. code-block:: shell + + export WASI_SDK_PATH=/opt/wasi-sdk + +.. note:: + + macOS ships with Python 3.9, which is too old to run the build script. + Use a newer Python via Homebrew (``brew install python``) or + `uv `__ + (``uv run --python 3.13 -- python3 Platforms/WASI build ...``). + Building for WASI requires doing a cross-build where you have a *build* Python to help produce a WASI build of CPython (technically it's a "host x host" cross-build because the build Python is also the target Python while the host @@ -407,11 +451,16 @@ 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 WASI is to use the -``Tools/wasm/wasi.py build`` command (which should be run w/ a recent version of -Python you have installed on your machine): +The easiest way to get a debug build of CPython for WASI is to run the +following command with Python 3.11 or newer: -.. tab:: Python 3.14+ +.. tab:: Python 3.15+ + + .. code-block:: shell + + python3 Platforms/WASI build --quiet -- --config-cache --with-pydebug + +.. tab:: Python 3.14 .. code-block:: shell @@ -424,14 +473,22 @@ Python you have installed on your machine): python3 Tools/wasm/wasi.py build --quiet -- --config-cache --with-pydebug That single command will configure and build both the build Python and the -WASI build in ``cross-build/build`` and ``cross-build/wasm32-wasi``, +WASI build in ``cross-build/`` and ``cross-build/wasm32-wasip1``, respectively. You can also do each configuration and build step separately; the command above is a convenience wrapper around the following commands: +.. tab:: Python 3.15+ + + .. code-block:: shell + + $ python3 Platforms/WASI configure-build-python --quiet -- --config-cache --with-pydebug + $ python3 Platforms/WASI make-build-python --quiet + $ python3 Platforms/WASI configure-host --quiet -- --config-cache + $ python3 Platforms/WASI make-host --quiet -.. tab:: Python 3.14+ +.. tab:: Python 3.14 .. code-block:: shell @@ -454,8 +511,8 @@ is a convenience wrapper around the following commands: The ``configure-host`` command infers the use of ``--with-pydebug`` from the build Python. -Running the separate commands after ``wasi build`` is useful if you, for example, -only want to run the ``make-host`` step after making code changes. +Running the separate commands after the ``build`` subcommand 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-wasip1/python.sh`` helper file which you can use to run the From 119254d5220f48a95b4ec234169ac935cd53b8f1 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 3 Mar 2026 10:05:27 -0800 Subject: [PATCH 02/10] Simplify --- 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 0e0bf3c95..8415e1f8b 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -377,7 +377,7 @@ host/runtime as a *guest*. .. note:: - The instructions below assume a Unix-based OS (including macOS) due to + The instructions below assume a Unix-based OS due to cross-compilation for CPython being designed for ``./configure`` / ``make``. To build for WASI, you will need to cross-compile CPython. This requires a C From 30b160da834e2a03319226cd6d7f003da69b4809 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 3 Mar 2026 10:06:13 -0800 Subject: [PATCH 03/10] Fix linebreak --- getting-started/setup-building.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 8415e1f8b..674fc9d05 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -377,8 +377,8 @@ host/runtime as a *guest*. .. note:: - The instructions below assume a Unix-based OS due to - cross-compilation for CPython being designed for ``./configure`` / ``make``. + The instructions below assume a Unix-based OS due to cross-compilation for + CPython being designed for ``./configure`` / ``make``. To build for WASI, you will need to cross-compile CPython. This requires a C compiler just like building for :ref:`Unix ` as well as: From 355e7eac2dad71144ff7d6740b3777148192bfcc Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 3 Mar 2026 10:07:02 -0800 Subject: [PATCH 04/10] Remove space --- 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 674fc9d05..2110a921f 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -377,7 +377,7 @@ host/runtime as a *guest*. .. note:: - The instructions below assume a Unix-based OS due to cross-compilation for + The instructions below assume a Unix-based OS due to cross-compilation for CPython being designed for ``./configure`` / ``make``. To build for WASI, you will need to cross-compile CPython. This requires a C From 17629a3c4fa2a3da17ca44202798ba06ee377d93 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 3 Mar 2026 10:42:19 -0800 Subject: [PATCH 05/10] Clean up --- getting-started/setup-building.rst | 45 +----------------------------- 1 file changed, 1 insertion(+), 44 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 2110a921f..ebb72e976 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -385,7 +385,7 @@ compiler just like building for :ref:`Unix ` as well as: 1. A C compiler that can target WebAssembly (for example, `WASI SDK`_) 2. A WASI host/runtime (for example, Wasmtime_) -3. Python 3.11 or newer to run the build script (``tomllib`` is required) +3. A system install of Python 3.11 or newer to run the build scripts All of this is provided in the WASI :ref:`dev container ` (which you can select as an alternative container when using a @@ -400,49 +400,6 @@ known to work. and their versions specified in the container and build scripts are tested via a :ref:`buildbot `. -Installing prerequisites (Linux) -''''''''''''''''''''''''''''''''' - -Install Wasmtime via the `official installer `__ or your -system package manager. Download the `WASI SDK`_ release archive for your -platform, extract it, and set the ``WASI_SDK_PATH`` environment variable: - -.. code-block:: shell - - export WASI_SDK_PATH=/path/to/wasi-sdk - -Installing prerequisites (macOS) -''''''''''''''''''''''''''''''''' - -Install Wasmtime via Homebrew: - -.. code-block:: shell - - brew install wasmtime - -Download the `WASI SDK`_ release archive for macOS (``arm64-macos`` for Apple -Silicon, ``x86_64-macos`` for Intel). Before extracting, remove the macOS -quarantine attribute to prevent Gatekeeper from blocking the compiler binaries: - -.. code-block:: shell - - xattr -d com.apple.quarantine wasi-sdk-*.tar.gz - sudo tar -xzf wasi-sdk-*.tar.gz -C /opt - sudo mv /opt/wasi-sdk-*-macos /opt/wasi-sdk - -Then add to your shell profile (e.g. ``~/.zshrc``): - -.. code-block:: shell - - export WASI_SDK_PATH=/opt/wasi-sdk - -.. note:: - - macOS ships with Python 3.9, which is too old to run the build script. - Use a newer Python via Homebrew (``brew install python``) or - `uv `__ - (``uv run --python 3.13 -- python3 Platforms/WASI build ...``). - Building for WASI requires doing a cross-build where you have a *build* Python to help produce a WASI build of CPython (technically it's a "host x host" cross-build because the build Python is also the target Python while the host From d26d4e155f06df1600179bc5cca2ed6be8bc5acc Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 3 Mar 2026 10:48:01 -0800 Subject: [PATCH 06/10] Update for clarity --- getting-started/setup-building.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index ebb72e976..658999687 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -468,8 +468,8 @@ is a convenience wrapper around the following commands: The ``configure-host`` command infers the use of ``--with-pydebug`` from the build Python. -Running the separate commands after the ``build`` subcommand is useful if you, -for example, only want to run the ``make-host`` step after making code changes. +Running the separate commands after ``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-wasip1/python.sh`` helper file which you can use to run the From c3427f197b98c00afeb10b654882ccd5d86ed2a2 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 3 Mar 2026 10:52:01 -0800 Subject: [PATCH 07/10] Fix line break again --- getting-started/setup-building.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 658999687..0bae46dda 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -468,8 +468,8 @@ is a convenience wrapper around the following commands: The ``configure-host`` command infers the use of ``--with-pydebug`` from the build Python. -Running the separate commands after ``build`` is useful if you, for example, only want to run -the ``make-host`` step after making code changes. +Running the separate commands after ``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-wasip1/python.sh`` helper file which you can use to run the From d9eeb32d7315a306e888f6049a3b36a4dc835719 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 3 Mar 2026 19:00:11 +0000 Subject: [PATCH 08/10] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- include/release-cycle-all.svg | 2 +- include/release-cycle.svg | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/include/release-cycle-all.svg b/include/release-cycle-all.svg index 3091b04ec..2918fd2e0 100644 --- a/include/release-cycle-all.svg +++ b/include/release-cycle-all.svg @@ -1402,4 +1402,4 @@ y2="513.0" font-size="18" /> - \ No newline at end of file + diff --git a/include/release-cycle.svg b/include/release-cycle.svg index 2ccd93c0d..26d2c5189 100644 --- a/include/release-cycle.svg +++ b/include/release-cycle.svg @@ -890,4 +890,4 @@ y2="351.0" font-size="18" /> - \ No newline at end of file + From 07a9e65aff9ae9ecd115692933700ad2771032ce Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Tue, 3 Mar 2026 11:06:33 -0800 Subject: [PATCH 09/10] Remove svgs? --- include/release-cycle-all.svg | 1405 --------------------------------- include/release-cycle.svg | 893 --------------------- 2 files changed, 2298 deletions(-) delete mode 100644 include/release-cycle-all.svg delete mode 100644 include/release-cycle.svg diff --git a/include/release-cycle-all.svg b/include/release-cycle-all.svg deleted file mode 100644 index 2918fd2e0..000000000 --- a/include/release-cycle-all.svg +++ /dev/null @@ -1,1405 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - '08 - - - - '09 - - - - '10 - - - - '11 - - - - '12 - - - - '13 - - - - '14 - - - - '15 - - - - '16 - - - - '17 - - - - '18 - - - - '19 - - - - '20 - - - - '21 - - - - '22 - - - - '23 - - - - '24 - - - - '25 - - - - '26 - - - - '27 - - - - '28 - - - - '29 - - - - '30 - - - - '31 - - - - - - - - - - - - - - - - - - - - - end-of-life - - - - - Python 2.6 - - - - - - - - - - - - - end-of-life - - - - - Python 2.7 - - - - - - - - - - - - - end-of-life - - - - - Python 3.0 - - - - - - - - - - - - - end-of-life - - - - - Python 3.1 - - - - - - - - - - - - - end-of-life - - - - - Python 3.2 - - - - - - - - - - - - - end-of-life - - - - - Python 3.3 - - - - - - - - - - - - - end-of-life - - - - - Python 3.4 - - - - - - - - - - - - - end-of-life - - - - - Python 3.5 - - - - - - - - - - - - - end-of-life - - - - - Python 3.6 - - - - - - - - - - - - - end-of-life - - - - - Python 3.7 - - - - - - - - - - - - - end-of-life - - - - - Python 3.8 - - - - - - - - - - - - - end-of-life - - - - - Python 3.9 - - - - - - - - - - - - - - - - security - - - - - Python 3.10 - - - - - - - - - - - - - - - - security - - - - - Python 3.11 - - - - - - - - - - - - - - - - security - - - - - Python 3.12 - - - - - - - - - - - - - - - - bugfix - - - - - Python 3.13 - - - - - - - - - - - - - - - - bugfix - - - - - Python 3.14 - - - - - - - - - - - - - - - - feature - - - - - Python 3.15 - - - - - diff --git a/include/release-cycle.svg b/include/release-cycle.svg deleted file mode 100644 index 26d2c5189..000000000 --- a/include/release-cycle.svg +++ /dev/null @@ -1,893 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - '19 - - - - '20 - - - - '21 - - - - '22 - - - - '23 - - - - '24 - - - - '25 - - - - '26 - - - - '27 - - - - '28 - - - - '29 - - - - '30 - - - - '31 - - - - - - - - - - - - - - - - - - - - - end-of-life - - - - - Python 2.7 - - - - - - - - - - - - - end-of-life - - - - - Python 3.6 - - - - - - - - - - - - - end-of-life - - - - - Python 3.7 - - - - - - - - - - - - - end-of-life - - - - - Python 3.8 - - - - - - - - - - - - - end-of-life - - - - - Python 3.9 - - - - - - - - - - - - - - - - security - - - - - Python 3.10 - - - - - - - - - - - - - - - - security - - - - - Python 3.11 - - - - - - - - - - - - - - - - security - - - - - Python 3.12 - - - - - - - - - - - - - - - - bugfix - - - - - Python 3.13 - - - - - - - - - - - - - - - - bugfix - - - - - Python 3.14 - - - - - - - - - - - - - - - - feature - - - - - Python 3.15 - - - - - From bb8ded345eabf6f9c355c9862fec46ca676acf63 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Wed, 4 Mar 2026 08:20:39 -0800 Subject: [PATCH 10/10] Update for consistency --- getting-started/setup-building.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 830c4468b..2204d6f94 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -409,19 +409,19 @@ following command with Python 3.11 or newer: .. code-block:: shell - python3 Platforms/WASI build --quiet -- --config-cache --with-pydebug + python Platforms/WASI build --quiet -- --config-cache --with-pydebug .. tab:: Python 3.14 .. code-block:: shell - python3 Tools/wasm/wasi build --quiet -- --config-cache --with-pydebug + python Tools/wasm/wasi build --quiet -- --config-cache --with-pydebug .. tab:: Python 3.13 .. code-block:: shell - python3 Tools/wasm/wasi.py build --quiet -- --config-cache --with-pydebug + python Tools/wasm/wasi.py build --quiet -- --config-cache --with-pydebug That single command will configure and build both the build Python and the WASI build in the ``cross-build/`` directory. @@ -433,10 +433,10 @@ is a convenience wrapper around the following commands: .. code-block:: shell - $ python3 Platforms/WASI configure-build-python --quiet -- --config-cache --with-pydebug - $ python3 Platforms/WASI make-build-python --quiet - $ python3 Platforms/WASI configure-host --quiet -- --config-cache - $ python3 Platforms/WASI make-host --quiet + $ python Platforms/WASI configure-build-python --quiet -- --config-cache --with-pydebug + $ python Platforms/WASI make-build-python --quiet + $ python Platforms/WASI configure-host --quiet -- --config-cache + $ python Platforms/WASI make-host --quiet .. tab:: Python 3.14