独自のNinjaファイルを書き込む

このマニュアルの残りの部分は、Ninjaファイルを自分で構築する場合にのみ有用です。例えば、メタビルドシステムを書いたり、新しい言語をサポートする場合などです。

コンセプトの概要

Ninjaはファイル間の依存関係のグラフを評価し、ファイルの変更時間から判断して、ビルド対象を最新の状態にするのに必要なコマンドを実行します。Makeに慣れている人なら、Ninjaは非常によく似ている。

ビルドファイル（デフォルト名：build.ninja）は、ルール（コンパイラの実行方法などの長いコマンドの短い名前）のリストと、そのルールを使ってどのようにファイルを構築するか（どのルールをどの入力に適用してどの出力を生成するか）を示すビルド文のリストを提供するものです。

概念的には、ビルドステートメントはプロジェクトの依存関係グラフを記述し、ルールステートメントはグラフの与えられたエッジに沿ってファイルを生成する方法を記述します。

構文例

ここに、ほとんどの構文を示す基本的な .ninja ファイルがあります。これは以下のセクションの例として使用されます。

cflags = -Wall

rule cc
  command = gcc $cflags -c $in -o $out

build foo.o: cc foo.c

変数

手書きで書くのが便利という非目的はあるものの、ビルドファイルの可読性（デバッグ性）を保つために、Ninjaは文字列の短い再利用可能な名前の宣言をサポートしています。以下のような宣言である。

cflags = -g

等号の右側で使用でき、次のようにドル記号で再参照します。

rule cc
  command = gcc $cflags -c $in -o $out

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

変数は、与えられた変数を変更することはできず、シャドウイングされるだけであるという点で、「バインディング」と呼ぶ方がよいかもしれません。シャドウイングがどのように機能するかについては、このドキュメントの後のほうで詳しく説明します。

ルール

ルールは、コマンドラインの短い名前を宣言するものです。ルールは、ルールのキーワードとルールの名前で構成される行から始まります。その後、インデントされた変数=値の行が続きます。

上記の基本的な例では、ccという名前の新しいルールと、実行するコマンドを宣言しています。ルールのコンテキストでは、command変数が実行するコマンドを定義し、$inが入力ファイルのリスト(foo.c)に展開し、$outがそのコマンドの出力ファイル(foo.o)に展開します。特殊変数の完全なリストは、リファレンスに記載されています。

ビルドステートメント

Build文は、入力ファイルと出力ファイルの関係を宣言します。build キーワードで始まり、build outputs: rulename inputs のような形式をとります。この宣言は、すべての出力ファイルが入力ファイルから派生していることを意味する。出力ファイルが存在しない場合や入力が変更された場合、Ninjaは出力を再生成するためにルールを実行する。

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

ビルドブロックのスコープ（関連するルールの評価も含む）において、変数$inは入力のリスト、変数$outは出力のリストである。

build文の後には、ルールのようにキーと値のペアをインデントで記述することができます。これらの変数は、コマンドの変数を評価するときに、すべての変数をシャドウします。たとえば、以下のようになります。

cflags = -Wall -Werror
rule cc
  command = gcc $cflags -c $in -o $out

# If left unspecified, builds get the outer $cflags.
build foo.o: cc foo.c

# But you can shadow variables like cflags for a particular build.
build special.o: cc special.c
  cflags = -Wall

# The variable was only shadowed for the scope of special.o;
# Subsequent build lines get the outer (original) cflags.
build bar.o: cc bar.c

スコープがどのように機能するかについては、参考文献を参照してください。

もし、build文からルールへより複雑な情報を渡す必要がある場合（例えば、ルールが「最初の入力のファイル拡張子」を必要とする場合）、上記のcflagsが渡される方法のように、追加の変数としてその情報を渡します。

トップレベルのNinjaファイルがbuild文の出力として指定され、それが古い場合、Ninjaはユーザが要求したターゲットを構築する前に、ファイルを再構築して再読み込みする。

コードからNinjaファイルを生成する

Ninjaの配布物に含まれる misc/ninja_syntax.py は、Ninjaファイルの生成を容易にするための小さなPythonモジュールです。ninja.rule(name='foo', command='bar', depfile='$out.d') のようなPythonの呼び出しを行うと、適切な構文を生成してくれます。もし有用であれば、あなたのプロジェクトのビルドシステムにインライン化するのも自由です。