(zilch lang ninja): document
Change-Id: I6a6a6964dcc713504ec57f40981a601696a573af
This commit is contained in:
parent
154ba9be1c
commit
93a1ebba00
11 changed files with 329 additions and 43 deletions
63
docs/modules/ROOT/pages/ninja/man.adoc
Normal file
63
docs/modules/ROOT/pages/ninja/man.adoc
Normal file
|
|
@ -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.
|
||||
131
docs/modules/ROOT/pages/ninja/usage.adoc
Normal file
131
docs/modules/ROOT/pages/ninja/usage.adoc
Normal file
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue