{"id":29419861,"url":"https://github.com/bytecodealliance/wamr-rust-sdk","last_synced_at":"2025-07-12T01:13:10.731Z","repository":{"id":225248407,"uuid":"764928990","full_name":"bytecodealliance/wamr-rust-sdk","owner":"bytecodealliance","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-07T03:04:31.000Z","size":1305,"stargazers_count":52,"open_issues_count":9,"forks_count":21,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-07-12T00:44:55.868Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bytecodealliance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-02-29T00:50:47.000Z","updated_at":"2025-07-07T14:31:29.000Z","dependencies_parsed_at":"2024-04-01T06:37:53.450Z","dependency_job_id":"083cfc0c-7ea6-4434-b4ed-c13f4a051e7a","html_url":"https://github.com/bytecodealliance/wamr-rust-sdk","commit_stats":null,"previous_names":["bytecodealliance/wamr-rust-sdk"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/bytecodealliance/wamr-rust-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fwamr-rust-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fwamr-rust-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fwamr-rust-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fwamr-rust-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytecodealliance","download_url":"https://codeload.github.com/bytecodealliance/wamr-rust-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytecodealliance%2Fwamr-rust-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264922908,"owners_count":23683705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-12T01:13:09.861Z","updated_at":"2025-07-12T01:13:10.710Z","avatar_url":"https://github.com/bytecodealliance.png","language":"Rust","readme":"# wamr-rust-sdk\n\n## WAMR Rust SDK\n\n### Overview\n\nWAMR Rust SDK provides Rust language bindings for WAMR. It is the wrapper\nof [*wasm_export.h*](../../../core/iwasm/include/wasm_export.h) but with Rust style.\nIt is more convenient to use WAMR in Rust with this crate.\n\nThis crate contains API used to interact with Wasm modules. You can compile\nmodules, instantiate modules, call their export functions, etc.\nPlus, as an embedded of Wasm, you can provide Wasm module functionality by\ncreating host-defined functions.\n\nWAMR Rust SDK includes a [*wamr-sys*](../crates/wamr-sys) crate. It will search for\nthe WAMR runtime source in the path *../..*. And then uses `rust-bindgen` durning\nthe build process to make a .so.\n\nThis crate has similar concepts to the\n[WebAssembly specification](https://webassembly.github.io/spec/core/).\n\n#### Core concepts\n\n- *Runtime*. It is the environment that hosts all the wasm modules. Each process has one runtime instance.\n- *Module*. It is the compiled .wasm or .aot. It can be loaded into runtime and instantiated into instance.\n- *Instance*. It is the running instance of a module. It can be used to call export functions.\n- *Function*. It is the exported function.\n\n#### WASI concepts\n\n- *WASIArgs*. It is used to configure the WASI environment.\n  - *pre-open*. All files and directories in the list will be opened before the .wasm or .aot loaded.\n  - *allowed address*. All ip addresses in the *allowed address* list will be allowed to connect with a socket.\n  - *allowed DNS*.\n\n#### WAMR private concepts\n\n- *loading linking* instead of *instantiation linking*. *instantiation linking* is\nused in Wasm JS API and Wasm C API. It means that every instance has its own, maybe\nvariant, imports. But *loading linking* means that all instances share the same *imports*.\n\n- *RuntimeArg*. Control runtime behavior.\n  - *running mode*.\n  - *allocator*.\n\n- *NativeFunction*.\n\n- *WasmValues*.\n\n### Examples\n\n#### Example: to run a wasm32-wasip1 .wasm\n\n*wasm32-wasip1* is a most common target for Wasm. It means that the .wasm is compiled with\n`cargo build --target wasm32-wasip1` or `wasi-sdk/bin/clang --target wasm32-wasip1`.\n\nSay there is a gcd_wasm32_wasi.wasm which includes a function named *gcd*. It returns the GCD\nof two parameters.\n\nThe rust code to call the function would be:\n\n```rust\nuse wamr_rust_sdk::{\n    runtime::Runtime, module::Module, instance::Instance, function::Function,\n    value::WasmValue, RuntimeError\n};\nuse std::path::PathBuf;\n\nfn main() -\u003e Result\u003c(), RuntimeError\u003e {\n    let runtime = Runtime::new()?;\n\n    let mut d = PathBuf::from(env!(\"CARGO_MANIFEST_DIR\"));\n    d.push(\"resources/test\");\n    d.push(\"gcd_wasm32_wasi.wasm\");\n\n    let module = Module::from_file(\u0026runtime, d.as_path())?;\n\n    let instance = Instance::new(\u0026runtime, \u0026module, 1024 * 64)?;\n\n    let function = Function::find_export_func(\u0026instance, \"gcd\")?;\n\n    let params: Vec\u003cWasmValue\u003e = vec![WasmValue::I32(9), WasmValue::I32(27)];\n    let result = function.call(\u0026instance, \u0026params)?;\n    assert_eq!(result, WasmValue::I32(9));\n\n    Ok(())\n}\n```\n\n#### Example: more configuration for runtime\n\nWith more configuration, runtime is capable to run .wasm with variant features, like\n\n- Wasm without WASI requirement. Usually, it means that the .wasm is compiled with `-nostdlib`\n  or `--target wasm32-unknown-unknown`\n- Configure runtime.\n- Provides host-defined functions to meet import requirements.\n\nSay there is an add_extra_wasm32_wasi.wasm. Its exported function, `add()`,\nrequires an imported function, `extra()`, during the execution. The `add()`\nadds two parameters and the result of `extra()` . It is like `a + b + extra()`.\n\nThe rust code to call the *add* function is like this:\n\n```rust\nuse wamr_rust_sdk::{\n    runtime::Runtime, module::Module, instance::Instance, function::Function,\n    value::WasmValue, RuntimeError\n};\nuse std::path::PathBuf;\nuse std::ffi::c_void;\n\nextern \"C\" fn extra() -\u003e i32 {\n    100\n}\n\nfn main() -\u003e Result\u003c(), RuntimeError\u003e {\n    let runtime = Runtime::builder()\n        .use_system_allocator()\n        .register_host_function(\"extra\", extra as *mut c_void)\n        .build()?;\n\n    let mut d = PathBuf::from(env!(\"CARGO_MANIFEST_DIR\"));\n    d.push(\"resources/test\");\n    d.push(\"add_extra_wasm32_wasi.wasm\");\n    let module = Module::from_file(\u0026runtime, d.as_path())?;\n\n    let instance = Instance::new(\u0026runtime, \u0026module, 1024 * 64)?;\n\n    let function = Function::find_export_func(\u0026instance, \"add\")?;\n\n    let params: Vec\u003cWasmValue\u003e = vec![WasmValue::I32(9), WasmValue::I32(27)];\n    let result = function.call(\u0026instance, \u0026params)?;\n    assert_eq!(result, WasmValue::I32(136));\n\n    Ok(())\n}\n```\n\n### Build Instructions\n\n#### Building `wamr-sys` and `wamr-rust-sdk`\n\nTo build the `wamr-sys` and `wamr-rust-sdk` crates, follow these steps:\n\n1. Ensure you have the Rust toolchain installed.\n2. Clone the repository:\n\n   ```sh\n   git clone https://github.com/bytecodealliance/wamr-rust-sdk.git\n   cd wamr-rust-sdk\n   ```\n\n3. Build the `wamr-sys` crate:\n\n   ```sh\n   cargo build -p wamr-sys\n   ```\n\n4. Build the `wamr-rust-sdk` crate:\n\n   ```sh\n   cargo build\n   ```\n\n#### Preparing a Development and Building Environment\n\n##### For non-espidf targets\n\n1. Prepare the Rust toolchain\n\n2. If targeting a non-linux platform, set `WAMR_BUILD_TARGET` and `WAMR_BUILD_PLATFORM` in the `.cargo/config.toml`:\n\n   ```toml\n   [env]\n   WAMR_BUILD_PLATFORM = \"OS name\"\n   WAMR_BUILD_TARGET = \"CPU architecture\"\n   ```\n\n3. If targeting a platform not supplied by WAMR, refer to the [WAMR porting guide](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/port_wamr.md#wamr-porting-guide) and set `WAMR_BUILD_TARGET`, `WAMR_BUILD_PLATFORM` and `WAMR_SHARED_PLATFORM_CONFIG` in the `.cargo/config.toml` properly.\n\n##### For espidf targets\n\n1. Get the latest information from [The Rust on ESP Book](https://docs.esp-rs.org/book/writing-your-own-application/index.html).\n2. Please make sure you have installed all [prerequisites](https://github.com/esp-rs/esp-idf-template?tab=readme-ov-file#prerequisites) first!\n3. Generate projects from templates following the instructions in [The Rust on ESP Book](https://docs.esp-rs.org/book/writing-your-own-application/generate-project/index.html).\n\n   ``` sh\n   $ cargo generate esp-rs/esp-idf-template cargo\n   # follow prompts from the command\n   ```\n\n4. Add the following configuration to your project's `Cargo.toml`:\n\n   ```toml\n   wamr-rust-sdk = { git = \"https://github.com/bytecodealliance/wamr-rust-sdk\", features = [\"esp-idf\"] }\n\n\n#### BKMs\n\n- [Rust on ESP-IDF \"Hello, World\" template](https://github.com/esp-rs/esp-idf-template?tab=readme-ov-file#rust-on-esp-idf-hello-world-template) is a good example\n- Ensure that `LIBCLANG_PATH` is correctly set (something like: */home/\u003cuser\u003e/.rustup/toolchains/esp/xtensa-esp32-elf-clang/esp-\u003cversion\u003e/esp-clang/lib*, if on a Mac). If not, there might be something wrong with your espup installation.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytecodealliance%2Fwamr-rust-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytecodealliance%2Fwamr-rust-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytecodealliance%2Fwamr-rust-sdk/lists"}