124 lines
4.6 KiB
Markdown
124 lines
4.6 KiB
Markdown
# Canary
|
|
|
|
Canary is a post-structuralist graphical user interface (GUI) framework that
|
|
uses standardized message-passing protocols to represent UI state instead of a
|
|
typical DOM-based GUI workflow.
|
|
|
|
Canary scripts (executed as WebAssembly) implement all of the rendering and
|
|
layout of the GUIs, so the host has little to no involvement in their
|
|
appearance. This allows virtually unlimited customization of Canary GUIs, as
|
|
scripts can be reloaded by applications with no impact on application behavior.
|
|
|
|
Canary's development has been documented on Tebibyte Media's blog:
|
|
https://tebibyte.media/blog/project/canary/
|
|
|
|
# Screenshots
|
|
|
|
<div align="center">
|
|
<figure>
|
|
<img src="./resources/sandbox-screenshot.jpg"/>
|
|
<figcaption>A screenshot of the Canary sandbox and Sword Art Online script.</figcaption>
|
|
</figure>
|
|
|
|
<figure>
|
|
<img src="./resources/music-player-screenshot.jpg"/>
|
|
<figcaption>A screenshot of the desktop music player controller using the Sword Art Online script.</figcaption>
|
|
</figure>
|
|
</div>
|
|
|
|
# Using `canary-rs`
|
|
|
|
This repository (`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 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>
|
|
```
|
|
|
|
## Running Magpie
|
|
|
|
## (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.
|