From f10cc106e7d16687a06702d7f3396d3070537ff1 Mon Sep 17 00:00:00 2001 From: boneyard93501 Date: Fri, 11 Jun 2021 23:15:29 +0000 Subject: [PATCH] GitBook: [main] 56 pages modified --- SUMMARY.md | 10 ++-- .../knowledge_aquamarine/hll/README.md | 6 ++ .../hll/knowledge_aquamarine_air.md | 55 +++++++++++++++++++ .../knowledge_aquamarine/hll/vm.md | 2 + .../knowledge_aquamarine/marine/marine-cli.md | 35 ++++++++++++ .../marine/marine-repl.md | 35 ++++++++++++ .../marine/marine-rs-sdk.md | 48 ++++++++++++---- knowledge_knowledge/knowledge_tools.md | 21 +++++-- ...k_start_building_from_multiple_services.md | 2 +- 9 files changed, 193 insertions(+), 21 deletions(-) create mode 100644 knowledge_knowledge/knowledge_aquamarine/hll/README.md create mode 100644 knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md create mode 100644 knowledge_knowledge/knowledge_aquamarine/hll/vm.md create mode 100644 knowledge_knowledge/knowledge_aquamarine/marine/marine-cli.md create mode 100644 knowledge_knowledge/knowledge_aquamarine/marine/marine-repl.md diff --git a/SUMMARY.md b/SUMMARY.md index d2ae32d..5d6e7c9 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -24,11 +24,13 @@ * [Concepts](knowledge_knowledge/knowledge_concepts.md) * [Tools](knowledge_knowledge/knowledge_tools.md) * [Aquamarine](knowledge_knowledge/knowledge_aquamarine/README.md) - * [AIR](knowledge_knowledge/knowledge_aquamarine/knowledge_aquamarine_air.md) - * [Aqua](knowledge_knowledge/knowledge_aquamarine/hll.md) - * [Aqua VM](knowledge_knowledge/knowledge_aquamarine/vm.md) + * [Aqua](knowledge_knowledge/knowledge_aquamarine/hll/README.md) + * [Aqua VM](knowledge_knowledge/knowledge_aquamarine/hll/vm.md) + * [AIR](knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md) * [Marine](knowledge_knowledge/knowledge_aquamarine/marine/README.md) - * [Marine-RS-SDK](knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md) + * [Marine CLI](knowledge_knowledge/knowledge_aquamarine/marine/marine-cli.md) + * [Marine Repl](knowledge_knowledge/knowledge_aquamarine/marine/marine-repl.md) + * [Marine Rust SDK](knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md) * [Node](knowledge_knowledge/node/README.md) * [Overview](knowledge_knowledge/node/overview.md) * [Services](knowledge_knowledge/node/knowledge_node_services.md) diff --git a/knowledge_knowledge/knowledge_aquamarine/hll/README.md b/knowledge_knowledge/knowledge_aquamarine/hll/README.md new file mode 100644 index 0000000..630f2b9 --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/hll/README.md @@ -0,0 +1,6 @@ +# Aqua + +## Aquamarine High Level Language + +_**Stay Tuned -- Coming Soon To A Repo Near You**_ + diff --git a/knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md b/knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md new file mode 100644 index 0000000..24d8bb8 --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md @@ -0,0 +1,55 @@ +# AIR + +The Aquamarine Intermediate Representation \(AIR\) is a low level language to program both distributed networks and the services deployed on them. The language is comprised of a small number of instructions: + +* _**call**_: : execution +* _**seq**_ : sequential +* _**par** :_ parallel +* _**fold**_ : iteration +* _**xor** :_ branching & error handling +* _**null**_ : empty instruction + +which operate on _peer-id_ \(location\), _service-id_, and _service method_ over an argument list, see Figure 1. + +**Figure 1: AIR Instruction Definition** ![Execution](../../../.gitbook/assets/air_call_execution_1.png) + +## Instructions + +AIR instructions are intended to launch the execution of a service method as follows: + +1. The method is executed on the peer specified by the peer id \(location\) parameter +2. The peer is expected to have the Wasm service specified by the service id parameter +3. The service must have a callable method specified be the method parameter +4. The arguments specified by the argument list are passed to the method +5. The result of the method returned under the name output name + +**Figure 2: Sequential Instruction** ![Execution](../../../.gitbook/assets/air_sequential_2%20%281%29%20%281%29%20%281%29%20%281%29%20%281%29%20%282%29%20%283%29%20%284%29%20%282%29.png) + +The _**seq**_ instruction takes two instructions at most as its arguments and executes them sequentially, one after the other. + +**Figure 3: Parallel Instruction** ![Execution](../../../.gitbook/assets/air_par_3.png) + +The _**par**_ instruction takes two instructions at most as its arguments and particles may execute on parallel paths iff each service referenced is hosted on a different node otherwise particles execute sequentially + +TODO: add better graphic showing the disticntion of branching vs seq. + +**Figure 4: Fold Instruction** ![Execution](https://github.com/fluencelabs/gitbook-docs/tree/84e814d02d9299034c9c031adf7f081bb59898b9/.gitbook/assets/air_fold_4%20%281%29%20%282%29%20%281%29.png) + +The _**fold**_ instruction iterates over the elements of an array and workds as follows: + +* _**fold**_ instruction takes three arguments: an array, a variable and an instruction +* At each iteration, the variable is assigned an element of the array and the argument-instruction is executed +* The argument-instruction can access the variable and uses the next statement to trigger the next iteration + +Figure 5: Branching Instruction ![Execution](../../../.gitbook/assets/air_xor_5.png) + +This instruction is intended for organizing branches in the flow of execution as well as for handling errors: + +* The _**XOR**_ instruction takes two instructions as its arguments +* The first instruction is executed and if the execution is successful, then the second instruction is ignored +* If the first instruction fails, then the second one is executed. + +**Figure 6: Null Instruction** ![Execution](https://github.com/fluencelabs/gitbook-docs/tree/84e814d02d9299034c9c031adf7f081bb59898b9/.gitbook/assets/air_null_6%20%281%29%20%282%29.png) + +This is an empty instruction: it takes no arguments and does nothing. The _**null**_ instruction is useful for generating code. + diff --git a/knowledge_knowledge/knowledge_aquamarine/hll/vm.md b/knowledge_knowledge/knowledge_aquamarine/hll/vm.md new file mode 100644 index 0000000..ec6c770 --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/hll/vm.md @@ -0,0 +1,2 @@ +# Aqua VM + diff --git a/knowledge_knowledge/knowledge_aquamarine/marine/marine-cli.md b/knowledge_knowledge/knowledge_aquamarine/marine/marine-cli.md new file mode 100644 index 0000000..a00c2ee --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/marine/marine-cli.md @@ -0,0 +1,35 @@ +# Marine CLI + +The [Marine command line tool](https://github.com/fluencelabs/marine) provides the project `marine build` functionality, analogous to `cargo build`, that results in the Rust code to be compiled to _wasm32-wasi_ modules. In addition, `marine` provides utilities to inspect Wasm modules, expose Wasm module attributes or manually set module properties. + +```rust +mbp16~(:|✔) % marine --help +Fluence Marine command line tool 0.6.7 +Fluence Labs + +USAGE: + marine [SUBCOMMAND] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +SUBCOMMANDS: + aqua Shows data types of provided module in a format suitable for Aqua + build Builds provided Rust project to Wasm + help Prints this message or the help of the given subcommand(s) + info Shows manifest and sdk version of the provided Wasm file + it Shows IT of the provided Wasm file + repl Starts Fluence application service REPL + set Sets interface types and version to the provided Wasm file +mbp16~(:|✔) % +``` + + + + + + + + + diff --git a/knowledge_knowledge/knowledge_aquamarine/marine/marine-repl.md b/knowledge_knowledge/knowledge_aquamarine/marine/marine-repl.md new file mode 100644 index 0000000..139c327 --- /dev/null +++ b/knowledge_knowledge/knowledge_aquamarine/marine/marine-repl.md @@ -0,0 +1,35 @@ +# Marine Repl + +[`mrepl`](https://crates.io/crates/mrepl) is a command line tool to locally run a Marine instance to inspect, run, and test Wasm modules and service configurations. We can run the Repl either with `mrepl` or `marine repl` + +```text +mbp16~(:|✔) % mrepl +Welcome to the Marine REPL (version 0.7.2) +Minimal supported versions + sdk: 0.6.0 + interface-types: 0.20.0 + +New version is available! 0.7.2 -> 0.7.4 +To update run: cargo +nightly install mrepl --force + +app service was created with service id = d81a4de5-55c3-4cb7-935c-3d5c6851320d +elapsed time 486.234µs + +1> help +Commands: + +n/new [config_path] create a new service (current will be removed) +l/load load a new Wasm module +u/unload unload a Wasm module +c/call [args] call function with given name from given module +i/interface print public interface of all loaded modules +e/envs print environment variables of a module +f/fs print filesystem state of a module +h/help print this message +q/quit/Ctrl-C exit + +2> +``` + + + diff --git a/knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md b/knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md index 54d6ca6..66b95e3 100644 --- a/knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md +++ b/knowledge_knowledge/knowledge_aquamarine/marine/marine-rs-sdk.md @@ -1,6 +1,6 @@ -# Marine-RS-SDK +# Marine Rust SDK -The marine-rs-sdk empowers developers to write services suitable for peer hosting in peer-to-peer networks using the Marine Virtual Machine by enabling the wasm32-wasi compile target for Marine. For an introduction to writing services with the marine-rs-sdk, see the [Developing Modules And Services](../../../development_development/) section. +The [marine-rs-sdk](https://github.com/fluencelabs/marine-rs-sdk) empowers developers to write services suitable for peer hosting in peer-to-peer networks using the Marine Virtual Machine by enabling the wasm32-wasi compile target for Marine. For an introduction to writing services with the marine-rs-sdk, see the [Developing Modules And Services](../../../development_development/) section. ### API @@ -210,9 +210,10 @@ fn some_function() -> Data { > * wrap a structure with the `[marine]` macro > * all structure fields must be of the `ftype` > * the structure must be pointed to without preceding package import in a function signature, i.e`StructureName` but not `package_name::module_name::StructureName` +> * wrapped structs can be imported from crates {% endhint %} - +#### #### Call Parameters @@ -325,6 +326,8 @@ pub struct MountedBinaryResult { MountedBinaryResult then can be used on a variety of match or conditional tests. + + #### Testing Since we are compiling to a wasm32-wasi target with `ftype` constrains, the basic `cargo test` is not all that useful or even usable for our purposes. To alleviate that limitation, Fluence has introduced the [`[marine-test]` macro ](https://github.com/fluencelabs/marine-rs-sdk/tree/master/crates/marine-test-macro)that does a lot of the heavy lifting to allow developers to use `cargo test` as intended. That is, `[marine-test]` macro generates the necessary code to call Marine, one instance per test function, based on the Wasm module and associated configuration file so that the actual test function is run against the Wasm module not the native code. @@ -375,7 +378,7 @@ The SDK has two useful features: `logger` and `debug`. #### Logger -Using logging is a simple way to assist in the debugging without deploying the module\(s\) to a peer-to-peer network node. The `logger` feature allows you to use a special logger that is based at the top of the [log](https://crates.io/crates/log) crate. +Using logging is a simple way to assist in debugging without deploying the module\(s\) to a peer-to-peer network node. The `logger` feature allows you to use a special logger that is based at the top of the [log](https://crates.io/crates/log) crate. To enable logging please specify the `logger` feature of the Fluence SDK in `Config.toml` and add the [log](https://docs.rs/log/0.4.11/log/) crate: @@ -407,8 +410,6 @@ pub fn put(name: String, file_content: Vec) -> String { } ``` - - In addition to the standard log creation features, the Fluence logger allows the so-called target map to be configured during the initialization step. This allows you to filter out logs by `logging_mask`, which can be set for each module in the service configuration. Let's consider an example: ```rust @@ -431,15 +432,13 @@ pub fn main() { .unwrap(); } -#[fce] +#[marine] pub fn foo() { log::info!(target: "instruction", "this will print if (logging_mask & 1) != 0"); log::info!(target: "data_cache", "this will print if (logging_mask & 2) != 0"); } ``` - - Here, an array called `TARGET_MAP` is defined and provided to a logger in the `main` function of a module. Each entry of this array contains a string \(a target\) and a number that represents the bit position in the 64-bit mask `logging_mask`. When you write a log message request `log::info!`, its target must coincide with one of the strings \(the targets\) defined in the `TARGET_MAP` array. The log will be printed if `logging_mask` for the module has the corresponding target bit set. {% hint style="info" %} @@ -477,7 +476,36 @@ The most important information these logs relates to the `allocate`/`deallocate` - +#### Module Manifest + +The `module_manifest!` macro embeds the Interface Type \(IT\), SDK and Rust project version as well as additional project and build information into Wasm module. For the macro to be usable, it needs to be imported and initialized in the _main.rs_ file: + +```text +// main.rs +use fluence::marine; +use fluence::module_manifest; // import manifest macro + +module_manifest!(); // initialize macro + +fn main() {} + +#[marine] +fn some_function() {} +} +``` + +Using the Marine CLI, we can inspect a module's manifest with `marine info`: + +```rust +mbp16~/localdev/struct-exp(main|…) % marine info -i artifacts/*.wasm +it version: 0.20.1 +sdk version: 0.6.0 +authors: The Fluence Team +version: 0.1.0 +description: foo-wasm, a Marine wasi module +repository: +build time: 2021-06-11 21:08:59.855352 +00:00 UTC +``` diff --git a/knowledge_knowledge/knowledge_tools.md b/knowledge_knowledge/knowledge_tools.md index b76d137..b736f7c 100644 --- a/knowledge_knowledge/knowledge_tools.md +++ b/knowledge_knowledge/knowledge_tools.md @@ -1,14 +1,21 @@ # Tools -## Fluence FCE REPL +## Fluence Marine REPL -\`\`[`fce-repl`](https://crates.io/crates/frepl) is a command line tool \(CLI\) to locally inspect, run, and test module and service configurations making it an invaluable development tool. +[`mrepl`](https://crates.io/crates/mrepl) is a command line tool \(CLI\) to locally run a Marine instance to inspect, run, and test module and service configurations. ```text -mbp16~(:|✔) % fce-repl -Welcome to the FCE REPL (version 0.5.2) -app service was created with service id = 2321fc56-8cb9-497a-8abb-03d04665e1cc -elapsed time 282.52µs +mbp16~(:|✔) % mrepl +Welcome to the Marine REPL (version 0.7.2) +Minimal supported versions + sdk: 0.6.0 + interface-types: 0.20.0 + +New version is available! 0.7.2 -> 0.7.4 +To update run: cargo +nightly install mrepl --force + +app service was created with service id = d81a4de5-55c3-4cb7-935c-3d5c6851320d +elapsed time 486.234µs 1> help Commands: @@ -22,6 +29,8 @@ e/envs print environment variables of a modul f/fs print filesystem state of a module h/help print this message q/quit/Ctrl-C exit + +2> ``` ## Fluence Proto Distributor: FLDIST diff --git a/quick_start/quick_start_building_from_multiple_services.md b/quick_start/quick_start_building_from_multiple_services.md index 3954d9c..c146ead 100644 --- a/quick_start/quick_start_building_from_multiple_services.md +++ b/quick_start/quick_start_building_from_multiple_services.md @@ -43,7 +43,7 @@ Let's test the hex conversion test in isolation with the following AIR script: ``` {% hint style="info" %} -Aquamarine Intermediate Representation \(AIR\) is a low level implementation of Aquamarine to coordinate services into applications. For a detailed introduction to AIR, please refer to the [Knowledgebase](../knowledge_knowledge/knowledge_aquamarine/knowledge_aquamarine_air.md). For the remainder of this section, we will see three AIR _instructions_: _seq, xor,_ and _call._ +Aquamarine Intermediate Representation \(AIR\) is a low level implementation of Aquamarine to coordinate services into applications. For a detailed introduction to AIR, please refer to the [Knowledgebase](../knowledge_knowledge/knowledge_aquamarine/hll/knowledge_aquamarine_air.md). For the remainder of this section, we will see three AIR _instructions_: _seq, xor,_ and _call._ _seq_ is the _sequential_ instruction that wraps arguments and executes them, you guessed it, sequentially. And yes, there is a _parallel_ instruction in the language.