Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

GH-116314: Update Tools/wasm/README.md to point to the devguide for building for WASI #116445

Merged
merged 1 commit into from Mar 7, 2024
Merged

GH-116314: Update Tools/wasm/README.md to point to the devguide for building for WASI #116445

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
64 changes: 3 additions & 61 deletions Tools/wasm/README.md
View file
Open in desktop
@@ -1,6 +1,7 @@
# 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
compilation of CPython to WebAssembly (WASM). Python supports Emscripten
Expand Down Expand Up @@ -298,66 +299,7 @@ AddType application/wasm wasm

## WASI (wasm32-wasi)

**NOTE**: The instructions below assume a Unix-based OS due to cross-compilation for CPython being set up for `./configure`.

### 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.

See [the devguide on how to build and run for WASI](https://devguide.python.org/getting-started/setup-building/#wasi).

## Detecting WebAssembly builds

Expand Down