Skip to content
Snippets Groups Projects
user avatar
Alex Crichton authored
There are a number of changes in this commit aimed at addressing #587
and making it easier to test #586 in CI. Notable changes here are:

* The matrix of what to test is much different from before. One matrix
entry now builds just one target and optionally tests that target.

* The CI matrix ensures that wasi-libc builds on a variety of platforms,
e.g. Windows/macOS/Linux as well as Linux aarch64.

* The CI matrix has one entry for building with an older version of
LLVM. This version was bumped from LLVM to LLVM 11 since LLVM is
installed through `apt-get`, not through downloads any more.

* On Linux LLVM/Clang are downloaded through `apt-get` instead of from
llvm-project binaries to avoid dealing with `libtinfo5` and
dependencies.

* The CI matrix has a test job per-target. This can be expanded/shrunk
as necessary but currently everything is tested with LLVM 16 (as before)
and only on Linux (also as before). The test run is seqeunced to happen
after the build of libc itself.

* The CI matrix has split out V8 headless tests into their own job to
avoid running multiple suites of tests in a single job.

* Installation of LLVM is refactored to a separate action to reduce the
noise in `main.yml`.

* Setting `TARGET_TRIPLE` can now be done through environment variables
as opposed to only through arguments to `make`.

* Handling of `BULITINS_LIB` has improved. Previously the build target
for `libc_so` would modify the compiler's resource directory and this is
updated to use a custom directory in `OBJDIR`.

* Arranging compiler-rt for tests is now done with `-resource-dir`
instead of copying the directory into the system compiler's location.

Overall it's the intention that no amount of testing is lost in this PR.
The goal is to expand things out in such a way that it's much easier to
add one-off tests of wasi-libc in various build configurations and such.
The theory is that this is as "simple" as adding a new matrix entry,
copied from previous ones, customized with various variables and
environment variables to affect the build (e.g. `CFLAGS`).

Closes #587
48eb92c1
History

wasi-libc

wasi-libc is a libc for WebAssembly programs built on top of WASI system calls. It provides a wide array of POSIX-compatible C APIs, including support for standard I/O, file I/O, filesystem manipulation, memory management, time, string, environment variables, program startup, and many other APIs.

wasi-libc is sufficiently stable and usable for many purposes, as most of the POSIX-compatible APIs are stable, though it is continuing to evolve to better align with wasm and WASI. For example, pthread support is experimentally provided via the wasi-threads proposal.

Usage

The easiest way to get started with this is to use wasi-sdk, which includes a build of wasi-libc in its sysroot.

Building from source

To build a WASI sysroot from source, obtain a WebAssembly-supporting C compiler (currently this is only clang 10+, though we'd like to support other compilers as well), and then run:

make CC=/path/to/clang/with/wasm/support \
     AR=/path/to/llvm-ar \
     NM=/path/to/llvm-nm

This makes a directory called "sysroot" by default. See the top of the Makefile for customization options.

To use the sysroot, use the --sysroot= option:

/path/to/wasm/supporting/c/compiler --sysroot=/path/to/the/newly/built/sysroot ...

to run the compiler using the newly built sysroot.

Note that Clang packages typically don't include cross-compiled builds of compiler-rt, libcxx, or libcxxabi, for libclang_rt.builtins-wasm32.a, libc++.a, or libc++abi.a, respectively, so they may not be usable without extra setup. This is one of the things wasi-sdk simplifies, as it includes cross-compiled builds of compiler-rt, libc++.a, and libc++abi.a.

Building in pthread support

To enable pthreads support via the wasi-threads proposal, follow the above build directions with one addition: make ... THREAD_MODEL=posix. This creates additional artifacts in sysroot/lib/wasm32-wasi-threads to support --target wasm32-wasi-threads.

Arch Linux AUR package

For Arch Linux users, there's an official wasi-libc package tracking this Git repository. You might want to install other WASI related packages as well.