Skip to content

fluencelabs/marine-rs-sdk

Repository files navigation

Marine Rust SDK

crates.io version

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:

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
  • 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.