From 3a778c0aa66ec88819ad8838fd3669b61f109684 Mon Sep 17 00:00:00 2001 From: mars Date: Tue, 28 Mar 2023 15:33:34 -0400 Subject: [PATCH] Add README --- README.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..33e2e54 --- /dev/null +++ b/README.md @@ -0,0 +1,113 @@ +# 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 + +TODO + +# 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 -- +``` + +## 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.