diff --git a/doc/manual/projects.xml b/doc/manual/projects.xml
index d3224215..88e239bb 100644
--- a/doc/manual/projects.xml
+++ b/doc/manual/projects.xml
@@ -150,15 +150,205 @@ DBIx::Class::ResultSet::create(): DBI Exception: DBD::SQLite::st execute failed:
- <filename>release.nix</filename>
+ Build Recipes
-- Voorbeelden van Nix expressies voor Hydra:
+
+ Build jobs and build recipes for a jobset are
+ specified in a text file written in the Nix language. The
+ recipe is actually called a Nix expression in
+ Nix parlance. By convention this file is often called
+ release.nix.
+
+
+ The release.nix file is typically kept under
+ version control, and the repository that contains it one of the
+ build inputs of the corresponding–often called
+ hydraConfig by convention. The repository for
+ that file and the actual file name are specified on the web
+ interface of Hydra under the Setup tab of the
+ jobset's overview page, under the Nix
+ expression heading. See, for example, the jobset
+ overview page of the PatchELF project, and
+ the corresponding Nix file.
+
+
+ Knowledge of the Nix language is recommended, but the example
+ below should already give a good idea of how it works:
+
-https://svn.nixos.org/repos/nix/patchelf/trunk/release.nix
-https://svn.nixos.org/repos/nix/nix/trunk/release.nix
-https://svn.nixos.org/repos/nix/hydra/trunk/release.nix
+
+ <filename>release.nix</filename> file for GNU Hello
+
+{ nixpkgs }:
+
+let
+ pkgs = import nixpkgs {};
+
+ jobs = rec {
+
+ tarball =
+ { helloSrc }:
+
+ pkgs.releaseTools.sourceTarball {
+ name = "hello-tarball";
+ src = helloSrc;
+ buildInputs = (with pkgs; [ gettext texLive texinfo ]);
+ };
+
+ build =
+ { tarball ? jobs.tarball {}
+ , system ? builtins.currentSystem
+ }:
+
+ let pkgs = import nixpkgs { inherit system; }; in
+ pkgs.releaseTools.nixBuild {
+ name = "hello" ;
+ src = tarball;
+ };
+ };
+in
+ jobs
+
+
+
+
+ shows what a
+ release.nix file for GNU Hello
+ would you like. GNU Hello is representative of many GNU
+ and non-GNU free software projects:
+
+
+ it uses the GNU Build System, namely GNU Autoconf,
+ and GNU Automake; for users, it means it can be installed
+ using the usual
+ ./configure && make install
+ procedure;
+
+ it uses Gettext for internationalization;
+ it has a Texinfo manual, which can be rendered as PDF
+ with TeX.
+
+
+ The file defines a jobset consisting of two jobs:
+ tarball, and build. It
+ contains the following elements (referenced from the figure by
+ numbers):
+
+
+
+
+
+ This specifies a function of one named arguments,
+ nixpkgs. This function and those
+ defined below is called by Hydra. Here the
+ nixpkgs argument is meant to be a
+ checkout of the Nixpkgs
+ software distribution.
+
+
+ Hydra inspects the formal argument list of the function
+ (here, the nixpkgs argument) and passes
+ it the corresponding parameter specified as a build input
+ on Hydra's web interface. In this case, the web interface
+ should show a nixpkgs build input,
+ which is a checkout of the Nixpkgs source code repository.
+
+
+
+
+ This defines a variable pkgs holding
+ the set of packages provided by Nixpkgs.
+
+
+
+
+
+ This defines a variable holding the two Hydra
+ jobs–an attribute set in Nix.
+
+
+
+
+
+ This is the definition of the first job, named
+ tarball. The purpose of this job is to
+ produce a usable source code tarball.
+
+
+
+
+ The tarball takes an additional
+ argument called helloSrc. Again, this
+ argument is passed by Hydra and is meant to be a checkout
+ of GNU Hello's source code repository.
+
+
+
+
+ The tarball job calls the
+ sourceTarball function, which (roughly)
+ runs autoreconf && ./configure &&
+ make dist on the checkout. The
+ buildInputs attribute specifies
+ additional software dependencies for the job.
+
+
+
+
+
+ This is the definition of the build
+ job, whose purpose is to build Hello from the tarball
+ produced above.
+
+
+
+
+ The build function takes two additional
+ parameter: tarball, which is meant to
+ be the result of the tarball job, and
+ system, which should be a string
+ defining the Nix system type–e.g.,
+ "x86_64-linux".
+
+
+ Again, these parameters are passed by Hydra when it calls
+ build. Thus, they must be defined as
+ build inputs in Hydra: tarball should
+ have type Build Output, its value being
+ the latest output of the tarball job,
+ and system should be a string.
+
+
+ The question mark after tarball and
+ system defines default values for these
+ arguments, and is only useful for debugging.
+
+
+
+
+ The build job calls the
+ nixBuild function, which unpacks the
+ tarball, then runs ./configure && make
+ && make check && make install.
+
+
+
+
+
+ Finally, the set of jobs is returned to Hydra, as a Nix
+ attribute set.
+
+
+
+