canary
/
canary-rs
2
1
Fork 0
Code Issues 11 Pull Requests 2 Projects Releases Wiki Activity

Proofread usage page

This commit is contained in:
mars 2022-08-16 20:07:23 -06:00
parent 6f185ae344
commit ce05070a92
1 changed files with 20 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
book/src/impl-rs/usage.md
View File

@ -4,14 +4,15 @@
implementation for Canary. It is written in Rust, and is licensed under the implementation for Canary. It is written in Rust, and is licensed under the
LGPLv3. LGPLv3.
It is in active development, and is, at the moment, the singular focal point for `canary-rs` is the central hub for Canary's development. It includes host-side
host-side Canary programming. Even this documentation's source code is located Rust code, helper crates for Canary hosts, wrapper crates for scripts
in the `canary-rs` source tree. authored in Rust, and even the source code for the documentation that you're
currently reading.
`canary-rs` provides a graphical "test harness" that embeds the Canary runtime `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 into a lightweight graphical app. It has two purposes: first, to give
script authors a playground independent of a larger framework to safely debug, 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 benchmark, and experiment with their scripts, and second, to give Canary
embedders a live, functioning example of how Canary can be integrated into their embedders a live, functioning example of how Canary can be integrated into their
applications. applications.
@ -19,7 +20,7 @@ applications.
The test harness requires a Canary script to run. If you don't already have one, 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) you can follow [these instructions](optional-building-the-sword-art-online-demonstration-ui-script)
to build the example script provieded by `canary-rs`. to build the example script provided by `canary-rs`.
## Building the test harness ## Building the test harness
@ -47,12 +48,11 @@ $ cargo run --release -p canary_egui_harness -- <path-to-script>
## (Optional) Building the Sword Art Online demonstration UI script ## (Optional) Building the Sword Art Online demonstration UI script
`canary-rs` provides an example of a fully-functioning script, that can `canary-rs` provides an example of a fully-functioning script which, optionally,
optionally be built and loaded into the test harness in order to ensure its can be built and loaded into the test harness to ensure its functioning.
functioning.
To build it, you must first follow the instructions above to clone and build the To build it, you must first follow [the instructions above](#building-the-test-harness)
test harness and to set up the Rust toolchain. 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 Then, add the `wasm32-unknown-unknown` target so that Rust can compile to
WebAssembly: WebAssembly:
@ -66,16 +66,16 @@ $ 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`. 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: Now it can be run using the test harness:
```sh ```sh
$ cargo run --release -p canary_egui_harness -- target/wasm32-unknown-unknown/release/sao_ui_rs.wasm $ cargo run --release -p canary_egui_harness -- target/wasm32-unknown-unknown/release/sao_ui_rs.wasm
``` ```
# Using `canary-rs` as a Rust library # Using `canary-rs` as a Rust library
***WARNING***: `canary-rs` is still in very early development, and has both ***WARNING***: `canary-rs` is still in alpha development so both its API and its
an unstable API and version. It is not advised to use it in projects not version number are unstable. It is not recommended to use it in your own
involved in its development in its current state. 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 `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) 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)
@ -87,10 +87,9 @@ canary = { git = "https://git.tebibyte.media/canary/canary-rs", rev = "deadbeef"
``` ```
Because `canary-rs` is still under active development, it is recommended to 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 pull a fixed, specific commit using the `rev` key. That can be a specific tag,
tag, some point in the commit history, or whatever the latest commit on `main` some point in the commit history, or whatever the latest commit on `main` is.
is.
Tebibyte Media is capable of hosting rustdocs yet, so to learn how the API [Tebibyte Media](https://tebibyte.media) is not capable of hosting rustdocs yet,
works, you can read the source code for the test harness, or dig through the so to learn how the API works, you can read the source code for the test
source code itself. harness, or dig through the source code itself.