他のビルドシステムを高水準言語にたとえるなら、Ninjaはアセンブラーを目指しています。

ビルドシステムは判断を行う必要があると遅くなります。編集とコンパイルを繰り返すときは、できるだけ速く動いてほしいものです。つまり、直ちにビルドが必要なものを特定するために、必要最小限の作業だけを行ってほしいのです。

Ninjaは任意の依存グラフを記述するための最小限の機能を備えています。構文が限られているため、複雑な判断を表現することはできません。

Ninjaは、入力ファイルを生成する別のプログラムと組み合わせて使うことを想定しています。生成プログラム（autotoolsプロジェクトにある./configureのようなもの）は、システムの依存関係を解析し、できる限り多くの判断を事前に済ませて、差分ビルドの速さを保てます。autotoolsよりさらに踏み込んで、「どのコンパイラーフラグを使うか」「デバッグ版とリリース版のどちらのバイナリーをビルドするか」といったビルド時の判断も、.ninjaファイルの生成プログラムで行うべきです。

Ninjaの設計目標は次のとおりです。

明示的に目標としていないこともあります。

言い換えると、Ninjaが他のビルドシステムより速いのは、極端に単純だからです。プロジェクトの.ninjaファイルを作るときに、実行すべきことを正確にNinjaへ伝えなければなりません。

Ninjaは、ファイルのタイムスタンプ間の単純な依存関係に基づく点で、思想も機能もMakeに最も近いものです。

ただし、makeには本質的に多くの機能があります。サフィックスルール、関数、ソースのビルド時にRCSファイルを探すような組み込みルールなどです。Makeの言語は人間が書くことを想定して設計されています。多くのプロジェクトでは、makeだけでビルドの課題を十分に解決できます。

それに対し、Ninjaにはほとんど機能がありません。正しいビルドに必要なものだけを備え、複雑さの大部分をNinja入力ファイルの生成へ委ねています。多くのプロジェクトでは、Ninjaだけを使っても役立つとは限りません。

NinjaがMakeに追加する機能をいくつか挙げます。（こうした機能は、より複雑なMakefileで実装できることもありますが、makeそのものの機能ではありません。）

ninjaを実行します。既定では、現在のディレクトリにあるbuild.ninjaというファイルを探し、更新が必要なすべてのターゲットをビルドします。ビルドするターゲット（ファイル）をコマンドライン引数で指定することもできます。

target^という特別な構文もあります。コマンドラインで指定したソースを含むルールが存在する場合、そのルールの最初の出力をターゲットとして指定します。たとえば、ターゲットをfoo.c^と指定すると、foo.oがビルドされます（ビルドファイルにそのターゲットがあると仮定します）。

ninja -hはヘルプを表示します。Ninjaのフラグの多くは、意図的にMakeに合わせてあります。たとえば、ninja -C build -j 20はbuildディレクトリへ移動し、20個のビルドコマンドを並列実行します。（なお、Ninjaはもともと既定でコマンドを並列実行するため、通常は-jを指定する必要はありません。）

バージョン1.13以降、NinjaのビルドはGNU Make jobserverのクライアントプロトコルに従えます。最上位のGNU Makeや、その他のjobserverプールの実装が制御する大きなビルドシステムの一部としてNinjaを呼び出すときに便利です。並列ビルドタスク間の連携を改善できるためです。

この機能は、次の条件を満たすと自動的に有効になります。

この場合、Ninjaは既定の並列実行の実装の代わりに、jobserverのジョブ枠のプールを使って並列数を制御します。

このモードでも、負荷平均による制限（-l<count>を使用した場合）は引き続き適用されます。

Ninjaは動作を制御する二つの環境変数に対応しています。NINJA_STATUSは、実行するルールの前に表示する進捗状況です。

次のプレースホルダーを使えます。

既定の進捗表示は"[%f/%t] "です（ビルドルールとの区切りのため、末尾に空白がある点に注意してください）。他の例として、"[%u/%r/%f] "という進捗表示も考えられます。

環境変数MAKEFLAGSが定義されていると、Ninjaの並列ビルドコマンドの割り当て方法が変わることがあります。詳しくはGNU jobserverへの対応の節を参照してください。

Ninjaのコマンドラインにある-tフラグは、Ninjaの開発中に便利だと分かったツールを実行します。現在のツールは次のとおりです。

Ninjaはファイル間の依存グラフを評価し、ファイルの更新時刻から判断してビルドターゲットを最新にするために必要なコマンドを実行します。Makeを知っているなら、Ninjaは非常によく似ています。

ビルドファイル（既定の名前はbuild.ninja）には、コンパイラーの実行方法など、長いコマンドの短い名前であるルールの一覧と、ルールを使ったファイルのビルド方法を示すbuild文の一覧が含まれます。build文は、どのルールをどの入力へ適用し、どの出力を生成するかを指定します。

概念上、build文はプロジェクトの依存グラフを記述し、rule文は、グラフのあるエッジに沿ってファイルを生成する方法を記述します。

構文の大部分を示す、基本的な.ninjaファイルを挙げます。以降の節では、このファイルを例として使います。

手書きの便利さは目標にしていませんが、ビルドファイルを読みやすく（デバッグしやすく）するため、Ninjaでは文字列に短く再利用可能な名前を付けられます。次のような宣言を、

等号の右辺でドル記号によって参照できます。たとえば次のように使います。

${in}のように、波括弧を使って変数を参照することもできます。

変数は変更できず、シャドーイングしかできないため、「束縛」と呼ぶ方が適切かもしれません。シャドーイングの仕組みについては、この文書の後半で詳しく説明します。

ルールはコマンドラインの短い名前を宣言します。ruleキーワードとルール名からなる行で始まり、その後にインデントしたvariable = valueの行を並べます。

前述の基本例では、ccという新しいルールを、実行するコマンドとともに宣言しています。ルール内では、command変数が実行するコマンドを定義し、$inはそのコマンドの入力ファイルの一覧（foo.c）へ、$outは出力ファイルの一覧（foo.o）へ展開されます。特殊変数の完全な一覧は、リファレンスを参照してください。

build文は、入力ファイルと出力ファイルの関係を宣言します。buildキーワードで始まり、build outputs: rulename inputsという形式です。この宣言は、すべての出力ファイルが入力ファイルから生成されることを示します。出力ファイルが存在しないか入力が変わったとき、Ninjaはルールを実行し、出力を再生成します。

前述の基本例では、ccルールを使ってfoo.oをビルドする方法を記述しています。

buildブロックのスコープ内（関連するruleの評価時も含む）では、$in変数は入力の一覧、$out変数は出力の一覧です。

build文の後にも、ルールと同様に、インデントしたkey = valueの組を並べられます。これらの変数は、コマンド内の変数を評価するとき、他の変数をシャドーイングします。たとえば次のとおりです。

スコープの仕組みについて詳しくは、リファレンスを参照してください。

build文からルールへ、より複雑な情報（たとえば「最初の入力のファイル拡張子」）を渡す必要がある場合は、前述のcflagsのように、追加の変数として渡してください。

最上位のNinjaファイルがいずれかのbuild文の出力に指定されており、更新が必要な場合、Ninjaはユーザーが要求したターゲットをビルドする前に、そのファイルを再ビルドして再読み込みします。

Ninjaの配布物にあるmisc/ninja_syntax.pyは、Ninjaファイルの生成を簡単にする小さなPythonモジュールです。ninja.rule(name='foo', command='bar', depfile='$out.d')のようにPythonから呼び出すと、適切な構文を生成します。役に立つなら、プロジェクトのビルドシステムへそのまま組み込んでかまいません。

特別なルール名phonyを使うと、他のターゲットに別名を付けられます。たとえば次のとおりです。

これにより、ninja fooで長いパスのファイルをビルドできます。意味上、phonyルールはcommandが何もしない通常のルールと同じですが、phonyルールは特別に扱われます。実行時に表示されず、ログにも記録されず（後述）、ビルド中に表示されるコマンド数にも含まれません。

phonyターゲットが別のビルドルールの入力に使われると、そのビルドルールは、意味上、phonyルールの入力を自身の入力として扱います。そのため、phonyルールで、ヘッダーファイルなどの入力をまとめられます。

phonyは、ビルド時には存在しないかもしれないファイルのダミーターゲットを作るためにも使えます。依存関係のないphonyのbuild文を記述した場合、そのターゲットが存在しなければ更新が必要と判断されます。phonyのbuild文がない場合、ビルドに必要なファイルが存在しなければ、Ninjaはエラーを報告します。

再ビルドされないルールを作るには、入力のないビルドルールを使います。

コマンドラインにターゲットの指定がない場合、既定では、他の場所で入力として指定されていないすべての出力をNinjaがビルドします。default文を使うと、この動作を変更できます。default文を指定すると、コマンドラインでターゲットを指定しなかった場合に、出力ファイルの指定した一部だけをビルドします。

default文はdefaultキーワードで始まり、default targetsという形式です。ターゲットを出力ファイルとして宣言するbuild文の後に置く必要があります。default文は累積するため、複数の文で既定のターゲットの一覧を拡張できます。たとえば次のとおりです。

これにより、Ninjaは既定でfoo、bar、bazターゲットをビルドします。

Ninjaは、ビルドしたファイルごとに、そのビルドに使ったコマンドをログに記録します。このログを使うことで、既存の出力がビルドファイルに指定されたものとは異なるコマンドラインでビルドされたこと（つまりコマンドラインが変わったこと）を検出し、そのファイルを再ビルドすべきだと判断できます。

ログはビルドのルートにある.ninja_logというファイルへ保存します。最も外側のスコープにbuilddirという変数を指定すると、.ninja_logは代わりにそのディレクトリへ保存されます。

Ninja 1.2以降で利用可能です。

Ninjaのバージョン表記は、標準的なmajor.minor.patch形式に従います。後方互換性のない構文や動作の変更ではメジャーバージョンが、新しい動作の追加ではマイナーバージョンが上がります。build.ninjaにはninja_required_versionという変数を宣言し、生成したファイルを使うために必要なNinjaの最低バージョンを指定できます。たとえば、

この宣言は、ビルドファイルがNinja 1.1で導入された機能（たとえばpool構文）に依存し、ビルドにNinja 1.1以降が必要であることを示します。他のNinja変数と異なり、このバージョン要件は、解析中に変数を見つけた時点ですぐに確認します。そのため、ビルドファイルの先頭に置くのが適切です。

Ninja自身とninja_required_versionのメジャーバージョンが一致しない場合、Ninjaは必ず警告します。メジャーバージョンの変更はまだ起きていないため、どのような動作が必要になるかを予測するのは困難です。

Ninjaには、C/C++のヘッダー依存関係（または同様の仕組みのビルド依存関係）を正しく扱うための追加機能があります。

ヘッダーの問題は、あるソースファイルが依存するファイルの完全な一覧を、コンパイラーだけが発見できることです。プリプロセッサーの定義やインクルードパスが変わると、使われるファイルも変わります。一部のコンパイラーはビルド中にこの情報を出力でき、Ninjaはそれを使って依存関係を正確に扱えます。

ファイルがまだコンパイルされたことがなければ、いずれにしてもビルドが必要で、その副作用としてヘッダー依存関係が生成されます。その後に何らかのファイルが変更されると（依存するヘッダーの組が変わるような変更であっても）、その変更によって再ビルドされ、依存関係も最新に保たれます。

こうした特殊な依存関係を読み込むとき、Ninjaは、列挙された依存ファイルが存在しなくてもエラーにならないよう、追加のビルドエッジを暗黙に作成します。これにより、ヘッダーファイルを削除して再ビルドしても、入力の欠落によってビルドが中断されません。

Ninja 1.1以降で利用可能です。

プールを使うと、一つ以上のルールやエッジに対し、既定の並列数より厳しく制限した、有限の並列ジョブ数を割り当てられます。

たとえば、大きな実行ファイルのリンク処理のような負荷の高い特定のルールや、並列実行すると性能が落ちることが分かっている特定のbuild文を制限するために使えます。

各プールには、ビルドファイル内で指定するdepth変数があります。ルールまたはbuild文のpool変数で、そのプールを参照します。

どのようなプールを指定しても、Ninjaが同時に実行するジョブ数は、既定の並列数またはコマンドラインの-jで指定したジョブ数を超えません。

Ninjaは、パス内のスラッシュなど、Ninjaが解釈するバイトがASCIIであれば、ほとんどの場合エンコーディングを問いません。したがって、UTF-8やISO-8859-1などの入力ファイルも動作するはずです。

コメントは#で始まり、行末まで続きます。

改行には意味があります。build foo barのような文は、空白で区切られたトークンの列で、改行で終わります。トークン内の改行と空白はエスケープする必要があります。

エスケープ文字は$の一つだけで、次のように動作します。

build文とdefault文は、まず空白で区切られたファイル名の一覧として解析され、その後、各名前が展開されます。したがって、変数内の空白は、展開後のファイル名の中の空白になります。

name = value文では、値の先頭にある空白文字は常に取り除かれます。行継続後の行の先頭にある空白文字も取り除かれます。

その他の空白文字は、行頭にある場合だけ意味を持ちます。ある行が直前の行より深くインデントされている場合は、親のスコープの一部とみなします。直前の行より浅い場合は、直前のスコープを閉じます。

最も外側のファイルスコープで宣言したときに意味を持つ変数は、二つあります。

ruleブロックには、ルールの処理に影響するkey = value宣言の一覧が含まれます。特殊なキーの完全な一覧を示します。

ビルドの出力には、わずかに異なる二つの種類があります。

ビルドの依存関係には、わずかに異なる三つの種類があります。

ファイルパスはそのまま比較します。したがって、同じファイルを指していても、絶対パスと相対パスはNinjaでは別のものとして扱います。

Ninja 1.11以降で利用可能です。

build行が、コマンドラインで指定されたターゲットまたは既定のターゲットの推移的な依存先である場合、その行に列挙した検証のファイルを、ビルドグラフの最上位へ追加します。Ninjaのコマンドラインで指定した場合と同じ扱いになります。

検証は、build文の出力ファイルに更新が必要かどうかに関係なく、ビルドグラフへ追加されます。また、検証として使うファイルを出力するbuild文の更新の必要性は、その検証を要求したbuild文の更新の必要性に影響しません。

あるビルドエッジは、別のビルドエッジが自身に依存していても、そのエッジを検証として列挙できます。

検証は、静的解析ツールなど、エラーチェックを行うものの、ビルドに必要な生成物を出力しないルールを扱うために設計されています。静的解析ルールを、ソースファイルの主要なビルドルールや、そのルールに依存するルールの暗黙の入力にすると、ビルドのクリティカルパスが遅くなります。検証を使えば、主要なビルドルールが完了した後、ビルドの続きと静的解析ルールを並列に実行できます。

変数は、パス（build文またはdefault文の中）と、name = value文の右辺で展開されます。

name = value文を評価すると、その右辺は直ちに展開されます（後述のスコープ規則に従います）。それ以降、$nameは、展開結果の固定された文字列に展開されます。二重に展開されることを防ぐために、値を「二重にエスケープ」する必要はありません。

すべての変数は、解析中に現れた時点で直ちに展開されます。ただし、一つ重要な例外があります。ruleブロックの変数は、宣言時ではなく、ルールを使うときに展開されます。次の例では、demoルールは「this is a demo of bar」と表示します。

最上位の変数宣言のスコープは、宣言したファイルです。

ルール宣言のスコープも、宣言したファイルです。（Ninja 1.6以降で利用可能。）

別の.ninjaファイルを取り込むsubninjaキーワードは、新しいスコープを作ります。取り込まれたsubninjaファイルは、親ファイルの変数とルールを利用でき、自身のファイルスコープ内でその値をシャドーイングできますが、親ファイルの変数の値には影響しません。

Cの#include文のように、現在のスコープへ別の.ninjaファイルを取り込むには、subninjaではなくincludeを使います。

buildブロック内でインデントした変数宣言のスコープは、そのbuildブロックです。buildブロック（または、そのブロックで使うrule）で展開する変数の検索順序は、次のとおりです。

dyndep束縛で指定するファイルは、Ninjaビルドファイルと同じ字句構文を使い、次の構成になります。

dyndepファイル内のbuild文は、dyndep束縛でそのdyndepファイルを指定しているNinjaビルドファイル内のbuild文と、一対一に対応しなければなりません。dyndepのbuild文を省略しても、余分なbuild文を指定してもいけません。