Add build instructions

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 -- <path-to-script>
+```
+
+## (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.