Initial import.

1 files changed, 916 insertions, 0 deletions

diff --git a/ninja/doc/manual.asciidoc b/ninja/doc/manual.asciidoc
new file mode 100644
index 00000000000..aa5644d6451
--- /dev/null
+++ b/ninja/doc/manual.asciidoc
@@ -0,0 +1,916 @@
+Ninja
+=====
+Evan Martin <martine@danga.com>
+
+
+Introduction
+------------
+
+Ninja is yet another build system.  It takes as input the
+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
+http://neugierig.org/software/chromium/notes/2011/02/ninja.html[my
+work on the Chromium browser project], which has over 30,000 source
+files and whose other build systems (including one built from custom
+non-recursive Makefiles) would take ten seconds to start building
+after changing one file.  Ninja is under a second.
+
+Philosophical overview
+~~~~~~~~~~~~~~~~~~~~~~
+
+Where other build systems are high-level languages, Ninja aims to be
+an assembler.
+
+Build systems get slow when they need to make decisions.  When you are
+in a edit-compile cycle you want it to be as fast as possible -- you
+want the build system to do the minimum work necessary to figure out
+what needs to be built immediately.
+
+Ninja contains the barest functionality necessary to describe
+arbitrary dependency graphs.  Its lack of syntax makes it impossible
+to express complex decisions.
+
+Instead, Ninja is intended to be used with a separate program
+generating its input files.  The generator program (like the
+`./configure` found in autotools projects) can analyze system
+dependencies and make as many decisions as possible up front so that
+incremental builds stay fast.  Going beyond autotools, even build-time
+decisions like "which compiler flags should I use?"  or "should I
+build a debug or release-mode binary?"  belong in the `.ninja` file
+generator.
+
+Design goals
+~~~~~~~~~~~~
+
+Here are the design goals of Ninja:
+
+* very fast (i.e., instant) incremental builds, even for very large
+  projects.
+
+* very little policy about how code is built.  Different projects and
+  higher-level build systems have different opinions about how code
+  should be built; for example, should built objects live alongside
+  the sources or should all build output go into a separate directory?
+  Is there an "package" rule that builds a distributable package of
+  the project?  Sidestep these decisions by trying to allow either to
+  be implemented, rather than choosing, even if that results in
+  more verbosity.
+
+* get dependencies correct, and in particular situations that are
+  difficult to get right with Makefiles (e.g. outputs need an implicit
+  dependency on the command line used to generate them; to build C
+  source code you need to use 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
+  can 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_.
+
+* build-time decision-making ability such as conditionals or search
+  paths. _Making decisions is slow._
+
+To restate, Ninja is faster than other build systems because it is
+painfully simple.  You must tell Ninja exactly what to do when you
+create your project's `.ninja` files.
+
+Comparison to Make
+~~~~~~~~~~~~~~~~~~
+
+Ninja is closest in spirit and functionality to Make, relying on
+simple dependencies between file timestamps.
+
+But fundamentally, make has a lot of _features_: suffix rules,
+functions, built-in rules that e.g. search for RCS files when building
+source.  Make's language was designed to be written by humans.  Many
+projects find make alone adequate for their build problems.
+
+In contrast, Ninja has almost no features; just those necessary to get
+builds correct while punting most complexity to generation of the
+ninja input files.  Ninja by itself is unlikely to be useful for most
+projects.
+
+Here are some of the features Ninja adds to Make.  (These sorts of
+features can often be implemented using more complicated Makefiles,
+but they are not part of make itself.)
+
+* Ninja has special support for discovering extra dependencies at build
+  time, making it easy to get <<ref_headers,header dependencies>>
+  correct for C/C++ code.
+
+* A build edge may have multiple outputs.
+
+* Outputs implicitly depend on the command line that was used to generate
+  them, which means that changing e.g. compilation flags will cause
+  the outputs to rebuild.
+
+* Output directories are always implicitly created before running the
+  command that relies on them.
+
+* Rules can provide shorter descriptions of the command being run, so
+  you can print e.g. `CC foo.o` instead of a long command line while
+  building.
+
+* Builds are always run in parallel, based by default on the number of
+  CPUs your system has.  Underspecified build dependencies will result
+  in incorrect builds.
+
+* Command output is always buffered.  This means commands running in
+  parallel don't interleave their output, and when a command fails we
+  can print its failure output next to the full command line that
+  produced the failure.
+
+
+Using Ninja for your project
+----------------------------
+
+Ninja currently works on Unix-like systems and Windows. It's seen the
+most testing on Linux (and has the best performance there) but it runs
+fine on Mac OS X and FreeBSD.
+
+If your project is small, Ninja's speed impact is likely unnoticeable.
+(However, even for small projects it sometimes turns out that Ninja's
+limited syntax forces simpler build rules that result in faster
+builds.)  Another way to say this is that if you're happy with the
+edit-compile cycle time of your project already then Ninja won't help.
+
+There are many other build systems that are more user-friendly or
+featureful than Ninja itself.  For some recommendations: the Ninja
+author found http://gittup.org/tup/[the tup build system] influential
+in Ninja's design, and thinks https://github.com/apenwarr/redo[redo]'s
+design is quite clever.
+
+Ninja's benefit comes from using it in conjunction with a smarter
+meta-build system.
+
+http://code.google.com/p/gyp/[gyp]:: The meta-build system used to
+generate build files for Google Chrome and related projects (v8,
+node.js).  gyp can generate Ninja files for all platforms supported by
+Chrome. See the
+http://code.google.com/p/chromium/wiki/NinjaBuild[Chromium Ninja
+documentation for more details].
+
+http://www.cmake.org/[CMake]:: A widely used meta-build system that
+can generate Ninja files on Linux as of CMake version 2.8.8.  (There
+is some Mac and Windows support -- http://www.reactos.org[ReactOS]
+uses Ninja on Windows for their buildbots, but those platforms are not
+yet officially supported by CMake as the full test suite doesn't
+pass.)
+
+others:: Ninja ought to fit perfectly into other meta-build software
+like http://industriousone.com/premake[premake].  If you do this work,
+please let us know!
+
+Running Ninja
+~~~~~~~~~~~~~
+
+Run `ninja`.  By default, it looks for a file named `build.ninja` in
+the current directory and builds all out-of-date targets.  You can
+specify which targets (files) to build as command line arguments.
+
+`ninja -h` prints help output.  Many of Ninja's flags intentionally
+match those of Make; e.g `ninja -C build -j 20` changes into the
+`build` directory and runs 20 build commands in parallel.  (Note that
+Ninja defaults to running commands in parallel anyway, so typically
+you don't need to pass `-j`.)
+
+
+Environment variables
+~~~~~~~~~~~~~~~~~~~~~
+
+Ninja supports one environment variable to control its behavior:
+`NINJA_STATUS`, the progress status printed before the rule being run.
+
+Several placeholders are available:
+
+`%s`:: The number of started edges.
+`%t`:: The total number of edges that must be run to complete the build.
+`%p`:: The percentage of started edges.
+`%r`:: The number of currently running edges.
+`%u`:: The number of remaining edges to start.
+`%f`:: The number of finished edges.
+`%o`:: Overall rate of finished edges per second
+`%c`:: Current rate of finished edges per second (average over builds
+specified by `-j` or its default)
+`%e`:: Elapsed time in seconds.  _(Available since Ninja 1.2.)_
+`%%`:: A plain `%` character.
+
+The default progress status is `"[%s/%t] "` (note the trailing space
+to separate from the build rule). Another example of possible progress status
+could be `"[%u/%r/%f] "`.
+
+Extra tools
+~~~~~~~~~~~
+
+The `-t` flag on the Ninja command line runs some tools that we have
+found useful during Ninja's development.  The current tools are:
+
+[horizontal]
+`query`:: dump the inputs and outputs of a given target.
+
+`browse`:: browse the dependency graph in a web browser.  Clicking a
+file focuses the view on that file, showing inputs and outputs.  This
+feature requires a Python installation.
+
+`graph`:: output a file in the syntax used by `graphviz`, a automatic
+graph layout tool.  Use it like:
++
+----
+ninja -t graph mytarget | dot -Tpng -ograph.png
+----
++
+In the Ninja source tree, `ninja graph.png`
+generates an image for Ninja itself.  If no target is given generate a
+graph for all root targets.
+
+`targets`:: output a list of targets either by rule or by depth.  If used
+like +ninja -t targets rule _name_+ it prints the list of targets
+using the given rule to be built.  If no rule is given, it prints the source
+files (the leaves of the graph).  If used like
++ninja -t targets depth _digit_+ it
+prints the list of targets in a depth-first manner starting by the root
+targets (the ones with no outputs). Indentation is used to mark dependencies.
+If the depth is zero it prints all targets. If no arguments are provided
++ninja -t targets depth 1+ is assumed. In this mode targets may be listed
+several times. If used like this +ninja -t targets all+ it
+prints all the targets available without indentation and it is faster
+than the _depth_ mode.
+
+`commands`:: given a list of targets, print a list of commands which, if
+executed in order, may be used to rebuild those targets, assuming that all
+output files are out of date.
+
+`clean`:: remove built files. By default it removes all built files
+except for those created by the generator.  Adding the `-g` flag also
+removes built files created by the generator (see <<ref_rule,the rule
+reference for the +generator+ attribute>>).  Additional arguments are
+targets, which removes the given targets and recursively all files
+built for them.
++
+If used like +ninja -t clean -r _rules_+ it removes all files built using
+the given rules.
++
+Files created but not referenced in the graph are not removed. This
+tool takes in account the +-v+ and the +-n+ options (note that +-n+
+implies +-v+).
+
+`compdb`:: given a list of rules, each of which is expected to be a
+C family language compiler rule whose first input is the name of the
+source file, prints on standard output a compilation database in the
+http://clang.llvm.org/docs/JSONCompilationDatabase.html[JSON format] expected
+by the Clang tooling interface.
+_Available since Ninja 1.2._
+
+
+Writing your own Ninja files
+----------------------------
+
+The remainder of this manual is only useful if you are constructing
+Ninja files yourself: for example, if you're writing a meta-build
+system or supporting a new language.
+
+Conceptual overview
+~~~~~~~~~~~~~~~~~~~
+
+Ninja evaluates a graph of dependencies between files, and runs
+whichever commands are necessary to make your build target up to date
+as determined by file modification times.  If you are familiar with
+Make, Ninja is very similar.
+
+A build file (default name: `build.ninja`) provides a list of _rules_
+-- short names for longer commands, like how to run the compiler --
+along with a list of _build_ statements saying how to build files
+using the rules -- which rule to apply to which inputs to produce
+which outputs.
+
+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.
+
+Syntax example
+~~~~~~~~~~~~~~
+
+Here's a basic `.ninja` file that demonstrates most of the syntax.
+It will be used as an example for the following sections.
+
+---------------------------------
+cflags = -Wall
+
+rule cc
+  command = gcc $cflags -c $in -o $out
+
+build foo.o: cc foo.c
+---------------------------------
+
+Variables
+~~~~~~~~~
+Despite the non-goal of being convenient to write by hand, to keep
+build files readable (debuggable), Ninja supports declaring shorter
+reusable names for strings.  A declaration like the following
+
+----------------
+cflags = -g
+----------------
+
+can be used on the right side of an equals sign, dereferencing it with
+a dollar 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.  There is more on how shadowing works
+later in this document.
+
+Rules
+~~~~~
+
+Rules declare a short name for a command line.  They begin with a line
+consisting of the `rule` keyword and a name for the rule.  Then
+follows an indented set of `variable = 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` variable
+defines the command to run, `$in` expands to the list of
+input files (`foo.c`), and `$out` to the output files (`foo.o`) for the
+command.  A full list of special variables is provided in
+<<ref_rule,the reference>>.
+
+Build statements
+~~~~~~~~~~~~~~~~
+
+Build statements declare a relationship between input and output
+files.  They 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.
+
+In the scope of a `build` block (including in the evaluation of its
+associated `rule`), the variable `$in` is the list of inputs and the
+variable `$out` is the list of outputs.
+
+A build statement may be followed by an indented set of `key = value`
+pairs, much like a rule.  These variables will shadow any variables
+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 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
+
+----------------
+
+For more discussion of how scoping works, consult <<ref_scope,the
+reference>>.
+
+If you need more complicated information passed from the build
+statement to the rule (for example, if the rule needs "the file
+extension of the first input"), pass that through as an extra
+variable, like how `cflags` is passed above.
+
+If the top-level Ninja file is specified as an output of any build
+statement and it is out of date, Ninja will rebuild and reload it
+before building the targets requested by the user.
+
+Generating Ninja files from code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`misc/ninja_syntax.py` in the Ninja distribution is a tiny Python
+module to facilitate generating Ninja files.  It allows you to make
+Python calls like `ninja.rule(name='foo', command='bar',
+depfile='$out.d')` and it will generate the appropriate syntax.  Feel
+free to just inline it into your project's build system if it's
+useful.
+
+
+More details
+------------
+
+The `phony` rule
+~~~~~~~~~~~~~~~~
+
+The special rule name `phony` can be used to create aliases for other
+targets.  For example:
+
+----------------
+build foo: phony some/file/in/a/faraway/subdir/foo
+----------------
+
+This makes `ninja foo` build the longer path.  Semantically, the
+`phony` rule is equivalent to a plain rule where the `command` does
+nothing, but phony rules are handled specially in that they aren't
+printed when run, logged (see below), nor do they contribute to the
+command count printed as part of the build process.
+
+`phony` can also be used to create dummy targets for files which
+may not exist at build time.  If a phony build statement is written
+without any dependencies, the target will be considered out of date if
+it does not exist.  Without a phony build statement, Ninja will report
+an error if the file does not exist and is required by the build.
+
+
+Default target statements
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, if no targets are specified on the command line, Ninja
+will build every output that is not named as an input elsewhere.
+You can override this behavior using a default target statement.
+A default target statement causes Ninja to build only a given subset
+of output files if none are specified on the command line.
+
+Default target statements begin with the `default` keyword, and have
+the format +default _targets_+.  A default target statement must appear
+after the build statement that declares the target as an output file.
+They are cumulative, so multiple statements may be used to extend
+the list of default targets.  For example:
+
+----------------
+default foo bar
+default baz
+----------------
+
+This causes Ninja to build the `foo`, `bar` and `baz` targets by
+default.
+
+
+[[ref_log]]
+The Ninja log
+~~~~~~~~~~~~~
+
+For each built file, Ninja keeps a log of the command used to build
+it.  Using this log Ninja can know when an existing output was built
+with a different command line than the build files specify (i.e., the
+command line changed) and knows to rebuild the file.
+
+The log file is kept in the build root in a file called `.ninja_log`.
+If you provide a variable named `builddir` in the outermost scope,
+`.ninja_log` will be kept in that directory instead.
+
+
+[[ref_versioning]]
+Version compatibility
+~~~~~~~~~~~~~~~~~~~~~
+
+_Available since Ninja 1.2._
+
+Ninja version labels follow the standard major.minor.patch format,
+where the major version is increased on backwards-incompatible
+syntax/behavioral changes and the minor version is increased on new
+behaviors.  Your `build.ninja` may declare a variable named
+`ninja_required_version` that asserts the minimum Ninja version
+required to use the generated file.  For example,
+
+-----
+ninja_required_version = 1.1
+-----
+
+declares that the build file relies on some feature that was
+introduced in Ninja 1.1 (perhaps the `pool` syntax), and that
+Ninja 1.1 or greater must be used to build.  Unlike other Ninja
+variables, this version requirement is checked immediately when
+the variable is encountered in parsing, so it's best to put it
+at the top of the build file.
+
+Ninja always warns if the major versions of Ninja and the
+`ninja_required_version` don't match; a major version change hasn't
+come up yet so it's difficult to predict what behavior might be
+required.
+
+[[ref_headers]]
+C/C++ header dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To get C/C++ header dependencies (or any other build dependency that
+works in a similar way) correct Ninja has some extra functionality.
+
+The problem with headers is that the full list of files that a given
+source file depends on can only be discovered by the compiler:
+different preprocessor defines and include paths cause different files
+to be used.  Some compilers can emit this information while building,
+and Ninja can use that to get its dependencies perfect.
+
+Consider: if the file has never been compiled, it must be built anyway,
+generating the header dependencies as a side effect.  If any file is
+later modified (even in a way that changes which headers it depends
+on) the modification will cause a rebuild as well, keeping the
+dependencies up to date.
+
+When loading these special dependencies, Ninja implicitly adds extra
+build edges such that it is not an error if the listed dependency is
+missing.  This allows you to delete a header file and rebuild without
+the build aborting due to a missing input.
+
+depfile
+^^^^^^^
+
+`gcc` (and other compilers like `clang`) support emitting dependency
+information in the syntax of a Makefile.  (Any command that can write
+dependencies in this form can be used, not just `gcc`.)
+
+To bring this information into Ninja requires cooperation.  On the
+Ninja side, the `depfile` attribute on the `build` must point to a
+path where this data is written.  (Ninja only supports the limited
+subset of the Makefile syntax emitted by compilers.)  Then the command
+must know to write dependencies into the `depfile` path.
+Use it like in the following example:
+
+----
+rule cc
+  depfile = $out.d
+  command = gcc -MMD -MF $out.d [other gcc flags here]
+----
+
+The `-MMD` flag to `gcc` tells it to output header dependencies, and
+the `-MF` flag tells it where to write them.
+
+deps
+^^^^
+
+_(Available since Ninja 1.3.)_
+
+It turns out that for large projects (and particularly on Windows,
+where the file system is slow) loading these dependency files on
+startup is slow.
+
+Ninja 1.3 can instead process dependencies just after they're generated
+and save a compacted form of the same information in a Ninja-internal
+database.
+
+Ninja supports this processing in two forms.
+
+1. `deps = gcc` specifies that the tool outputs `gcc`-style dependencies
+   in the form of Makefiles.  Adding this to the above example will
+   cause Ninja to process the `depfile` immediately after the
+   compilation finishes, then delete the `.d` file (which is only used
+   as a temporary).
+
+2. `deps = msvc` specifies that the tool outputs header dependencies
+   in the form produced by Visual Studio's compiler's
+   http://msdn.microsoft.com/en-us/library/hdkef6tk(v=vs.90).aspx[`/showIncludes`
+   flag].  Briefly, this means the tool outputs specially-formatted lines
+   to its stdout.  Ninja then filters these lines from the displayed
+   output.  No `depfile` attribute is necessary.
++
+----
+rule cc
+  deps = msvc
+  command = cl /showIncludes -c $in /Fo$out
+----
+
+Pools
+~~~~~
+
+_Available since Ninja 1.1._
+
+Pools allow you to allocate one or more rules or edges a finite number
+of concurrent jobs which is more tightly restricted than the default
+parallelism.
+
+This can be useful, for example, to restrict a particular expensive rule
+(like link steps for huge executables), or to restrict particular build
+statements which you know perform poorly when run concurrently.
+
+Each pool has a `depth` variable which is specified in the build file.
+The pool is then referred to with the `pool` variable on either a rule
+or a build statement.
+
+No matter what pools you specify, ninja will never run more concurrent jobs
+than the default parallelism, or the number of jobs specified on the command
+line (with `-j`).
+
+----------------
+# No more than 4 links at a time.
+pool link_pool
+  depth = 4
+
+# No more than 1 heavy object at a time.
+pool heavy_object_pool
+  depth = 1
+
+rule link
+  ...
+  pool = link_pool
+
+rule cc
+  ...
+
+# The link_pool is used here. Only 4 links will run concurrently.
+build foo.exe: link input.obj
+
+# A build statement can be exempted from its rule's pool by setting an
+# empty pool. This effectively puts the build statement back into the default
+# pool, which has infinite depth.
+build other.exe: link input.obj
+  pool =
+
+# A build statement can specify a pool directly.
+# Only one of these builds will run at a time.
+build heavy_object1.obj: cc heavy_obj1.cc
+  pool = heavy_object_pool
+build heavy_object2.obj: cc heavy_obj2.cc
+  pool = heavy_object_pool
+
+----------------
+
+
+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_+, and
+   then has a series of indented lines defining variables.
+
+2. A build edge, which looks like +build _output1_ _output2_:
+   _rulename_ _input1_ _input2_+. +
+   Implicit dependencies may be tacked on the end with +|
+   _dependency1_ _dependency2_+. +
+   Order-only dependencies may be tacked on the end with +||
+   _dependency1_ _dependency2_+.  (See <<ref_dependencies,the reference on
+   dependency types>>.)
+
+3. Variable declarations, which look like +_variable_ = _value_+.
+
+4. Default target statements, which look like +default _target1_ _target2_+.
+
+5. References to more files, which look like +subninja _path_+ or
+   +include _path_+.  The difference between these is explained below
+   <<ref_scope,in the discussion about scoping>>.
+
+Lexical syntax
+~~~~~~~~~~~~~~
+
+Ninja is mostly encoding agnostic, as long as the bytes Ninja cares
+about (like slashes in paths) are ASCII.  This means e.g. UTF-8 or
+ISO-8859-1 input files ought to work.  (To simplify some code, tabs
+and carriage returns are currently disallowed; this could be fixed if
+it really mattered to you.)
+
+Comments begin with `#` and extend to the end of the line.
+
+Newlines are significant.  Statements like `build foo bar` are a set
+of space-separated tokens that end at the newline.  Newlines and
+spaces within a token must be escaped.
+
+There is only one escape character, `$`, and it has the following
+behaviors:
+
+[horizontal]
+`$` followed by a newline:: escape the newline (continue the current line
+across a line break).
+
+`$` followed by text:: a variable reference.
+
+`${varname}`:: alternate syntax for `$varname`.
+
+`$` followed by space:: a space.  (This is only necessary in lists of
+paths, where a space would otherwise separate filenames.  See below.)
+
+`$:` :: a colon.  (This is only necessary in `build` lines, where a colon
+would otherwise terminate the list of outputs.)
+
+`$$`:: a literal `$`.
+
+A `build` or `default` statement is first parsed as a space-separated
+list of filenames and then each name is expanded.  This means that
+spaces within a variable will result in spaces in the expanded
+filename.
+
+----
+spaced = foo bar
+build $spaced/baz other$ file: ...
+# The above build line has two outputs: "foo bar/baz" and "other file".
+----
+
+In a `name = value` statement, whitespace at the beginning of a value
+is always stripped.  Whitespace at the beginning of a line after a
+line continuation is also stripped.
+
+----
+two_words_with_one_space = foo $
+    bar
+one_word_with_no_space = foo$
+    bar
+----
+
+Other whitespace is only significant if it's at the beginning of a
+line.  If a line is indented 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.
+
+[[ref_toplevel]]
+Top-level variables
+~~~~~~~~~~~~~~~~~~~
+
+Two variables are significant when declared in the outermost file scope.
+
+`builddir`:: a directory for some Ninja output files.  See <<ref_log,the
+  discussion of the build log>>.  (You can also store other build output
+  in this directory.)
+
+`ninja_required_version`:: the minimum version of Ninja required to process
+  the build correctly.  See <<ref_versioning,the discussion of versioning>>.
+
+
+[[ref_rule]]
+Rule variables
+~~~~~~~~~~~~~~
+
+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.  This string (after
+  $variables are expanded) is passed directly to `sh -c` without
+  interpretation by Ninja. Each `rule` may have only one `command`
+  declaration. To specify multiple commands use `&&` (or similar) to
+  concatenate operations.
+
+`depfile`:: path to an optional `Makefile` that contains extra
+  _implicit dependencies_ (see <<ref_dependencies,the reference on
+  dependency types>>).  This is explicitly to support C/C++ header
+  dependencies; see <<ref_headers,the full discussion>>.
+
+`deps`:: _(Available since Ninja 1.3.)_ if present, must be one of
+  `gcc` or `msvc` to specify special dependency processing.  See
+   <<ref_headers,the full discussion>>.  The generated database is
+   stored as `.ninja_deps` in the `builddir`, see <<ref_toplevel,the
+   discussion of `builddir`>>.
+
+`description`:: a short description of the command, used to pretty-print
+  the command as it's running.  The `-v` flag controls whether to print
+  the full command or its description; if a command fails, the full command
+  line will always be printed before the command's output.
+
+`generator`:: if present, specifies that this rule is used to
+  re-invoke the generator program.  Files built using `generator`
+  rules are treated specially in two ways: firstly, they will not be
+  rebuilt if the command line changes; and secondly, they are not
+  cleaned by default.
+
+`in`:: the shell-quoted space-separated list of files provided as
+  inputs to the build line referencing this `rule`.  (`$in` is provided
+  solely for convenience; if you need some subset or variant of this
+  list of files, just construct a new variable with that list and use
+  that instead.)
+
+`in_newline`:: the same as `$in` except that multiple inputs are
+  separated by newlines rather than spaces.  (For use with
+  `$rspfile_content`; this works around a bug in the MSVC linker where
+  it uses a fixed-size buffer for processing input.)
+
+`out`:: the shell-quoted space-separated list of files provided as
+  outputs to the build line referencing this `rule`.
+
+`restat`:: if present, causes Ninja to re-stat the command's outputs
+  after execution of the command.  Each output whose modification time
+  the command did not change will be treated as though it had never
+  needed to be built.  This may cause the output's reverse
+  dependencies to be removed from the list of pending build actions.
+
+`rspfile`, `rspfile_content`:: if present (both), Ninja will use a
+  response file for the given command, i.e. write the selected string
+  (`rspfile_content`) to the given file (`rspfile`) before calling the
+  command and delete the file after successful execution of the
+  command.
++
+This is particularly useful on Windows OS, where the maximal length of
+a command line is limited and response files must be used instead.
++
+Use it like in the following example:
++
+----
+rule link
+  command = link.exe /OUT$out [usual link flags here] @$out.rsp
+  rspfile = $out.rsp
+  rspfile_content = $in
+
+build myapp.exe: link a.obj b.obj [possibly many other .obj files]
+----
+
+[[ref_dependencies]]
+Build dependencies
+~~~~~~~~~~~~~~~~~~
+
+There are three types of build dependencies which are subtly different.
+
+1. _Explicit dependencies_, as listed in a build line.  These are
+   available as the `$in` variable in the rule.  Changes in these files
+   cause the output to be rebuilt; if these file are missing and
+   Ninja doesn't know how to build them, the build is aborted.
++
+This is the standard form of dependency to be used for e.g. the
+source file of a compile command.
+
+2. _Implicit dependencies_, either as picked up from
+   a `depfile` attribute on a rule or from the syntax +| _dep1_
+   _dep2_+ on the end of a build line.  The semantics are identical to
+   explicit dependencies, the only difference is that implicit dependencies
+   don't show up in the `$in` variable.
++
+This is for expressing dependencies that don't show up on the
+command line of the command; for example, for a rule that runs a
+script, the script itself should be an implicit dependency, as
+changes to the script should cause the output to rebuild.
++
+Note that dependencies as loaded through depfiles have slightly different
+semantics, as described in the <<ref_rule,rule reference>>.
+
+3. _Order-only dependencies_, expressed with the syntax +|| _dep1_
+   _dep2_+ on the end of a build line.  When these are out of date, the
+   output is not rebuilt until they are built, but changes in order-only
+   dependencies alone do not cause the output to be rebuilt.
++
+Order-only dependencies can be useful for bootstrapping dependencies
+that are only discovered during build time: for example, to generate a
+header file before starting a subsequent compilation step.  (Once the
+header is used in compilation, a generated dependency file will then
+express the implicit dependency.)
+
+Variable expansion
+~~~~~~~~~~~~~~~~~~
+
+Variables are expanded in paths (in a `build` or `default` statement)
+and on the right side of a `name = value` statement.
+
+When a `name = value` statement is evaluated, its right-hand side is
+expanded immediately (according to the below scoping rules), and
+from then on `$name` expands to the static string as the result of the
+expansion.  It is never the case that you'll need to "double-escape" a
+value to prevent it from getting expanded twice.
+
+All variables are expanded immediately as they're encountered in parsing,
+with one important exception: variables in `rule` blocks are expanded
+when the rule is _used_, not when it is declared.  In the following
+example, the `demo` rule prints "this is a demo of bar".
+
+----
+rule demo
+  command = echo "this is a demo of $foo"
+
+build out: demo
+  foo = bar
+----
+
+[[ref_scope]]
+Evaluation and scoping
+~~~~~~~~~~~~~~~~~~~~~~
+
+Top-level variable declarations are scoped to the file they occur in.
+
+The `subninja` keyword, used to include another `.ninja` file,
+introduces a new scope.  The included `subninja` file may use the
+variables from the parent file, and shadow their values for the file's
+scope, but it won't affect values of the variables in the parent.
+
+To include another `.ninja` file in the current scope, much like a C
+`#include` statement, use `include` instead of `subninja`.
+
+Variable declarations indented in a `build` block are scoped to the
+`build` block.  The full lookup order for a variable expanded in a
+`build` block (or the `rule` is uses) is:
+
+1. Special built-in variables (`$in`, `$out`).
+
+2. Build-level variables from the `build` block.
+
+3. Rule-level variables from the `rule` block (i.e. `$command`).
+   (Note from the above discussion on expansion that these are
+   expanded "late", and may make use of in-scope bindings like `$in`.)
+
+4. File-level variables from the file that the `build` line was in.
+
+5. Variables from the file that included that file using the
+   `subninja` keyword.
+