wasmer/wasm_c_api/mod.rs
1//! Implementation of the [official WebAssembly C
2//! API](https://github.com/WebAssembly/wasm-c-api) for Wasmer.
3//!
4//! We would like to remind the reader that this official standard can
5//! be characterized as a _living standard_. As such, the API is not
6//! yet stable, even though it shows maturity over time. The API is
7//! described by the `wasm.h` C header, which is included by
8//! `wasmer.h` C header file (which contains extension of the
9//! standard API, for example to provide WASI or vendor-specific
10//! features).
11//!
12//! # Quick Guide
13//!
14//! Usually, the user first needs to create an [`engine`] and a
15//! [`store`]. Once it's done, the user needs to create a [`module`]
16//! and then [instantiate][instance] it. When instantiating the
17//! module, the user is able to pass a set of
18//! [imports][externals]. With an instance, the user is able to call
19//! the [exports][instance::wasm_instance_exports].
20//!
21//! Every module comes with examples and entry points to guide the
22//! discovery of this API.
23
24/// `Context`.
25mod function_env;
26
27/// Private Rust macros.
28#[macro_use]
29mod macros;
30
31/// An engine drives the compilation and the runtime.
32///
33/// Entry points: A default engine is created with
34/// [`wasm_engine_new`][engine::wasm_engine_new] and freed with
35/// [`wasm_engine_delete`][engine::wasm_engine_delete].
36///
37/// # Example
38///
39/// The simplest way to get a default engine is the following:
40///
41/// ```rust
42/// # use inline_c::assert_c;
43/// # fn main() {
44/// # (assert_c! {
45/// # #include "tests/wasmer.h"
46/// #
47/// int main() {
48/// // Create the engine.
49/// wasm_engine_t* engine = wasm_engine_new();
50///
51/// // Check we have a valid engine!
52/// assert(engine);
53///
54/// // Free everything.
55/// wasm_engine_delete(engine);
56///
57/// return 0;
58/// }
59/// # })
60/// # .success();
61/// # }
62/// ```
63///
64/// To configure the engine, see the [`wasm_config_new`][engine::wasm_config_new].
65pub mod engine;
66
67/// cbindgen:ignore
68pub mod externals;
69
70/// A WebAssembly instance is a stateful, executable instance of a
71/// WebAssembly module.
72///
73/// Instance objects contain all the exported WebAssembly functions,
74/// memories, tables and globals that allow interacting with
75/// WebAssembly.
76///
77/// Entry points: A WebAssembly instance is created with
78/// [`wasm_instance_new`][instance::wasm_instance_new] and freed with
79/// [`wasm_instance_delete`][instance::wasm_instance_delete].
80///
81/// # Example
82///
83/// The simplest way to instantiate a Wasm module is the following:
84///
85/// ```rust
86/// # use inline_c::assert_c;
87/// # fn main() {
88/// # (assert_c! {
89/// # #include "tests/wasmer.h"
90/// #
91/// int main() {
92/// // Create the engine and the store.
93/// wasm_engine_t* engine = wasm_engine_new();
94/// wasm_store_t* store = wasm_store_new(engine);
95///
96/// // Create a WebAssembly module from a WAT definition.
97/// wasm_byte_vec_t wat;
98/// wasmer_byte_vec_new_from_string(&wat, "(module)");
99/// wasm_byte_vec_t wasm;
100/// wat2wasm(&wat, &wasm);
101///
102/// // Create the module.
103/// wasm_module_t* module = wasm_module_new(store, &wasm);
104/// assert(module);
105///
106/// // Instantiate the module.
107/// wasm_extern_vec_t imports = WASM_EMPTY_VEC;
108/// wasm_trap_t* trap = NULL;
109///
110/// wasm_instance_t* instance = wasm_instance_new(store, module, &imports, &trap);
111/// assert(instance);
112///
113/// // Now do something with the instance, like calling the
114/// // exports with `wasm_instance_exports`.
115///
116/// // Free everything.
117/// wasm_instance_delete(instance);
118/// wasm_module_delete(module);
119/// wasm_byte_vec_delete(&wasm);
120/// wasm_byte_vec_delete(&wat);
121/// wasm_store_delete(store);
122/// wasm_engine_delete(engine);
123///
124/// return 0;
125/// }
126/// # })
127/// # .success();
128/// # }
129/// ```
130///
131/// cbindgen:ignore
132pub mod instance;
133
134/// Host-side import helpers for guests that import the WebAssembly C API.
135///
136/// cbindgen:ignore
137pub mod imports;
138
139/// A WebAssembly module contains stateless WebAssembly code that has
140/// already been compiled and can be instantiated multiple times.
141///
142/// Entry points: A WebAssembly module is created with
143/// [`wasm_module_new`][module::wasm_module_new] and freed with
144/// [`wasm_module_delete`][module::wasm_module_delete].
145///
146/// # Example
147///
148/// ```rust
149/// # use inline_c::assert_c;
150/// # fn main() {
151/// # (assert_c! {
152/// # #include "tests/wasmer.h"
153/// #
154/// int main() {
155/// // Create the engine and the store.
156/// wasm_engine_t* engine = wasm_engine_new();
157/// wasm_store_t* store = wasm_store_new(engine);
158///
159/// // Create a WebAssembly module from a WAT definition.
160/// wasm_byte_vec_t wat;
161/// wasmer_byte_vec_new_from_string(&wat, "(module)");
162/// wasm_byte_vec_t wasm;
163/// wat2wasm(&wat, &wasm);
164///
165/// // Create the module.
166/// wasm_module_t* module = wasm_module_new(store, &wasm);
167///
168/// // It works!
169/// assert(module);
170///
171/// // Free everything.
172/// wasm_byte_vec_delete(&wasm);
173/// wasm_byte_vec_delete(&wat);
174/// wasm_module_delete(module);
175/// wasm_store_delete(store);
176/// wasm_engine_delete(engine);
177///
178/// return 0;
179/// }
180/// # })
181/// # .success();
182/// # }
183/// ```
184///
185/// cbindgen:ignore
186pub mod module;
187
188/// A store represents all global state that can be manipulated by
189/// WebAssembly programs. It consists of the runtime representation of
190/// all instances of functions, tables, memories, and globals that
191/// have been allocated during the lifetime of the abstract machine.
192///
193/// The store holds the [engine] (that is —amongst many things— used to
194/// compile the Wasm bytes into a valid [module] artifact), in addition
195/// to extra private types.
196///
197/// Entry points: A store is created with
198/// [`wasm_store_new`][store::wasm_store_new] and freed with
199/// [`wasm_store_delete`][store::wasm_store_delete]. To customize the
200/// engine the store holds, see
201/// [`wasm_config_new`][engine::wasm_config_new].
202///
203/// # Example
204///
205/// ```rust
206/// # use inline_c::assert_c;
207/// # fn main() {
208/// # (assert_c! {
209/// # #include "tests/wasmer.h"
210/// #
211/// int main() {
212/// // Create the engine.
213/// wasm_engine_t* engine = wasm_engine_new();
214///
215/// // Create the store.
216/// wasm_store_t* store = wasm_store_new(engine);
217///
218/// // It works!
219/// assert(store);
220///
221/// // Free everything.
222/// wasm_store_delete(store);
223/// wasm_engine_delete(engine);
224///
225/// return 0;
226/// }
227/// # })
228/// # .success();
229/// # }
230/// ```
231///
232/// cbindgen:ignore
233pub mod store;
234
235/// A trap represents an error which stores trace message with
236/// backtrace.
237///
238/// # Example
239///
240/// ```rust
241/// # use inline_c::assert_c;
242/// # fn main() {
243/// # (assert_c! {
244/// # #include "tests/wasmer.h"
245/// #
246/// int main() {
247/// // Create an engine and a store.
248/// wasm_engine_t* engine = wasm_engine_new();
249/// wasm_store_t* store = wasm_store_new(engine);
250///
251/// // Create the trap message.
252/// wasm_message_t message;
253/// wasm_name_new_from_string_nt(&message, "foobar");
254///
255/// // Create the trap with its message.
256/// // The backtrace will be generated automatically.
257/// wasm_trap_t* trap = wasm_trap_new(store, &message);
258/// assert(trap);
259///
260/// wasm_name_delete(&message);
261///
262/// // Do something with the trap.
263///
264/// // Free everything.
265/// wasm_trap_delete(trap);
266/// wasm_store_delete(store);
267/// wasm_engine_delete(engine);
268///
269/// return 0;
270/// }
271/// # })
272/// # .success();
273/// # }
274/// ```
275///
276/// Usually, a trap is returned from a host function (an imported
277/// function).
278///
279/// cbindgen:ignore
280pub mod trap;
281
282/// cbindgen:ignore
283pub mod types;
284
285/// This module contains _unstable non-standard_ C API.
286///
287/// Use them at your own risks. The API is subject to change or to
288/// break without any plan to keep any compatibility :-).
289pub mod unstable;
290
291/// Possible runtime values that a WebAssembly module can either
292/// consume or produce.
293///
294/// cbindgen:ignore
295pub mod value;
296
297/// Wasmer-specific API to get or query the version of this Wasm C API.
298///
299/// The `wasmer.h` file provides the `WASMER_VERSION`,
300/// `WASMER_VERSION_MAJOR`, `WASMER_VERSION_MINOR`,
301/// `WASMER_VERSION_PATCH` and `WASMER_VERSION_PRE`
302/// constants. However, in absence of this header file, it is possible
303/// to retrieve the same information with their respective functions,
304/// namely [`wasmer_version`][version::wasmer_version],
305/// [`wasmer_version_major`][version::wasmer_version_major],
306/// [`wasmer_version_minor`][version::wasmer_version_minor],
307/// [`wasmer_version_patch`][version::wasmer_version_patch], and
308/// [`wasmer_version_pre`][version::wasmer_version_pre].
309///
310/// # Example
311///
312/// ```rust
313/// # use inline_c::assert_c;
314/// # fn main() {
315/// # (assert_c! {
316/// # #include "tests/wasmer.h"
317/// # #include <string.h>
318/// #
319/// int main() {
320/// // Get and check the version.
321/// const char* version = wasmer_version();
322/// assert(strcmp(version, WASMER_VERSION) == 0);
323///
324/// // No need to free the string. It's statically allocated on
325/// // the Rust side.
326///
327/// return 0;
328/// }
329/// # })
330/// # .success();
331/// # }
332/// ```
333pub mod version;
334
335#[cfg(feature = "wasi")]
336pub mod wasi;
337
338/// Wasmer-specific API to transform the WAT format into Wasm bytes.
339///
340/// It is used mostly for testing or for small program purposes.
341///
342/// # Example
343///
344/// ```rust
345/// # use inline_c::assert_c;
346/// # fn main() {
347/// # (assert_c! {
348/// # #include "tests/wasmer.h"
349/// #
350/// int main() {
351/// // Our WAT module.
352/// wasm_byte_vec_t wat;
353/// wasm_byte_vec_new(&wat, 8, "(module)");
354///
355/// // Our Wasm bytes.
356/// wasm_byte_vec_t wasm;
357/// wat2wasm(&wat, &wasm);
358///
359/// // It works!
360/// assert(wasm.size > 0);
361///
362/// // Free everything.
363/// wasm_byte_vec_delete(&wasm);
364/// wasm_byte_vec_delete(&wat);
365///
366/// return 0;
367/// }
368/// # })
369/// # .success();
370/// # }
371/// ```
372#[cfg(feature = "wat")]
373pub mod wat;