1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
//! Raw API bindings to the [WebAssembly System Interface (WASI)][WASI]
//!
//! [WASI]: https://github.com/WebAssembly/WASI
//!
//! This crate provides Rust API bindings to the imports of [WASI] [worlds] such
//! as:
//!
//! * [`wasi:cli/command`]
//! * [`wasi:http/proxy`]
//!
//! This crate is procedurally generated with the [`wit-bindgen`] bindings
//! generator. Note that generated code is published to crates.io to slim this
//! crate down in terms of build dependencies and resources.
//!
//! # What is WASI?
//!
//! [WASI] is a set of APIs defined for the WebAssembly [Component Model] to
//! help components interact with the outside world. Core WebAssembly has no
//! intrinsic ability to access the host, for example `println!` don't work, but
//! [WASI] defines how to do so with the [`wasi:cli/stdio`] package.
//!
//! [WASI] is defined by an IDL called [WIT] using files that have the extension
//! `*.wit`. [WASI] and [WIT] are themselves then both defined in terms of the
//! [Component Model] in terms of types available and base semantics for APIs.
//!
//! [WASI] defines a number of standard "worlds" which are a description of a
//! what a WebAssembly component can import from an embedding and must export to
//! an embedding. An example world is [`wasi:cli/command`] which is a world for
//! running CLI applications. This world provides basic system utilities such as
//! clocks, a filesystem, CLI arguments, etc. The one required export is a main
//! function.
//!
//! The purpose of this crate is to provide pregenerated bindings to access
//! [WASI]-defined imports available to components.
//!
//! # What is a Component?
//!
//! An important aspect of [WASI] is that it is defined in terms of the
//! [Component Model]. The [Component Model] is a proposal for WebAssembly which
//! is a new format for wasm binaries, a component. A component contains "core"
//! WebAssembly modules (which are [standard WebAssembly modules]) but also has
//! the ability to do more:
//!
//! * A component can contain multiple core WebAssembly modules.
//! * Types used with component imports and exports are more comprehensive than
//! core WebAssembly. Core WebAssembly provides integers and floats, for
//! example, and components build on this and add strings, records (aka a Rust
//! `struct`), variants (aka a Rust `enum`), and resources (think a file
//! descriptor on Unix).
//! * A component provides procedural instructions of how to instantiate its
//! internal core WebAssembly modules with the imports it has.
//!
//! The [Component Model] is a not considered an official WebAssembly standard
//! at this time. It has been in development for 5 years (as of January 2024),
//! however, and the WASI 0.2.0 milestone (more on versioning in a moment) in
//! January 2024 represents a concrete target for ecosystems to use. Runtimes
//! such as [Wasmtime] support the [Component Model] for out-of-browser usage
//! and [jco] is an example of how components can be run in a browser.
//!
//! A full description of the component model is out of scope for this crate's
//! documentation but it suffices to say that [WASI], and this crate, are
//! intended to target components. Components use core WebAssembly modules as an
//! important technical detail, but the final output of this crate is intended
//! to be a component.
//!
//! # What are generated bindings?
//!
//! Above it was seen that [WASI] is defined with [WIT]. These programmatic
//! descriptions of [WASI] APIs are not suitable for use directly in Rust,
//! however these descriptions define how Rust can use them. Each [WIT] function
//! has a defined meaning in core WebAssembly via the [Canonical ABI]. This is a
//! lower level than most users want to operate at, however, so the generated
//! bindings in this crate serve as the bridge.
//!
//! More specifically the generated functions in this crate take the [Canonical
//! ABI] format of [WIT] functions and provide idiomatic Rust functions to call.
//! For example the [`wasi:cli/environment`] definition includes:
//!
//! ```wit
//! interface environment {
//! // ...
//! get-environment: func() -> list<tuple<string, string>>;
//! // ...
//! }
//! ```
//!
//! This corresponds to
//! [`wasi::cli::environment::get_environment`](crate::cli::environment::get_environment).
//!
//! Bindings are pre-generated in this crate with the [`wit-bindgen`] tool. You
//! can also generate your own bindings with [`wit-bindgen`] and [WASI] [WIT]
//! files too, but that's not covered by this crate.
//!
//! # WASI Today and `wasi_snapshot_preview1`
//!
//! This crate is based on the 0.2.0 version of [WASI] APIs. This version of
//! [WASI] was declared "phase 3" (suitable for general use and testing) in
//! January of 2024. Prior to this 0.2.0 "preview2" release of [WASI] there was
//! `wasi_snapshot_preview1`. This previous "preview1" release of [WASI] was
//! circa 2019 and was the initial vision for [WASI] as a standard. Development
//! of [WASI] migrated to the [Component Model] in the meantime.
//!
//! This means that the old `wasi_snapshot_preview1` interfaces are no longer
//! provided by this crate because [WASI] is no longer defined by those
//! interfaces. This includes the historical `*.witx` format which has now been
//! sueprseded. Note that the 0.11.x release series of this crate contains
//! bindings to the historical `wasi_snapshot_preview1` APIs if you're
//! interested in using them.
//!
//! # Crate Organization
//!
//! This crate is currently entirely generated by [`wit-bindgen`] which has the
//! following structure:
//!
//! * Each [WIT] package with bindings corresponds to a top-level module. For
//! example [`wasi:random`] can be found in the [`random`] module.
//! * Each [WIT] interface then corresponds to a submodule of its package's
//! module. For example [`wasi:random/insecure`] can be found in the
//! [`random::insecure`] module.
//! * Each [WIT] function has a Rust function with an idiomatic signature.
//! module. For example [`random::insecure::get_insecure_random_u64`].
//!
//! Note that [WIT] documentation is rendered as rustdoc documentation in these
//! APIs as well.
//!
//! # Using this Crate
//!
//! This crate is intended to be easiest to use with a future
//! `wasm32-wasi-preview2` target added to the Rust compiler. In the meantime
//! it's recommended to use the `wasm32-wasi` target (soon to be renamed to
//! `wasm32-wasi-preview1`) instead:
//!
//! ```sh
//! $ cargo build --target wasm32-wasi
//! ```
//!
//! Note that the output of the `wasm32-wasi` target is a core wasm module, not
//! a component, so to turn it into a component you can use the [`wasm-tools`]
//! CLI in combination with an "adapter module" for the `wasi_snapshot_preview1`
//! APIs that the Rust standard library uses (example adapters can be found on
//! [Wasmtime's release page][adapters] as
//! [`wasi_snapshot_preview1.command.wasm`] for example)
//!
//! ```sh
//! $ wasm-tools component new ./target/wasm32-wasi/debug/my-app.wasm \
//! --adapt ./wasi_snapshot_preview1.command.wasm \
//! -o my-component.wasm
//! ```
//!
//! [worlds]: https://component-model.bytecodealliance.org/design/worlds.html
//! [`wasi:cli/command`]: https://github.com/WebAssembly/wasi-cli/
//! [`wasi:http/proxy`]: https://github.com/WebAssembly/wasi-http
//! [`wasi:cli/stdio`]: https://github.com/WebAssembly/wasi-cli/blob/main/wit/stdio.wit
//! [`wit-bindgen`]: https://github.com/bytecodealliance/wit-bindgen/
//! [Component Model]: https://component-model.bytecodealliance.org/
//! [WIT]: https://component-model.bytecodealliance.org/design/wit.html
//! [standard WebAssembly modules]: https://webassembly.github.io/spec/
//! [Wasmtime]: https://github.com/bytecodealliance/wasmtime
//! [jco]: https://github.com/bytecodealliance/jco
//! [Canonical ABI]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/CanonicalABI.md
//! [`wasi:cli/environment`]: https://github.com/WebAssembly/wasi-cli/blob/main/wit/environment.wit
//! [`wasi:random`]: https://github.com/WebAssembly/wasi-random
//! [`wasi:random/insecure`]: https://github.com/WebAssembly/wasi-random/blob/main/wit/insecure.wit
//! [`wasm-tools`]: https://github.com/bytecodealliance/wasm-tools
//! [adapters]: https://github.com/bytecodealliance/wasmtime/releases
//! [`wasi_snapshot_preview1.command.wasm`]: https://github.com/bytecodealliance/wasmtime/releases/download/v17.0.0/wasi_snapshot_preview1.command.wasm
extern crate std;
pub use *;