6 releases
0.1.5 | May 9, 2021 |
---|---|
0.1.4 | May 6, 2021 |
0.1.3 | Apr 28, 2021 |
#7 in #procedural-macros
36KB
479 lines
Marine Rust SDK
This SDK empowers developers to create general-purpose Wasm modules and combine them in a multi-module setup with the help of interface-types and a shared-nothing linking scheme. The SDK provides all necessary macros and other features to make Wasm developing process as close as possible to the one with the "vanilla" Rust. Compiled modules are intended to run with the Marine runtime.
Usage
The core component of the SDK is the #[marine]
macro that should be used with export functions, external blocks, and structures. Let's consider a simple scenario with a module with one export function:
use marine_rs_sdk::marine;
#[marine]
pub fn greeting(name: String) -> String {
format!("Hi, {}", name)
}
This code imports the Marine SDK and wraps the greeting function with the #[marine]
macro. Every function wrapped in such way will be exported from a compiled Wasm module.
To compile this code to Wasm, you need the Marine CLI tool. If you haven't installed the cli already, use cargo install marine
:
marine build --release
Finally, you obtain a build manifest embedded into a Wasm binary and can interact with a module in the Marine REPL (mrepl). If you don't have it, install it with cargo install mrepl
:
> marine info ./target/wasm32-wasi/release/greeting.wasm
it version: 0.23.1
sdk version: 0.7.0
authors: <user-name>
version: 0.1.0
description:
repository:
build time: 2023-02-15 18:52:37.865550 +00:00 UTC
> mrepl --quiet
1> load greeting ./target/wasm32-wasi/release/greeting.wasm
module successfully loaded into App service
elapsed time: 52.153308ms
2> interface
Application service interface:
greeting:
fn greeting(name: String) -> String
3> call greeting greeting "user"
result: String("Hi, user")
elapsed time: 132.021µs
The complete guide of developing this simple module can be found here.
SDK components
The SDK exports the following major components:
#[marine]
procedure macro that can be applied to- function making it export from a module
- external block making it imported from a module in a Marine-suitable way
- structure, making it usable as an argument of an export or an import function
- call parameters interface intended to provide a set of module start parameters
- mounted binaries interface that can be used to call a CLI tool
- module_manifest macro intended to embed some info into a compiled Wasm
- logging stuff that allows adjusting a Marine logging mechanism
Supported Rust types
At the moment, the #[marine]
macro allows the following Rust types as an argument of export and import functions or the field of a structure:
- one of the following Rust basic types:
bool
,u8
,u16
,u32
,u64
,i8
,i16
,i32
,i64
,f32
,f64
- strings
String
,&str
- a vector of elements of the above types
- a vector composed of vectors of the above type, where recursion is acceptable, e.g., the type
Vec<Vec<Vec<u8>>>
is permissible - a reference of all of the above types
- a structure where all fields are of the basic Rust types
- a structure where all fields are of the above types or other structures build with such a way
Documentation
Also, check our YouTube channel.
Repository structure
- crates
- macro-testing-utils contains internal testing utils
- main contains export_allocator, logger and results modules
- marine-macro is the proc-macro crate for the
#[marine]
macro - marine-macro-impl is the actual realization of the
#[marine]
macro - timestamp-macro is a macro to support timestamp embedding into a compiled Wasm binary
- src contains call_parameters and mounted_binary modules along with reexporting all necessary for a user stuff
Support
Please, file an issue if you find a bug. You can also contact us at Discord or Telegram. We will do our best to resolve the issue ASAP.
Contributing
Any interested person is welcome to contribute to the project. Please, make sure you read and follow some basic rules.
License
All software code is copyright (c) Fluence Labs, Inc. under the Apache-2.0 license.
Dependencies
~20MB
~411K SLoC