Building from Source - RTK (Rust Token Killer)

This guide covers building RTK from source, including prerequisites, development builds, release builds, and cross-compilation.

Prerequisites

Rust Toolchain

RTK requires Rust 1.70 or later (2021 edition).

Install Rust

Install Rust using rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Verify installation

Confirm Rust and Cargo are installed:

rustc --version
cargo --version

Update toolchain (optional)

If you already have Rust, update to the latest version:

rustup update

System Dependencies

RTK uses rusqlite with the bundled feature, so no external SQLite installation is required. Platform-specific requirements:

macOS: Xcode Command Line Tools
xcode-select --install

Linux: gcc, pkg-config

# Debian/Ubuntu
sudo apt-get install build-essential pkg-config

# Fedora/RHEL
sudo dnf install gcc pkg-config

Windows: MSVC or GNU toolchain via rustup

rustup toolchain install stable-x86_64-pc-windows-msvc

Development Builds

Quick Build

Build RTK for local development:

# Clone the repository
git clone https://github.com/rtk-ai/rtk.git
cd rtk

# Build in debug mode (faster compilation, slower runtime)
cargo build

# Binary location: target/debug/rtk
./target/debug/rtk --version

Development Build Profile

Debug builds include:

Debug symbols for debugging
No optimizations (fast compilation)
Runtime assertions enabled
Larger binary size (~10-15 MB)

Use for: Active development, debugging, testing

Running Without Installing

Test RTK without installing:

# Run directly with cargo
cargo run -- git status
cargo run -- --help

# Pass arguments after --
cargo run -- git log -v --oneline

Local Installation

Install the development build to ~/.cargo/bin/:

# Install from local directory
cargo install --path .

# Verify installation
rtk --version
rtk gain

Local installs override crates.io versions. Uninstall with cargo uninstall rtk.

Release Builds

Optimized Build

Build RTK with full optimizations:

# Build with release profile
cargo build --release

# Binary location: target/release/rtk
./target/release/rtk --version

# Install optimized binary
cargo install --path . --release

Release Profile Configuration

From Cargo.toml (lines 34-39):

[profile.release]
opt-level = 3          # Maximum optimization
lto = true             # Link-time optimization
codegen-units = 1      # Single codegen unit for better optimization
strip = true           # Remove debug symbols
panic = "abort"        # Smaller binary size

Benefits:

Binary size: ~4.1 MB (stripped)
Startup time: <10ms
Memory: 2-5 MB typical usage
Optimization: Maximum runtime performance

Release builds take significantly longer to compile (2-5 minutes vs 30 seconds for debug).

Build Commands Reference

From CLAUDE.md

# Development build
cargo build                   # raw
rtk cargo build               # preferred (token-optimized output)

# Release build (optimized)
cargo build --release
rtk cargo build --release

# Run directly without building
cargo run -- <command>

# Install locally
cargo install --path .

Quality Checks

Run quality gates before committing:

# Check without building (fast)
cargo check                   # raw
rtk cargo check               # preferred

# Format code
cargo fmt --all

# Run linter
cargo clippy --all-targets    # raw
rtk cargo clippy --all-targets # preferred

# Run tests
cargo test                    # raw
rtk cargo test                # preferred

# Full quality pipeline
cargo fmt --all && cargo clippy --all-targets && cargo test

If you have RTK installed, prefer rtk cargo <cmd> for token-optimized output (60-90% reduction).

Cross-Compilation

Linux x86_64 to ARM64

# Install ARM64 target
rustup target add aarch64-unknown-linux-gnu

# Install cross-compilation toolchain
sudo apt-get install gcc-aarch64-linux-gnu

# Build for ARM64
cargo build --release --target aarch64-unknown-linux-gnu

# Binary: target/aarch64-unknown-linux-gnu/release/rtk

macOS Universal Binary

# Install targets
rustup target add x86_64-apple-darwin
rustup target add aarch64-apple-darwin

# Build for both architectures
cargo build --release --target x86_64-apple-darwin
cargo build --release --target aarch64-apple-darwin

# Create universal binary
lipo -create \
  target/x86_64-apple-darwin/release/rtk \
  target/aarch64-apple-darwin/release/rtk \
  -output target/release/rtk-universal

Windows from Linux (via MinGW)

# Install Windows target
rustup target add x86_64-pc-windows-gnu

# Install MinGW toolchain
sudo apt-get install mingw-w64

# Build for Windows
cargo build --release --target x86_64-pc-windows-gnu

# Binary: target/x86_64-pc-windows-gnu/release/rtk.exe

Package Building

DEB Package (Debian/Ubuntu)

Install cargo-deb

cargo install cargo-deb

Build DEB package

cargo deb

Package created at: target/debian/rtk_<version>_<arch>.deb

Install DEB package

sudo dpkg -i target/debian/rtk_*.deb

RPM Package (Fedora/RHEL)

Install cargo-generate-rpm

cargo install cargo-generate-rpm

Build release binary first

cargo build --release

Generate RPM package

cargo generate-rpm

Package created at: target/generate-rpm/rtk-<version>.<arch>.rpm

Install RPM package

sudo rpm -i target/generate-rpm/rtk-*.rpm

Package configurations are defined in Cargo.toml under [package.metadata.deb] and [package.metadata.generate-rpm].

Build Performance Tips

Speed Up Compilation

Use a faster linker:

# .cargo/config.toml
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=lld"]

Incremental compilation (default in debug mode):
export CARGO_INCREMENTAL=1

Parallel jobs:

# Use all CPU cores
cargo build -j$(nproc)

Reduce Binary Size

The release profile already optimizes for size. Additional options:

[profile.release]
opt-level = "z"     # Optimize for size instead of speed
lto = true
strip = true
panic = "abort"
codegen-units = 1

Don’t optimize for size in production! The default opt-level = 3 provides the best runtime performance (<10ms startup).

Troubleshooting

Compilation Errors

Rust version too old:

rustup update stable

Missing system dependencies (Linux):

# Debian/Ubuntu
sudo apt-get install build-essential pkg-config libssl-dev

# Fedora/RHEL
sudo dnf install gcc pkg-config openssl-devel

Linker errors (Windows):

# Install MSVC toolchain
rustup toolchain install stable-x86_64-pc-windows-msvc
rustup default stable-x86_64-pc-windows-msvc

Clean Builds

Remove build artifacts and start fresh:

# Remove target directory
cargo clean

# Rebuild
cargo build --release

Verify Binary

Check the built binary:

# Verify it runs
./target/release/rtk --version

# Check size
ls -lh target/release/rtk

# Check symbols are stripped (Linux/macOS)
nm target/release/rtk | wc -l  # Should be 0 or very small

# Test basic functionality
./target/release/rtk git status
./target/release/rtk gain

CI/CD Builds

RTK uses GitHub Actions for automated builds:

Platforms: macOS, Linux (x86_64 + ARM64), Windows
Workflow: .github/workflows/release.yml
Artifacts: Binaries, DEB/RPM packages, checksums
Triggers: Version tags (v*)

View the workflow for multi-platform build configuration.

Next Steps

Testing Guide - Run tests and verify changes
Architecture - Understand the codebase structure
Adding Commands - Implement new filters

​Prerequisites

​Rust Toolchain

​System Dependencies

​Development Builds

​Quick Build

​Development Build Profile

​Running Without Installing

​Local Installation

​Release Builds

​Optimized Build

​Release Profile Configuration

​Build Commands Reference

​From CLAUDE.md

​Quality Checks

​Cross-Compilation

​Linux x86_64 to ARM64

​macOS Universal Binary

​Windows from Linux (via MinGW)

​Package Building

​DEB Package (Debian/Ubuntu)

​RPM Package (Fedora/RHEL)

​Build Performance Tips

​Speed Up Compilation

​Reduce Binary Size

​Troubleshooting

​Compilation Errors

​Clean Builds

​Verify Binary

​CI/CD Builds

​Next Steps

Prerequisites

Rust Toolchain

System Dependencies

Development Builds

Quick Build

Development Build Profile

Running Without Installing

Local Installation

Release Builds

Optimized Build

Release Profile Configuration

Build Commands Reference

From CLAUDE.md

Quality Checks

Cross-Compilation

Linux x86_64 to ARM64

macOS Universal Binary

Windows from Linux (via MinGW)

Package Building

DEB Package (Debian/Ubuntu)

RPM Package (Fedora/RHEL)

Build Performance Tips

Speed Up Compilation

Reduce Binary Size

Troubleshooting

Compilation Errors

Clean Builds

Verify Binary

CI/CD Builds

Next Steps