From 310e6677dcef82ef1e1f607de24c91d90ee4d4fa Mon Sep 17 00:00:00 2001 From: Rik Huijzer Date: Thu, 14 Mar 2024 18:41:27 +0100 Subject: [PATCH] Reorder book-based documentation (#8130) On a high level, this is what this PR changed: 1. Move the CLI chapter before the API chapter. I think this makes sense because the CLI is more high-level. The same change was proposed in https://github.com/bytecodealliance/wasmtime/pull/7987. 1. Move some Rust and C examples from the "Examples" chapter into the API chapter. 1. Remove the original main C and Rust chapter introduction files. They contained mostly outdated or duplicate information. 1. Rename the "Examples" chapter to "Further Examples". (For lack of a better name.) 1. Rename "Embedding" to "API" at some places since API is a more generally known term. The term "embedding" is also slightly more confusing, I think, because the term nowadays also used a lot in LLM-related communication. 1. Read through the entire document and fix some outdated links and information. 1. Fix a missing subheading for Elixir (it was mentioned on the lang page, but not in the menu). --- docs/SUMMARY.md | 41 ++++++++++++++++++------------------- docs/cli-install.md | 2 +- docs/examples-c-embed.md | 7 +------ docs/examples-profiling.md | 14 +++++++------ docs/examples-rust-embed.md | 6 ------ docs/examples.md | 2 +- docs/lang-c.md | 9 ++++---- docs/lang-rust.md | 10 ++++----- docs/lang.md | 2 +- 9 files changed, 40 insertions(+), 53 deletions(-) delete mode 100644 docs/examples-rust-embed.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index f4758b7ef0..d6ce4a5d95 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,16 +1,13 @@ # Summary - [Introduction](./introduction.md) -- [Examples](./examples.md) - - [Debugging WebAssembly](./examples-debugging.md) - - [Debugging with `gdb` and `lldb`](./examples-debugging-native-debugger.md) - - [Debugging with Core Dumps](./examples-debugging-core-dumps.md) - - [Profiling WebAssembly](./examples-profiling.md) - - [Profiling with Perf](./examples-profiling-perf.md) - - [Profiling with VTune](./examples-profiling-vtune.md) - - [Profiling with samply](./examples-profiling-samply.md) - - [Cross-platform Profiling](./examples-profiling-guest.md) - - [Embedding in Rust](./examples-rust-embed.md) +- [Using the Wasmtime CLI](./cli.md) + - [Installation](./cli-install.md) + - [CLI Options](./cli-options.md) + - [CLI Logging](./cli-logging.md) + - [Cache Configuration](./cli-cache.md) +- [Using the Wasmtime API](./lang.md) + - [Rust](./lang-rust.md) - [Hello, world!](./examples-rust-hello-world.md) - [Calculating the GCD](./examples-rust-gcd.md) - [Using Linear Memory](./examples-rust-memory.md) @@ -19,7 +16,7 @@ - [Debugging](./examples-rust-debugging.md) - [Core Dumps](./examples-rust-core-dumps.md) - [Using Multi-Value](./examples-rust-multi-value.md) - - [Embedding in C](./examples-c-embed.md) + - [C](./lang-c.md) - [Hello, World!](./examples-c-hello-world.md) - [Calculating the GCD](./examples-c-gcd.md) - [Using Linear Memory](./examples-c-memory.md) @@ -27,21 +24,23 @@ - [Linking Modules](./examples-c-linking.md) - [Debugging](./examples-c-debugging.md) - [Using Multi-Value](./examples-c-multi-value.md) - - [Checking Guests' Memory Accesses](./wmemcheck.md) - - [Building a minimal embedding](./examples-minimal.md) -- [Using WebAssembly from your language](./lang.md) - - [Rust](./lang-rust.md) - - [C](./lang-c.md) - [Python](./lang-python.md) - [.NET](./lang-dotnet.md) - [Go](./lang-go.md) - [Bash](./lang-bash.md) - [Ruby](./lang-ruby.md) -- [Using the `wasmtime` CLI](./cli.md) - - [Installation](./cli-install.md) - - [CLI Options](./cli-options.md) - - [CLI Logging](./cli-logging.md) - - [Cache Configuration](./cli-cache.md) + - [Elixir](./lang-elixir.md) +- [Further Examples](./examples.md) + - [Debugging WebAssembly](./examples-debugging.md) + - [Debugging with `gdb` and `lldb`](./examples-debugging-native-debugger.md) + - [Debugging with Core Dumps](./examples-debugging-core-dumps.md) + - [Profiling WebAssembly](./examples-profiling.md) + - [Profiling with Perf](./examples-profiling-perf.md) + - [Profiling with VTune](./examples-profiling-vtune.md) + - [Profiling with samply](./examples-profiling-samply.md) + - [Cross-platform Profiling](./examples-profiling-guest.md) + - [Checking Guests' Memory Accesses](./wmemcheck.md) + - [Building a minimal embedding](./examples-minimal.md) - [Stability](stability.md) - [Release Process](./stability-release.md) - [Tiers of support](./stability-tiers.md) diff --git a/docs/cli-install.md b/docs/cli-install.md index b6f98b42b7..ffd370f624 100644 --- a/docs/cli-install.md +++ b/docs/cli-install.md @@ -2,7 +2,7 @@ Here we'll show you how to install the `wasmtime` command line tool. Note that this is distinct from embedding the Wasmtime project into another, for that -you'll want to consult the [embedding documentation](embed.md). +you'll want to consult the [embedding documentation](lang.md). The easiest way to install the `wasmtime` CLI tool is through our installation script. Linux and macOS users can execute the following: diff --git a/docs/examples-c-embed.md b/docs/examples-c-embed.md index c6dc5b6787..57b88955ad 100644 --- a/docs/examples-c-embed.md +++ b/docs/examples-c-embed.md @@ -1,6 +1 @@ -# Embedding in C - -This section is intended to showcase the C embedding API for Wasmtime. Full -reference documentation for the C API [can be found online][online] - -[online]: https://bytecodealliance.github.io/wasmtime/c-api/ +# C diff --git a/docs/examples-profiling.md b/docs/examples-profiling.md index 348979c037..d1b0ab0c71 100644 --- a/docs/examples-profiling.md +++ b/docs/examples-profiling.md @@ -20,14 +20,16 @@ platforms: - For Intel's x86 CPUs on Linux or Windows, we support [VTune](./examples-profiling-vtune.md). -- For everything else, see the cross-platform profiler below. +- For Linux and macOS, we support [samply](./examples-profiling-samply.md). + +- For everything else, see the [cross-platform + profiler](./examples-profiling-guest.md). The native profilers can measure time spent in WebAssembly guest code as well as time spent in the Wasmtime host and potentially even time spent in the kernel. This provides a comprehensive view of performance. -If the native profiling tools don't work for you, Wasmtime also provides a -[cross-platform profiler](./examples-profiling-guest.md). This profiler can only -measure time spent in WebAssembly guest code, and its timing measurements are -not as precise as the native profilers. However, it works on every platform that -Wasmtime supports. +The cross-platform-profiler can only measure time spent in WebAssembly guest +code, and its timing measurements are not as precise as the native profilers. +However, it works on every platform that Wasmtime supports. + diff --git a/docs/examples-rust-embed.md b/docs/examples-rust-embed.md deleted file mode 100644 index 14b4b1ebbe..0000000000 --- a/docs/examples-rust-embed.md +++ /dev/null @@ -1,6 +0,0 @@ -# Embedding in Rust - -This section is intended to showcase the Rust embedding API for Wasmtime. This -is done through the [`wasmtime` crate](https://crates.io/crates/wasmtime). In -addition to browsing the following examples you can also browse the [full API -documentation](https://docs.rs/wasmtime). diff --git a/docs/examples.md b/docs/examples.md index f2cc544ef8..1ab9078d16 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,4 +1,4 @@ -# Examples +# Further Examples The examples contained in this section explain how to use Wasmtime in several common scenarios. diff --git a/docs/lang-c.md b/docs/lang-c.md index a40cd10d12..5db21c9277 100644 --- a/docs/lang-c.md +++ b/docs/lang-c.md @@ -1,7 +1,6 @@ -# C +# Embedding in C -... more coming soon +This section is intended to showcase the C embedding API for Wasmtime. Full +reference documentation for the C API [can be found online][online]. -In the meantime, have a look at the [C API docs]. - -[C API docs]: https://bytecodealliance.github.io/wasmtime/c-api/ +[online]: https://bytecodealliance.github.io/wasmtime/c-api/ diff --git a/docs/lang-rust.md b/docs/lang-rust.md index cc5d57248d..9199605a14 100644 --- a/docs/lang-rust.md +++ b/docs/lang-rust.md @@ -3,18 +3,16 @@ This document shows an example of how to embed Wasmtime using the [Rust API][apidoc] to execute a simple wasm program. Be sure to also check out the [full API documentation][apidoc] for a full listing of what the [`wasmtime` -crate][wasmtime] has to offer and the [book examples for -Rust](./examples-rust-embed.md) for more information. +crate][wasmtime] has to offer. [apidoc]: https://bytecodealliance.github.io/wasmtime/api/wasmtime/ [wasmtime]: https://crates.io/crates/wasmtime ## Creating the WebAssembly to execute -Creation of a WebAssembly file is generally covered by the [Writing -WebAssembly chapter](./wasm.md), so we'll just assume that you've already got a -wasm file on hand for the rest of this tutorial. To make things simple we'll -also just assume you've got a `hello.wat` file which looks like this: +We'll just assume that you've already got a wasm file on hand for the rest of +this tutorial. To make things simple we'll also just assume you've got a +`hello.wat` file which looks like this: ```wat (module diff --git a/docs/lang.md b/docs/lang.md index 94e38d1b08..be222bf6ea 100644 --- a/docs/lang.md +++ b/docs/lang.md @@ -1,4 +1,4 @@ -# Using WebAssembly from your Language +# Using the Wasmtime API Wasmtime can be used as a library to embed WebAssembly execution support within applications. Wasmtime is written in Rust, but bindings are available