diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/docbook.xsl | 17 | ||||
-rw-r--r-- | doc/manual.asciidoc | 183 | ||||
-rw-r--r-- | doc/style.css | 29 |
3 files changed, 172 insertions, 57 deletions
diff --git a/doc/docbook.xsl b/doc/docbook.xsl new file mode 100644 index 0000000..8afdc8c --- /dev/null +++ b/doc/docbook.xsl @@ -0,0 +1,17 @@ +<!-- This soup of XML is the minimum customization necessary to make the + autogenerated manual look ok. --> +<!DOCTYPE xsl:stylesheet [ +<!ENTITY css SYSTEM "style.css"> +]> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0'> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/> + <xsl:template name="user.head.content"><style>&css;</style></xsl:template> + <xsl:template name="body.attributes"></xsl:template> + <xsl:param name="generate.toc" select="'book toc'"/> + <xsl:param name="chapter.autolabel" select="0" /> + <xsl:param name="toc.list.type">ul</xsl:param> + + <xsl:output method="html" encoding="utf-8" indent="no" + doctype-public=""/> +</xsl:stylesheet> diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc index 674231c..688ec93 100644 --- a/doc/manual.asciidoc +++ b/doc/manual.asciidoc @@ -210,20 +210,23 @@ you don't need to pass `-j`.) Environment variables ~~~~~~~~~~~~~~~~~~~~~ -Ninja supports one environment variable to control its behavior. +Ninja supports one environment variable to control its behavior: +`NINJA_STATUS`, the progress status printed before the rule being run. -`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) -* `%%`: A plain `%` character. -* The default progress status is `"[%s/%t] "` (note the trailing space + +`%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] "`. @@ -264,10 +267,6 @@ 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. -`rules`:: output the list of all rules with their description if they have -one. It can be used to know which rule name to pass to -+ninja -t targets rule _name_+. - `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. @@ -286,6 +285,12 @@ 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 @@ -359,17 +364,11 @@ 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 is -special and defines the command to run. A full list of special -variables is provided in <<ref_rule,the reference>>.) - -Within the context of a rule, three additional special variables are -available: `$in` expands to the list of input files (`foo.c`) and -`$out` to the output file (`foo.o`) for the command. For use with -`$rspfile_content`, there is also `$in_newline`, which is the same as -`$in`, except that multiple inputs are separated by `\n`, rather than -spaces. - +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 ~~~~~~~~~~~~~~~~ @@ -400,7 +399,7 @@ rule cc # 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. +# But you can shadow variables like cflags for a particular build. build special.o: cc special.c cflags = -Wall @@ -425,9 +424,7 @@ before building the targets requested by the user. Pools ~~~~~ -*Note: pools were added as an experiment and may be removed in a future -version of Ninja. Are they useful for you? Let us know on the mailing -list.* +_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 @@ -541,6 +538,7 @@ This causes Ninja to build the `foo`, `bar` and `baz` targets by default. +[[ref_log]] The Ninja log ~~~~~~~~~~~~~ @@ -554,6 +552,36 @@ 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.XXX._ + +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. + + Ninja file reference -------------------- @@ -608,7 +636,7 @@ across a line break). 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 inputs.) +would otherwise terminate the list of outputs.) `$$`:: a literal `$`. @@ -639,9 +667,22 @@ 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. +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 ~~~~~~~~~~~~~~ -[[ref_rule]] A `rule` block contains a list of `key = value` declarations that affect the processing of the rule. Here is a full list of special @@ -651,7 +692,7 @@ keys. $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. + concatenate operations. `depfile`:: path to an optional `Makefile` that contains extra _implicit dependencies_ (see <<ref_dependencies,the reference on @@ -683,6 +724,20 @@ aborting due to a missing input. 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 @@ -709,13 +764,9 @@ rule link build myapp.exe: link a.obj b.obj [possibly many other .obj files] ---- -Finally, the special `$in` and `$out` variables expand to the -shell-quoted space-separated list of files provided to the `build` -line referencing this `rule`. - +[[ref_dependencies]] Build dependencies ~~~~~~~~~~~~~~~~~~ -[[ref_dependencies]] There are three types of build dependencies which are subtly different. @@ -752,9 +803,34 @@ 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 ~~~~~~~~~~~~~~~~~~~~~~ -[[ref_scope]] Top-level variable declarations are scoped to the file they occur in. @@ -767,26 +843,19 @@ 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. This scope is inherited by the `rule`. The full -lookup order for a variable referenced in a rule is: +`build` block. The full lookup order for a variable expanded in a +`build` block (or the `rule` is uses) is: -1. Rule-level variables (i.e. `$in`, `$command`). +1. Special built-in variables (`$in`, `$out`). -2. Build-level variables from the `build` that references this rule. +2. Build-level variables from the `build` block. -3. File-level variables from the file that the `build` line was in. +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. Variables from the file that included that file using the - `subninja` keyword. +4. File-level variables from the file that the `build` line was in. -Variable expansion -~~~~~~~~~~~~~~~~~~ - -Variables are expanded in paths (in a `build` or `default` statement) -and on the right side of a `name = value` statement. +5. Variables from the file that included that file using the + `subninja` keyword. -When a `name = value` statement is evaluated, its right-hand side is -expanded once (according to the above scoping rules) immediately, 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. diff --git a/doc/style.css b/doc/style.css new file mode 100644 index 0000000..fc22ec1 --- /dev/null +++ b/doc/style.css @@ -0,0 +1,29 @@ +body { + margin: 5ex 10ex; + max-width: 40em; + line-height: 1.4; + font-family: sans-serif; + font-size: 0.8em; +} +h1, h2, h3 { + font-weight: normal; +} +pre, code { + font-family: x, monospace; +} +pre { + padding: 1ex; + background: #eee; + border: solid 1px #ddd; + min-width: 0; + font-size: 90%; +} +code { + color: #007; +} +.chapter { + margin-top: 4em; +} +p { + margin-top: 0; +} |