Skip to content

Commit

Permalink
Reorder book-based documentation (#8130)
Browse files Browse the repository at this point in the history
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
    #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).
  • Loading branch information
rikhuijzer authored Mar 14, 2024
1 parent 34f504c commit 310e667
Show file tree
Hide file tree
Showing 9 changed files with 40 additions and 53 deletions.
41 changes: 20 additions & 21 deletions docs/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -19,29 +16,31 @@
- [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)
- [WASI](./examples-c-wasi.md)
- [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)
Expand Down
2 changes: 1 addition & 1 deletion docs/cli-install.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
7 changes: 1 addition & 6 deletions docs/examples-c-embed.md
Original file line number Diff line number Diff line change
@@ -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
14 changes: 8 additions & 6 deletions docs/examples-profiling.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

6 changes: 0 additions & 6 deletions docs/examples-rust-embed.md

This file was deleted.

2 changes: 1 addition & 1 deletion docs/examples.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Examples
# Further Examples

The examples contained in this section explain how to use Wasmtime in several
common scenarios.
9 changes: 4 additions & 5 deletions docs/lang-c.md
Original file line number Diff line number Diff line change
@@ -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/
10 changes: 4 additions & 6 deletions docs/lang-rust.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/lang.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down

0 comments on commit 310e667

Please sign in to comment.