---
title: Overview
description: What is rninja and why should you use it
tags:
  - getting-started
  - overview
---

# Overview

rninja is a high-performance, drop-in replacement for the [Ninja build system](https://ninja-build.org/), written in Rust. It maintains full compatibility with existing Ninja build files while adding powerful features like built-in caching and improved scheduling.

## What is Ninja?

Ninja is a small, fast build system focused on speed. Unlike make or other build systems, Ninja is designed to have its input files generated by a higher-level build system like CMake, Meson, or GN. Its simplicity and speed have made it the build backend of choice for many large projects, including Chromium, Android, and LLVM.

## What is rninja?

rninja takes everything that makes Ninja great and adds:

- **Built-in caching** - Content-addressed artifact caching that persists across clean builds
- **Remote cache support** - Share cached artifacts across your team and CI
- **Modern scheduler** - Tokio-based async runtime for better CPU utilization
- **Daemon mode** - Long-running process that caches parsed manifests

## Key Features

### Drop-in Compatibility

rninja reads the same `build.ninja` files that Ninja uses. You don't need to modify your build configuration or change how your build generator (CMake, Meson, GN) works.

```bash
# If this works...
ninja -C out/Release

# ...then this works too
rninja -C out/Release
```

All standard Ninja CLI flags are supported:

| Flag | Description |
|------|-------------|
| `-C DIR` | Change to DIR before building |
| `-f FILE` | Use FILE as the build file |
| `-j N` | Run N jobs in parallel |
| `-k N` | Keep going after N failures |
| `-n` | Dry run |
| `-v` | Verbose output |
| `-d MODE` | Debug mode |
| `-t TOOL` | Run a subtool |

### Content-Addressed Caching

rninja automatically caches build outputs based on their inputs:

- **BLAKE3 hashing** for fast, secure content addressing
- **Local cache** stored in `~/.cache/rninja` by default
- **Automatic restoration** when inputs match a cached build
- **Correct invalidation** when any input changes

This means:

- `make clean && make` becomes instant (cache hit)
- Switching branches and back restores previous builds
- CI builds can reuse artifacts from previous runs

### Remote Cache Support

Share cached artifacts across machines:

```bash
export RNINJA_CACHE_REMOTE_SERVER=tcp://cache.internal:9999
export RNINJA_CACHE_TOKEN=your-token
rninja
```

Benefits:

- CI runners share artifacts, reducing build times
- Team members benefit from each other's builds
- Remote-first or local-fallback modes available

### Daemon Mode

rninja can run as a long-lived daemon that:

- Caches parsed `build.ninja` manifests
- Maintains warm file system caches
- Handles multiple concurrent build requests
- Auto-spawns when you run `rninja`

## rninja vs Ninja

| Feature | Ninja | rninja |
|---------|-------|--------|
| Build file format | `.ninja` | `.ninja` (same) |
| CLI compatibility | - | Full |
| Build caching | None | Built-in |
| Remote cache | None | Built-in |
| No-op build speed | ~0.23s | ~0.01s |
| Daemon mode | No | Yes |
| Written in | C++ | Rust |

## When to Use rninja

rninja is ideal for:

- **Large C/C++ projects** with long incremental build times
- **CI/CD pipelines** where build time directly impacts costs
- **Monorepos** where multiple teams share code
- **Teams** that want to share build artifacts
- **Developers** who frequently switch between branches

## When NOT to Use rninja

rninja may not be necessary for:

- **Small projects** where builds complete in seconds
- **Single-file builds** with no caching benefit
- **Environments** where Ninja isn't already in use

## Next Steps

<div class="grid cards" markdown>

-   :material-download: [__Installation__](installation.md)

    Install rninja on your system

-   :material-rocket-launch: [__Quick Start__](quick-start.md)

    Get rninja running in 5 minutes

-   :material-swap-horizontal: [__Migration Guide__](migration.md)

    Switch from Ninja to rninja

</div>
