diff options
Diffstat (limited to 'doc/manual.asciidoc')
| -rw-r--r-- | doc/manual.asciidoc | 44 |
1 files changed, 44 insertions, 0 deletions
diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc index 6b1de9b..93e34e2 100644 --- a/doc/manual.asciidoc +++ b/doc/manual.asciidoc @@ -539,6 +539,8 @@ default. The Ninja log ~~~~~~~~~~~~~ +[[ref_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 @@ -549,6 +551,35 @@ If you provide a variable named `builddir` in the outermost scope, `.ninja_log` will be kept in that directory instead. +Version compatibility +~~~~~~~~~~~~~~~~~~~~~ + +[[ref_versioning]] + +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 -------------------- @@ -634,6 +665,19 @@ 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 verison of Ninja required to process + the build correctly. See <<ref_versioning,the discussion of versioning>>. + + Rule variables ~~~~~~~~~~~~~~ [[ref_rule]] |