Skip to content

Quick Start

This guide gets you from zero to your first cached build in under 5 minutes.

Prerequisites

  • Rust toolchain (for installation)
  • An existing project with a build.ninja file (or a build generator like CMake)

Step 1: Install rninja

cargo install rninja

Verify the installation:

rninja --version

Step 2: Run Your First Build

Navigate to a project directory containing a build.ninja file:

cd /path/to/your/project
rninja

That's it!

rninja reads your existing build.ninja file with no configuration needed.

If your project uses CMake, Meson, or another generator:

# Generate build files
cmake -G Ninja -B build

# Build with rninja
rninja -C build

# Generate build files
meson setup build

# Build with rninja
rninja -C build

# Just run rninja in place of ninja
rninja

Step 3: Experience Cached Builds

Run the build again without changes:

rninja

Expected output:

ninja: no work to do.

Now clean and rebuild:

rninja -t clean
rninja

Cache Hit

Notice how the rebuild is much faster? rninja restored cached artifacts instead of recompiling everything.

Step 4: Check Cache Statistics

View your cache status:

rninja -t cache-stats

Example output:

Cache Statistics:
  Enabled: true
  Mode: local
  Directory: /home/user/.cache/rninja

  Local Cache:
    Total entries: 42
    Total size: 128.5 MB
    Hit rate: 95.2%

Step 5: Enable Verbose Mode (Optional)

See what rninja is doing:

# Show all commands
rninja -v

# Explain why targets are rebuilt
rninja -d explain

Common Workflows

Building Specific Targets

# Build a specific target
rninja my_target

# Build multiple targets
rninja target1 target2

Parallel Builds

# Use all CPU cores (default)
rninja -j0

# Limit to 4 parallel jobs
rninja -j4

Different Build Directories

# Build in a different directory
rninja -C out/Release

# Use a different build file
rninja -f custom.ninja

Dry Run

See what would be built without actually building:

rninja -n

What's Next?

You now have rninja working with local caching. Here are some next steps:

Quick Reference

Task Command
Build default targets rninja
Build specific target rninja target_name
Build in directory rninja -C path/to/build
Parallel jobs rninja -j8
Verbose output rninja -v
Dry run rninja -n
Clean build outputs rninja -t clean
Show cache stats rninja -t cache-stats
List all tools rninja -t list
Show dependencies rninja -t deps target
Generate compile_commands.json rninja -t compdb