From 43e7123958174bedbad2fdef4589db66fb2aa62b Mon Sep 17 00:00:00 2001 From: Andrew Brown Date: Fri, 23 Jun 2023 13:24:08 -0700 Subject: [PATCH] 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 --- README.md | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 60307a1c..ca5d1540 100644 --- 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