|
||
---|---|---|
apps | ||
crates | ||
resources | ||
scripts | ||
src | ||
.gitignore | ||
COPYING | ||
COPYING.LESSER | ||
Cargo.toml | ||
README.md | ||
check_licenses.sh |
README.md
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


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
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,
including rustup
, rustc
, and cargo
, as well as a frontend to
Git. This guide assumes that you are using the Git
command-line interface (CLI).
Next, clone the upstream repository:
$ git clone https://git.tebibyte.media/canary/canary-rs.git
$ cd canary-rs
Then, run cargo
to build the sandbox package:
$ cargo build --release -p canary_sandbox
Now, the sandbox can be ran with a script:
$ 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 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:
$ rustup target add wasm32-unknown-unknown
Next, compile the example script:
$ 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:
$ 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, so to add it
as a dependency, you must add its upstream git repository
instead:
[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 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.