Development

Home · Installation · Adding a backend · Platform support

Work from a source checkout. Read the repository’s AGENTS.md and CONVENTIONS.md for current engineering and validation requirements. The workspace uses Rust 1.99, edition 2024 and Cargo’s resolver 3. Linux builds need GTK 4.18 development files and a C toolchain; the CI package script .github/actions/install-distro-packages/install.sh lists distribution-specific build and test dependencies. See Installation for a minimal source build.

Boundaries

tessera-core holds protocol-neutral tiling policy. tessera-backend defines capabilities and session contracts; platform adapters implement them, with X11 protocol details in tessera-backend-x11. tessera-config owns configuration, tessera-i18n owns localized messages, tessera-worker owns the isolated JavaScript runtime, and tessera-app composes the application. The UI model and platform providers are separate. A backend requests operations from the session’s existing window manager; it does not become one. See Adding a backend.

Validation

The repository’s documented Linux display gate runs in a private Xvfb, xfwm4 and session bus:

scripts/test-env.sh gate

It runs formatting, clippy and tests, including the app’s adwaita feature. It needs the tools listed in AGENTS.md. Exit 3 means the environment was unavailable, not that tests passed. Other display profiles have their own private harness profiles. Never run display-dependent tests against your everyday desktop or treat ignored tests as passing. Record the actual commands, results, environment and any unrun tests; virtual tests do not replace real-session smoke evidence.

For a workspace build or check from the root:

cargo check --workspace --all-targets --locked
cargo build --workspace --all-targets --locked

Changes to user-facing messages need catalog entries and coverage for all shipped languages. Keep unknown configuration fields and report unsupported capabilities explicitly. Update the compatibility ledger when behavior changes. Packaging scripts are under packages/; recipes are not proof of publication or support. Do not create a remote, release or public artifact without an explicitly authorized destination.

Documentation images

Images for these pages live in wiki/images/ (subfolders are free, for example images/layouts/tall.svg). Pages reference them by a path relative to the wiki root, ![descriptive alt text](images/layouts/tall.svg), which works on the GitHub wiki; the documentation site publishes the contents of wiki/images/ as site assets, so nothing outside wiki/ may be referenced for documentation images.

To update images:

• Layout animations: run cargo run -p tessera-ui --example generate_layout_svgs, then cp crates/tessera-ui/assets/layouts/*.svg wiki/images/layouts/. The test crates/tessera-ui/tests/layout_svgs.rs covers only the copy under crates/, so check the wiki copy with diff -r crates/tessera-ui/assets/layouts wiki/images/layouts.
• Logo: copy crates/tessera-ui/assets/icons/org.xfce.Tessera.svg to wiki/images/.
• Screenshots: copy only real captures that were actually observed (for example from docs/compatibility/evidence/) into wiki/images/screenshots/, and state in the page how they were captured (the current ones come from a private Xvfb + Xfwm4 session, not a real XFCE session). Never add invented or mocked images.
• Give every image descriptive alt text and verify that each images/... reference points to an existing file.