ma27/hydra
0
0
Fork 0
forked from lix-project/hydra
Code Pull requests Activity

doc: Update to use angle brackets and `tarball' in the same evaluation.

Browse source
This commit is contained in:
Ludovic Courtès 2012-05-23 00:07:49 +02:00
parent 97d41a2102
commit 2865569392
1 changed files with 43 additions and 78 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

121
doc/manual/projects.xml
View file

@ -184,31 +184,25 @@ system String value "i686-linux"
<example xml:id='ex-hello'> <example xml:id='ex-hello'>
<title><filename>release.nix</filename> file for GNU Hello</title> <title><filename>release.nix</filename> file for GNU Hello</title>
<programlisting> <programlisting>
{ nixpkgs }: <co xml:id='ex-hello-co-nixpkgs' />
let let
pkgs = import nixpkgs {}; <co xml:id='ex-hello-co-import-nixpkgs' /> pkgs = import &lt;nixpkgs&gt; {}; <co xml:id='ex-hello-co-import-nixpkgs' />
jobs = rec { <co xml:id='ex-hello-co-jobs' /> jobs = rec { <co xml:id='ex-hello-co-jobs' />
tarball = <co xml:id='ex-hello-co-tarball' /> tarball = <co xml:id='ex-hello-co-tarball' />
{ helloSrc }: <co xml:id='ex-hello-co-tarball-args' />
pkgs.releaseTools.sourceTarball { <co xml:id='ex-hello-co-source-tarball' /> pkgs.releaseTools.sourceTarball { <co xml:id='ex-hello-co-source-tarball' />
name = "hello-tarball"; name = "hello-tarball";
src = helloSrc; src = &lt;hello&gt;; <co xml:id='ex-hello-co-tarball-args' />
buildInputs = (with pkgs; [ gettext texLive texinfo ]); buildInputs = (with pkgs; [ gettext texLive texinfo ]);
}; };
build = <co xml:id='ex-hello-co-build' /> build = <co xml:id='ex-hello-co-build' />
{ tarball ? jobs.tarball {} <co xml:id='ex-hello-co-build-args' /> { system ? builtins.currentSystem }: <co xml:id='ex-hello-co-build-args' />
, system ? builtins.currentSystem
}:
let pkgs = import nixpkgs { inherit system; }; in let pkgs = import &lt;nixpkgs&gt; { inherit system; }; in
pkgs.releaseTools.nixBuild { <co xml:id='ex-hello-co-nix-build' /> pkgs.releaseTools.nixBuild { <co xml:id='ex-hello-co-nix-build' />
name = "hello"; name = "hello";
src = tarball; src = jobs.tarball;
configureFlags = [ "--disable-silent-rules" ]; configureFlags = [ "--disable-silent-rules" ];
}; };
}; };
@ -244,29 +238,20 @@ in
<calloutlist> <calloutlist>
<callout arearefs='ex-hello-co-nixpkgs'>
<para>
This specifies a function of one named arguments,
<varname>nixpkgs</varname>. This function and those
defined below is called by Hydra. Here the
<varname>nixpkgs</varname> argument is meant to be a
checkout of the <link
xlink:href="http://nixos.org/nixpkgs/">Nixpkgs</link>
software distribution.
</para>
<para>
Hydra inspects the formal argument list of the function
(here, the <varname>nixpkgs</varname> 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 <varname>nixpkgs</varname> build input,
which is a checkout of the Nixpkgs source code repository.
</para>
</callout>
<callout arearefs='ex-hello-co-import-nixpkgs'> <callout arearefs='ex-hello-co-import-nixpkgs'>
<para> <para>
This defines a variable <varname>pkgs</varname> holding This defines a variable <varname>pkgs</varname> holding
the set of packages provided by Nixpkgs. the set of packages provided by <link
xlink:href="http://nixos.org/nixpkgs/">Nixpkgs</link>.
</para>
<para>
Since <varname>nixpkgs</varname> appears in angle brackets,
there must be a build input of that name in the Nix search
path. In this case, the web interface should show a
<varname>nixpkgs</varname> build input, which is a checkout
of the Nixpkgs source code repository; Hydra then adds this
and other build inputs to the Nix search path when
evaluating <filename>release.nix</filename>.
</para> </para>
</callout> </callout>
@ -286,10 +271,11 @@ in
</callout> </callout>
<callout arearefs='ex-hello-co-tarball-args'> <callout arearefs='ex-hello-co-tarball-args'>
<para> <para>
The <varname>tarball</varname> takes an additional The <varname>tarball</varname> jobs expects a
argument called <varname>helloSrc</varname>. Again, this <varname>hello</varname> build input to be available in the
argument is passed by Hydra and is meant to be a checkout Nix search path. Again, this input is passed by Hydra and
of GNU Hello's source code repository. is meant to be a checkout of GNU Hello's source code
repository.
</para> </para>
</callout> </callout>
<callout arearefs='ex-hello-co-source-tarball'> <callout arearefs='ex-hello-co-source-tarball'>
@ -320,25 +306,25 @@ in
</callout> </callout>
<callout arearefs='ex-hello-co-build-args'> <callout arearefs='ex-hello-co-build-args'>
<para> <para>
The <varname>build</varname> function takes two additional The <varname>build</varname> function takes one
parameter: <varname>tarball</varname>, which is meant to parameter, <varname>system</varname>, which should be a string
be the result of the <varname>tarball</varname> job, and
<varname>system</varname>, which should be a string
defining the Nix system type–e.g., defining the Nix system type–e.g.,
<literal>"x86_64-linux"</literal>. <literal>"x86_64-linux"</literal>. Additionally, it refers
to <varname>jobs.tarball</varname>, seen above.
</para> </para>
<para> <para>
Again, these parameters are passed by Hydra when it calls Hydra inspects the formal argument list of the function
<varname>build</varname>. Thus, they must be defined as (here, the <varname>system</varname> argument) and passes it
build inputs in Hydra: <varname>tarball</varname> should the corresponding parameter specified as a build input on
have type <literal>Build Output</literal>, its value being Hydra's web interface. Here, <varname>system</varname> is
the latest output of the <varname>tarball</varname> job, passed by Hydra when it calls <varname>build</varname>.
and <varname>system</varname> should be a string. Thus, it must be defined as a build input of type string in
Hydra, which could take one of several values.
</para> </para>
<para> <para>
The question mark after <literal>tarball</literal> and The question mark after <literal>system</literal> defines
<literal>system</literal> defines default values for these the default value for this argument, and is only useful when
arguments, and is only useful for debugging. debugging locally.
</para> </para>
</callout> </callout>
<callout arearefs='ex-hello-co-nix-build'> <callout arearefs='ex-hello-co-nix-build'>
@ -383,29 +369,12 @@ $ nix-build release.nix -A tarball
probably yield an error like this: probably yield an error like this:
<screen> <screen>
error: cannot auto-call a function that has an argument without a default value (`nixpkgs') error: user-thrown exception: file `hello' was not found in the Nix search path (add it using $NIX_PATH or -I)
</screen> </screen>
This is because no value was specified for the The error is self-explanatory. Assuming
<varname>nixpkgs</varname> argument of the Nix expression. <filename>$HOME/src/hello</filename> points to a checkout of
</para> Hello, this can be fixed this way:
<para>
This is fixed by providing a default value for that argument in
the Nix expression, which will allow <command>nix-build</command>
to auto-call the function: instfead of writing <literal>{ nixpkgs
}:</literal>, we now write <literal>{ nixpkgs ? &lt;nixpkgs&gt;
}:</literal>. What it means is that, by default, the
<varname>nixpkgs</varname> variable will be bound to the absolute
path of any <filename>nixpkgs</filename> file found in the Nix
search path. Similarly, a default value for
<varname>helloSrc</varname> needs to be provided.
</para>
<para>
Thus, assuming a checkout of Nixpkgs is available under
<filename>$HOME/src/nixpkgs</filename>, the
<varname>tarball</varname> jobset can now be evaluated by running:
<screen> <screen>
$ nix-build -I ~/src release.nix -A tarball $ nix-build -I ~/src release.nix -A tarball
@ -445,14 +414,12 @@ $ nix-build -I ~/src release.nix -A build
<programlisting> <programlisting>
coverage = coverage =
{ tarball ? jobs.tarball {} { system ? builtins.currentSystem }:
, system ? builtins.currentSystem
}:
let pkgs = import nixpkgs { inherit system; }; in let pkgs = import nixpkgs { inherit system; }; in
pkgs.releaseTools.coverageAnalysis { pkgs.releaseTools.coverageAnalysis {
name = "hello"; name = "hello";
src = tarball; src = jobs.tarball;
configureFlags = [ "--disable-silent-rules" ]; configureFlags = [ "--disable-silent-rules" ];
}; };
</programlisting> </programlisting>
@ -482,13 +449,11 @@ coverage =
<programlisting> <programlisting>
build_exotic = build_exotic =
{ tarball ? jobs.tarball {} { system ? builtins.currentSystem }:
, system ? builtins.currentSystem
}:
let let
pkgs = import nixpkgs { inherit system; }; pkgs = import nixpkgs { inherit system; };
build = jobs.build { inherit tarball system; }; build = jobs.build { inherit system; };
in in
pkgs.lib.overrideDerivation build (attrs: { pkgs.lib.overrideDerivation build (attrs: {
buildInputs = [ pkgs.gcc33 ]; buildInputs = [ pkgs.gcc33 ];