Skip to content

Commit 653a610

Browse files
brettcannonhugovk
andauthored
Document how to do a WASI build (#1273)
Co-authored-by: Hugo van Kemenade <[email protected]>
1 parent b5f49de commit 653a610

File tree

1 file changed

+101
-0
lines changed

1 file changed

+101
-0
lines changed

getting-started/setup-building.rst

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -345,6 +345,107 @@ and how to build.
345345
.. _Git for Windows download from the official Git website: https://git-scm.com/download/win
346346

347347

348+
.. _wasi-compiling:
349+
350+
WASI
351+
----
352+
353+
WASI_ is a system interface standard for WebAssembly_. Through a combination of
354+
C compilers that can target WebAssembly and `wasi-libc`_ providing
355+
POSIX-compatible shims for WASI, it's possible for CPython to run on a WASI
356+
host/runtime as a *guest*.
357+
358+
.. note::
359+
360+
The instructions below assume a Unix-based OS due to cross-compilation for
361+
CPython being designed for ``./configure`` / ``make``.
362+
363+
To build for WASI, you will need to cross-compile CPython. This requires a C
364+
compiler just like building for :ref:`Unix <unix-compiling>` as well as:
365+
366+
1. A C compiler that can target WebAssembly (e.g. `WASI SDK`_)
367+
2. A WASI host/runtime (e.g. Wasmtime_)
368+
369+
All of this is provided in the :ref:`devcontainer <using-codespaces>`. You can
370+
also use what's installed in the container as a reference of what versions of
371+
these tools are known to work.
372+
373+
.. note::
374+
375+
CPython has only been verified with the above tools for WASI. Using
376+
other compilers, hosts, or WASI versions *should* work, but the above tools
377+
and their versions specified in the container are tested via a
378+
:ref:`buildbot <buildbots>`.
379+
380+
Building for WASI requires doing a cross-build where you have a *build* Python
381+
to help produce a WASI build of CPython (technically it's a "host x host"
382+
cross-build because the build Python is also the target Python while the host
383+
build is the WASI build). This means you effectively build CPython twice: once
384+
to have a version of Python for the build system to use and another that's the
385+
build you ultimately care about (i.e. the build Python is not meant for use by
386+
you directly, only the build system).
387+
388+
The easiest way to get a debug build of CPython for WASI is to use the
389+
``Tools/wasm/wasi.py build`` command (which should be run w/ a recent version of
390+
Python you have installed on your machine):
391+
392+
.. code-block:: shell
393+
394+
$ python3 Tools/wasm/wasi.py build --quiet -- --config-cache --with-pydebug
395+
396+
That single command will configure and build both the build Python and the
397+
WASI build in ``cross-build/build`` and ``cross-build/wasm32-wasi``,
398+
respectively.
399+
400+
You can also do each configuration and build step separately; the command above
401+
is a convenience wrapper around the following commands:
402+
403+
.. code-block:: shell
404+
405+
$ python Tools/wasm/wasi.py configure-build-python --quiet -- --config-cache --with-pydebug
406+
$ python Tools/wasm/wasi.py make-build-python --quiet
407+
$ python Tools/wasm/wasi.py configure-host --quiet -- --config-cache
408+
$ python Tools/wasm/wasi.py make-host --quiet
409+
410+
.. note::
411+
412+
The ``configure-host`` command infers the use of ``--with-pydebug`` from the
413+
build Python.
414+
415+
Running the separate commands after ``wasi.py build`` is useful if you, for example, only want to
416+
run the ``make-host`` step after making code changes.
417+
418+
Once everything is complete, there will be a
419+
``cross-build/wasm32-wasi/python.sh`` helper file which you can use to run the
420+
``python.wasm`` file (see the output from the ``configure-host`` subcommand):
421+
422+
.. code-block:: shell
423+
424+
$ cross-build/wasm32-wasi/python.sh --version
425+
426+
You can also use ``Makefile`` targets and they will work as expected thanks to
427+
the ``HOSTRUNNER`` environment variable having been set to a similar value as
428+
used in ``python.sh``:
429+
430+
.. code-block:: shell
431+
432+
$ make -C cross-build/wasm32-wasi test
433+
434+
.. note::
435+
436+
WASI uses a *capability-based* security model. This means that the WASI host
437+
does not give full access to your machine unless you tell it to. This
438+
also means things like files can end up being mapped to a different path
439+
inside the WASI host. So, if you try passing a file path to
440+
``python.wasm``/ ``python.sh``, it needs to match the path **inside** the
441+
WASI host, not the path on your machine (much like using a container).
442+
443+
.. _WASI: https://wasi.dev
444+
.. _wasi-libc: https://github.com/WebAssembly/wasi-libc
445+
.. _WASI SDK: https://github.com/WebAssembly/wasi-sdk
446+
.. _wasmtime: https://wasmtime.dev
447+
.. _WebAssembly: https://webassembly.org
448+
348449
.. _build-dependencies:
349450
.. _deps-on-linux:
350451
.. _macOS and OS X:

0 commit comments

Comments
 (0)