ninja

Ninja

目的

エージェントがビルド実行ツールとして Ninja を使う際に、失敗の診断、並列処理の制御、CMake からの生成、必要に応じた .ninja ファイル形式の理解を支援します。

トリガー

• 「Ninja でエラーが発生しています。出力をもっと表示するにはどうすればよいですか？」
• 「Ninja を CMake と一緒に使うにはどうすればよいですか？」
• 「Ninja は並列ジョブをいくつ実行しますか？」
• 「Ninja にカスタムビルドステップを追加するにはどうすればよいですか？」
• 「build.ninja ファイルとは何ですか？」

ワークフロー

1. CMake ジェネレーターとしての Ninja

Ninja は、CMake のビルド実行ツールとして使われることが最も一般的です。

# Configure with Ninja
cmake -S . -B build -G Ninja
cmake --build build                    # uses ninja internally

# Or invoke ninja directly
cd build && ninja

# Specify parallelism
ninja -j4
ninja -j$(nproc)

# Build specific target
ninja myapp
ninja install

CMake は Ninja Multi-Config にも対応しています。

cmake -S . -B build -G "Ninja Multi-Config"
cmake --build build --config Release
cmake --build build --config Debug

2. 詳細出力と診断

# Show full commands (not just [CC] foo.c)
ninja -v

# Dry run (show what would be built)
ninja -n

# Show why a target needs rebuilding
ninja -d explain myapp

# Print all targets
ninja -t targets all

# Print targets grouped by rule
ninja -t targets rule cc

# Dependency graph (graphviz)
ninja -t graph myapp | dot -Tsvg -o deps.svg

3. よく使う Ninja フラグ

フラグ	効果
-j N	並列ジョブ数（デフォルト：CPU 数 + 2）
-l N	ロードアベレージが N を超えている場合、新しいジョブを開始しません
-k N	N 件の失敗後も処理を続行します（デフォルトは 1）
-v	詳細表示：コマンドライン全体を表示します
-n	ドライラン
-C dir	すべての処理に先立って dir に移動します
-t tool	サブツール（clean、query、targets、graph、compdb）を実行します

4. クリーンアップ

ninja -t clean          # remove build outputs
ninja -t clean -g       # also remove generated files

または CMake 経由で実行します。

cmake --build build --target clean

5. compile_commands.json

Ninja は（CMake 経由で）IDE 連携や clang-tidy 用の compile_commands.json を生成できます。

cmake -S . -B build -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
ln -sf build/compile_commands.json .

6. build.ninja の形式（参考）

手書きされることはほとんどありませんが、デバッグ時に理解しておくと役立ちます。

# Variable
cflags = -Wall -O2

# Rule
rule cc
  command = gcc $cflags -c $in -o $out
  description = CC $in

# Build edge
build foo.o: cc foo.c

# Phony target
build all: phony foo.o

# Default target
default all

主な概念：

• rule：入力から出力を生成する方法を定義します
• build：特定のファイルを使ってルールをインスタンス化します
• $in / $out：入力／出力に使う自動変数です
• phony：常に古いものと見なされるターゲットです（make の .PHONY のようなものです）

7. Ninja サブツール

# List all build targets
ninja -t targets

# Query dependencies of a target
ninja -t query myapp

# Clean (already mentioned)
ninja -t clean

# Generate compile_commands.json (if supported by generator)
ninja -t compdb cc cxx > compile_commands.json

# List rules
ninja -t rules

8. よくある問題

問題	原因	対処方法
ninja: error: 'foo.o', needed by 'prog', missing and no known rule to make it	ビルドルールがありません	CMake で再生成し、add_executable のソース一覧を確認します
ビルドで変更が反映されない	build.ninja が古くなっています	cmake -S . -B build を再実行します
並列ビルドが非常に遅い	I/O 負荷の高いビルドに対して -j の値が大きすぎます	-l$(nproc) を使って負荷を制限します
循環依存	ルールが自分自身に依存しています	CMake のターゲット依存関係を確認します

Ninja コマンドの完全なリファレンス、build.ninja 形式の詳細、CMake との連携パターンについては、references/cheatsheet.md を参照してください。

関連スキル

• Ninja ファイルを生成する CMake の設定には、skills/build-systems/cmake を使用します
• Make ベースのプロジェクトには、skills/build-systems/make を使用します