Skip to content

Installation

rninja can be installed on Linux, macOS, and Windows. Choose the installation method that works best for your environment.

Requirements

  • Rust toolchain (for installation via Cargo)
  • Git (for building from source)

Installation Methods

The simplest way to install rninja is via Cargo:

cargo install rninja

This installs the following binaries:

Binary Description
rninja Main CLI (drop-in Ninja replacement)
rninja-daemon Build daemon for faster subsequent builds
rninja-cached Remote cache server

From Source

To build from source with the latest changes:

# Clone the repository
git clone https://github.com/neul-labs/rninja
cd rninja

# Build and install
cargo install --path .

For development builds:

# Debug build (faster compilation, slower runtime)
cargo build

# Release build (slower compilation, faster runtime)
cargo build --release

Verifying Installation

After installation, verify rninja is working:

rninja --version

Expected output:

rninja 0.1.0

List available subtools:

rninja -t list

Setting Up as Ninja Replacement

Option 1: Alias

Add to your shell configuration (~/.bashrc, ~/.zshrc, etc.):

alias ninja='rninja'

Create a symlink so tools that call ninja use rninja:

sudo ln -s $(which rninja) /usr/local/bin/ninja

mkdir -p ~/.local/bin
ln -s $(which rninja) ~/.local/bin/ninja
# Ensure ~/.local/bin is in your PATH

Symlink Priority

If you already have Ninja installed, ensure the symlink location comes before Ninja in your PATH, or remove the original Ninja binary.

Option 3: Environment Variable

Some build systems respect environment variables:

# For CMake
export CMAKE_MAKE_PROGRAM=$(which rninja)

# Or configure CMake directly
cmake -DCMAKE_MAKE_PROGRAM=$(which rninja) ..

Platform-Specific Notes

Linux

rninja works on all modern Linux distributions. No special configuration needed.

# Verify installation
which rninja
rninja --version

macOS

rninja works on macOS 10.15 (Catalina) and later.

# Install Rust if needed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install rninja
cargo install rninja

Windows

rninja works on Windows 10 and later with the Rust toolchain installed.

# Install via Cargo
cargo install rninja

# Add to PATH if needed
$env:PATH += ";$env:USERPROFILE\.cargo\bin"

Installing Additional Components

Remote Cache Server

The remote cache server (rninja-cached) is installed automatically with the main package. To run it:

rninja-cached --help

See Remote Cache Deployment for setup instructions.

Daemon

The daemon (rninja-daemon) is also installed automatically. It typically auto-starts when you run rninja, but can be managed manually:

rninja-daemon --help

See Daemon Management for details.

Updating rninja

To update to the latest version:

cargo install rninja --force

Or if you built from source:

cd rninja
git pull
cargo install --path . --force

Uninstalling

To remove rninja:

cargo uninstall rninja

If you created a symlink:

sudo rm /usr/local/bin/ninja  # or wherever you created it

Troubleshooting Installation

Cargo Not Found

If cargo is not found, install the Rust toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Build Fails

If the build fails, ensure you have the required build tools:

sudo apt update
sudo apt install build-essential pkg-config

sudo dnf install gcc pkg-config

xcode-select --install

Permission Denied

If you get permission errors when creating symlinks:

# Use user-local directory instead
mkdir -p ~/.local/bin
ln -s $(which rninja) ~/.local/bin/ninja

# Add to PATH in your shell config
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Next Steps