1# Example: Minimal Platform Build of Wasmtime
2
3This example is a showcase of what it looks like to build Wasmtime with a
4minimal set of platform dependencies. This might be suitable when running
5WebAssembly outside of Linux on a smaller system with a custom operating system
6for example. Support here is built on Wasmtime's support of "custom platforms"
7and more details can be found [online as
8well](https://docs.wasmtime.dev/examples-minimal.html).
9
10The example is organized into a few locations:
11
12* `examples/min-platform/embedding/{Cargo.toml,src}` - source code for the
13  embedding of Wasmtime itself. This is compiled to the target architecture
14  and will have a minimal set of dependencies.
15
16* `examples/min-platform/embedding/wasmtime-platform.{h,c}` - an example
17  implementation of the platform dependencies that Wasmtime requires. This is
18  defined and documented in
19  `crates/wasmtime/src/runtime/vm/sys/custom/capi.rs`. The example here
20  implements the required functions with Linux syscalls. Note that by default
21  most of the file is not necessary to implement and is gated by
22  `WASMTIME_VIRTUAL_MEMORY` and `WASMTIME_NATIVE_SIGNALS`. These correspond
23  to the `custom-virtual-memory` and `custom-native-signals` crate features of
24  `wasmtime` which are off-by-default and are optional performance
25  optimizations.
26
27* `examples/min-platform/{Cargo.toml,src}` - an example "host embedding" which
28  loads and runs the `embedding` from above. This is a bit contrived and mostly
29  serves as a bit of a test case for Wasmtime itself to execute in CI. The
30  general idea though is that this is a Linux program which will load the
31  `embedding` project above and execute it to showcase that the code works.
32
33* `examples/min-platform/build.sh` - a script to build/run this example.
34
35Taken together this example is unlikely to satisfy any one individual use case
36but should set up the scaffolding to show how Wasmtime can be built for a
37nonstandard platform. Wasmtime effectively requires one pointer of thread-local
38memory and otherwise all other dependencies can be internalized.
39
40## Description
41
42This example will compile Wasmtime to any Rust target specified. The embedding
43will run a few small examples of WebAssembly modules and then return. This
44example is built in Wasmtime's CI with `x86_64-unknown-none` for example as a
45Rust target.
46
47The host for this is a Linux program which supplies the platform dependencies
48that the embedding requires, for example the `wasmtime_*` symbols. This host
49program will load the embedding and execute it. This is mostly specific to
50executing this example in CI and is not necessarily representative of a "real"
51embedding where you'd probably use static linking instead of dynamic linking
52for example at the very least.
53
54## Running this example
55
56This example can be built and run with the `./build.sh` script in this
57directory.
58