From f8a160901b7553146296e90225b5fa01ac4bec94 Mon Sep 17 00:00:00 2001 From: DieMyst Date: Thu, 16 Jul 2020 18:35:52 +0300 Subject: [PATCH 1/4] readme docs --- README.md | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) diff --git a/README.md b/README.md index 501a1063..4b3c6658 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,134 @@ # Fluence Compute Engine FCE is intended to run various Wasm binaries. At now, it is in the heavily developing phase. + +# Installation +- Clone this project +- `cargo install --path ` + +# Usage +- `fce build` in Rust project + +# HOW TO: Create App with FCE Modules + +## Recommendations: + +- Modules architecture should be upwards from `effectors` (WASI modules) that will work with local binaries, local storage and syscalls to `pure modules` that perform business logic. +- Splitting app to small FCE modules are easier to support, reuse and distribute +- Each module for its own task (npm like) + +## Module project structure + +- Init simple rust project `cargo init --bin` + +- `Config.toml`: +``` +[lib] +name = "wasm_application" +path = "src/lib.rs" +crate-type = ["cdylib"] + +[dependencies] +// logger - if you'll use logging +fluence = { git = "https://github.com/fluencelabs/rust-sdk", features = ["logger"] } +``` + +- Methods that will be used outside this module marked with `#[fce]` +``` +use fluence::fce; + +#[fce] +pub fn get(url: String) -> String { +... +} +``` +- Multiple arguments with primitive Rust types and only one return argument could be used + +- Build project with `fce build` + +- Copy wasm file from `target/wasm32-wasi/debug` to directory with other modules + +- To import other wasm modules to your project use similar code: +``` +#[fce] +#[link(wasm_import_module = "wasm_curl.wasm")] +extern "C" { + #[link_name = "get"] + pub fn curl_get(url: String) -> String; +} + +#[fce] +#[link(wasm_import_module = "wasm_local_storage.wasm")] +extern "C" { + #[link_name = "get"] + pub fn curl_get(url: String) -> String; +} +``` + +## Combine modules to Application + +- Create simple Rust project +- Create `Config.toml` to describe existed wasm modules and give accesses to host binaries and local storage if needed: +``` +core_modules_dir = "wasm/artifacts/modules" + +[[core_module]] + name = "wasm_local_storage_with_curl.wasm" + mem_pages_count = 100 + + [core_module.imports] + curl = "/usr/bin/curl" + + [core_module.wasi] + envs = [] + preopened_files = ["./wasm/artifacts"] + mapped_dirs = { "tmp" = "./wasm/artifacts" } +``` + +`core_modules_dir` - path to directory with all modules. All subsequent paths will be relative to this path + +`[[core_module]]` - modules list + +`name` - wasm file name in `core_modules_dir` + +`mem_pages_count` - a maximum number of Wasm memory pages that loaded module can use. Each Wasm pages is 65536 bytes long + +`[core_module.imports]` - list of available imports + +`curl = "/usr/bin/curl"` - gives possibility to call binary file `/usr/bin/curl` as method `curl` in Rust code + +Import example: +``` +#[link(wasm_import_module = "host")] +extern "C" { + fn curl(ptr: i32, size: i32) -> i32; +} +``` +It is not possible for now to use `String` as arguments. Use tweek for this: +``` +fn call_curl(cmd: String) -> String { + unsafe { + // TODO: better error handling + match curl(cmd.as_ptr() as _, cmd.len() as _) { + 0 => String::from_raw_parts( + fluence::internal::get_result_ptr() as _, + fluence::internal::get_result_size(), + fluence::internal::get_result_size(), + ), + _ => "host ipfs call failed".to_string(), + } + } +} +``` +Call binary with arguments: `call_curl("-vvv ya.ru")` + +`[core_module.wasi]` - this block manages communication with the "outside" world +`env` - environment variables. Usage: `std::env::var("IPFS_ADDR")` +`preopened_files` - list of available directories for loaded modules +`mapped_dirs` - mapping between paths + +Working with files as usual: +``` +fs::write(PathBuf::from("/tmp/somefile"), vec!(1,2,3)); +fs::read(...); +``` \ No newline at end of file From eb45acd95b1cb81479b0fd965dfd5be237696e72 Mon Sep 17 00:00:00 2001 From: DieMyst Date: Sat, 18 Jul 2020 15:44:02 +0300 Subject: [PATCH 2/4] greeting and readme: lib.rs -> main.rs --- README.md | 5 ++--- examples/greeting/wasm/Cargo.toml | 5 ++--- examples/greeting/wasm/src/{lib.rs => main.rs} | 4 ++++ 3 files changed, 8 insertions(+), 6 deletions(-) rename examples/greeting/wasm/src/{lib.rs => main.rs} (97%) diff --git a/README.md b/README.md index 4b3c6658..ee651430 100644 --- a/README.md +++ b/README.md @@ -23,10 +23,9 @@ FCE is intended to run various Wasm binaries. At now, it is in the heavily devel - `Config.toml`: ``` -[lib] +[[bin]] name = "wasm_application" -path = "src/lib.rs" -crate-type = ["cdylib"] +path = "src/main.rs" [dependencies] // logger - if you'll use logging diff --git a/examples/greeting/wasm/Cargo.toml b/examples/greeting/wasm/Cargo.toml index bf3c27ce..01d4efc1 100644 --- a/examples/greeting/wasm/Cargo.toml +++ b/examples/greeting/wasm/Cargo.toml @@ -4,10 +4,9 @@ version = "0.1.0" authors = ["Fluence Labs"] edition = "2018" -[lib] +[[bin]] name = "greeting" -path = "src/lib.rs" -crate-type = ["cdylib"] +path = "src/main.rs" [dependencies] fluence = { git = "https://github.com/fluencelabs/rust-sdk" } diff --git a/examples/greeting/wasm/src/lib.rs b/examples/greeting/wasm/src/main.rs similarity index 97% rename from examples/greeting/wasm/src/lib.rs rename to examples/greeting/wasm/src/main.rs index 736b8065..dcb0c1fa 100644 --- a/examples/greeting/wasm/src/lib.rs +++ b/examples/greeting/wasm/src/main.rs @@ -16,6 +16,10 @@ use fluence::fce; +pub fn main() { + +} + #[fce] pub fn greeting(name: String) -> String { format!("Hi, {}", name) From afa08d9a24c93820eb9a862e366e2d3144b2a433 Mon Sep 17 00:00:00 2001 From: DieMyst Date: Mon, 20 Jul 2020 12:32:02 +0300 Subject: [PATCH 3/4] PR fixes --- README.md | 29 +++++++---------------------- 1 file changed, 7 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index ee651430..d5dcd409 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ FCE is intended to run various Wasm binaries. At now, it is in the heavily devel ## Recommendations: -- Modules architecture should be upwards from `effectors` (WASI modules) that will work with local binaries, local storage and syscalls to `pure modules` that perform business logic. +- Modules architecture should be upwards from `effectors` (modules that persist data and WASI modules) that will work with local binaries, local storage and syscalls to `pure modules` that perform business logic. - Splitting app to small FCE modules are easier to support, reuse and distribute - Each module for its own task (npm like) @@ -32,7 +32,7 @@ path = "src/main.rs" fluence = { git = "https://github.com/fluencelabs/rust-sdk", features = ["logger"] } ``` -- Methods that will be used outside this module marked with `#[fce]` +- Methods that will be exported from this module marked with `#[fce]` ``` use fluence::fce; @@ -41,9 +41,9 @@ pub fn get(url: String) -> String { ... } ``` -- Multiple arguments with primitive Rust types and only one return argument could be used +- Multiple arguments with primitive Rust types (`bool, u8, u16, u32, u64, i8, i16, i32, i64, f32, f64, String, Vec`) and only one return argument could be used -- Build project with `fce build` +- Build project with `fce build` (supports --release and all other cargo flags now) - Copy wasm file from `target/wasm32-wasi/debug` to directory with other modules @@ -100,26 +100,11 @@ Import example: ``` #[link(wasm_import_module = "host")] extern "C" { - fn curl(ptr: i32, size: i32) -> i32; + fn curl(args: String) -> String; } ``` -It is not possible for now to use `String` as arguments. Use tweek for this: -``` -fn call_curl(cmd: String) -> String { - unsafe { - // TODO: better error handling - match curl(cmd.as_ptr() as _, cmd.len() as _) { - 0 => String::from_raw_parts( - fluence::internal::get_result_ptr() as _, - fluence::internal::get_result_size(), - fluence::internal::get_result_size(), - ), - _ => "host ipfs call failed".to_string(), - } - } -} -``` -Call binary with arguments: `call_curl("-vvv ya.ru")` + +Call binary with arguments: `curl("-vvv ya.ru")` `[core_module.wasi]` - this block manages communication with the "outside" world `env` - environment variables. Usage: `std::env::var("IPFS_ADDR")` From 98a3e6871fc2f52205b827f9fb253333bf2be171 Mon Sep 17 00:00:00 2001 From: DieMyst Date: Mon, 20 Jul 2020 12:44:32 +0300 Subject: [PATCH 4/4] cargo fmt --- examples/greeting/wasm/src/main.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/examples/greeting/wasm/src/main.rs b/examples/greeting/wasm/src/main.rs index dcb0c1fa..dcf27182 100644 --- a/examples/greeting/wasm/src/main.rs +++ b/examples/greeting/wasm/src/main.rs @@ -16,9 +16,7 @@ use fluence::fce; -pub fn main() { - -} +pub fn main() {} #[fce] pub fn greeting(name: String) -> String {