README.md

   1 # WASI Libc
   2
   3 WASI Libc is a libc for WebAssembly programs built on top of WASI system calls.
   4 It provides a wide array of POSIX-compatible C APIs, including support for
   5 standard I/O, file I/O, filesystem manipulation, memory management, time, string,
   6 environment variables, program startup, and many other APIs.
   7
   8 WASI Libc is sufficiently stable and usable for many purposes, as most of the
   9 POSIX-compatible APIs are stable, though it is continuing to evolve to better
  10 align with wasm and WASI.
  11
  12 ## Usage
  13
  14 The easiest way to get started with this is to use [wasi-sdk], which includes a
  15 build of WASI Libc in its sysroot.
  16
  17 ## Building from source
  18
  19 To build a WASI sysroot from source, obtain a WebAssembly-supporting C compiler
  20 (currently this is only clang 8+, though we'd like to support other compilers as well),
  21 and then run:
  22
  23 ```sh
  24 make CC=/path/to/clang/with/wasm/support \
  25      AR=/path/to/llvm-ar \
  26      NM=/path/to/llvm-nm
  27 ```
  28
  29 This makes a directory called "sysroot", by default. See the top of the Makefile
  30 for customization options.
  31
  32 To use the sysroot, use the `--sysroot=` option:
  33
  34 ```sh
  35 /path/to/wasm/supporting/c/compiler --sysroot=/path/to/the/newly/built/sysroot ...
  36 ```
  37
  38 to run the compiler using the newly built sysroot.
  39
  40 Note that Clang packages typically don't include cross-compiled builds of
  41 compiler-rt, libcxx, or libcxxabi, for `libclang_rt.builtins-wasm32.a`, libc++.a,
  42 or libc++abi.a, respectively, so they may not be usable without
  43 extra setup. This is one of the things [wasi-sdk] simplifies, as it includes
  44 cross-compiled builds of compiler-rt, libc++.a, and libc++abi.a.
  45
  46 ## Arch Linux AUR package
  47 For Arch Linux users, there's an unofficial AUR package tracking this git repo that can be installed under the name [wasi-libc-git].
  48
  49 [wasi-sdk]: https://github.com/WebAssembly/wasi-sdk
  50 [wasi-libc-git]: https://aur.archlinux.org/packages/wasi-libc-git/