[wasi-libc.git] / README.md

# WASI Sysroot

This is a work in progress. It's usable for many purposes, though the APIs
aren't stable yet.

## What is this?

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.

## 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).

## 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:

```
make WASM_CC=/path/to/wasm/supporting/c/compiler
```

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:

```
/path/to/wasm/supporting/c/compiler --sysroot=/path/to/the/newly/built/sysroot ...
```

to run the compiler using the newly built sysroot.
Commit	Line	Data
320054e8	1	# WASI Sysroot
dcf13b6f	2
320054e8 DG	3	This is a work in progress. It's usable for many purposes, though the APIs
320054e8 DG	4	aren't stable yet.
dcf13b6f DG	5
	6	## What is this?
	7
320054e8 DG	8	It's several things.
	9
	10	First, it's a usable libc. It builds a "sysroot" which can be pointed to by
	11	compilers, such as Clang 8.0, using the wasm32-unknown-wasi target triple.
	12	It's a work in progress, but it is already sufficient to run basic programs.
	13
	14	Second, it's a "reference" implementation, which means the interfaces defined
	15	here can be used by other tools and libraries, even if they don't use all the
	16	actual implementations here. For example, we don't expect everyone will want
	17	to use the exact `malloc` implementation provided here, but tools and
	18	libraries using an ABI-compatible `malloc` interface will be able to
	19	interoperate regardless of which actual implementation is used.
	20
	21	Third, it's an example showing the use of the WASI API. The libc functionality
	22	is implemented using calls to WASI functions.
dcf13b6f DG	23
	24	## Usage
	25
320054e8 DG	26	The easiest way to get started with this is to use one of the
	27	[prepackaged releases](https://github.com/CraneStation/wasmtime-wasi/blob/wasi/docs/WASI-intro.md#how-can-i-write-programs-that-use-wasi).
	28
	29	## Building from source
	30
	31	To build a WASI sysroot from source, obtain a WebAssembly-supporting C compiler
	32	(currently this is only clang, though we'd like to support other compilers as well),
	33	and then run:
dcf13b6f DG	34
	35	```
	36	make WASM_CC=/path/to/wasm/supporting/c/compiler
	37	```
	38
c9850bfd	39	This makes a directory called "sysroot", by default. See the top of the Makefile
dcf13b6f DG	40	for customization options.
	41
	42	To use the sysroot, use the `--sysroot=` option:
	43
	44	```
	45	/path/to/wasm/supporting/c/compiler --sysroot=/path/to/the/newly/built/sysroot ...
f2049d9b	46	```
dcf13b6f DG	47
dcf13b6f DG	48	to run the compiler using the newly built sysroot.