Skip to content

Migrating from Ninja

This guide helps teams migrate from Ninja to rninja with minimal disruption.

Migration Overview

rninja is designed as a drop-in replacement for Ninja. In most cases, migration is as simple as:

# Instead of
ninja

# Use
rninja

No changes to your build.ninja files, build generators, or CI scripts are required.

Compatibility Checklist

rninja is compatible with:

Feature Status
.ninja file format Full support
.ninja_log format Full support
.ninja_deps format Full support
All CLI flags Full support
All subtools Full support
CMake generator Tested
Meson generator Tested
GN generator Tested

Step-by-Step Migration

Step 1: Install rninja

cargo install rninja

Verify installation:

rninja --version

Step 2: Test Locally

Before changing anything, test rninja on your project:

# Clean to ensure fresh build
ninja -t clean

# Build with rninja
rninja

# Run tests to verify outputs

Compare the outputs to ensure everything builds correctly.

Step 3: Create an Alias (Optional)

For gradual migration, create an alias:

# In ~/.bashrc or ~/.zshrc
alias ninja='rninja'

This lets you use ninja commands while actually using rninja.

Step 4: Replace Ninja Binary (Full Migration)

For complete migration, replace the ninja binary:

# Create symlink
sudo ln -sf $(which rninja) /usr/local/bin/ninja

# Or rename the original
sudo mv /usr/bin/ninja /usr/bin/ninja.orig
sudo ln -s $(which rninja) /usr/bin/ninja

Step 5: Update CI Configuration

Update your CI scripts to use rninja:

.github/workflows/build.yml
- name: Install rninja
  run: cargo install rninja

- name: Build
  run: rninja -C build
.gitlab-ci.yml
build:
  script:
    - cargo install rninja
    - rninja -C build
Jenkinsfile
stage('Build') {
    sh 'cargo install rninja'
    sh 'rninja -C build'
}

See CI/CD Integration for detailed guides.

Handling Differences

Caching Behavior

rninja caches build outputs by default. This is almost always beneficial, but you can disable it if needed:

# Disable caching for a single build
RNINJA_CACHE_ENABLED=0 rninja

# Or in config file
# ~/.config/rninja/config.toml
[cache]
enabled = false

Daemon Mode

rninja uses a daemon for faster subsequent builds. This is transparent but can be disabled:

# Run without daemon
rninja --no-daemon

Additional Output

rninja may show additional output (cache statistics, timing). Use standard flags to control this:

# Quiet mode (same as ninja)
rninja 2>/dev/null

Migration for Teams

Gradual Rollout

  1. Start with developers: Have a few developers test rninja locally
  2. Add to CI: Update one CI pipeline to use rninja
  3. Monitor: Watch for any issues or unexpected behavior
  4. Expand: Roll out to more developers and pipelines
  5. Complete: Replace ninja system-wide

Communication Template

Share with your team:

We're switching from Ninja to rninja for faster builds. rninja is a drop-in replacement with:

  • 23x faster no-op builds
  • Built-in caching for 2-5x faster incremental builds
  • Optional remote cache sharing

Migration is simple: replace ninja with rninja. All flags and build files work identically.

Rollback Plan

If issues occur, rolling back is simple:

# Remove symlink
sudo rm /usr/local/bin/ninja

# Reinstall original ninja
# Ubuntu/Debian
sudo apt install ninja-build

# Or just use ninja directly
ninja  # original binary

Common Migration Issues

Issue: Build Outputs Differ

rninja should produce identical outputs, but if you notice differences:

  1. Check for non-deterministic build steps (timestamps, random values)
  2. Ensure all inputs are properly declared in the build file
  3. Report issues at github.com/neul-labs/rninja/issues

Issue: Cache Takes Too Much Space

The default cache can grow large. Configure limits:

~/.config/rninja/config.toml
[cache]
max_size = 5368709120  # 5GB

Or run garbage collection:

rninja -t cache-gc

Issue: Daemon Won't Start

If the daemon fails to start:

# Run without daemon
rninja --no-daemon

# Check daemon logs
rninja-daemon --foreground

# Use custom socket path
rninja --daemon-socket /tmp/my-rninja.sock

Issue: CI Builds Are Slower

First builds in CI may be slower because the cache is cold. Solutions:

  1. Persist cache: Save ~/.cache/rninja between CI runs
  2. Use remote cache: Set up shared cache server
  3. Warm cache: Pre-populate cache with common builds

Verifying Migration

After migration, verify everything works:

# 1. Clean build
rninja -t clean
rninja

# 2. Incremental build
touch some_file.c
rninja

# 3. No-op build
rninja

# 4. Run tests
./run_tests.sh

# 5. Check cache
rninja -t cache-stats

Getting Help

If you encounter issues:

  1. Check Troubleshooting
  2. Search GitHub Issues
  3. Open a new issue with:
  4. rninja version (rninja --version)
  5. Operating system
  6. Build generator (CMake, Meson, etc.)
  7. Steps to reproduce

Next Steps