diff options
| -rw-r--r-- | doc/manual/writing-nix-expressions.xml | 89 |
1 files changed, 84 insertions, 5 deletions
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index b6f426d663a7..99d766872fc7 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -447,7 +447,7 @@ following: <programlisting> (import pkgs/system/i686-linux.nix).hello</programlisting> -Call it <filename>test.nix</filename>. Then you can build it without +Call it <filename>test.nix</filename>. You can then build it without installing it using the command <command>nix-build</command>: <screen> @@ -501,7 +501,86 @@ run in parallel. Typically this should be the number of CPUs.</para> <sect2><title>The generic builder</title> -<para>TODO</para> +<para>Recall from <xref linkend='ex-hello-builder' /> that the builder +looked something like this: + +<programlisting> +PATH=$perl/bin:$PATH +tar xvfz $src +cd hello-* +./configure --prefix=$out +make +make install</programlisting> + +The builders for almost all Unix packages look like this — set up some +environment variables, unpack the sources, configure, build, and +install. For this reason the standard environment provides some Bash +functions that automate the build process. A builder using the +generic build facilities in shown in <xref linkend='ex-hello-builder2' +/>.</para> + +<example id='ex-hello-builder2'><title>Build script using the generic +build functions</title> +<programlisting> +buildInputs="$perl" <co id='ex-hello-builder2-co-1' /> + +. $stdenv/setup <co id='ex-hello-builder2-co-2' /> + +genericBuild <co id='ex-hello-builder2-co-3' /></programlisting> +</example> + +<calloutlist> + + <callout arearefs='ex-hello-builder2-co-1'> + + <para>The <envar>buildInputs</envar> variable tells + <filename>setup</filename> to use the indicated components as + <quote>inputs</quote>. This means that if a component provides a + <filename>bin</filename> subdirectory, it's added to + <envar>PATH</envar>; if it has a <filename>include</filename> + subdirectory, it's added to GCC's header search path; and so + on.</para> + + </callout> + + <callout arearefs='ex-hello-builder2-co-2'> + + <para>The function <function>genericBuild</function> is defined in + the file <literal>$stdenv/setup</literal>.</para> + + </callout> + + <callout arearefs='ex-hello-builder2-co-3'> + + <para>The final step calls the shell function + <function>genericBuild</function>, which performs the steps that + were done explicitly in <xref linkend='ex-hello-builder' />. The + generic builder is smart enough to figure out whether to unpack + the sources using <command>gzip</command>, + <command>bzip2</command>, etc. It can be customised in many ways; + see <xref linkend='sec-standard-environment' />.</para> + + </callout> + +</calloutlist> + +<para>Discerning readers will note that the +<envar>buildInputs</envar> could just as well have been set in the Nix +expression, like this: + +<programlisting> + buildInputs = [perl];</programlisting> + +The <varname>perl</varname> attribute can then be removed, and the +builder becomes even shorter: + +<programlisting> +. $stdenv/setup +genericBuilder></programlisting> + +In fact, <varname>mkDerivation</varname> provides a default builder +that looks exactly like that, so it is actually possible to omit the +builder for Hello entirely.</para> </sect2> @@ -661,7 +740,7 @@ shortened using the <literal>inherit</literal> keyword. For instance, --> -<simplesect><title>Lets</title> +<simplesect><title>Let expressions</title> <para>TODO</para> @@ -691,7 +770,7 @@ shortened using the <literal>inherit</literal> keyword. For instance, </simplesect> -<simplesect><title><quote>With</quote> expressions</title> +<simplesect><title>With expressions</title> <para>TODO</para> @@ -723,7 +802,7 @@ shortened using the <literal>inherit</literal> keyword. For instance, -<sect1><title>The standard environment</title> +<sect1 id='sec-standard-environment'><title>The standard environment</title> <para>TODO</para> |