]>
Commit | Line | Data |
---|---|---|
43e71239 | 1 | # `wasi-libc` |
dcf13b6f | 2 | |
43e71239 AB |
3 | `wasi-libc` is a libc for WebAssembly programs built on top of WASI system |
4 | calls. It provides a wide array of POSIX-compatible C APIs, including support | |
5 | for standard I/O, file I/O, filesystem manipulation, memory management, time, | |
6 | string, environment variables, program startup, and many other APIs. | |
dcf13b6f | 7 | |
43e71239 | 8 | `wasi-libc` is sufficiently stable and usable for many purposes, as most of the |
c33ea73e | 9 | POSIX-compatible APIs are stable, though it is continuing to evolve to better |
43e71239 AB |
10 | align with wasm and WASI. For example, pthread support is experimentally |
11 | provided via the [wasi-threads] proposal.` | |
12 | ||
13 | [wasi-threads]: https://github.com/WebAssembly/wasi-threads | |
dcf13b6f DG |
14 | |
15 | ## Usage | |
16 | ||
c33ea73e | 17 | The easiest way to get started with this is to use [wasi-sdk], which includes a |
43e71239 | 18 | build of `wasi-libc` in its sysroot. |
320054e8 DG |
19 | |
20 | ## Building from source | |
21 | ||
22 | To build a WASI sysroot from source, obtain a WebAssembly-supporting C compiler | |
43e71239 AB |
23 | (currently this is only clang 10+, though we'd like to support other compilers |
24 | as well), and then run: | |
dcf13b6f | 25 | |
b1e234b6 | 26 | ```sh |
9e09e02a | 27 | make CC=/path/to/clang/with/wasm/support \ |
9eb4a995 | 28 | AR=/path/to/llvm-ar \ |
a279514a | 29 | NM=/path/to/llvm-nm |
dcf13b6f DG |
30 | ``` |
31 | ||
43e71239 | 32 | This makes a directory called "sysroot" by default. See the top of the Makefile |
dcf13b6f DG |
33 | for customization options. |
34 | ||
35 | To use the sysroot, use the `--sysroot=` option: | |
36 | ||
b1e234b6 | 37 | ```sh |
dcf13b6f | 38 | /path/to/wasm/supporting/c/compiler --sysroot=/path/to/the/newly/built/sysroot ... |
f2049d9b | 39 | ``` |
dcf13b6f DG |
40 | |
41 | to run the compiler using the newly built sysroot. | |
c33ea73e DG |
42 | |
43 | Note that Clang packages typically don't include cross-compiled builds of | |
43e71239 AB |
44 | compiler-rt, libcxx, or libcxxabi, for `libclang_rt.builtins-wasm32.a`, |
45 | `libc++.a`, or `libc++abi.a`, respectively, so they may not be usable without | |
c33ea73e | 46 | extra setup. This is one of the things [wasi-sdk] simplifies, as it includes |
43e71239 AB |
47 | cross-compiled builds of compiler-rt, `libc++.a`, and `libc++abi.a`. |
48 | ||
49 | ## Building in pthread support | |
50 | ||
51 | To enable pthreads support via the [wasi-threads] proposal, follow the above | |
52 | build directions with one addition: `make ... THREAD_MODEL=posix`. This creates | |
53 | additional artifacts in `sysroot/lib/wasm32-wasi-threads` to support `--target | |
54 | wasm32-wasi-threads`. | |
c33ea73e | 55 | |
ca4d2f0c | 56 | ## Arch Linux AUR package |
3189cd1c JP |
57 | |
58 | For Arch Linux users, there's an official [wasi-libc] package tracking this Git | |
59 | repository. You might want to install other [WASI related packages] as well. | |
b6390079 | 60 | |
c33ea73e | 61 | [wasi-sdk]: https://github.com/WebAssembly/wasi-sdk |
3189cd1c JP |
62 | [wasi-libc]: https://archlinux.org/packages/community/any/wasi-libc/ |
63 | [WASI related packages]: https://archlinux.org/packages/?q=wasi- |