canary-rs/book/src/impl-rs/usage.md

# 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.

`canary-rs` is the central hub for Canary's development. It includes host-side
Rust code, helper crates for Canary hosts, wrapper crates for scripts
authored in Rust, and even the source code for the documentation that you're
currently reading.

`canary-rs` provides a graphical "sandbox" that embeds the Canary runtime
into a lightweight graphical app. It has two purposes: first, to give
script authors a playground independent of a larger framework to safely debug,
benchmark, and experiment with their scripts, and second, to give Canary
embedders a live, functioning example of how Canary can be integrated into their
applications.

# Running the `canary-rs` sandbox

The sandbox 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 provided by `canary-rs`.

## Building the sandbox

To build the sandbox 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 sandbox package:
```sh
$ cargo build --release -p canary_sandbox
```

Now, the sandbox can be ran with a script:
```sh
$ cargo run --release -p canary_sandbox -- <path-to-script>
```

## (Optional) Building the Sword Art Online demonstration UI script

`canary-rs` provides an example of a fully-functioning script which, optionally,
can be built and loaded into the sandbox to ensure its functioning.

To build it, you must first follow [the instructions above](#building-the-test-harness)
to clone and build the sandbox 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 sandbox:
```sh
$ cargo run --release -p canary_sandbox -- target/wasm32-unknown-unknown/release/sao_ui_rs.wasm
```

# Using `canary-rs` as a Rust library

***WARNING***: `canary-rs` is still in alpha development so both its API and its
version number are unstable. It is not recommended to use it in your own
projects unless you are involved with Canary's development.

`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 be a specific tag,
some point in the commit history, or whatever the latest commit on `main` is.

[Tebibyte Media](https://tebibyte.media) is not 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.