From 46b38dc6231f867484d6ae856516511ff4dee863 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Tue, 11 Oct 2011 21:05:06 +0000 Subject: [PATCH] doc: Add preliminary section about `release.nix'. --- doc/manual/projects.xml | 200 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 195 insertions(+), 5 deletions(-) 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. + + + +