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

• Marine Book
• Marine Examples
• Quickstart

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.