@@ -345,6 +345,107 @@ and how to build.
345
345
.. _Git for Windows download from the official Git website : https://git-scm.com/download/win
346
346
347
347
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
+
348
449
.. _build-dependencies :
349
450
.. _deps-on-linux :
350
451
.. _macOS and OS X :
0 commit comments