README.md
1# WASI Libc
2
3This is a work in progress. It's usable for many purposes, though the APIs
4aren't stable yet.
5
6## What is this?
7
8It's several things.
9
10First, it's a usable libc. It builds a "libc" which can be used by
11compilers, such as Clang 8.0, using the wasm32-wasi target. It's a work in
12progress, but it is already sufficient to run basic programs.
13
14Second, it's a "reference" implementation, which means the interfaces defined
15here can be used by other tools and libraries, even if they don't use all the
16actual implementations here. For example, we don't expect everyone will want
17to use the exact `malloc` implementation provided here, but tools and
18libraries using an ABI-compatible `malloc` interface will be able to
19interoperate regardless of which actual implementation is used.
20
21Third, it's an example showing the use of the WASI API. The libc functionality
22is implemented using calls to WASI functions.
23
24## Usage
25
26The easiest way to get started with this is to use one of the
27[prepackaged releases](https://github.com/CraneStation/wasmtime/blob/master/docs/WASI-intro.md#how-can-i-write-programs-that-use-wasi).
28
29## Building from source
30
31To build a WASI sysroot from source, obtain a WebAssembly-supporting C compiler
32(currently this is only clang 8+, though we'd like to support other compilers as well),
33and then run:
34
35```sh
36make WASM_CC=/path/to/clang/with/wasm/support \
37 WASM_AR=/path/to/llvm-ar \
38 WASM_NM=/path/to/llvm-nm
39```
40
41This makes a directory called "sysroot", by default. See the top of the Makefile
42for customization options.
43
44To use the sysroot, use the `--sysroot=` option:
45
46```sh
47/path/to/wasm/supporting/c/compiler --sysroot=/path/to/the/newly/built/sysroot ...
48```
49
50to run the compiler using the newly built sysroot.
51