> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/rtk-ai/rtk/llms.txt
> Use this file to discover all available pages before exploring further.

# Building from Source

> How to build and compile RTK locally

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).

**1. Install Rust**

Install Rust using rustup:

```bash theme={null}
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

**2. Verify installation**

Confirm Rust and Cargo are installed:

```bash theme={null}
rustc --version
cargo --version
```

**3. Update toolchain (optional)**

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

```bash theme={null}
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
  ```bash theme={null}
  xcode-select --install
  ```

* **Linux**: gcc, pkg-config
  ```bash theme={null}
  # 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
  ```bash theme={null}
  rustup toolchain install stable-x86_64-pc-windows-msvc
  ```

## Development Builds

### Quick Build

Build RTK for local development:

```bash theme={null}
# 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:

```bash theme={null}
# 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/`:

```bash theme={null}
# Install from local directory
cargo install --path .

# Verify installation
rtk --version
rtk gain
```

> [!NOTE]
>
> Local installs override crates.io versions. Uninstall with `cargo uninstall rtk`.

## Release Builds

### Optimized Build

Build RTK with full optimizations:

```bash theme={null}
# 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):

```toml theme={null}
[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

> [!WARNING]
>
> Release builds take significantly longer to compile (2-5 minutes vs 30 seconds for debug).

## Build Commands Reference

### From CLAUDE.md

```bash theme={null}
# 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:

```bash theme={null}
# 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
```

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

## Cross-Compilation

### Linux x86\_64 to ARM64

```bash theme={null}
# 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

```bash theme={null}
# 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)

```bash theme={null}
# 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)

**1. Install cargo-deb**

```bash theme={null}
cargo install cargo-deb
```

**2. Build DEB package**

```bash theme={null}
cargo deb
```

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

**3. Install DEB package**

```bash theme={null}
sudo dpkg -i target/debian/rtk_*.deb
```

### RPM Package (Fedora/RHEL)

**1. Install cargo-generate-rpm**

```bash theme={null}
cargo install cargo-generate-rpm
```

**2. Build release binary first**

```bash theme={null}
cargo build --release
```

**3. Generate RPM package**

```bash theme={null}
cargo generate-rpm
```

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

**4. Install RPM package**

```bash theme={null}
sudo rpm -i target/generate-rpm/rtk-*.rpm
```

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

## Build Performance Tips

### Speed Up Compilation

1. **Use a faster linker**:
   ```toml theme={null}
   # .cargo/config.toml
   [target.x86_64-unknown-linux-gnu]
   linker = "clang"
   rustflags = ["-C", "link-arg=-fuse-ld=lld"]
   ```

2. **Incremental compilation** (default in debug mode):
   ```bash theme={null}
   export CARGO_INCREMENTAL=1
   ```

3. **Parallel jobs**:
   ```bash theme={null}
   # Use all CPU cores
   cargo build -j$(nproc)
   ```

### Reduce Binary Size

The release profile already optimizes for size. Additional options:

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

> [!WARNING]
>
> **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**:

```bash theme={null}
rustup update stable
```

**Missing system dependencies** (Linux):

```bash theme={null}
# 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):

```bash theme={null}
# 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:

```bash theme={null}
# Remove target directory
cargo clean

# Rebuild
cargo build --release
```

### Verify Binary

Check the built binary:

```bash theme={null}
# 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](/contributing/testing.md) - Run tests and verify changes
* [Architecture](/contributing/architecture.md) - Understand the codebase structure
* [Adding Commands](/contributing/adding-commands.md) - Implement new filters


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.