Quickstart

CrownUI needs Rust 1.97 or newer and runs on Linux under a Wayland compositor. This page takes you from an empty directory to a running counter app.

Install and run#

1. Install the native libraries

   CrownUI links against Wayland, Vulkan, EGL, fontconfig, FreeType and D-Bus.

   Arch LinuxDebian and Ubuntu

   sudo pacman -S base-devel wayland wayland-protocols libxkbcommon \
     vulkan-icd-loader vulkan-headers mesa fontconfig freetype2 dbus

2. Create a project and add the crate

   cargo new counter
   cd counter
   cargo add crownui

3. Write the app

   use crownui::prelude::*;
    
   fn main() -> Result<(), crownui::RunError> {
       crownui::run(
           component(|cx| {
               let count = cx.signal(0);
               vstack((
                   text(bind(move |rt| format!("Count: {}", count.get(rt)))).text_size(24.0),
                   button("+1")
                       .on_click(move |cx, _| count.update(cx, |count| *count += 1))
                       .hover(|style| style.scale(1.04))
                       .transition(Spring::snappy()),
               ))
               .p(24.0)
               .gap(12.0)
           }),
           AppConfig::new("Counter"),
       )
   }

4. Run it

   cargo run

The first build downloads the Impeller SDK (about 23 MB) into .impeller_cache/. Later builds reuse it.

What the code does#

• use crownui::prelude::* brings in every builder, modifier, signal type and color an app needs.
• crownui::run(view, config) opens a window and runs until it closes. Call it from main before you start other threads.
• component(|cx| ..) runs its closure once. It creates state and returns the view tree.
• cx.signal(0) creates a Signal<i32>, a small Copy handle to a value in the runtime.
• text(bind(move |rt| ..)) is a text whose content is recomputed whenever a signal it reads changes. Here only this one text updates when you click.
• button("+1").on_click(..) handles clicks. Handlers get (&mut Cx, &mut Event<T>).
• .hover(|style| style.scale(1.04)) is a variant that applies while the pointer is over the button. .transition(Spring::snappy()) animates the change with a spring.
• .p(24.0) and .gap(12.0) are Tailwind names with values in logical pixels.
• AppConfig::new("Counter") sets the window title. Its size defaults to 800 by 600.

Cargo features#

crownui::run and crownui::run_windows exist only with both wayland and impeller on.

Offline and static builds#

• Set IMPELLER_CACHE_DIR to a vendored copy of the Impeller SDK to build without network access.
• Enable the static feature to link Impeller into your binary instead of loading the shared library at runtime.

cargo add crownui --features static

See the logs#

CrownUI logs through tracing. Errors carry a stable code such as CUI0402, listed on the errors page. Add a subscriber to see them:

cargo add tracing-subscriber

use crownui::prelude::*;
 
fn main() -> Result<(), crownui::RunError> {
    tracing_subscriber::fmt::init();
    crownui::run(app(), AppConfig::new("Counter"))
}

When it does not start#

Run the examples#

The repository has five examples. Clone it next to the four sibling repositories it depends on by path:

mkdir crownos && cd crownos
git clone https://github.com/Crown-OS/crownui.git
git clone https://github.com/Crown-OS/crownos-config.git
git clone https://github.com/Crown-OS/crownos-protocols.git
git clone https://github.com/Crown-OS/crownos-ipc.git
git clone https://github.com/Crown-OS/crownos-voice.git
cd crownui
cargo run -p crownui --example counter

rust-toolchain.toml pins the toolchain, so rustup installs Rust 1.97 on the first build.

Next steps#