README.md
1<div align="center">
2 <h1><code>wasmtime</code></h1>
3
4 <p>
5 <strong>A standalone runtime for
6 <a href="https://webassembly.org/">WebAssembly</a></strong>
7 </p>
8
9 <strong>A <a href="https://bytecodealliance.org/">Bytecode Alliance</a> project</strong>
10</div>
11
12## About
13
14This crate is the Rust embedding API for the [Wasmtime] project: a
15cross-platform engine for running WebAssembly programs. Notable features of
16Wasmtime are:
17
18* **Fast**. Wasmtime is built on the optimizing [Cranelift] code generator to
19 quickly generate high-quality machine code either at runtime or
20 ahead-of-time. Wasmtime's runtime is also optimized for cases such as
21 efficient instantiation, low-overhead transitions between the embedder and
22 wasm, and scalability of concurrent instances.
23
24* **[Secure]**. Wasmtime's development is strongly focused on the correctness of
25 its implementation with 24/7 fuzzing donated by [Google's OSS Fuzz],
26 leveraging Rust's API and runtime safety guarantees, careful design of
27 features and APIs through an [RFC process], a [security policy] in place
28 for when things go wrong, and a [release policy] for patching older versions
29 as well. We follow best practices for defense-in-depth and known
30 protections and mitigations for issues like Spectre. Finally, we're working
31 to push the state-of-the-art by collaborating with academic
32 researchers to formally verify critical parts of Wasmtime and Cranelift.
33
34* **[Configurable]**. Wastime supports a rich set of APIs and build time
35 configuration to provide many options such as further means of restricting
36 WebAssembly beyond its basic guarantees such as its CPU and Memory
37 consumption. Wasmtime also runs in tiny environments all the way up to massive
38 servers with many concurrent instances.
39
40* **[WASI]**. Wasmtime supports a rich set of APIs for interacting with the host
41 environment through the [WASI standard](https://wasi.dev).
42
43* **[Standards Compliant]**. Wasmtime passes the [official WebAssembly test
44 suite](https://github.com/WebAssembly/testsuite), implements the [official C
45 API of wasm](https://github.com/WebAssembly/wasm-c-api), and implements
46 [future proposals to WebAssembly](https://github.com/WebAssembly/proposals) as
47 well. Wasmtime developers are intimately engaged with the WebAssembly
48 standards process all along the way too.
49
50[Wasmtime]: https://github.com/bytecodealliance/wasmtime
51[Cranelift]: https://github.com/bytecodealliance/wasmtime/blob/main/cranelift/README.md
52[Google's OSS Fuzz]: https://google.github.io/oss-fuzz/
53[security policy]: https://bytecodealliance.org/security
54[RFC process]: https://github.com/bytecodealliance/rfcs
55[release policy]: https://docs.wasmtime.dev/stability-release.html
56[Secure]: https://docs.wasmtime.dev/security.html
57[Configurable]: https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html
58[WASI]: https://docs.rs/wasmtime-wasi/latest/wasmtime_wasi/
59[Standards Compliant]: https://docs.wasmtime.dev/stability-wasm-proposals.html
60
61## Example
62
63An example of using the Wasmtime embedding API for running a small WebAssembly
64module might look like:
65
66```rust
67use anyhow::Result;
68use wasmtime::*;
69
70fn main() -> Result<()> {
71 // Modules can be compiled through either the text or binary format
72 let engine = Engine::default();
73 let wat = r#"
74 (module
75 (import "host" "host_func" (func $host_hello (param i32)))
76
77 (func (export "hello")
78 i32.const 3
79 call $host_hello)
80 )
81 "#;
82 let module = Module::new(&engine, wat)?;
83
84 // Create a `Linker` which will be later used to instantiate this module.
85 // Host functionality is defined by name within the `Linker`.
86 let mut linker = Linker::new(&engine);
87 linker.func_wrap("host", "host_func", |caller: Caller<'_, u32>, param: i32| {
88 println!("Got {} from WebAssembly", param);
89 println!("my host state is: {}", caller.data());
90 })?;
91
92 // All wasm objects operate within the context of a "store". Each
93 // `Store` has a type parameter to store host-specific data, which in
94 // this case we're using `4` for.
95 let mut store = Store::new(&engine, 4);
96 let instance = linker.instantiate(&mut store, &module)?;
97 let hello = instance.get_typed_func::<(), ()>(&mut store, "hello")?;
98
99 // And finally we can call the wasm!
100 hello.call(&mut store, ())?;
101
102 Ok(())
103}
104```
105
106More examples and information can be found in the `wasmtime` crate's [online
107documentation](https://docs.rs/wasmtime) as well.
108
109## Documentation
110
111[�� Read the Wasmtime guide here! ��][guide]
112
113The [wasmtime guide][guide] is the best starting point to learn about what
114Wasmtime can do for you or help answer your questions about Wasmtime. If you're
115curious in contributing to Wasmtime, [it can also help you do
116that][contributing]!
117
118For information on supported versions of Wasmtime see [the corresponding online book
119documentation](https://docs.wasmtime.dev/stability-release.html#current-versions).
120
121[contributing]: https://bytecodealliance.github.io/wasmtime/contributing.html
122[guide]: https://bytecodealliance.github.io/wasmtime
123