Skip to content

Configuration Overview

rninja is designed to work out of the box with sensible defaults, but offers extensive configuration options for customization.

Configuration Methods

rninja can be configured through three methods, in order of precedence (highest to lowest):

  1. Command-line arguments - Highest priority, per-invocation
  2. Environment variables - Per-session or CI configuration
  3. Configuration files - Persistent project or user settings

Quick Configuration

Generate Sample Config

Generate a sample configuration file:

rninja -t config -v

This outputs a complete sample configuration you can customize.

Show Config Paths

See where rninja looks for configuration:

rninja -t config

Configuration Sections

Build Configuration

Control build behavior:

[build]
jobs = 0              # Parallel jobs (0 = CPU count)
keep_going = 1        # Failures before stopping
explain = false       # Show rebuild reasons
default_targets = []  # Default targets to build

Cache Configuration

Configure the build cache:

[cache]
enabled = true        # Enable caching
mode = "auto"         # local, remote, or auto
directory = ""        # Cache directory (default: ~/.cache/rninja)
max_size = 10737418240  # Max size in bytes (10GB)

Output Configuration

Control output behavior:

[output]
verbose = false       # Verbose output
stats = false         # Show statistics
color = "auto"        # auto, always, or never
trace_file = ""       # Trace output file

Common Configurations

Development Machine

[build]
jobs = 0
explain = false

[cache]
enabled = true
mode = "local"

[output]
verbose = false
color = "auto"

CI/CD Pipeline

[build]
jobs = 0
keep_going = 0  # Build as much as possible

[cache]
enabled = true
mode = "auto"  # Use remote if available

[output]
verbose = true
stats = true
color = "never"

Team with Remote Cache

[cache]
enabled = true
mode = "auto"
# Remote settings from environment variables

With environment:

export RNINJA_CACHE_REMOTE_SERVER=tcp://cache.internal:9999
export RNINJA_CACHE_TOKEN=your-secret-token

Configuration Precedence

When the same option is set in multiple places:

CLI flags > Environment variables > Config files

Example:

# config.toml has jobs = 4
# Environment has RNINJA_JOBS=8

rninja -j2  # Uses 2 (CLI wins)

Viewing Effective Configuration

To see what configuration rninja is using:

# Show config file locations
rninja -t config

# Verbose shows loaded config
rninja -t config -v

Next Steps