From 95478a2cedcc3511096d0d8dbfffe6f863ff6051 Mon Sep 17 00:00:00 2001 From: Evan Martin Date: Sat, 4 Dec 2010 16:14:48 -0800 Subject: rename docs --- README | 1 + README.asciidoc | 228 -------------------------------------------------------- build.ninja | 4 +- manual.asciidoc | 228 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 231 insertions(+), 230 deletions(-) create mode 100644 README delete mode 100644 README.asciidoc create mode 100644 manual.asciidoc diff --git a/README b/README new file mode 100644 index 0000000..de7c975 --- /dev/null +++ b/README @@ -0,0 +1 @@ +See manual.html. diff --git a/README.asciidoc b/README.asciidoc deleted file mode 100644 index b348459..0000000 --- a/README.asciidoc +++ /dev/null @@ -1,228 +0,0 @@ -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 diff --git a/build.ninja b/build.ninja index 50bbe4e..981a6a6 100644 --- a/build.ninja +++ b/build.ninja @@ -63,8 +63,8 @@ build graph.png: gengraph @graph.dot rule asciidoc command = asciidoc -a toc $in -build README.html: asciidoc README.asciidoc -build doc: phony | README.html +build manual.html: asciidoc manual.asciidoc +build doc: phony | manual.html # Use the built-in phony rule and an order-only dependency # to make building "all" build all targets. 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 -- cgit v0.12