path: root/manual.asciidoc

Ninja
=====

Introduction
------------

Ninja is yet another build system.  It takes as input a file
describing interdependencies of files (typically source code and
output executables) and orchestrates building them, _quickly_.

Ninja joins a sea of other build systems.  Its distinguishing goal is
to be fast.  It is born from my work on the Chromium browser project,
which has well over 20,000 source files and whose other build systems
(including one built from custom non-recursive Makefiles) take tens of
seconds to rebuild after changing one file, even on a fast computer.

Here are some of the design goals of Ninja:

* very fast (i.e., instant) incremental builds, even for very large
  projects.

* very little implicit policy; "explicit is better than implicit".

* get dependencies correct, and in particular situations that are
  difficult to get right with Makefiles (e.g. outputs should have an
  implicit dependency on the command line used to generate them; using
  gcc's `-M` flags for header dependencies).

* when convenience and speed are in conflict, prefer speed.

Some explicit _non-goals_:

* convenient syntax for writing build files by hand.  _You should
  generate your ninja files using another program_.  This is how we
  sidestep many policy decisions.

* built-in rules. _Out of the box, ninja has no rules for
  e.g. compiling C code._

* build-time customization of the build. _Options belong in
  the program that generates the ninja files_.

To restate, Ninja manages to be simpler and faster than other build
systems by being much more stupid.  It has no built-in behavior
describing how to build C source, or build libraries, or install
binaries.  You instead decide this policy when you create your
project's `.ninja` files.  Customization and configuration are out of
scope; instead you should provide customization in the system that
generates your `.ninja` files, like how autoconf provides
`./configure`.

Getting started
---------------

The included `bootstrap.sh` should hopefully produce a working `ninja`
binary, by first blindly compiling all non-test files together then
re-building ninja using itself.

Usage is currently just

----------------
ninja target
----------------

where `target` is a known output described by `build.ninja` in the
current directory.

Creating .ninja files
~~~~~~~~~~~~~~~~~~~~~
A build file (default name: `build.ninja`) provides a list of _rules_
along with a list of _build_ statements saying how to build files
using the rules.  The only other syntax is a way of declaring
(immutable) variables.

Conceptually, `build` statements describe the dependency graph of your
project, while `rule` statements describe how to generate the files
along a given edge of the graph.

Here's a basic `.ninja` file that demonstrates most of the syntax.

---------------------------------
cflags = -Wall

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

build foo.o: cc foo.c
---------------------------------

Rules
~~~~~

Rules begin with a line consisting of the `rule` keyword and a name
for the rule.  Then follows an indented set of `key = value` lines.

The basic example above declares a new rule named `cc`, along with the
command to run.  (In the context of a rule, the `command` key is
special and defines the command to run.  A full list of special keys
is provided in the reference.)

Variables begin with a `$` and are described more fully later, but
here `$in` expands to the list of input files (`foo.c`) and `$out` to
the output file (`foo.o`) for the command.


Build statements
~~~~~~~~~~~~~~~~

Build statements begin with the `build` keyword, and have the format
+build _outputs_: _rulename_ _inputs_+.  Such a declaration says that
all of the output files are derived from the input files.  When the output
files are missing or when the inputs change, ninja will run the rule
to regenerate the outputs.

The basic example above describes how to build `foo.o`, using the `cc`
rule.

A build statement may be followed by an indented set of `key = value`
pairs, much like a rule.  These bindings will shadow any bindings when
evaluating the variables in the command.  For example:

----------------
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 can shadow variables like cflags for a particular build.
build special.o: cc.special.c
  cflags = -Wall
----------------


Variables
~~~~~~~~~
Despite the non-goal of being convenient to write by hand, to keep
build files readable (debuggable), Ninja supports declaring bindings
(variables).  A declaration like the following

----------------
cflags = -g
----------------

Can be used on the right side of an equals sign like this:

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

Variables can also be referenced using curly braces like `${in}`.

Variables might better be called "bindings", in that a given variable
cannot be changed, only shadowed.  Within a larger Ninja project,
different _scopes_ allow variable values to be overridden.  XXX finish
describing me.

Ninja file reference
--------------------
A file is a series of declarations.  A declaration can be one of:

1. A rule declaration, which begins with +rule _rulename_+.
2. A build edge, which looks like +build _outputs_: _rulename_ _inputs_+
3. Variable declarations, which look like +_variable_ = _value_+.

Comments begin with `#` and extend to the end of the line.

Newlines are significant, but they can be escaped by putting a `\`
before them.

Whitespace is only significant if it's at the beginning of a line.  If
a line is intended more than the previous one, it's considered part of
its parent's scope; if it is indented less than the previous one, it
closes the previous scope.

Rule declarations
~~~~~~~~~~~~~~~~~

A `rule` block contains a list of `key = value` declarations that
affect the processing of the rule.  Here is a full list of special
keys.

`command` (_required_):: the command line to run.

`depfile`:: path to an optional `Makefile` that contains _implicit
  dependencies_.  Implicit dependencies are inputs to a build that are
  not given on the command line; the best example is how `gcc` has the
  `-M` family of flags to output the list of headers a given `.c` file
  depends on.
+
----
rule cc
  depfile = $out.d
  command = gcc -MMD -MF $out.d [other gcc flags here]
----

`description`:: a short description of the command, used to pretty-print
  the command as it's running.  _XXX not implemented yet_.

Special variables
~~~~~~~~~~~~~~~~~
`builddir` is a directory for intermediate build output.  (The name
comes from autoconf.)  It is special in a few ways:

1. It gets a shorter alias: `@`.
2. It is implicitly a directory and has a `/` appended if needed.
3. It may be used in the filenames of a `build` line.

You must still be explicit in your rules.  In the following
example, the files prefixed with `@` will end up in the `out/`
subdirectory.

----------------
builddir = out
build @intermediate_file: combine @generated_file source_file

# Equivalent rule:
# build out/intermediate_file: combine out/generated_file source_file
----------------

XXX I hacked in a special `$root` only understood in builddir -- fix
the semantics here, is this path relative or absolute?

Evaluation and scoping
~~~~~~~~~~~~~~~~~~~~~~
XXX talk about where variables live, nested scopes etc