wasmedge_sdk/lib.rs
1#![doc(
2 html_logo_url = "https://github.com/cncf/artwork/blob/master/projects/wasm-edge-runtime/icon/color/wasm-edge-runtime-icon-color.png?raw=true",
3 html_favicon_url = "https://raw.githubusercontent.com/cncf/artwork/49169bdbc88a7ce3c4a722c641cc2d548bd5c340/projects/wasm-edge-runtime/icon/color/wasm-edge-runtime-icon-color.svg"
4)]
5// If the version of rust used is less than v1.63, please uncomment the follow attribute.
6// #![feature(explicit_generic_args_with_impl_trait)]
7#![allow(clippy::vec_init_then_push)]
8#![cfg_attr(docsrs, feature(doc_cfg))]
9
10//! # Overview
11//!
12//! WasmEdge Rust SDK provides idiomatic [Rust](https://www.rust-lang.org/) language bindings for [WasmEdge](https://wasmedge.org/)
13//!
14//! **Notice:** This project is still under active development and not guaranteed to have a stable API.
15//!
16//! - [WasmEdge website](https://wasmedge.org/)
17//! - [WasmEdge Docs](https://wasmedge.org/docs/)
18//! - [WasmEdge GitHub Page](https://github.com/WasmEdge/WasmEdge)
19//! - [WasmEdge Rust SDK GitHub Page](https://github.com/WasmEdge/wasmedge-rust-sdk)
20//! - [WasmEdge Rust SDK Examples](https://github.com/second-state/wasmedge-rustsdk-examples)
21//!
22//! ## Get Started
23//!
24//! Since this crate depends on the WasmEdge C API, it needs to be installed in your system first. Please refer to [WasmEdge Installation and Uninstallation](https://wasmedge.org/book/en/quick_start/install.html) to install the WasmEdge library. The versioning table below shows the version of the WasmEdge library required by each version of the `wasmedge-sdk` crate.
25//!
26//! | wasmedge-sdk | WasmEdge lib | wasmedge-sys | wasmedge-types| wasmedge-macro| async-wasi|
27//! | :-----------: | :-----------: | :-----------: | :-----------: | :-----------: | :-------: |
28//! | 0.17.1 | 0.17.1 | 0.21.0 | 0.6.1 | 0.6.1 | 0.2.2 |
29//! | 0.16.1 | 0.16.1 | 0.20.0 | 0.6.0 | 0.6.1 | 0.2.1 |
30//! | 0.14.1 | 0.14.1 | 0.19.4 | 0.6.0 | 0.6.1 | 0.2.1 |
31//! | 0.14.0 | 0.14.0 | 0.19.0 | 0.6.0 | 0.6.1 | 0.2.0 |
32//! | 0.13.5-newapi | 0.13.5 | 0.18.0 | 0.5.0 | 0.6.1 | 0.2.0 |
33//! | 0.13.2 | 0.13.5 | 0.17.5 | 0.4.4 | 0.6.1 | 0.1.0 |
34//! | 0.13.1 | 0.13.5 | 0.17.4 | 0.4.4 | 0.6.1 | 0.1.0 |
35//! | 0.13.0 | 0.13.5 | 0.17.3 | 0.4.4 | 0.6.1 | 0.1.0 |
36//! | 0.12.2 | 0.13.4 | 0.17.2 | 0.4.4 | 0.6.1 | 0.1.0 |
37//! | 0.12.1 | 0.13.4 | 0.17.1 | 0.4.4 | 0.6.1 | 0.1.0 |
38//! | 0.12.0 | 0.13.4 | 0.17.0 | 0.4.4 | 0.6.1 | 0.1.0 |
39//! | 0.11.2 | 0.13.3 | 0.16.2 | 0.4.3 | 0.6.1 | 0.1.0 |
40//! | 0.11.0 | 0.13.3 | 0.16.0 | 0.4.3 | 0.6.0 | 0.0.3 |
41//! | 0.10.1 | 0.13.3 | 0.15.1 | 0.4.2 | 0.5.0 | 0.0.2 |
42//! | 0.10.0 | 0.13.2 | 0.15.0 | 0.4.2 | 0.5.0 | 0.0.2 |
43//! | 0.9.0 | 0.13.1 | 0.14.0 | 0.4.2 | 0.4.0 | 0.0.1 |
44//! | 0.9.0 | 0.13.0 | 0.14.0 | 0.4.2 | 0.4.0 | 0.0.1 |
45//! | 0.8.1 | 0.12.1 | 0.13.1 | 0.4.1 | 0.3.0 | - |
46//! | 0.8.0 | 0.12.0 | 0.13.0 | 0.4.1 | 0.3.0 | - |
47//! | 0.7.1 | 0.11.2 | 0.12.2 | 0.3.1 | 0.3.0 | - |
48//! | 0.7.0 | 0.11.2 | 0.12 | 0.3.1 | 0.3.0 | - |
49//! | 0.6.0 | 0.11.2 | 0.11 | 0.3.0 | 0.2.0 | - |
50//! | 0.5.0 | 0.11.1 | 0.10 | 0.3.0 | 0.1.0 | - |
51//! | 0.4.0 | 0.11.0 | 0.9 | 0.2.1 | - | - |
52//! | 0.3.0 | 0.10.1 | 0.8 | 0.2 | - | - |
53//! | 0.1.0 | 0.10.0 | 0.7 | 0.1 | - | - |
54//!
55//!
56//! WasmEdge Rust SDK will automatically search for the WasmEdge library in your system. Alternatively you can set the `WASMEDGE_DIR` environment variable to the path of the WasmEdge library (or the `WASMEDGE_INCLUDE_DIR` and `WASMEDGE_LIB_DIR` variables for more fine-grained control). If you want to use a local `cmake` build of WasmEdge you can set the `WASMEDGE_BUILD_DIR` instead.
57//!
58//! WasmEdge Rust SDK will search for the WasmEdge library in the following paths in order:
59//!
60//! - `$WASMEDGE_[INCLUDE|LIB]_DIR`
61//! - `$WASMEDGE_DIR`
62//! - `$WASMEDGE_BUILD_DIR`
63//! - `$HOME/.wasmedge`
64//! - `/usr/local`
65//! - `$HOME/.local`
66//!
67//! When the `standalone` feature is enabled the correct library will be downloaded during build time and the previous locations are ignored. You can specify a proxy for the download process using the `WASMEDGE_STANDALONE_PROXY`, `WASMEDGE_STANDALONE_PROXY_USER` and `WASMEDGE_STANDALONE_PROXY_PASS` environment variables. You can set the `WASMEDGE_STANDALONE_ARCHIVE` environment variable to use a local archive instead of downloading one.
68//! The following architectures are supported for automatic downloads:
69//!
70//! | os | libc | architecture | linking type |
71//! | :---: | :-----: | :-----------------: | :-------------: |
72//! | macos | - | `x86_64`, `aarch64` | dynamic |
73//! | linux | `glibc` | `x86_64`, `aarch64` | static, dynamic |
74//! | linux | `musl` | `x86_64`, `aarch64` | static |
75//!
76//! This crate uses `rust-bindgen` during the build process. If you would like to use an external `rust-bindgen` you can set the `WASMEDGE_RUST_BINDGEN_PATH` environment variable to the `bindgen` executable path. This is particularly useful in systems like Alpine Linux (see [rust-lang/rust-bindgen#2360](https://github.com/rust-lang/rust-bindgen/issues/2360#issuecomment-1595869379), [rust-lang/rust-bindgen#2333](https://github.com/rust-lang/rust-bindgen/issues/2333)).
77//!
78//! **Notice:** The minimum supported Rust version is 1.71.
79//!
80//! ## API Reference
81//!
82//! - [API Reference](https://wasmedge.github.io/wasmedge-rust-sdk/wasmedge_sdk/index.html)
83//! - [Async API Reference](https://second-state.github.io/wasmedge-async-rust-sdk/wasmedge_sdk/index.html)
84//!
85//! ## Examples
86//!
87//! The [Examples of WasmEdge RustSDK](https://github.com/second-state/wasmedge-rustsdk-examples) repo contains a number of examples that demonstrate how to use the WasmEdge Rust SDK.
88//!
89//! ## Contributing
90//!
91//! Please read the [contribution guidelines](https://github.com/WasmEdge/wasmedge-rust-sdk/blob/main/CONTRIBUTING.md) on how to contribute code.
92//!
93//! ## License
94//!
95//! This project is licensed under the terms of the [Apache 2.0 license](https://github.com/tensorflow/rust/blob/HEAD/LICENSE).
96//!
97
98#[doc(hidden)]
99#[cfg(feature = "aot")]
100#[cfg_attr(docsrs, doc(cfg(feature = "aot")))]
101mod compiler;
102pub mod config;
103
104// #[cfg(feature = "dock")]
105// pub mod dock;
106
107mod import;
108mod instance;
109#[doc(hidden)]
110pub mod io;
111#[doc(hidden)]
112pub mod log;
113mod module;
114pub mod plugin;
115mod statistics;
116mod store;
117pub mod types;
118pub mod utils;
119#[doc(hidden)]
120pub mod vm;
121
122#[cfg(all(feature = "async", target_os = "linux"))]
123pub mod r#async;
124
125#[doc(inline)]
126#[cfg(feature = "aot")]
127#[cfg_attr(docsrs, doc(cfg(feature = "aot")))]
128pub use compiler::Compiler;
129
130#[doc(inline)]
131pub use import::{AsInstance, ImportObject, ImportObjectBuilder};
132pub use instance::Instance;
133#[doc(inline)]
134pub use io::{WasmVal, WasmValType, WasmValTypeList};
135#[doc(inline)]
136pub use log::LogManager;
137#[doc(inline)]
138pub use module::{ExportType, ImportType, Module};
139#[doc(inline)]
140pub use statistics::Statistics;
141#[doc(inline)]
142pub use store::Store;
143#[doc(inline)]
144pub use vm::Vm;
145
146pub use wasmedge_types::{
147 error, wat2wasm, CompilerOptimizationLevel, CompilerOutputFormat, ExternalInstanceType,
148 FuncType, GlobalType, HostRegistration, MemoryType, Mutability, RefType, RunMode, TableType,
149 ValType, WasmEdgeResult, WasmStandard,
150};
151
152#[cfg(all(feature = "async", target_os = "linux"))]
153#[cfg_attr(docsrs, doc(cfg(all(feature = "async", target_os = "linux"))))]
154pub use wasmedge_macro::async_host_function;
155pub use wasmedge_macro::host_function;
156
157/// WebAssembly value type.
158pub type WasmValue = wasmedge_sys::types::WasmValue;
159
160/// This is a workaround solution to the [`never`](https://doc.rust-lang.org/std/primitive.never.html) type in Rust. It will be replaced by `!` once it is stable.
161pub type NeverType = wasmedge_types::NeverType;
162
163#[doc(hidden)]
164pub type CallingFrame = wasmedge_sys::CallingFrame;
165
166pub mod wasi {
167 pub use wasmedge_sys::WasiModule;
168}