Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve README.md #425

Merged
merged 1 commit into from
Jun 23, 2023
Merged

Improve README.md #425

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 24 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,35 @@
# 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 \
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:
Expand All @@ -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

Expand Down