rename docs

1 files changed, 228 insertions, 0 deletions

diff --git a/manual.asciidoc b/manual.asciidoc
new file mode 100644
index 0000000..b348459
--- /dev/null
+++ b/manual.asciidoc
@@ -0,0 +1,228 @@
+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