README.md

   1 # WASI Libc
   2
   3 This is a work in progress. It's usable for many purposes, though the APIs
   4 aren't stable yet.
   5
   6 ## What is this?
   7
   8 It's several things.
   9
  10 First, it's a usable libc. It builds a "sysroot" which can be pointed to by
  11 compilers, such as Clang 8.0, using the wasm32-wasi target. It's a work in
  12 progress, but it is already sufficient to run basic programs.
  13
  14 Second, it's a "reference" implementation, which means the interfaces defined
  15 here can be used by other tools and libraries, even if they don't use all the
  16 actual implementations here. For example, we don't expect everyone will want
  17 to use the exact `malloc` implementation provided here, but tools and
  18 libraries using an ABI-compatible `malloc` interface will be able to
  19 interoperate regardless of which actual implementation is used.
  20
  21 Third, it's an example showing the use of the WASI API. The libc functionality
  22 is implemented using calls to WASI functions.
  23
  24 ## Usage
  25
  26 The 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
  31 To 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),
  33 and then run:
  34
  35 ```sh
  36 make WASM_CC=/path/to/clang/with/wasm/support \
  37      WASM_AR=/path/to/llvm-ar \
  38      WASM_NM=/path/to/llvm-nm
  39 ```
  40
  41 This makes a directory called "sysroot", by default. See the top of the Makefile
  42 for customization options.
  43
  44 To 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
  50 to run the compiler using the newly built sysroot.