Improve `README.md` (#425)

This changes the front-page documentation to:
- use `wasi-libc` instead of "WASI Libc"
- explain how to build the pthreads-enabled `wasm32-wasi-threads` target

diff --git a/README.md b/README.md
index 60307a1c9eb25476ec3a5882a6142c219dbbe263..ca5d15406ae9a49c7bdc20e858e4a658f1fa70d8 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,25 +1,27 @@
-# WASI Libc
+# `wasi-libc`
 
-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.
+`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.
 
-WASI Libc is sufficiently stable and usable for many purposes, as most of the
+`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 still a work in
-progress.
+align with wasm and WASI. For example, pthread support is experimentally
+provided via the [wasi-threads] proposal.`
+
+[wasi-threads]: https://github.com/WebAssembly/wasi-threads
 
 ## Usage
 
 The easiest way to get started with this is to use [wasi-sdk], which includes a
-build of WASI Libc in its sysroot.
+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 10+, 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:
 
 ```sh
 make CC=/path/to/clang/with/wasm/support \
@@ -27,7 +29,7 @@ make CC=/path/to/clang/with/wasm/support \
      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:
@@ -39,10 +41,17 @@ To use the sysroot, use the `--sysroot=` option:
 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
+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.
+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