Skip to content

development.md

Latest commit

 

History

History
114 lines (70 loc) · 6.57 KB

development.md

File metadata and controls

114 lines (70 loc) · 6.57 KB
Raw

Development

Rill is a Rust workspace with a shared core, a native desktop app, and a CLI. Use an isolated library for development. A normal library is user data.

Toolchain

rust-toolchain.toml pins Rust 1.95.0 with rustfmt and Clippy. GPUI Kit is pinned to 0.6.0, and Cargo.lock fixes its GPUI dependencies. Use --locked to preserve that dependency set. Do not add a separate gpui = 0.2 dependency alongside it.

The workspace overrides two GPUI Kit crates. Their source, patches, licenses, and removal conditions are documented in Dependency patches.

Platform prerequisites

macOS

macOS 15 or later, Xcode, and its command-line tools are required. GPUI renders with Metal. Select the full Xcode installation if the linker cannot find Apple frameworks.

Users can install the published desktop app without Rust or Xcode:

brew tap Geektrovert/tap
brew install --cask rill

The cask selects an Apple Silicon or Intel build. Contributors building Rill from source still need the prerequisites above.

Linux

The desktop requires a Vulkan-capable graphics driver and a running X11 or Wayland session. On Ubuntu 24.04, install the build dependencies with:

sudo apt-get update
sudo apt-get install -y build-essential clang cmake pkg-config \
  libfontconfig1-dev libfreetype6-dev libssl-dev libwayland-dev \
  libxkbcommon-x11-dev libx11-xcb-dev libxrandr-dev libxi-dev \
  libvulkan-dev mesa-vulkan-drivers libasound2-dev

The Linux binary embeds Noto Sans and Noto Serif under the included SIL Open Font License. Install system fonts for scripts outside their coverage. The core and CLI do not require a graphics session. See the GPUI Kit installation guide for upstream platform guidance.

Run an isolated library

Add a real subscription and open it:

cargo run --locked -p rill-cli -- --data-dir /tmp/rill-dev add https://blog.rust-lang.org/feed.xml
cargo run --locked -p rill-desktop -- --data-dir /tmp/rill-dev

For a fictional fixture, use a separate empty directory:

cargo run --locked -p rill-desktop -- --data-dir /tmp/rill-demo --demo

Demo article URLs are placeholders. Use real feeds for refresh, extraction, and original-link checks.

--window-size 980x640 opens the minimum supported layout; the default is 1380 × 860. An explicit size overrides saved geometry and fullscreen state. Omit the flag when checking restoration. Each data directory has its own desktop-session.json; create a new directory for first-launch checks.

Checks

Run the repository check script:

scripts/check.sh

It tests license-notice generation, verifies dependency texts, checks formatting, runs locked workspace tests, and runs Clippy with warnings denied. CI runs on Ubuntu 24.04. macOS users build from source and run checks locally. Tests use temporary libraries, local fixtures, and fake providers. See Testing for individual commands and the native, provider, and packaging checks that apply to each kind of change. See Performance for storage and process measurements.

Both CI workflows also run cargo audit --deny unsound with cargo-audit 0.22.2. Vulnerability and soundness advisories fail the job; maintenance advisories remain visible for dependency review.

Build and package

Build optimized binaries on the target platform:

cargo build --locked --release --workspace

This produces target/release/rill and target/release/rill-cli. The development profile disables debug information and incremental artifacts to reduce build-directory size; use release builds for performance measurements.

For normal use, install the published macOS app through the Homebrew tap. After building from source, create a local application bundle and matching release archive:

scripts/package-macos.sh

The result is dist/Rill.app plus dist/Rill-VERSION-ARCH.zip. Open the bundle with Finder or copy it to Applications. The script stages and validates a complete bundle before replacing the previous artifact. Its default ad hoc signature is for local use. Tagged releases build both macOS architectures and publish the archives used by the Homebrew cask.

On Linux, create an archive:

scripts/package-linux.sh

The result is dist/rill-linux-ARCH.tar.gz, where ARCH is the host architecture. Extract it and launch bin/rill. The archive includes both binaries, a desktop entry, an icon, documentation, and license notices. It requires the system graphics and TLS libraries listed above. Add its bin directory to PATH before installing the desktop entry, whose command is rill.

The Build Linux release artifact workflow runs the repository checks before building and uploading the Linux x86_64 archive. A failed check, missing binary, or incomplete dependency notice stops packaging.

Packaging uses Python 3 to collect license files from locked Cargo dependencies. It includes case-insensitive license filenames and the reviewed supplements in packaging/licenses. Each supplement applies to one package version and has a pinned source and SHA-256 hash. Missing or changed license text fails generation. Both package scripts generate notices from the current dependencies; they do not accept a pre-generated inventory. Linux font attribution is included separately.

Environment variable Purpose
CARGO_TARGET_DIR Select the build-output directory used by Cargo and both package scripts
RILL_SIGN_IDENTITY Select the macOS signing identity; defaults to ad hoc signing

Troubleshooting

Launch the binary from a terminal to see startup errors if no window opens. Use a new --data-dir to distinguish application behavior from persisted data. Do not reset an existing library as a debugging shortcut.

An older binary refuses to open a newer database schema. Use the Rill version that created or migrated the library. Backup and recovery describes how to restore into a separate directory. Remove private content before sharing a reproduction.

GUI launches may not inherit a terminal's environment variables. For providers that use variable references, launch from a shell or a user service with the required environment. See Integrations.

The IMAP client is pinned to 3.0.0-alpha.15, an upstream prerelease that uses the newer protocol parser. Review upgrades explicitly and run the mailbox fixture tests, which cover server greetings, read-only commands, size limits, and checkpoints across restarts and UIDVALIDITY changes.