puck/zilch
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

(zilch lang ninja): document incremental build

Browse source 
Change-Id: I6a6a696472806049b5ecab203487254f32a716b7
This commit is contained in:
puck 2025-10-01 14:59:25 +00:00
parent 0036f464ac
commit 3e23769348
2 changed files with 38 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

11
docs/modules/ROOT/pages/ninja/man.adoc
View file

@ -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_::

32
docs/modules/ROOT/pages/ninja/usage.adoc
View file

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