X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=README.md;h=30682951f15e1f6e793c08988c812761eeb769ec;hb=HEAD;hp=d32f522902d29e182d58d8278cf3f0636fba6596;hpb=320054e84f8f2440def3b1c8700cedb8fd697bf8;p=wasi-libc.git

diff --git a/README.md b/README.md
index d32f522..ca5d154 100644
--- a/README.md
+++ b/README.md
@@ -1,48 +1,63 @@
-# WASI Sysroot
+# `wasi-libc`
 
-This is a work in progress. It's usable for many purposes, though the APIs
-aren't stable yet.
+`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.
 
-## What is this?
+`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.`
 
-It's several things.
-
-First, it's a usable libc. It builds a "sysroot" which can be pointed to by
-compilers, such as Clang 8.0, using the wasm32-unknown-wasi target triple.
-It's a work in progress, but it is already sufficient to run basic programs.
-
-Second, it's a "reference" implementation, which means the interfaces defined
-here can be used by other tools and libraries, even if they don't use all the
-actual implementations here. For example, we don't expect everyone will want
-to use the exact `malloc` implementation provided here, but tools and
-libraries using an ABI-compatible `malloc` interface will be able to
-interoperate regardless of which actual implementation is used.
-
-Third, it's an example showing the use of the WASI API. The libc functionality
-is implemented using calls to WASI functions.
+[wasi-threads]: https://github.com/WebAssembly/wasi-threads
 
 ## Usage
 
-The easiest way to get started with this is to use one of the
-[prepackaged releases](https://github.com/CraneStation/wasmtime-wasi/blob/wasi/docs/WASI-intro.md#how-can-i-write-programs-that-use-wasi).
+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, though we'd like to support other compilers as well),
-and then run:
+(currently this is only clang 10+, though we'd like to support other compilers
+as well), and then run:
 
-```
-make WASM_CC=/path/to/wasm/supporting/c/compiler
+```sh
+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
+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:
 
-```
+```sh
 /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.
+
+[wasi-sdk]: https://github.com/WebAssembly/wasi-sdk
+[wasi-libc]: https://archlinux.org/packages/community/any/wasi-libc/
+[WASI related packages]: https://archlinux.org/packages/?q=wasi-