From 3e237693483a8ef185ca5ebc86e95ad54ff22f4e Mon Sep 17 00:00:00 2001 From: Puck Meerburg Date: Wed, 1 Oct 2025 14:59:25 +0000 Subject: [PATCH] (zilch lang ninja): document incremental build Change-Id: I6a6a696472806049b5ecab203487254f32a716b7 --- docs/modules/ROOT/pages/ninja/man.adoc | 11 +++++--- docs/modules/ROOT/pages/ninja/usage.adoc | 32 +++++++++++++++++++++++- 2 files changed, 38 insertions(+), 5 deletions(-) diff --git a/docs/modules/ROOT/pages/ninja/man.adoc b/docs/modules/ROOT/pages/ninja/man.adoc index 17eaf51..77c49dd 100644 --- a/docs/modules/ROOT/pages/ninja/man.adoc +++ b/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_:: diff --git a/docs/modules/ROOT/pages/ninja/usage.adoc b/docs/modules/ROOT/pages/ninja/usage.adoc index 6def8ab..c7c9670 100644 --- a/docs/modules/ROOT/pages/ninja/usage.adoc +++ b/docs/modules/ROOT/pages/ninja/usage.adoc @@ -50,6 +50,11 @@ dev -> # # ---- +It's also possible to use `override-source: ""` 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 <> 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