(zilch lang ninja): document

Change-Id: I6a6a6964dcc713504ec57f40981a601696a573af

docs/modules/ROOT/nav.adoc

@@ -14,6 +14,9 @@
 *** xref:rust/usage.adoc[]
 *** xref:rust/library.adoc[]
 *** xref:rust/man.adoc[Man page]
+** Ninja
+*** xref:ninja/usage.adoc[]
+*** xref:ninja/man.adoc[Man page]
 
 * Code reference
 include::generated:partial$nav.adoc[]

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

@@ -0,0 +1,63 @@
+= zilch-cli-ninja(1)
+Puck Meerburg
+v0.0.1
+:doctype: manpage
+:manmanual: ZILCH-CLI-NINJA
+:mansource: ZILCH
+:page-pagination: prev
+
+== Name
+
+zilch-cli-ninja - builds a Nixpkgs package using Ninja, using Zilch
+
+== Synopsis
+
+*zilch-cli-ninja* [_OPTION_]... _COMMAND_ [_ARG_]...
+
+== Description
+
+This command uses Zilch to build a Ninja-based project entirely within
+Nix, using content-addressed derivations.
+
+This program requires the derivation to build has a configuration file
+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.
+
+*source* [_DIR_]::
+  Write the source of the derivation to _DIR_, or to `src` 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`.)
+
+== Options
+
+*-h*::
+*--help*::
+  Print a help message.
+
+*-s* _DIR_::
+*--source* _DIR_::
+  Override the input source for builds. Doesn't reconfigure the build,
+  so changes to the build system do not apply.
+
+*-f* _PATH_::
+*--config-file* _PATH_::
+  The location of the configuration file. Defaults to `zilch.scm`.
+
+*-j* _COUNT_::
+*--max-jobs* _COUNT_::
+  The maximum amount of builds to run. Defaults to the amount of cores.
+
+*-v*::
+*--verbose*::
+  Increase the verbosity configured in the Nix daemon.
+
+*-L*::
+*--print-build-logs*::
+  Print derivation logs as they come in.

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

@@ -0,0 +1,131 @@
+= Usage
+:page-pagination: next
+
+`zilch-cli-ninja` allows you to use Zilch to compile a Ninja-based nixpkgs
+derivation reproducibly, and to quickly modify it and rebuild it reproducibly
+as well. To use the tool, you first have to write a configuration file. This
+document will use this example, for `gtest`:
+
+.`gtest.scm`
+[,scheme]
+----
+(environment: "pkgs.gtest"
+ depfile-path: "gtest-deps.scm")
+----
+
+This can then be used with the various subcommands of `zilch-cli-ninja`:
+
+== Building
+To build a derivation with `zilch-cli-ninja`, use the `build` subcommand.
+[,console]
+----
+$ zilch-cli-ninja -f gtest.scm build <1>
+…
+dev	-> #<store path /nix/store/lmdgblqm0prkx3hcs2q76rzcvg1xm6cm-gtest-1.16.0-dev (/nix/store/ksrbqg2nkgm8zq3g59gzydf5976griis-gtest-1.16.0.drv!dev)>
+out	-> #<store path /nix/store/b2ylcnfsaf2wmzk51whgq5r86xb955xq-gtest-1.16.0 (/nix/store/ksrbqg2nkgm8zq3g59gzydf5976griis-gtest-1.16.0.drv!out)>
+
+$ zilch-cli-ninja -f gtest.scm build googlemock/CMakeFiles/gmock_main.dir/src/gmock_main.cc.o <2>
+…
+googlemock/CMakeFiles/gmock_main.dir/src/gmock_main.cc.o	-> "/nix/store/c96j8sqk08xj15pififz5myjzskg0cqw-Building-CXX-object-googlemock-CMakeFiles-gmock_main.dir-src-gmock_main.cc.o"
+----
+<1> Build the full derivation
+<2> Build a specific output of the Ninja file
+
+== Source editing
+Zilch makes it very easy to edit the source of any derivation built in this
+manner. With one command, you can export the source code used for building.
+This source can then be used to rebuild parts of the derivation that have changed.
+
+[,console]
+----
+$ zilch-cli-ninja -f gtest.scm source gtest-src <1>
+…
+
+$ zilch-cli-ninja -f gtest.scm -s gtest-src diff <2>
+…
+
+$ zilch-cli-ninja -f gtest.scm -s gtest-src build <3>
+…
+dev	-> #<store path /nix/store/lmdgblqm0prkx3hcs2q76rzcvg1xm6cm-gtest-1.16.0-dev (/nix/store/ksrbqg2nkgm8zq3g59gzydf5976griis-gtest-1.16.0.drv!dev)>
+out	-> #<store path /nix/store/b2ylcnfsaf2wmzk51whgq5r86xb955xq-gtest-1.16.0 (/nix/store/ksrbqg2nkgm8zq3g59gzydf5976griis-gtest-1.16.0.drv!out)>
+----
+
+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.
+
+== Limitations
+To make the Nixpkgs integration work, the Zilch code breaks up the derivation's
+phases into two steps: unpack + patch + configure, and check + install. This
+can cause issues with derivations that expect to share variables between these
+phases. If `meson` is present, it is assumed to be used, otherwise it is
+assumed the derivation is `cmake`-based. Other build systems are not yet
+supported.
+
+The final store path of the derivation is not known at configuration time,
+unlike normal derivations. Meson and CMake are configured to install into a
+prefix, and are then rewritten (using `sed`) to the final output store path.
+This may cause issues with programs that e.g. compress a file containing these
+paths during their build.footnote:[The only one to have known issues is Node.]
+
+== Patches
+In some cases, the code may not handle running in Zilch's environment. In this
+case, it's possible to add extra code to run before running the command of a
+target.
+
+These patches are defined as part of the configuration file, and are arbitrary
+Scheme code:
+
+[,scheme]
+----
+(environment: "import ./sample.drv"
+ patch:
+  (lambda (edge)
+   (if (string=? (build-edge-rule edge) "foo")
+     "rm src/foo; echo 'replacement file' > src/foo"
+     #f))) 
+----
+
+Patches are arbitrary shell scripts, run with GNU Coreutils in `$PATH`. The
+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.
+
+== 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
+ends in `.cc` or `.c` and is directly depended upon as in input file to a
+target, it will be elided, and only the targets that depend on it directly will
+be able to read its contents.
+
+The `build/meson-private` directory is fully elided, except for derivations
+that directly depend upon it. This is to limit the amount of impurities that
+are part of the configuration process. 
+
+=== Dependency tracking
+When a depfile cache is provided, and the output being built supports
+dependency files, any files ending in `.h` and `.hh` that aren't a known
+dependency are elided. However, if the build fails, it will be retried with all
+header files visible to the client.
+
+In some cases, this dependency tracking is imprecise, and causes some header
+files to not be properly visible to targets that need it. In this case, you can
+add an extra entry to the configuration file:
+
+.`lix.scm`
+[,scheme]
+----
+(environment: "(pkgs.lix.override { enableDocumentation = false; }).overrideAttrs (a: { doCheck = false; doInstallCheck = false; })"
+ depfile-path: "lix-depfile.scm"
+ disallow-elide: (lambda (path) (string=? path "config.h")))
+----
+
+This example ensures that `config.h` will be available to all targets being
+built for the derivation.
+
+== Library stubs
+When using Meson, any libraries that are linked will also simultaneously
+generate a stub `.so` file, using `llvm-ifs`. This stub library is valid for
+linking, but contains no code, and is generated deterministically. When linking
+any other libraries or binaries that depend on this library, the stub is
+automatically used, which improves early cutoff between library builds.