diff --git a/book/src/impl-rs/usage.md b/book/src/impl-rs/usage.md index 8f04b05..d9815eb 100644 --- a/book/src/impl-rs/usage.md +++ b/book/src/impl-rs/usage.md @@ -1 +1,96 @@ -# Usage +# Using `canary-rs` + +[`canary-rs`](https://git.tebibyte.media/canary/canary-rs) is the reference +implementation for Canary. It is written in Rust, and is licensed under the +LGPLv3. + +It is in active development, and is, at the moment, the singular focal point for +host-side Canary programming. Even this documentation's source code is located +in the `canary-rs` source tree. + +`canary-rs` provides a graphical "test harness" that embeds the Canary runtime +into a lightweight graphical app. It has two purposes: first of all, to give +script authors a playground independent of a larger framework to safely debug, +benchmark, and experiment with their scripts, and second of all, to give Canary +embedders a live, functioning example of how Canary can be integrated into their +applications. + +# Running the `canary-rs` test harness + +The test harness requires a Canary script to run. If you don't already have one, +you can follow [these instructions](optional-building-the-sword-art-online-demonstration-ui-script) +to build the example script provieded by `canary-rs`. + +## Building the test harness + +To build the test harness from source, first make sure that you have +[installed the standard Rust toolchain](https://www.rustlang.org/tools/install), +including `rustup`, `rustc`, and `cargo`, as well as a frontend to +[Git](https://git-scm.com/). This guide assumes that you are using the Git +command-line interface (CLI). + +Next, clone the upstream repository: +```sh +$ git clone https://git.tebibyte.media/canary/canary-rs.git +$ cd canary-rs +``` + +Then, run `cargo` to build the test harness package: +```sh +$ cargo build --release -p canary_egui_harness +``` + +Now, the test harness can be ran with a script: +```sh +$ cargo run --release -p canary_egui_harness -- +``` + +## (Optional) Building the Sword Art Online demonstration UI script + +`canary-rs` provides an example of a fully-functioning script, that can +optionally be built and loaded into the test harness in order to ensure its +functioning. + +To build it, you must first follow the instructions above to clone and build the +test harness and to set up the Rust toolchain. + +Then, add the `wasm32-unknown-unknown` target so that Rust can compile to +WebAssembly: +```sh +$ rustup target add wasm32-unknown-unknown +``` + +Next, compile the example script: +```sh +$ cargo build --release -p sao_ui_rs --target wasm32-unknown-unknown +``` + +The path to the built example script is `target/wasm32-unknown-unknown/release/sao_ui_rs.wasm`. +Now, it can be run using the test harness: +```sh +$ cargo run --release -p canary_egui_harness -- target/wasm32-unknown-unknown/release/sao_ui_rs.wasm +``` + +# Using `canary-rs` as a Rust library + +***WARNING***: `canary-rs` is still in very early development, and has both +an unstable API and version. It is not advised to use it in projects not +involved in its development in its current state. + +`canary-rs` is not yet available on [crates.io](https://crates.io), so to add it +as a dependency, you must add its [upstream git repository](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories) +instead: + +```toml +[dependencies] +canary = { git = "https://git.tebibyte.media/canary/canary-rs", rev = "deadbeef" } +``` + +Because `canary-rs` is still under active development, it is recommended to +pull a fixed, specific commit using the `rev` key. That can either be a specific +tag, some point in the commit history, or whatever the latest commit on `main` +is. + +Tebibyte Media is capable of hosting rustdocs yet, so to learn how the API +works, you can read the source code for the test harness, or dig through the +source code itself.