docs for ninja_required_version

(And some extra docs for top-level variables in general.)

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]]