mirror of https://github.com/python/cpython
GH-116314: Update `Tools/wasm/README.md` to point to the devguide for building for WASI (GH-116445)
This commit is contained in:
Brett Cannon
GitHub
parent
2d4955fcf2
commit
bc708c76d2
|
|
@ -1,6 +1,7 @@
|
||||||
# Python WebAssembly (WASM) build
|
# Python WebAssembly (WASM) build
|
||||||
|
|
||||||
**WARNING: WASM support is work-in-progress! Lots of features are not working yet.**
|
**WASI support is [tier 2](https://peps.python.org/pep-0011/#tier-2).**
|
||||||
|
**Emscripten is NOT officially supported as of Python 3.13.**
|
||||||
|
|
||||||
This directory contains configuration and helpers to facilitate cross
|
This directory contains configuration and helpers to facilitate cross
|
||||||
compilation of CPython to WebAssembly (WASM). Python supports Emscripten
|
compilation of CPython to WebAssembly (WASM). Python supports Emscripten
|
||||||
|
|
@ -298,66 +299,7 @@ AddType application/wasm wasm
|
||||||
|
|
||||||
## WASI (wasm32-wasi)
|
## WASI (wasm32-wasi)
|
||||||
|
|
||||||
**NOTE**: The instructions below assume a Unix-based OS due to cross-compilation for CPython being set up for `./configure`.
|
See [the devguide on how to build and run for WASI](https://devguide.python.org/getting-started/setup-building/#wasi).
|
||||||
|
|
||||||
### Prerequisites
|
|
||||||
|
|
||||||
Developing for WASI requires two additional tools to be installed beyond the typical tools required to build CPython:
|
|
||||||
|
|
||||||
1. The [WASI SDK](https://github.com/WebAssembly/wasi-sdk) 16.0+
|
|
||||||
2. A WASI host/runtime ([wasmtime](https://wasmtime.dev) 14+ is recommended and what the instructions below assume)
|
|
||||||
|
|
||||||
All of this is provided in the [devcontainer](https://devguide.python.org/getting-started/setup-building/#contribute-using-github-codespaces) if you don't want to install these tools locally.
|
|
||||||
|
|
||||||
### Building
|
|
||||||
|
|
||||||
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 build is the WASI build; yes, it's confusing terminology). In the end you should have a build Python in `cross-build/build` and a WASI build in `cross-build/wasm32-wasi`.
|
|
||||||
|
|
||||||
The easiest way to do a build is to use the `wasi.py` script. You can either have it perform the entire build process from start to finish in one step, or you can do it in discrete steps that mirror running `configure` and `make` for each of the two builds of Python you end up producing (which are beneficial when you only need to do a specific step after getting a complete build, e.g. editing some code and you just need to run `make` for the WASI build). The script is designed to self-document what actions it is performing on your behalf, both as a way to check its work but also for educaitonal purposes.
|
|
||||||
|
|
||||||
The discrete steps for building via `wasi.py` are:
|
|
||||||
```shell
|
|
||||||
python Tools/wasm/wasi.py configure-build-python
|
|
||||||
python Tools/wasm/wasi.py make-build-python
|
|
||||||
python Tools/wasm/wasi.py configure-host
|
|
||||||
python Tools/wasm/wasi.py make-host
|
|
||||||
```
|
|
||||||
|
|
||||||
To do it all in a single command, run:
|
|
||||||
```shell
|
|
||||||
python Tools/wasm/wasi.py build
|
|
||||||
```
|
|
||||||
|
|
||||||
That will:
|
|
||||||
|
|
||||||
1. Run `configure` for the build Python (same as `wasi.py configure-build-python`)
|
|
||||||
2. Run `make` for the build Python (`wasi.py make-build-python`)
|
|
||||||
3. Run `configure` for the WASI build (`wasi.py configure-host`)
|
|
||||||
4. Run `make` for the WASI build (`wasi.py make-host`)
|
|
||||||
|
|
||||||
See the `--help` for the various options available for each of the subcommands which controls things like the location of the WASI SDK, the command to use with the WASI host/runtime, etc. Also note that you can use `--` as a separator for any of the `configure`-related commands -- including `build` itself -- to pass arguments to the underlying `configure` call. For example, if you want a pydebug build that also caches the results from `configure`, you can do:
|
|
||||||
```shell
|
|
||||||
python Tools/wasm/wasi.py build -- -C --with-pydebug
|
|
||||||
```
|
|
||||||
|
|
||||||
The `wasi.py` script is able to infer details from the build Python, and so you only technically need to specify `--with-pydebug` once via `configure-build-python` as this will lead to `configure-host` detecting its use if you use the discrete steps:
|
|
||||||
```shell
|
|
||||||
python Tools/wasm/wasi.py configure-build-python -- -C --with-pydebug
|
|
||||||
python Tools/wasm/wasi.py make-build-python
|
|
||||||
python Tools/wasm/wasi.py configure-host -- -C
|
|
||||||
python Tools/wasm/wasi.py make-host
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
### Running
|
|
||||||
|
|
||||||
If you used `wasi.py` to do your build then there will be a `cross-build/wasm32-wasi/python.sh` file which you can use to run the `python.wasm` file (see the output from the `configure-host` subcommand):
|
|
||||||
```shell
|
|
||||||
cross-build/wasm32-wasi/python.sh --version
|
|
||||||
```
|
|
||||||
|
|
||||||
While you _can_ run `python.wasm` directly, Python will fail to start up without certain things being set (e.g. `PYTHONPATH` for `sysconfig` data). As such, the `python.sh` file records these details for you.
|
|
||||||
|
|
||||||
|
|
||||||
## Detecting WebAssembly builds
|
## Detecting WebAssembly builds
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue