development
Welcome to Tuna Desktop. This guide covers everything you need to set up your development environment, understand the codebase structure, and contribute to the project.
Prerequisites
Rust toolchain
- Rust stable with
rustfmtandclippy, from rustup.rs:rustup component add rustfmt clippy. CI builds with the current stable toolchain. No crate declares arust-version(MSRV); all crates use edition 2021, and some dependencies need a recent stable compiler. The API stability policy explains why and what would change it. - Git.
System packages
The list below is what the CI check job installs on Ubuntu 24.04
(.github/workflows/ci.yml); it is enough to build, lint and test the
whole workspace:
sudo apt-get install -y \
libseat-dev libinput-dev libudev-dev libgbm-dev libdrm-dev \
libxkbcommon-dev pkg-config libgtk-4-dev libpipewire-0.3-dev \
libfontconfig1-dev librsvg2-common libadwaita-1-dev libgweather-4-dev \
libpam-wrapper libpam0g-dev libclang-dev zstd \
libglib2.0-dev libglib2.0-bin libglib2.0-dev-bin \
python3-yaml gsettings-desktop-schemas \
meson ninja-build libwayland-dev wayland-protocols
scripts/ci-install-gtk4-layer-shell
Ubuntu 24.04 does not package gtk4-layer-shell, which the GTK shell links;
scripts/ci-install-gtk4-layer-shell builds it from source and installs it
under /usr/local. The pipewire crate also needs libclang (libclang-dev)
at build time; GitHub's runners have it preinstalled. libpam-wrapper is
only needed for the lock-screen PAM test, which skips without it.
To run a nested session, also install the libraries the nested backend loads at startup and, on a machine without a display, Xvfb:
sudo apt-get install -y libxkbcommon-x11-dev libegl1 libgl1-mesa-dri libgbm1 xvfb
Each proof script needs a few more packages; running tests locally lists them per script.
On Arch Linux (TunaOS Marlin's base), the arch-package CI job builds with:
sudo pacman -S --needed base-devel git rust pkgconf clang pipewire gtk4 \
gtk4-layer-shell libadwaita libgweather-4 libxkbcommon libxkbcommon-x11 mesa wayland \
dbus glib2 seatd libinput systemd-libs libdrm \
libsecret libcanberra sound-theme-freedesktop gnome-settings-daemon gnome-session \
librsvg glycin gdk-pixbuf2 fontconfig adwaita-fonts namcap
Spektacular CLI (planning work only)
Building, testing and running Tuna Desktop do not need Spektacular. You need it
only to read or change specs and plans, which are managed through the
Spektacular CLI rather than by
editing .spektacular/ by hand. It is a Go program; with a Go toolchain
installed:
go install github.com/hivecommons/spektacular@latest
export PATH="$(go env GOPATH)/bin:$PATH"
spektacular version check
Project Structure
The project is a Cargo workspace with eight crates. The crate manifests and
existing crate README.md files describe their purpose and dependencies.
tuna-desktop/
├── crates/
│ ├── backlight/ # tuna-backlight: bounded backlight/owned-connector reads
│ ├── compositor/ # tuna-compositor and tuna-session binaries (Smithay)
│ ├── shell-control-schema/ # tuna-shell-control: compositor/shell IPC protocol
│ ├── shell-host/ # tuna-shell-host: original shell binary and shared shell logic
│ ├── shell-gtk/ # tuna-shell-gtk: GTK4/libadwaita shell (ADR 0006)
│ ├── wallpaper/ # tuna-wallpaper: wallpaper decoding
│ ├── wallpaper-svg/ # tuna-wallpaper-svg: bounded native stream helper
│ └── magnifier/ # tuna-magnifier: shared session magnifier settings
│
├── docs/ # architecture, roadmap, test strategy, ADRs, guides
├── packaging/ # Arch package and Marlin image (scripts/tuna-release builds the .deb)
├── scripts/ # nested launcher, proof scripts, release and ledger tools
├── tests/ # a11y golden trees, GNOME 51 reference container
└── Cargo.toml # workspace configuration and pinned dependencies
Setting Up Your Environment
-
Clone the repository:
git clone https://github.com/tuna-os/tuna-desktop.gitcd tuna-desktop -
Build all crates:
cargo build --workspace -
Run the tests (see running tests locally for clippy, fmt and the nested proofs CI runs):
cargo test --workspace
The compositor also supports a nested-only build without its default DRM and XWayland features:
cargo build --locked -p tuna-compositor --no-default-features
cargo check --locked -p tuna-compositor --no-default-features
The existing CI check job runs the second command to guard this configuration.
Winit rendering and its shared scene/damage tracking remain available; disabling
default features does not remove the nested backend's EGL/GLES requirements.
Running the Nested Compositor
The nested compositor runs inside your current Wayland or X11 session for safe development and testing. It creates a Tuna Desktop session as a client of your host display.
First-time setup
# Build and start a nested Tuna Desktop session
./scripts/tuna-nested run
This command:
- Builds
tuna-compositorandtuna-shell-host(debug build) - Starts the compositor on a private socket (named
tuna-nested-<pid>by default) - Logs output to
~/.local/state/tuna-nested/tuna-nested-<pid>/nested.log - Displays the socket name and log path for reference
The session runs until you press Ctrl+C or terminate the process.
Testing shell crashes and recovery
Tuna Desktop implements a supervised shell-host restart mechanism. Test it with:
# In one terminal, start the nested session:
./scripts/tuna-nested run
# In another terminal, simulate a shell crash:
./scripts/tuna-nested kill-shell --socket tuna-nested-<pid>
The compositor will:
- Detect the shell-host crash
- Display a recovery overlay
- Restart the shell-host automatically within a bounded restart budget
- Keep all application connections alive during the restart
See docs/nested-session.md for details on the crash recovery design.
Understanding Spektacular Workflows
Tuna Desktop uses Spektacular for planning and tracking implementation work. Each work item has:
- Spec: A specification document (in
.spektacular/specs/) - Plan: Implementation roadmap and checklist (in
.spektacular/plans/) - Context: Mutable tracking state and work artifacts
Common Spektacular commands
# List specs (use the full timestamp-prefixed name in later commands)
spektacular spec file list
# Start the plan workflow for a spec
spektacular plan new --data '{"name":"<full spec name>"}'
Run spektacular <command> --help for the rest. For more details, see the Spektacular repository and CONTRIBUTING.md.
Spektacular is initialized for Codex. Each program unit has a spek plus a draft plan, context and research artifacts. Review a draft plan against the current implementation and open decision gates before its implementation workflow starts.
Continuing from the first spek
The first spek is
nested compositor and shell recovery.
Use a spek's full timestamp-prefixed name from spektacular spec file list:
spektacular version check
spektacular plan new --data '{"name":"20260927170317-a01f0011-001-nested-compositor-shell-recovery"}'
The plan workflow refreshes its draft from the current source and the linked spek. Complete its walkthrough and review before starting implementation; the implementation workflow then starts with the full plan name.
Architecture and Design
For deeper understanding of Tuna Desktop's design:
- Architecture overview: Read
docs/architecture.mdfor the compositor/shell separation, nested recovery design, and long-term roadmap - Design decisions: Check
docs/adr/(Architecture Decision Records) for rationale on key choices (e.g., Smithay pinning, backend selection) - Verification strategy: See
docs/test-strategy.mdfor how we validate each layer (unit tests, protocol probes, integration tests, hardware qualification) - Test strategy and matrix: Tuna Desktop targets multiple environments, GPU configurations, and client types; the test strategy document details the coverage plan
Workflow for contributors
- Choose a spec: Find an open spec in
.spektacular/specs/or create one - Review the plan: Check the associated plan in
.spektacular/plans/for implementation guidance - Implement: Edit crates as needed, using the test strategy guide to add tests
- Test locally: Follow running tests locally and use
./scripts/tuna-nested runto validate - Create a PR: Reference the spec number and plan state in your PR body
- Update spec/plan state: Once merged, update the spec and plan in Spektacular to reflect completion
Common tasks
Adding a new protocol feature
- Define the protocol in
crates/shell-control-schema/ - Implement compositor side in
crates/compositor/ - Implement shell-host side in
crates/shell-host/ - Add a protocol probe in
.spektacular/work/if appropriate - Document the change in
docs/adr/if it's a significant choice
Writing a test
- Unit tests: Add inline tests in the crate (follow
#[cfg(test)]patterns) - Protocol probes: Add scripts under
scripts/ - Nested integration: Use
./scripts/tuna-journeyas a base or add a new harness
Timing rule (#72). Never gate a test on a fixed iteration budget or a
sleep length: a loaded CI runner exhausts both. Wait on a wall-clock
deadline that is generous (seconds, not milliseconds) and only makes a
slow run slower, or make the ordering deterministic (a latch the test
releases, a manual clock, a counter of finished workers). Assert on
state, never on elapsed time, except for explicit no-hang bounds. There
is no retry policy for deterministic tests: gh run rerun --failed is a
diagnostic, not a fix.
Debugging
- Compositor logs: Check the output of
./scripts/tuna-nested runor tail the log file; nested session troubleshooting explains the common lines - Shell-host logs: Printed to the same log file as the compositor
- Nested shell interaction: Use
./scripts/tuna-nested shell-pidto identify the shell process for attaching a debugger - Build, install, login and CI problems: troubleshooting
- Logs in a GDM session, restarting the shell, the lock screen and debuggers: session operations
- Trace output and every other variable the code reads: environment variables
Performance
See the performance profiling guide. It covers
local perf and Sysprof profiling, the compositor's frame_cost state,
RSS/PSS memory measurement, the paired GNOME 51 comparison, and the CI
regression gates.
Reporting issues
If you find a bug or have a feature request:
- Check existing issues in the repository
- Open a new issue with:
- Clear title and description
- Steps to reproduce (for bugs)
- Expected vs. actual behavior
- Environment (distro, GPU, Rust version, Tuna Desktop commit); filing a bug lists the details and the commands that print them
- Reference relevant specs in
.spektacular/specs/if applicable
Further reading
- Nested session architecture:
docs/nested-session.md - Roadmap:
docs/roadmap.mdfor the full vision and current priorities - Smithay documentation: https://docs.rs/smithay/latest/smithay/
- Wayland protocol specs: https://wayland.freedesktop.org/
- Spektacular: https://github.com/hivecommons/spektacular
Welcome to the project, and happy hacking!