Remove the book
This commit is contained in:
parent
f842ae608b
commit
73d524cddf
|
@ -1 +0,0 @@
|
||||||
book
|
|
|
@ -1,6 +0,0 @@
|
||||||
[book]
|
|
||||||
authors = ["marceline-cramer"]
|
|
||||||
language = "en"
|
|
||||||
multilingual = false
|
|
||||||
src = "src"
|
|
||||||
title = "Canary GUI Book"
|
|
|
@ -1,30 +0,0 @@
|
||||||
# Summary
|
|
||||||
|
|
||||||
[Introduction](introduction.md)
|
|
||||||
[History](history.md)
|
|
||||||
|
|
||||||
- [Implementation](impl/README.md)
|
|
||||||
- [Development Process](impl-rs/process.md)
|
|
||||||
- [Usage](impl-rs/usage.md)
|
|
||||||
- [Backends](impl-rs/backends.md)
|
|
||||||
- [Examples](impl-rs/examples.md)
|
|
||||||
- [Ecosystem](ecosystem/README.md)
|
|
||||||
- [Messages](ecosystem/messages.md)
|
|
||||||
- [Protocols](ecosystem/protocols.md)
|
|
||||||
- [Finding Scripts](ecosystem/finding-scripts.md)
|
|
||||||
- [Fonts](ecosystem/fonts.md)
|
|
||||||
- [Localization](ecosystem/localization.md)
|
|
||||||
- [Rendering](rendering/README.md)
|
|
||||||
- [Graphics State](rendering/state.md)
|
|
||||||
- [Primitives](rendering/primitives.md)
|
|
||||||
- [Canvases](rendering/canvases.md)
|
|
||||||
- [Tessellation](rendering/tessellation.md)
|
|
||||||
- [Text](rendering/text.md)
|
|
||||||
- [Input](input/README.md)
|
|
||||||
- [Pointer](input/pointer.md)
|
|
||||||
- [Text](input/text.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[Glossary](glossary.md)
|
|
||||||
[Credits](credits.md)
|
|
|
@ -1 +0,0 @@
|
||||||
# Credits
|
|
|
@ -1 +0,0 @@
|
||||||
# Ecosystem
|
|
|
@ -1 +0,0 @@
|
||||||
# Finding Scripts
|
|
|
@ -1 +0,0 @@
|
||||||
# Fonts
|
|
|
@ -1 +0,0 @@
|
||||||
# Localization
|
|
|
@ -1 +0,0 @@
|
||||||
# Messages
|
|
|
@ -1 +0,0 @@
|
||||||
# Protocols
|
|
|
@ -1 +0,0 @@
|
||||||
# Glossary
|
|
|
@ -1,16 +0,0 @@
|
||||||
# History
|
|
||||||
|
|
||||||
Canary was originally conceived in early 2021 as a WebAssembly-based,
|
|
||||||
minimalistic UI framework during the development of [Mondradiko](https://mondradiko.github.io),
|
|
||||||
where it was a dedicated subsystem of a larger game engine. When the new UI
|
|
||||||
system turned out to be even more powerful than originally expected, it was
|
|
||||||
decided that the UI code would be broken out into a separate project. The
|
|
||||||
Mondradiko community voted to name it "Canary" (the other contenders were
|
|
||||||
"Robin" and "Magpie"), and it was given [a new repository](https://github.com/mondradiko/canary).
|
|
||||||
However, before Canary could be fully fleshed-out, development on Mondradiko
|
|
||||||
was ceased and there was no reason to continue working on Canary.
|
|
||||||
|
|
||||||
In mid-2022, development was started back up, as a member project of
|
|
||||||
[Tebibyte Media](https://tebibyte.media). This new community of free software
|
|
||||||
enthusiasts had new interest in Canary apart from its usage in a larger game
|
|
||||||
engine, so development was restarted.
|
|
|
@ -1 +0,0 @@
|
||||||
# Backends
|
|
|
@ -1 +0,0 @@
|
||||||
# Examples
|
|
|
@ -1,23 +0,0 @@
|
||||||
# Development Process
|
|
||||||
|
|
||||||
# Adding New Features
|
|
||||||
|
|
||||||
To keep Canary as minimal as possible we adopt a conservative policy for what
|
|
||||||
features are added to its specification. This is to avoid the feature-creep that
|
|
||||||
plagues large UI and UX frameworks in the long run. The following reasons are
|
|
||||||
general guidelines for what features should and should not be added to Canary.
|
|
||||||
|
|
||||||
## Reasons to add a feature
|
|
||||||
|
|
||||||
The feature provides a clear benefit to a cultural class of users. For example,
|
|
||||||
Arabic speakers will require that text can be rendered right-to-left.
|
|
||||||
|
|
||||||
The feature reduces the resource usage of scripts.
|
|
||||||
|
|
||||||
## Reasons NOT to add a feature
|
|
||||||
|
|
||||||
The feature adds more complexity to the host than is removed from scripts.
|
|
||||||
|
|
||||||
The feature only applies to certain host configurations.
|
|
||||||
|
|
||||||
The feature can be effectively emulated in a script.
|
|
|
@ -1,97 +0,0 @@
|
||||||
# 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>
|
|
||||||
```
|
|
||||||
|
|
||||||
# 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 canary-sao-ui --target wasm32-unknown-unknown
|
|
||||||
```
|
|
||||||
|
|
||||||
The path to the built example script is `target/wasm32-unknown-unknown/release/canary_sao_ui.wasm`.
|
|
||||||
Now it can be run using the sandbox:
|
|
||||||
```sh
|
|
||||||
$ cargo run --release -p canary-sandbox -- target/wasm32-unknown-unknown/release/canary_sao_ui.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.
|
|
|
@ -1,4 +0,0 @@
|
||||||
# Implementation
|
|
||||||
|
|
||||||
This chapter discusses the design and usage of [canary-rs](https://git.tebibyte.media/canary/canary-rs),
|
|
||||||
the canonical implementation of Canary.
|
|
|
@ -1 +0,0 @@
|
||||||
# Input
|
|
|
@ -1 +0,0 @@
|
||||||
# Pointer
|
|
|
@ -1 +0,0 @@
|
||||||
# Text
|
|
|
@ -1 +0,0 @@
|
||||||
# Introduction
|
|
|
@ -1 +0,0 @@
|
||||||
# Rendering
|
|
|
@ -1 +0,0 @@
|
||||||
# Canvases
|
|
|
@ -1 +0,0 @@
|
||||||
# Primitives
|
|
|
@ -1 +0,0 @@
|
||||||
# Graphics State
|
|
|
@ -1 +0,0 @@
|
||||||
# Tessellation
|
|
|
@ -1 +0,0 @@
|
||||||
# Text
|
|
Loading…
Reference in New Issue