diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/expressions/arguments-variables.xml | 51 | ||||
| -rw-r--r-- | doc/manual/expressions/build-script.xml | 48 | ||||
| -rw-r--r-- | doc/manual/expressions/builtins.xml | 72 | ||||
| -rw-r--r-- | doc/manual/expressions/expression-syntax.xml | 48 | ||||
| -rw-r--r-- | doc/manual/expressions/generic-builder.xml | 34 | ||||
| -rw-r--r-- | doc/manual/expressions/language-constructs.xml | 36 | ||||
| -rw-r--r-- | doc/manual/src/expressions/arguments-variables.md | 28 | ||||
| -rw-r--r-- | doc/manual/src/expressions/build-script.md | 32 | ||||
| -rw-r--r-- | doc/manual/src/expressions/builtins.md | 54 | ||||
| -rw-r--r-- | doc/manual/src/expressions/expression-syntax.md | 29 | ||||
| -rw-r--r-- | doc/manual/src/expressions/generic-builder.md | 18 | ||||
| -rw-r--r-- | doc/manual/src/expressions/language-constructs.md | 22 |
12 files changed, 227 insertions, 245 deletions
diff --git a/doc/manual/expressions/arguments-variables.xml b/doc/manual/expressions/arguments-variables.xml index bf60cb7ee..a4375c777 100644 --- a/doc/manual/expressions/arguments-variables.xml +++ b/doc/manual/expressions/arguments-variables.xml @@ -6,20 +6,25 @@ <title>Arguments and Variables</title> -<example xml:id='ex-hello-composition'> +<para>The Nix expression in <xref linkend='ex-hello-nix' /> is a +function; it is missing some arguments that have to be filled in +somewhere. In the Nix Packages collection this is done in the file +<filename>pkgs/top-level/all-packages.nix</filename>, where all Nix +expressions for packages are imported and called with the appropriate +arguments. Here are some fragments of +<filename>all-packages.nix</filename>, with annotations of what they +mean:</para> -<title>Composing GNU Hello -(<filename>all-packages.nix</filename>)</title> <programlisting> ... -rec { <co xml:id='ex-hello-composition-co-1' /> +rec { ① - hello = import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' /> { <co xml:id='ex-hello-composition-co-3' /> + hello = import ../applications/misc/hello/ex-1 ② { ③ inherit fetchurl stdenv perl; }; - perl = import ../development/interpreters/perl { <co xml:id='ex-hello-composition-co-4' /> + perl = import ../development/interpreters/perl { ④ inherit fetchurl stdenv; }; @@ -31,31 +36,19 @@ rec { <co xml:id='ex-hello-composition-co-1' /> } </programlisting> -</example> -<para>The Nix expression in <xref linkend='ex-hello-nix' /> is a -function; it is missing some arguments that have to be filled in -somewhere. In the Nix Packages collection this is done in the file -<filename>pkgs/top-level/all-packages.nix</filename>, where all -Nix expressions for packages are imported and called with the -appropriate arguments. <xref linkend='ex-hello-composition' /> shows -some fragments of -<filename>all-packages.nix</filename>.</para> - -<calloutlist> - - <callout arearefs='ex-hello-composition-co-1'> +<orderedlist> + <listitem> <para>This file defines a set of attributes, all of which are concrete derivations (i.e., not functions). In fact, we define a <emphasis>mutually recursive</emphasis> set of attributes. That is, the attributes can refer to each other. This is precisely what we want since we want to <quote>plug</quote> the various packages into each other.</para> + </listitem> - </callout> - - <callout arearefs='ex-hello-composition-co-2'> + <listitem> <para>Here we <emphasis>import</emphasis> the Nix expression for GNU Hello. The import operation just loads and returns the @@ -71,9 +64,9 @@ some fragments of When you try to import a directory, Nix automatically appends <filename>/default.nix</filename> to the file name.</para> - </callout> + </listitem> - <callout arearefs='ex-hello-composition-co-3'> + <listitem> <para>This is where the actual composition takes place. Here we <emphasis>call</emphasis> the function imported from @@ -107,15 +100,15 @@ hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; }; </para></note> - </callout> + </listitem> - <callout arearefs='ex-hello-composition-co-4'> + <listitem> <para>Likewise, we have to instantiate Perl, <varname>fetchurl</varname>, and the standard environment.</para> - </callout> + </listitem> -</calloutlist> +</orderedlist> -</section>
\ No newline at end of file +</section> diff --git a/doc/manual/expressions/build-script.xml b/doc/manual/expressions/build-script.xml index 44264239d..892274f50 100644 --- a/doc/manual/expressions/build-script.xml +++ b/doc/manual/expressions/build-script.xml @@ -6,32 +6,30 @@ <title>Build Script</title> -<example xml:id='ex-hello-builder'><title>Build script for GNU Hello -(<filename>builder.sh</filename>)</title> +<para>Here is the builder referenced +from Hello's Nix expression (stored in +<filename>pkgs/applications/misc/hello/ex-1/builder.sh</filename>):</para> + <programlisting> -source $stdenv/setup <co xml:id='ex-hello-builder-co-1' /> +source $stdenv/setup ① -PATH=$perl/bin:$PATH <co xml:id='ex-hello-builder-co-2' /> +PATH=$perl/bin:$PATH ② -tar xvfz $src <co xml:id='ex-hello-builder-co-3' /> +tar xvfz $src ③ cd hello-* -./configure --prefix=$out <co xml:id='ex-hello-builder-co-4' /> -make <co xml:id='ex-hello-builder-co-5' /> +./configure --prefix=$out ④ +make ⑤ make install</programlisting> -</example> -<para><xref linkend='ex-hello-builder' /> shows the builder referenced -from Hello's Nix expression (stored in -<filename>pkgs/applications/misc/hello/ex-1/builder.sh</filename>). -The builder can actually be made a lot shorter by using the +<para>The builder can actually be made a lot shorter by using the <emphasis>generic builder</emphasis> functions provided by <varname>stdenv</varname>, but here we write out the build steps to elucidate what a builder does. It performs the following steps:</para> -<calloutlist> +<orderedlist> - <callout arearefs='ex-hello-builder-co-1'> + <listitem> <para>When Nix runs a builder, it initially completely clears the environment (except for the attributes declared in the @@ -52,9 +50,9 @@ steps:</para> attribute in <xref linkend='ex-hello-nix' />, but <varname>mkDerivation</varname> adds it automatically.)</para> - </callout> + </listitem> - <callout arearefs='ex-hello-builder-co-2'> + <listitem> <para>Since Hello needs Perl, we have to make sure that Perl is in the <literal>PATH</literal>. The <literal>perl</literal> environment @@ -63,9 +61,9 @@ steps:</para> <filename><replaceable>$perl</replaceable>/bin</filename> is the directory containing the Perl interpreter.</para> - </callout> + </listitem> - <callout arearefs='ex-hello-builder-co-3'> + <listitem> <para>Now we have to unpack the sources. The <varname>src</varname> attribute was bound to the result of @@ -82,9 +80,9 @@ steps:</para> always newly created, so you don't have to worry about files from previous builds interfering with the current build.</para> - </callout> + </listitem> - <callout arearefs='ex-hello-builder-co-4'> + <listitem> <para>GNU Hello is a typical Autoconf-based package, so we first have to run its <filename>configure</filename> script. In Nix @@ -98,17 +96,17 @@ steps:</para> <literal>--prefix=$out</literal> to cause Hello to be installed in the expected location.</para> - </callout> + </listitem> - <callout arearefs='ex-hello-builder-co-5'> + <listitem> <para>Finally we build Hello (<literal>make</literal>) and install it into the location specified by <literal>out</literal> (<literal>make install</literal>).</para> - </callout> + </listitem> -</calloutlist> +</orderedlist> <para>If you are wondering about the absence of error checking on the result of various commands called in the builder: this is because the @@ -116,4 +114,4 @@ shell script is evaluated with Bash's <option>-e</option> option, which causes the script to be aborted if any command fails without an error check.</para> -</section>
\ No newline at end of file +</section> diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml index a18c5801a..478b67ce8 100644 --- a/doc/manual/expressions/builtins.xml +++ b/doc/manual/expressions/builtins.xml @@ -1511,39 +1511,9 @@ in foo</programlisting> <!-- TODO: more formally describe the schema of the XML representation --> - <para><xref linkend='ex-toxml' /> shows an example where this is - the case. The builder is supposed to generate the configuration - file for a <link xlink:href='http://jetty.mortbay.org/'>Jetty - servlet container</link>. A servlet container contains a number - of servlets (<filename>*.war</filename> files) each exported under - a specific URI prefix. So the servlet configuration is a list of - sets containing the <varname>path</varname> and - <varname>war</varname> of the servlet (<xref - linkend='ex-toxml-co-servlets' />). This kind of information is - difficult to communicate with the normal method of passing - information through an environment variable, which just - concatenates everything together into a string (which might just - work in this case, but wouldn’t work if fields are optional or - contain lists themselves). Instead the Nix expression is - converted to an XML representation with - <function>toXML</function>, which is unambiguous and can easily be - processed with the appropriate tools. For instance, in the - example an XSLT stylesheet (<xref linkend='ex-toxml-co-stylesheet' - />) is applied to it (<xref linkend='ex-toxml-co-apply' />) to - generate the XML configuration file for the Jetty server. The XML - representation produced from <xref linkend='ex-toxml-co-servlets' - /> by <function>toXML</function> is shown in <xref - linkend='ex-toxml-result' />.</para> - - <para>Note that <xref linkend='ex-toxml' /> uses the <function - linkend='builtin-toFile'>toFile</function> built-in to write the - builder and the stylesheet “inline” in the Nix expression. The - path of the stylesheet is spliced into the builder at - <literal>xsltproc ${stylesheet} - <replaceable>...</replaceable></literal>.</para> - - <example xml:id='ex-toxml'><title>Passing information to a builder - using <function>toXML</function></title> + <para>Here is an example where this is + the case: + </para> <programlisting><![CDATA[ { stdenv, fetchurl, libxslt, jira, uberwiki }: @@ -1556,10 +1526,10 @@ stdenv.mkDerivation (rec { builder = builtins.toFile "builder.sh" " source $stdenv/setup mkdir $out - echo "$servlets" | xsltproc ${stylesheet} - > $out/server-conf.xml]]> <co xml:id='ex-toxml-co-apply' /> <![CDATA[ + echo "$servlets" | xsltproc ${stylesheet} - > $out/server-conf.xml]]> ① <![CDATA[ "; - stylesheet = builtins.toFile "stylesheet.xsl"]]> <co xml:id='ex-toxml-co-stylesheet' /> <![CDATA[ + stylesheet = builtins.toFile "stylesheet.xsl"]]> ② <![CDATA[ "<?xml version='1.0' encoding='UTF-8'?> <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'> <xsl:template match='/'> @@ -1575,16 +1545,32 @@ stdenv.mkDerivation (rec { </xsl:stylesheet> "; - servlets = builtins.toXML []]> <co xml:id='ex-toxml-co-servlets' /> <![CDATA[ + servlets = builtins.toXML []]> ③ <![CDATA[ { path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; } { path = "/wiki"; war = uberwiki + "/uberwiki.war"; } ]; })]]></programlisting> - </example> - - <example xml:id='ex-toxml-result'><title>XML representation produced by - <function>toXML</function></title> + <para>The builder is supposed to generate the configuration file + for a <link xlink:href='http://jetty.mortbay.org/'>Jetty servlet + container</link>. A servlet container contains a number of + servlets (<filename>*.war</filename> files) each exported under a + specific URI prefix. So the servlet configuration is a list of + sets containing the <varname>path</varname> and + <varname>war</varname> of the servlet (<xref + linkend='ex-toxml-co-servlets' />). This kind of information is + difficult to communicate with the normal method of passing + information through an environment variable, which just + concatenates everything together into a string (which might just + work in this case, but wouldn’t work if fields are optional or + contain lists themselves). Instead the Nix expression is + converted to an XML representation with + <function>toXML</function>, which is unambiguous and can easily be + processed with the appropriate tools. For instance, in the + example an XSLT stylesheet (at point ②) is applied to it (at point + ①) to generate the XML configuration file for the Jetty server. + The XML representation produced at point ③ by + <function>toXML</function> is as follows:</para> <programlisting><![CDATA[<?xml version='1.0' encoding='utf-8'?> <expr> @@ -1608,7 +1594,11 @@ stdenv.mkDerivation (rec { </list> </expr>]]></programlisting> - </example> + <para>Note that <xref linkend='ex-toxml' /> uses the <function + linkend='builtin-toFile'>toFile</function> built-in to write the + builder and the stylesheet “inline” in the Nix expression. The + path of the stylesheet is spliced into the builder using the + syntax <literal>xsltproc ${stylesheet}</literal>.</para> </listitem> diff --git a/doc/manual/expressions/expression-syntax.xml b/doc/manual/expressions/expression-syntax.xml index a3de20713..562a9e9f4 100644 --- a/doc/manual/expressions/expression-syntax.xml +++ b/doc/manual/expressions/expression-syntax.xml @@ -6,33 +6,31 @@ <title>Expression Syntax</title> -<example xml:id='ex-hello-nix'><title>Nix expression for GNU Hello -(<filename>default.nix</filename>)</title> +<para>Here is a Nix expression for GNU Hello:</para> + <programlisting> -{ stdenv, fetchurl, perl }: <co xml:id='ex-hello-nix-co-1' /> +{ stdenv, fetchurl, perl }: ① -stdenv.mkDerivation { <co xml:id='ex-hello-nix-co-2' /> - name = "hello-2.1.1"; <co xml:id='ex-hello-nix-co-3' /> - builder = ./builder.sh; <co xml:id='ex-hello-nix-co-4' /> - src = fetchurl { <co xml:id='ex-hello-nix-co-5' /> +stdenv.mkDerivation { ② + name = "hello-2.1.1"; ③ + builder = ./builder.sh; ④ + src = fetchurl { ⑤ url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; }; - inherit perl; <co xml:id='ex-hello-nix-co-6' /> + inherit perl; ⑥ }</programlisting> -</example> -<para><xref linkend='ex-hello-nix' /> shows a Nix expression for GNU -Hello. It's actually already in the Nix Packages collection in +<para>This file is actually already in the Nix Packages collection in <filename>pkgs/applications/misc/hello/ex-1/default.nix</filename>. It is customary to place each package in a separate directory and call the single Nix expression in that directory <filename>default.nix</filename>. The file has the following elements (referenced from the figure by number): -<calloutlist> +<orderedlist> - <callout arearefs='ex-hello-nix-co-1'> + <listitem> <para>This states that the expression is a <emphasis>function</emphasis> that expects to be called with three @@ -57,9 +55,9 @@ the single Nix expression in that directory function; when given the required arguments, the body should describe how to build an instance of the Hello package.</para> - </callout> + </listitem> - <callout arearefs='ex-hello-nix-co-2'> + <listitem> <para>So we have to build a package. Building something from other stuff is called a <emphasis>derivation</emphasis> in Nix (as @@ -76,9 +74,9 @@ the single Nix expression in that directory <replaceable>nameN</replaceable> = <replaceable>exprN</replaceable>; }</literal>.</para> - </callout> + </listitem> - <callout arearefs='ex-hello-nix-co-3'> + <listitem> <para>The attribute <varname>name</varname> specifies the symbolic name and version of the package. Nix doesn't really care about @@ -87,9 +85,9 @@ the single Nix expression in that directory packages. This attribute is required by <varname>mkDerivation</varname>.</para> - </callout> + </listitem> - <callout arearefs='ex-hello-nix-co-4'> + <listitem> <para>The attribute <varname>builder</varname> specifies the builder. This attribute can sometimes be omitted, in which case @@ -101,9 +99,9 @@ the single Nix expression in that directory <command>./builder.sh</command> refers to the shell script shown in <xref linkend='ex-hello-builder' />, discussed below.</para> - </callout> + </listitem> - <callout arearefs='ex-hello-nix-co-5'> + <listitem> <para>The builder has to know what the sources of the package are. Here, the attribute <varname>src</varname> is bound to the @@ -120,9 +118,9 @@ the single Nix expression in that directory customary, and it's also expected by the default builder (which we don't use in this example).</para> - </callout> + </listitem> - <callout arearefs='ex-hello-nix-co-6'> + <listitem> <para>Since the derivation requires Perl, we have to pass the value of the <varname>perl</varname> function argument to the @@ -139,9 +137,9 @@ perl = perl;</programlisting> causes the specified attributes to be bound to whatever variables with the same name happen to be in scope.</para> - </callout> + </listitem> -</calloutlist> +</orderedlist> </para> diff --git a/doc/manual/expressions/generic-builder.xml b/doc/manual/expressions/generic-builder.xml index 16b0268a7..71b342f99 100644 --- a/doc/manual/expressions/generic-builder.xml +++ b/doc/manual/expressions/generic-builder.xml @@ -20,23 +20,21 @@ 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> +functions that automate the build process. Here is what a builder +using the generic build facilities looks like:</para> -<example xml:id='ex-hello-builder2'><title>Build script using the generic -build functions</title> <programlisting> -buildInputs="$perl" <co xml:id='ex-hello-builder2-co-1' /> +buildInputs="$perl" ① -source $stdenv/setup <co xml:id='ex-hello-builder2-co-2' /> +source $stdenv/setup ② -genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting> -</example> +genericBuild ③</programlisting> -<calloutlist> +<para>Here is what each line means: - <callout arearefs='ex-hello-builder2-co-1'> +<orderedlist> + + <listitem> <para>The <literal>buildInputs</literal> variable tells <filename>setup</filename> to use the indicated packages as @@ -54,16 +52,16 @@ genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting> inputs.</para></footnote> </para> - </callout> + </listitem> - <callout arearefs='ex-hello-builder2-co-2'> + <listitem arearefs='ex-hello-builder2-co-2'> <para>The function <function>genericBuild</function> is defined in the file <literal>$stdenv/setup</literal>.</para> - </callout> + </listitem> - <callout arearefs='ex-hello-builder2-co-3'> + <listitem arearefs='ex-hello-builder2-co-3'> <para>The final step calls the shell function <function>genericBuild</function>, which performs the steps that @@ -73,9 +71,11 @@ genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting> <command>bzip2</command>, etc. It can be customised in many ways; see the Nixpkgs manual for details.</para> - </callout> + </listitem> + +</orderedlist> -</calloutlist> +</para> <para>Discerning readers will note that the <literal>buildInputs</literal> could just as well have been set in the Nix diff --git a/doc/manual/expressions/language-constructs.xml b/doc/manual/expressions/language-constructs.xml index 0d0cbbe15..4d316609c 100644 --- a/doc/manual/expressions/language-constructs.xml +++ b/doc/manual/expressions/language-constructs.xml @@ -278,7 +278,9 @@ evaluate to a Boolean value. If it evaluates to <literal>true</literal>, <replaceable>e2</replaceable> is returned; otherwise expression evaluation is aborted and a backtrace is printed.</para> -<example xml:id='ex-subversion-nix'><title>Nix expression for Subversion</title> +<para>Here is a Nix expression for the Subversion package that shows +how assertions can be used:.</para> + <programlisting> { localServer ? false , httpServer ? false @@ -290,9 +292,9 @@ otherwise expression evaluation is aborted and a backtrace is printed.</para> , openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null }: -assert localServer -> db4 != null; <co xml:id='ex-subversion-nix-co-1' /> -assert httpServer -> httpd != null && httpd.expat == expat; <co xml:id='ex-subversion-nix-co-2' /> -assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); <co xml:id='ex-subversion-nix-co-3' /> +assert localServer -> db4 != null; ① +assert httpServer -> httpd != null && httpd.expat == expat; ② +assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); ③ assert pythonBindings -> swig != null && swig.pythonSupport; assert javaSwigBindings -> swig != null && swig.javaSupport; assert javahlBindings -> j2sdk != null; @@ -300,26 +302,24 @@ assert javahlBindings -> j2sdk != null; stdenv.mkDerivation { name = "subversion-1.1.1"; ... - openssl = if sslSupport then openssl else null; <co xml:id='ex-subversion-nix-co-4' /> + openssl = if sslSupport then openssl else null; ④ ... }</programlisting> -</example> -<para><xref linkend='ex-subversion-nix' /> show how assertions are -used in the Nix expression for Subversion.</para> +<para>The points of interest are:</para> -<calloutlist> +<orderedlist> - <callout arearefs='ex-subversion-nix-co-1'> + <listitem> <para>This assertion states that if Subversion is to have support for local repositories, then Berkeley DB is needed. So if the Subversion function is called with the <varname>localServer</varname> argument set to <literal>true</literal> but the <varname>db4</varname> argument set to <literal>null</literal>, then the evaluation fails.</para> - </callout> + </listitem> - <callout arearefs='ex-subversion-nix-co-2'> + <listitem> <para>This is a more subtle condition: if Subversion is built with Apache (<literal>httpServer</literal>) support, then the Expat library (an XML library) used by Subversion should be same as the @@ -327,27 +327,27 @@ used in the Nix expression for Subversion.</para> Subversion code ends up being linked with Apache code, and if the Expat libraries do not match, a build- or runtime link error or incompatibility might occur.</para> - </callout> + </listitem> - <callout arearefs='ex-subversion-nix-co-3'> + <listitem> <para>This assertion says that in order for Subversion to have SSL support (so that it can access <literal>https</literal> URLs), an OpenSSL library must be passed. Additionally, it says that <emphasis>if</emphasis> Apache support is enabled, then Apache's OpenSSL should match Subversion's. (Note that if Apache support is not enabled, we don't care about Apache's OpenSSL.)</para> - </callout> + </listitem> - <callout arearefs='ex-subversion-nix-co-4'> + <listitem> <para>The conditional here is not really related to assertions, but is worth pointing out: it ensures that if SSL support is disabled, then the Subversion derivation is not dependent on OpenSSL, even if a non-<literal>null</literal> value was passed. This prevents an unnecessary rebuild of Subversion if OpenSSL changes.</para> - </callout> + </listitem> -</calloutlist> +</orderedlist> </simplesect> diff --git a/doc/manual/src/expressions/arguments-variables.md b/doc/manual/src/expressions/arguments-variables.md index 9a373d94d..436ae559d 100644 --- a/doc/manual/src/expressions/arguments-variables.md +++ b/doc/manual/src/expressions/arguments-variables.md @@ -1,14 +1,21 @@ # Arguments and Variables +The Nix expression in [???](#ex-hello-nix) is a function; it is missing +some arguments that have to be filled in somewhere. In the Nix Packages +collection this is done in the file `pkgs/top-level/all-packages.nix`, +where all Nix expressions for packages are imported and called with the +appropriate arguments. Here are some fragments of `all-packages.nix`, +with annotations of what they mean: + ... - rec { + rec { ① - hello = import ../applications/misc/hello/ex-1 { + hello = import ../applications/misc/hello/ex-1 ② { ③ inherit fetchurl stdenv perl; }; - perl = import ../development/interpreters/perl { + perl = import ../development/interpreters/perl { ④ inherit fetchurl stdenv; }; @@ -20,20 +27,13 @@ } -The Nix expression in [???](#ex-hello-nix) is a function; it is missing -some arguments that have to be filled in somewhere. In the Nix Packages -collection this is done in the file `pkgs/top-level/all-packages.nix`, -where all Nix expressions for packages are imported and called with the -appropriate arguments. [example\_title](#ex-hello-composition) shows -some fragments of `all-packages.nix`. - - - This file defines a set of attributes, all of which are concrete +1. This file defines a set of attributes, all of which are concrete derivations (i.e., not functions). In fact, we define a *mutually recursive* set of attributes. That is, the attributes can refer to each other. This is precisely what we want since we want to “plug” the various packages into each other. - - Here we *import* the Nix expression for GNU Hello. The import +2. Here we *import* the Nix expression for GNU Hello. The import operation just loads and returns the specified Nix expression. In fact, we could just have put the contents of [???](#ex-hello-nix) in `all-packages.nix` at this point. That would be completely @@ -44,7 +44,7 @@ some fragments of `all-packages.nix`. import a directory, Nix automatically appends `/default.nix` to the file name. - - This is where the actual composition takes place. Here we *call* the +3. This is where the actual composition takes place. Here we *call* the function imported from `../applications/misc/hello/ex-1` with a set containing the things that the function expects, namely `fetchurl`, `stdenv`, and `perl`. We use inherit again to use the attributes @@ -68,5 +68,5 @@ some fragments of `all-packages.nix`. > > hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; }; - - Likewise, we have to instantiate Perl, `fetchurl`, and the standard +4. Likewise, we have to instantiate Perl, `fetchurl`, and the standard environment. diff --git a/doc/manual/src/expressions/build-script.md b/doc/manual/src/expressions/build-script.md index a359ebc46..f922182c2 100644 --- a/doc/manual/src/expressions/build-script.md +++ b/doc/manual/src/expressions/build-script.md @@ -1,23 +1,23 @@ # Build Script - source $stdenv/setup +Here is the builder referenced from Hello's Nix expression (stored in +`pkgs/applications/misc/hello/ex-1/builder.sh`): + + source $stdenv/setup ① - PATH=$perl/bin:$PATH + PATH=$perl/bin:$PATH ② - tar xvfz $src + tar xvfz $src ③ cd hello-* - ./configure --prefix=$out - make + ./configure --prefix=$out ④ + make ⑤ make install -[example\_title](#ex-hello-builder) shows the builder referenced from -Hello's Nix expression (stored in -`pkgs/applications/misc/hello/ex-1/builder.sh`). The builder can -actually be made a lot shorter by using the *generic builder* functions -provided by `stdenv`, but here we write out the build steps to elucidate -what a builder does. It performs the following steps: +The builder can actually be made a lot shorter by using the *generic +builder* functions provided by `stdenv`, but here we write out the build +steps to elucidate what a builder does. It performs the following steps: - - When Nix runs a builder, it initially completely clears the +1. When Nix runs a builder, it initially completely clears the environment (except for the attributes declared in the derivation). For instance, the `PATH` variable is empty\[1\]. This is done to prevent undeclared inputs from being used in the build process. If @@ -31,13 +31,13 @@ what a builder does. It performs the following steps: attribute in [???](#ex-hello-nix), but `mkDerivation` adds it automatically.) - - Since Hello needs Perl, we have to make sure that Perl is in the +2. Since Hello needs Perl, we have to make sure that Perl is in the `PATH`. The `perl` environment variable points to the location of the Perl package (since it was passed in as an attribute to the derivation), so `$perl/bin` is the directory containing the Perl interpreter. - - Now we have to unpack the sources. The `src` attribute was bound to +3. Now we have to unpack the sources. The `src` attribute was bound to the result of fetching the Hello source tarball from the network, so the `src` environment variable points to the location in the Nix store to which the tarball was downloaded. After unpacking, we `cd` @@ -50,7 +50,7 @@ what a builder does. It performs the following steps: have to worry about files from previous builds interfering with the current build. - - GNU Hello is a typical Autoconf-based package, so we first have to +4. GNU Hello is a typical Autoconf-based package, so we first have to run its `configure` script. In Nix every package is stored in a separate location in the Nix store, for instance `/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix @@ -60,7 +60,7 @@ what a builder does. It performs the following steps: `--prefix=$out` to cause Hello to be installed in the expected location. - - Finally we build Hello (`make`) and install it into the location +5. Finally we build Hello (`make`) and install it into the location specified by `out` (`make install`). If you are wondering about the absence of error checking on the result diff --git a/doc/manual/src/expressions/builtins.md b/doc/manual/src/expressions/builtins.md index a378fe8e4..f60af9d24 100644 --- a/doc/manual/src/expressions/builtins.md +++ b/doc/manual/src/expressions/builtins.md @@ -735,31 +735,7 @@ For instance, `derivation` is also available as `builtins.derivation`. builder in a more structured format than plain environment variables. - [example\_title](#ex-toxml) shows an example where this is the case. - The builder is supposed to generate the configuration file for a - [Jetty servlet container](http://jetty.mortbay.org/). A servlet - container contains a number of servlets (`*.war` files) each - exported under a specific URI prefix. So the servlet configuration - is a list of sets containing the `path` and `war` of the servlet - ([co\_title](#ex-toxml-co-servlets)). This kind of information is - difficult to communicate with the normal method of passing - information through an environment variable, which just concatenates - everything together into a string (which might just work in this - case, but wouldn’t work if fields are optional or contain lists - themselves). Instead the Nix expression is converted to an XML - representation with `toXML`, which is unambiguous and can easily be - processed with the appropriate tools. For instance, in the example - an XSLT stylesheet ([co\_title](#ex-toxml-co-stylesheet)) is applied - to it ([co\_title](#ex-toxml-co-apply)) to generate the XML - configuration file for the Jetty server. The XML representation - produced from [co\_title](#ex-toxml-co-servlets) by `toXML` is shown - in [example\_title](#ex-toxml-result). - - Note that [example\_title](#ex-toxml) uses the `toFile` built-in to - write the builder and the stylesheet “inline” in the Nix expression. - The path of the stylesheet is spliced into the builder at `xsltproc - ${stylesheet} - ...`. + Here is an example where this is the case: { stdenv, fetchurl, libxslt, jira, uberwiki }: @@ -771,10 +747,10 @@ For instance, `derivation` is also available as `builtins.derivation`. builder = builtins.toFile "builder.sh" " source $stdenv/setup mkdir $out - echo "$servlets" | xsltproc ${stylesheet} - > $out/server-conf.xml + echo "$servlets" | xsltproc ${stylesheet} - > $out/server-conf.xml ① "; - stylesheet = builtins.toFile "stylesheet.xsl" + stylesheet = builtins.toFile "stylesheet.xsl" ② "<?xml version='1.0' encoding='UTF-8'?> <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'> <xsl:template match='/'> @@ -790,12 +766,29 @@ For instance, `derivation` is also available as `builtins.derivation`. </xsl:stylesheet> "; - servlets = builtins.toXML [ + servlets = builtins.toXML [ ③ { path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; } { path = "/wiki"; war = uberwiki + "/uberwiki.war"; } ]; }) + The builder is supposed to generate the configuration file for a + [Jetty servlet container](http://jetty.mortbay.org/). A servlet + container contains a number of servlets (`*.war` files) each + exported under a specific URI prefix. So the servlet configuration + is a list of sets containing the `path` and `war` of the servlet + ([???](#ex-toxml-co-servlets)). This kind of information is + difficult to communicate with the normal method of passing + information through an environment variable, which just concatenates + everything together into a string (which might just work in this + case, but wouldn’t work if fields are optional or contain lists + themselves). Instead the Nix expression is converted to an XML + representation with `toXML`, which is unambiguous and can easily be + processed with the appropriate tools. For instance, in the example + an XSLT stylesheet (at point ②) is applied to it (at point ①) to + generate the XML configuration file for the Jetty server. The XML + representation produced at point ③ by `toXML` is as follows: + <?xml version='1.0' encoding='utf-8'?> <expr> <list> @@ -817,6 +810,11 @@ For instance, `derivation` is also available as `builtins.derivation`. </attrs> </list> </expr> + + Note that [???](#ex-toxml) uses the `toFile` built-in to write the + builder and the stylesheet “inline” in the Nix expression. The path + of the stylesheet is spliced into the builder using the syntax + `xsltproc ${stylesheet}`. - `builtins.trace` e1 e2 Evaluate e1 and print its abstract syntax representation on standard diff --git a/doc/manual/src/expressions/expression-syntax.md b/doc/manual/src/expressions/expression-syntax.md index 935484c33..9e99a1f60 100644 --- a/doc/manual/src/expressions/expression-syntax.md +++ b/doc/manual/src/expressions/expression-syntax.md @@ -1,25 +1,26 @@ # Expression Syntax - { stdenv, fetchurl, perl }: +Here is a Nix expression for GNU Hello: + + { stdenv, fetchurl, perl }: ① - stdenv.mkDerivation { - name = "hello-2.1.1"; - builder = ./builder.sh; - src = fetchurl { + stdenv.mkDerivation { ② + name = "hello-2.1.1"; ③ + builder = ./builder.sh; ④ + src = fetchurl { ⑤ url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; }; - inherit perl; + inherit perl; ⑥ } -[example\_title](#ex-hello-nix) shows a Nix expression for GNU Hello. -It's actually already in the Nix Packages collection in +This file is actually already in the Nix Packages collection in `pkgs/applications/misc/hello/ex-1/default.nix`. It is customary to place each package in a separate directory and call the single Nix expression in that directory `default.nix`. The file has the following elements (referenced from the figure by number): - - This states that the expression is a *function* that expects to be +1. This states that the expression is a *function* that expects to be called with three arguments: `stdenv`, `fetchurl`, and `perl`. They are needed to build Hello, but we don't know how to build them here; that's why they are function arguments. `stdenv` is a package that @@ -37,7 +38,7 @@ elements (referenced from the figure by number): the required arguments, the body should describe how to build an instance of the Hello package. - - So we have to build a package. Building something from other stuff +2. So we have to build a package. Building something from other stuff is called a *derivation* in Nix (as opposed to sources, which are built by humans instead of computers). We perform a derivation by calling `stdenv.mkDerivation`. `mkDerivation` is a function provided @@ -50,13 +51,13 @@ elements (referenced from the figure by number): nameN = exprN; }`. - - The attribute `name` specifies the symbolic name and version of the +3. The attribute `name` specifies the symbolic name and version of the package. Nix doesn't really care about these things, but they are used by for instance `nix-env -q` to show a “human-readable” name for packages. This attribute is required by `mkDerivation`. - - The attribute `builder` specifies the builder. This attribute can +4. The attribute `builder` specifies the builder. This attribute can sometimes be omitted, in which case `mkDerivation` will fill in a default builder (which does a `configure; make; make install`, in essence). Hello is sufficiently simple that the default builder @@ -64,7 +65,7 @@ elements (referenced from the figure by number): educational purposes. The value `./builder.sh` refers to the shell script shown in [???](#ex-hello-builder), discussed below. - - The builder has to know what the sources of the package are. Here, +5. The builder has to know what the sources of the package are. Here, the attribute `src` is bound to the result of a call to the `fetchurl` function. Given a URL and a SHA-256 hash of the expected contents of the file at that URL, this function builds a derivation @@ -77,7 +78,7 @@ elements (referenced from the figure by number): However, `src` is customary, and it's also expected by the default builder (which we don't use in this example). - - Since the derivation requires Perl, we have to pass the value of the +6. Since the derivation requires Perl, we have to pass the value of the `perl` function argument to the builder. All attributes in the set are actually passed as environment variables to the builder, so declaring an attribute diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md index a00b08b55..90bdc556b 100644 --- a/doc/manual/src/expressions/generic-builder.md +++ b/doc/manual/src/expressions/generic-builder.md @@ -13,24 +13,26 @@ like this: 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 [example\_title](#ex-hello-builder2). +functions that automate the build process. Here is what a builder using +the generic build facilities looks like: - buildInputs="$perl" + buildInputs="$perl" ① - source $stdenv/setup + source $stdenv/setup ② - genericBuild + genericBuild ③ - - The `buildInputs` variable tells `setup` to use the indicated +Here is what each line means: + +1. The `buildInputs` variable tells `setup` to use the indicated packages as “inputs”. This means that if a package provides a `bin` subdirectory, it's added to `PATH`; if it has a `include` subdirectory, it's added to GCC's header search path; and so on.\[1\] - - The function `genericBuild` is defined in the file `$stdenv/setup`. +2. The function `genericBuild` is defined in the file `$stdenv/setup`. - - The final step calls the shell function `genericBuild`, which +3. The final step calls the shell function `genericBuild`, which performs the steps that were done explicitly in [???](#ex-hello-builder). The generic builder is smart enough to figure out whether to unpack the sources using `gzip`, `bzip2`, etc. diff --git a/doc/manual/src/expressions/language-constructs.md b/doc/manual/src/expressions/language-constructs.md index a773c239b..121e4d998 100644 --- a/doc/manual/src/expressions/language-constructs.md +++ b/doc/manual/src/expressions/language-constructs.md @@ -203,6 +203,9 @@ where e1 is an expression that should evaluate to a Boolean value. If it evaluates to `true`, e2 is returned; otherwise expression evaluation is aborted and a backtrace is printed. +Here is a Nix expression for the Subversion package that shows how +assertions can be used:. + { localServer ? false , httpServer ? false , sslSupport ? false @@ -213,9 +216,9 @@ aborted and a backtrace is printed. , openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null }: - assert localServer -> db4 != null; - assert httpServer -> httpd != null && httpd.expat == expat; - assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); + assert localServer -> db4 != null; ① + assert httpServer -> httpd != null && httpd.expat == expat; ② + assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); ③ assert pythonBindings -> swig != null && swig.pythonSupport; assert javaSwigBindings -> swig != null && swig.javaSupport; assert javahlBindings -> j2sdk != null; @@ -223,33 +226,32 @@ aborted and a backtrace is printed. stdenv.mkDerivation { name = "subversion-1.1.1"; ... - openssl = if sslSupport then openssl else null; + openssl = if sslSupport then openssl else null; ④ ... } -[example\_title](#ex-subversion-nix) show how assertions are used in the -Nix expression for Subversion. +The points of interest are: - - This assertion states that if Subversion is to have support for +1. This assertion states that if Subversion is to have support for local repositories, then Berkeley DB is needed. So if the Subversion function is called with the `localServer` argument set to `true` but the `db4` argument set to `null`, then the evaluation fails. - - This is a more subtle condition: if Subversion is built with Apache +2. This is a more subtle condition: if Subversion is built with Apache (`httpServer`) support, then the Expat library (an XML library) used by Subversion should be same as the one used by Apache. This is because in this configuration Subversion code ends up being linked with Apache code, and if the Expat libraries do not match, a build- or runtime link error or incompatibility might occur. - - This assertion says that in order for Subversion to have SSL support +3. This assertion says that in order for Subversion to have SSL support (so that it can access `https` URLs), an OpenSSL library must be passed. Additionally, it says that *if* Apache support is enabled, then Apache's OpenSSL should match Subversion's. (Note that if Apache support is not enabled, we don't care about Apache's OpenSSL.) - - The conditional here is not really related to assertions, but is +4. The conditional here is not really related to assertions, but is worth pointing out: it ensures that if SSL support is disabled, then the Subversion derivation is not dependent on OpenSSL, even if a non-`null` value was passed. This prevents an unnecessary rebuild of |