Avoid varargs conventions when calling open (#126)

[wasi-libc.git] / README.md

diff --git a/README.md b/README.md
index ecd58b56644b10ca7c9f1152aa67e161c7181002..8bd9ab0815b55d2e55400f6741ffa3a5c4289a58 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,22 +1,41 @@
-# WebAssembly Reference Sysroot
+# WASI Libc
 
-Caution: This is currently quite experimental and not generally usable yet!
+This is a work in progress. It's usable for many purposes, though the APIs
+aren't stable yet.
 
 ## What is this?
 
-This is a "reference sysroot", which is meant to be part of a common C ABI
-that can be shared across C libraries and compilers. While it's intended to
-(eventually) be usable in its own right, we fully expect other
-implementations to be used in practice by many different systems, though
-we do hope that in those cases, this library defines a useful ABI that can
-be followed.
+It's several things.
+
+First, it's a usable libc. It builds a "libc" which can be used by
+compilers, such as Clang 8.0, using the wasm32-wasi target. 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
 
-Obtain a WebAssembly-supporting C compiler, and then run:
+The easiest way to get started with this is to use one of the
+[prepackaged releases](https://github.com/CraneStation/wasmtime/blob/master/docs/WASI-intro.md#how-can-i-write-programs-that-use-wasi).
 
-```
-make WASM_CC=/path/to/wasm/supporting/c/compiler
+## Building from source
+
+To build a WASI sysroot from source, obtain a WebAssembly-supporting C compiler
+(currently this is only clang 8+, though we'd like to support other compilers as well),
+and then run:
+
+```sh
+make WASM_CC=/path/to/clang/with/wasm/support \
+     WASM_AR=/path/to/llvm-ar \
+     WASM_NM=/path/to/llvm-nm
 ```
 
 This makes a directory called "sysroot", by default. See the top of the Makefile
@@ -24,25 +43,8 @@ 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.
-
-## Why doesn't this contain a full libc implementation?
-
-In the short term, one of the main goals is just to provide a reference
-point for people already maintaining their own libc codebases, to help
-reduce interface incompatibilities between the several different
-environments out there.
-
-In the long term, there may some day be some form of standardized
-syscall/import layer for wasm which would could support a full
-"reference libc", at which point this repository might make sense as
-a place to host such a thing.
-
-In between, if there are specific pieces of libc functionality which
-people would find useful to have here, and which don't depend on any
-syscalls, we could add them, using code from existing third-party
-codebases as appropriate.