From 920e0984d3aa65474636aeaeac298927d0b937cf Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Thu, 2 Jul 2020 08:49:27 -0700 Subject: [PATCH] Link to C API docs and make a landing page Spice up the landing page a bit for the C API documentation and then link to it from a few places to ensure it's discoverable. --- README.md | 6 +-- crates/c-api/README.md | 5 +- crates/c-api/include/doc-wasm.h | 87 +++++++++++++++++++++++++++++++++ docs/examples-c-embed.md | 12 ++--- 4 files changed, 95 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 415fb15aa34f..bb8b1617a5f0 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ You can use Wasmtime from a variety of different languages through embeddings of the implementation: * **[Rust]** - the [`wasmtime` crate] -* **[C]** - the [`wasm.h`], [`wasi.h`], and [`wasmtime.h`] headers +* **[C]** - the [`wasm.h`, `wasi.h`, and `wasmtime.h` headers][c-headers] * **[Python]** - the [`wasmtime` PyPI package] * **[.NET]** - the [`Wasmtime` NuGet package] * **[Go]** - the [wasmtime-go repository] @@ -100,9 +100,7 @@ the implementation: [Rust]: https://bytecodealliance.github.io/wasmtime/lang-rust.html [C]: https://bytecodealliance.github.io/wasmtime/examples-c-embed.html [`wasmtime` crate]: https://crates.io/crates/wasmtime -[`wasm.h`]: https://github.com/WebAssembly/wasm-c-api/blob/master/include/wasm.h -[`wasi.h`]: https://github.com/bytecodealliance/wasmtime/blob/main/crates/c-api/include/wasi.h -[`wasmtime.h`]: https://github.com/bytecodealliance/wasmtime/blob/main/crates/c-api/include/wasmtime.h +[c-headers]: https://bytecodealliance.github.io/wasmtime/c-api/ [Python]: https://bytecodealliance.github.io/wasmtime/lang-python.html [`wasmtime` PyPI package]: https://pypi.org/project/wasmtime/ [.NET]: https://bytecodealliance.github.io/wasmtime/lang-dotnet.html diff --git a/crates/c-api/README.md b/crates/c-api/README.md index b0edded9c2ba..5d7149dd18ac 100644 --- a/crates/c-api/README.md +++ b/crates/c-api/README.md @@ -1,3 +1,4 @@ -# Implementation of wasm-c-api in Rust +# Wasmtime's C API -https://github.com/WebAssembly/wasm-c-api +For more information you can find the documentation for this library +[online](https://bytecodealliance.github.io/wasmtime/c-api/). diff --git a/crates/c-api/include/doc-wasm.h b/crates/c-api/include/doc-wasm.h index bd3703c7ab1b..462b7c529be2 100644 --- a/crates/c-api/include/doc-wasm.h +++ b/crates/c-api/include/doc-wasm.h @@ -1,3 +1,90 @@ +/** + * \mainpage Wasmtime C API + * + * This documentation is an overview and API reference for the C API of + * Wasmtime. The C API is spread between three different header files: + * + * * \ref wasm.h + * * \ref wasi.h + * * \ref wasmtime.h + * + * The \ref wasm.h header file comes directly from the + * [WebAssembly/wasm-c-api](https://github.com/WebAssembly/wasm-c-api) + * repository. At this time the upstream header file does not have documentation + * so Wasmtime provides documentation here. It should be noted, however, that + * some semantics may be Wasmtime-specific and may not be portable to other + * engines. The Wasmtime project intends to assist in the development of the + * upstream C API. + * + * The \ref wasi.h and \ref wasmtime.h header files are specific to the Wasmtime + * project. It's hoped to standardize \ref wasi.h in the WASI standard + * eventually, but \ref wasmtime.h provides Wasmtime-specific extensions to the + * C API which are not intended to standardize. + * + * ## Installing the C API + * + * To install the C API from precompiled binaries you can download the + * appropriate binary from the [releases page of + * Wasmtime](https://github.com/bytecodealliance/wasmtime/releases). Artifacts + * for the C API all end in "-c-api" for the filename. + * + * Each archive contains an `include` directory with necessary headers, as well + * as a `lib` directory with both a static archive and a dynamic library of + * Wasmtime. You can link to either of them as you see fit. + * + * ## Linking against the C API + * + * You'll want to arrange the `include` directory of the C API to be in your + * compiler's header path (e.g. the `-I` flag). If you're compiling for Windows + * and you're using the static library then you'll also need to pass + * `-DWASM_API_EXTERN=` and `-DWASI_API_EXTERN=` to disable dllimport. + * + * Your final artifact can then be linked with `-lwasmtime`. If you're linking + * against the static library you may need to pass other system libraries + * depending on your platform: + * + * * Linux - `-lpthread -ldl -lm` + * * macOS - no extra flags needed + * * Windows - `ws2_32.lib advapi32.lib userenv.lib ntdll.lib shell32.lib ole32.lib` + * + * ## Building from Source + * + * The C API is located in the + * [`crates/c-api`](https://github.com/bytecodealliance/wasmtime/tree/main/crates/c-api) + * directory of the [Wasmtime + * repository](https://github.com/bytecodealliance/wasmtime). To build from + * source you'll need a Rust compiler and a checkout of the `wasmtime` project. + * Afterwards you can execute: + * + * ``` + * $ cargo build --release -p wasmtime-c-api + * ``` + * + * This will place the final artifacts in `target/release`, with names depending + * on what platform you're compiling for. + * + * ## Other resources + * + * Some other handy resources you might find useful when exploring the C API + * documentation are: + * + * * [Rust `wasmtime` crate + * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/) - + * although this documentation is for Rust and not C, you'll find that many + * functions mirror one another and there may be extra documentation in Rust + * you find helpful. If you find yourself having to frequently do this, + * though, please feel free to [file an + * issue](https://github.com/bytecodealliance/wasmtime/issues/new). + * + * * [C embedding + * examples](https://bytecodealliance.github.io/wasmtime/examples-c-embed.html) + * are available online and are tested from the Wasmtime repository itself. + * + * * [Contribution documentation for + * Wasmtime](https://bytecodealliance.github.io/wasmtime/contributing.html) in + * case you're interested in helping out! + */ + /** * \file wasm.h * diff --git a/docs/examples-c-embed.md b/docs/examples-c-embed.md index d5c5918b313f..c6dc5b678780 100644 --- a/docs/examples-c-embed.md +++ b/docs/examples-c-embed.md @@ -1,12 +1,6 @@ # Embedding in C -This section is intended to showcase the C embedding API for Wasmtime. The C -embedding API is based on the [proposed wasm C embedding API][proposal] (namely -[`wasm.h`]) and has a few extension headers (like [`wasi.h`] and -[`wasmtime.h`]) which are intended to eventually become part of the standard -themselves one day. +This section is intended to showcase the C embedding API for Wasmtime. Full +reference documentation for the C API [can be found online][online] -[proposal]: https://github.com/webassembly/wasm-c-api -[`wasm.h`]: https://github.com/WebAssembly/wasm-c-api/blob/master/include/wasm.h -[`wasi.h`]: https://github.com/bytecodealliance/wasmtime/blob/main/crates/c-api/include/wasi.h -[`wasmtime.h`]: https://github.com/bytecodealliance/wasmtime/blob/main/crates/c-api/include/wasmtime.h +[online]: https://bytecodealliance.github.io/wasmtime/c-api/