(zilch lang ninja): document incremental build

Change-Id: I6a6a696472806049b5ecab203487254f32a716b7

docs/modules/ROOT/pages/ninja/man.adoc

@@ -25,15 +25,17 @@ written. See the documentation at https://puck.moe/zilch/docs/.
 == Subcommands
 *build* [_TARGET_]...::
   Build the derivation described by the configuration file, or the
-  target nammes from its Ninja file, if any are passed as arguments.
+  target names from its Ninja file, if any are passed as arguments.
 
 *source* [_DIR_]::
-  Write the source of the derivation to _DIR_, or to `src` if no
+  Write the source of the derivation and its rewrites to the path in
+  `override-source`, using _DIR_ (or `src`) for the root if no
   directory is provided.
 
 *diff*::
   Compare the 'canonical' source of the derivation to that in the
-  source directory (`src`, or the path selected by `--source`.)
+  source directory (the path in `override-source:`, `src`, or the path
+  selected by `--source`.)
 
 == Options
 
@@ -43,7 +45,8 @@ written. See the documentation at https://puck.moe/zilch/docs/.
 
 *-p* _NAME_::
 *--project* _NAME_::
-  Operate only on a rewritten input derivation.
+  Operate only on a rewrite of the derivation. Repeat to operate on a
+  rewrite of a rewrite.
 
 *-s* _DIR_::
 *--source* _DIR_::

docs/modules/ROOT/pages/ninja/usage.adoc

@@ -50,6 +50,11 @@ dev	-> #<store path /nix/store/lmdgblqm0prkx3hcs2q76rzcvg1xm6cm-gtest-1.16.0-dev
 out	-> #<store path /nix/store/b2ylcnfsaf2wmzk51whgq5r86xb955xq-gtest-1.16.0 (/nix/store/ksrbqg2nkgm8zq3g59gzydf5976griis-gtest-1.16.0.drv!out)>
 ----
 
+It's also possible to use `override-source: "<path>"` inside the configuration
+file, which allows skipping the `-s` arguments. This is also used when
+<<_rewrite,using cross-project builds>>.
+
+[#source-editing-warning]
 WARNING: Zilch will not regenerate the build files when editing source in this
 manner, for performance and logistical reasons. To change the build files,
 override the `src` attribute of the environment's derivation.
@@ -78,7 +83,7 @@ Scheme code:
 
 [,scheme]
 ----
-(environment: "import ./sample.drv"
+(environment: "import ./sample.nix"
  patch:
   (lambda (edge)
    (if (string=? (build-edge-rule edge) "foo")
@@ -91,6 +96,31 @@ environment variable `$_ZILCH_ROOT` points to the root of the source + build
 file tree, and can be used to copy non-symlinked files into the working
 directory.
 
+[#_rewrite]
+== Cross-project incremental builds
+Zilch supports rewriting the input of a Ninja project with another Ninja
+project. To do this, you will need the name of the derivation, and a project
+configuration:
+
+[,scheme]
+----
+(environment: "import ./sample.nix"
+ override-source: "sample-src"
+ rewrite:
+ ("input-1.2.3"
+  environment: "import ../input.nix"
+  override-source: "input-src"
+  #<...more configuration here>))
+----
+
+WARNING: The <<source-editing-warning,warning under "Source editing">> applies
+here too. As addition, the boundary between projects is determined by running
+the `installPhase` of the project to rewrite. If the installPhase is complex
+(e.g. by using compression, rather than just copying inputs to outputs) this
+will not work properly. Any code that assumes it can run outputs from the
+rewritten project will also not function, as any shared libraries are stubbed
+out.
+
 == Automatic file elision
 To implement incremental builds efficiently, Zilch automatically slims down the
 part of the source directory that is accessible to each target. If a filename