wasi-wheels

Compile Python wheels for use with WASI targets. Specifically, generate wheels that can be consumed by componentize-py.

This is very much a work in progress. The goal is to get to a point where wheels are built and stored as GitHub releases, and provided through an alternate Python package registry for WASI builds until PyPi supports them natively.

Right now this tooling can:

• Setup the necessary build tooling
• Download an sdist build for a given project and version
• Build wheels for specific packages
• Upload wheels to GitHub releases
• Provide a registry for installation

Supported Wheel	Versions
pydantic-core	>= 2.18.3
regex	>= 2021.11.10

Use a wheel

If you want to use a wheel for use with componentize-py, you can run the following:

python3 -m pip install --target wasi_deps --platform any --platform wasi_0_0_0_wasm32 --python-version "3.12" --only-binary :all: --index-url https://benbrandt.github.io/wasi-wheels/ --extra-index-url https://pypi.org/simple --upgrade .

Then you can run your componentize-py build like so:

componentize-py -w world componentize skill_module -o output_file -p . -p wasi_deps

Setup

Make sure you have python3.12 or python3.13 and rustup installed.

After cloning the repo, you can run:

cargo run -- install-build-tools

This will setup WASI SDK v24 with some minor patches for compiling CPython (mainly making wasip2 look like wasi for now, until better support for the correct target is available).

It also pulls down Cpython for 3.12 and 3.13 and compiles it for wasi.

Building a wheel locally

If you need to debug a build locally, you can run:

cargo run -- build <project> <version>

Building the Index locally

cargo run -- generate-index benbrandt/wasi-wheels

Scientific pipeline

The active non-serving scientific build profile is recipes/scientific-sdk33.v1.json. It targets CPython 3.14.6 and WASI SDK 33 with the WebAssembly C++ exception ABI used by the certified NumPy FFT and pandas wheels. recipes/scientific.v1.json is retained as the historical SDK24 profile; it is not current build authority.

W020 freezes the complete active runtime/build closure in recipes/scientific-sdk33-lock.v1.json: exact wheels, source archives and Git revisions, licence hashes, build flags, recipe/patch hashes, tags, and immutable index policy. Validate it with:

cargo run -- validate-scientific-lock --lock recipes/scientific-sdk33-lock.v1.json

Publish only the exact six-wheel closure with:

cargo run -- publish-locked-index \
  --lock recipes/scientific-sdk33-lock.v1.json \
  --wheels /path/to/locked-wheels \
  --output /path/to/internal-index

The locked publisher rejects missing, unexpected, renamed, retagged, or byte-drifted artifacts. Universal Python wheels are admitted only when they contain no native extension; native wheels remain restricted to the governed WASI tag and WebAssembly .so payloads.

Validate the active pinned NumPy/pandas graph with:

cargo run -- validate-scientific-recipes --manifest recipes/scientific-sdk33.v1.json

Build pandas from a disposable clean source worktree with the certified SDK33 toolchain and NumPy wheel:

bash recipes/pandas/build-wasi-p2.sh \
  /path/to/pandas-source \
  /path/to/candidate-wheels \
  /path/to/wasi-sdk-33-pic-eh \
  /path/to/componentize-py/cpython/builddir \
  /path/to/build-venv/bin/python \
  /path/to/certified-numpy.whl \
  /path/to/patched-meson

The recipe retains the real C++ exception path and normalizes Cython's random shared-utility source path before compilation so independent clean builds are byte-identical. It does not patch published wheels or provide a fallback pandas implementation.

The section below documents the retired SDK24 build profile.

The governed scientific path is manifest-driven and targets CPython 3.14.6, WASI SDK 24, and cp314-cp314-wasi_0_0_0_wasm32. Validate the pinned NumPy/pandas source and dependency graph with:

cargo run -- validate-scientific-recipes --manifest recipes/scientific.v1.json

Build NumPy from a disposable source checkout with all pinned submodules present:

bash recipes/numpy/build-wasi-p2.sh \
  /path/to/numpy-source \
  /path/to/candidate-wheels \
  /path/to/wasi-sdk-24.0 \
  /path/to/componentize-py/cpython/builddir \
  /path/to/build-venv/bin/python

The recipe applies the maintained patch stack, disables CPU dispatch and external BLAS, and emits only the governed cp314-cp314-wasi_0_0_0_wasm32 wheel. numpy.fft is intentionally absent because the pinned SDK has no C++ exception runtime; importing it fails explicitly instead of loading an extension with unresolved ABI symbols.

Publish candidate wheels into a content-addressed internal snapshot with:

cargo run -- publish-immutable-index \
  --manifest recipes/scientific.v1.json \
  --wheels /path/to/candidate-wheels \
  --output /path/to/internal-index

Publication rejects the wrong Python ABI or platform tag, host-native DLL/DYLIB/PYD files, non-WebAssembly .so extensions, unsafe archive paths, and missing governed wheel metadata. It writes only beneath snapshots/<sha256> and rejects mutation of any existing path; there is deliberately no mutable latest pointer.

The historical dicej/wasi-wheels NumPy/pandas recipes are source material only. Their binaries and obsolete CPython/toolchain assumptions are never inputs to this pipeline.