Skip to content

Development

Ö. Efe D. edited this page Sep 16, 2026 · 4 revisions

Development

Building

See Installation for the dependencies. Then:

git clone https://github.com/skyline69/tron-terminal.git
cd tron-terminal
cargo build --release
./target/release/tron

Development builds optimize dependencies, so cargo run stays usable for testing.

Checks

These run in CI on Linux and macOS:

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo nextest run --workspace
shellcheck install.sh

Tests use cargo-nextest: cargo install cargo-nextest.

Architecture

Crate Purpose
tron-core Parser, grid, scrollback, reflow, selection, search, images and terminal state. No GPU or window code
tron-font Font discovery and fallback, shaping, rasterization and generated box drawing glyphs
tron-render wgpu renderer: instanced cells, glyph atlases, images and post-processing shaders
tron-pty Pseudo terminal and child process
tron-config Configuration, themes, key bindings, built-in themes and shaders, hot reload
tron-startup The startup screen, a ratatui program run inside the terminal
tron The application: windows, input, clipboard, terminfo, accessibility

The pty reader thread parses output into tron-core under a lock. For each frame, the event loop takes a snapshot of the changed rows and renders from it, so parsing never waits for drawing.

Headless benchmark

cargo run --release -p tron-core --example throughput [plain|sgr|unicode] [repeat]

For steadier numbers than wall time, use perf stat -e cycles.

Adding a built-in theme or shader

  • Themes: add examples/themes/<name>.toml. The build embeds every file in that directory.
  • Shaders: add examples/shaders/<name>.wgsl. Record the author and license in three places: the file header, crates/tron-startup/src/credits.toml and the table in examples/shaders/README.md.

Releasing

  1. Bump version under [workspace.package] in Cargo.toml and commit.
  2. Push to the release branch: git push origin main:release.

The release workflow then builds these packages:

Package Built by
tron-VERSION-ARCH-linux.tar.gz An AlmaLinux 9 container (glibc 2.34) on x86_64 and aarch64 runners
tron-VERSION-ARCH.AppImage appimagetool from the same binaries, with zsync update information
tron-VERSION-ARCH.flatpak flatpak-builder from dist/flatpak/dev.tron.Terminal.yml
tron-VERSION-ARCH-macos.tar.gz macOS runners, for aarch64 and x86_64
tron-VERSION-macos.dmg A universal tron.app (lipo), packed by dmgbuild with dist/macos/dmg-settings.py and the background from dist/macos/background.svg

Finally it generates release notes and CHANGELOG.md with git-cliff from cliff.toml, writes SHA256SUMS, tags vX.Y.Z and publishes the GitHub release.

After the release is published, the homebrew job fills in dist/homebrew/tron.rb with the version and the checksum of the disk image and commits it as Casks/tron.rb to skyline69/homebrew-tap. It needs the HOMEBREW_TAP_TOKEN secret, a fine-grained token that may write to the contents of the tap. Without it, the job warns and the cask keeps naming the previous release. Change the cask in dist/homebrew/tron.rb, not in the tap, since the next release overwrites the tap's copy.

To test packaging changes without releasing, run the workflow by hand with publish turned off:

gh workflow run release.yml -f publish=false

The packages then appear as workflow artifacts.

After changing dist/macos/background.svg, render the disk image background again:

magick -background none -density 96 dist/macos/background.svg -resize 660x400 -depth 8 dist/macos/background.png
magick -background none -density 192 dist/macos/background.svg -resize 1320x800 -depth 8 dist/macos/background@2x.png

The macOS app icon

macOS 26 draws app icons as Liquid Glass and puts icons that do not follow its grid on a gray tile. tron's macOS icon is an Icon Composer bundle, dist/macos/Icon.icon: square, full-bleed layers that macOS masks and lights itself. The layers are rendered from dist/macos/icon-scene.svg (the synthwave screen) and dist/macos/icon-letter.svg (the chrome T, drawn as glass).

The release workflow compiles the bundle with actool into Assets.car, for macOS 26 and later, and Icon.icns, for earlier releases. Info.plist names both with CFBundleIconName and CFBundleIconFile. Without actool, install.sh and the workflow use dist/macos/icon-1024.png: the classic icon on Apple's grid, an 824 px body with 185.4 px corners and a soft shadow on the 1024 px canvas.

On a Mac, open dist/macos/Icon.icon in Icon Composer to preview and tune the glass. After changing the SVGs, render the layers and the classic icon again:

cd dist/macos
magick -background none -density 384 icon-scene.svg -resize 1024x1024 -depth 8 Icon.icon/Assets/scene.png
magick -background none -density 384 icon-letter.svg -resize 1024x1024 -depth 8 Icon.icon/Assets/letter.png
magick Icon.icon/Assets/scene.png Icon.icon/Assets/letter.png -composite -resize 824x824 body.png
magick -size 824x824 xc:none -fill white -draw "roundrectangle 0,0 823,823 185.4,185.4" mask.png
magick body.png mask.png -compose CopyOpacity -composite rounded.png
magick -size 1024x1024 xc:none \( rounded.png -background black -shadow 50x14+0+0 \) -gravity center \
  -geometry +0+12 -composite rounded.png -gravity center -composite -depth 8 icon-1024.png
rm body.png mask.png rounded.png

A version that is already tagged is skipped. Commit subjects are plain sentences ("Fix the crash when tron exits"); cliff.toml groups them into features, fixes, performance and other changes by their first word.

License

tron is licensed under MIT OR Apache-2.0. Built-in shaders ported from other authors keep their own licenses; see examples/shaders/README.md.

Clone this wiki locally