about summary refs log tree commit diff
path: root/third_party/nix/doc/manual/expressions/builtins.xml
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/nix/doc/manual/expressions/builtins.xml')
-rw-r--r--third_party/nix/doc/manual/expressions/builtins.xml1658
1 files changed, 0 insertions, 1658 deletions
diff --git a/third_party/nix/doc/manual/expressions/builtins.xml b/third_party/nix/doc/manual/expressions/builtins.xml
deleted file mode 100644
index 394e1fc32c95..000000000000
--- a/third_party/nix/doc/manual/expressions/builtins.xml
+++ /dev/null
@@ -1,1658 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      version="5.0"
-      xml:id='ssec-builtins'>
-
-<title>Built-in Functions</title>
-
-<para>This section lists the functions and constants built into the
-Nix expression evaluator.  (The built-in function
-<function>derivation</function> is discussed above.)  Some built-ins,
-such as <function>derivation</function>, are always in scope of every
-Nix expression; you can just access them right away.  But to prevent
-polluting the namespace too much, most built-ins are not in scope.
-Instead, you can access them through the <varname>builtins</varname>
-built-in value, which is a set that contains all built-in functions
-and values.  For instance, <function>derivation</function> is also
-available as <function>builtins.derivation</function>.</para>
-
-
-<variablelist>
-
-
-  <varlistentry xml:id='builtin-abort'>
-    <term><function>abort</function> <replaceable>s</replaceable></term>
-    <term><function>builtins.abort</function> <replaceable>s</replaceable></term>
-
-    <listitem><para>Abort Nix expression evaluation, print error
-    message <replaceable>s</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-add'>
-    <term><function>builtins.add</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable>
-    </term>
-
-    <listitem><para>Return the sum of the numbers
-    <replaceable>e1</replaceable> and
-    <replaceable>e2</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-all'>
-    <term><function>builtins.all</function>
-    <replaceable>pred</replaceable> <replaceable>list</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if the function
-    <replaceable>pred</replaceable> returns <literal>true</literal>
-    for all elements of <replaceable>list</replaceable>,
-    and <literal>false</literal> otherwise.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-any'>
-    <term><function>builtins.any</function>
-    <replaceable>pred</replaceable> <replaceable>list</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if the function
-    <replaceable>pred</replaceable> returns <literal>true</literal>
-    for at least one element of <replaceable>list</replaceable>,
-    and <literal>false</literal> otherwise.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-attrNames'>
-    <term><function>builtins.attrNames</function>
-    <replaceable>set</replaceable></term>
-
-    <listitem><para>Return the names of the attributes in the set
-    <replaceable>set</replaceable> in an alphabetically sorted list.  For instance,
-    <literal>builtins.attrNames { y = 1; x = "foo"; }</literal>
-    evaluates to <literal>[ "x" "y" ]</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-attrValues'>
-    <term><function>builtins.attrValues</function>
-    <replaceable>set</replaceable></term>
-
-    <listitem><para>Return the values of the attributes in the set
-    <replaceable>set</replaceable> in the order corresponding to the
-    sorted attribute names.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-baseNameOf'>
-    <term><function>baseNameOf</function> <replaceable>s</replaceable></term>
-
-    <listitem><para>Return the <emphasis>base name</emphasis> of the
-    string <replaceable>s</replaceable>, that is, everything following
-    the final slash in the string.  This is similar to the GNU
-    <command>basename</command> command.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-bitAnd'>
-    <term><function>builtins.bitAnd</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem><para>Return the bitwise AND of the integers
-    <replaceable>e1</replaceable> and
-    <replaceable>e2</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-bitOr'>
-    <term><function>builtins.bitOr</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem><para>Return the bitwise OR of the integers
-    <replaceable>e1</replaceable> and
-    <replaceable>e2</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-bitXor'>
-    <term><function>builtins.bitXor</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem><para>Return the bitwise XOR of the integers
-    <replaceable>e1</replaceable> and
-    <replaceable>e2</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-builtins'>
-    <term><varname>builtins</varname></term>
-
-    <listitem><para>The set <varname>builtins</varname> contains all
-    the built-in functions and values.  You can use
-    <varname>builtins</varname> to test for the availability of
-    features in the Nix installation, e.g.,
-
-<programlisting>
-if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
-
-    This allows a Nix expression to fall back gracefully on older Nix
-    installations that don’t have the desired built-in
-    function.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-compareVersions'>
-    <term><function>builtins.compareVersions</function>
-    <replaceable>s1</replaceable> <replaceable>s2</replaceable></term>
-
-    <listitem><para>Compare two strings representing versions and
-    return <literal>-1</literal> if version
-    <replaceable>s1</replaceable> is older than version
-    <replaceable>s2</replaceable>, <literal>0</literal> if they are
-    the same, and <literal>1</literal> if
-    <replaceable>s1</replaceable> is newer than
-    <replaceable>s2</replaceable>.  The version comparison algorithm
-    is the same as the one used by <link
-    linkend="ssec-version-comparisons"><command>nix-env
-    -u</command></link>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-concatLists'>
-    <term><function>builtins.concatLists</function>
-    <replaceable>lists</replaceable></term>
-
-    <listitem><para>Concatenate a list of lists into a single
-    list.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-concatStringsSep'>
-    <term><function>builtins.concatStringsSep</function>
-    <replaceable>separator</replaceable> <replaceable>list</replaceable></term>
-
-    <listitem><para>Concatenate a list of strings with a separator
-    between each element, e.g. <literal>concatStringsSep "/"
-    ["usr" "local" "bin"] == "usr/local/bin"</literal></para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-currentSystem'>
-    <term><varname>builtins.currentSystem</varname></term>
-
-    <listitem><para>The built-in value <varname>currentSystem</varname>
-    evaluates to the Nix platform identifier for the Nix installation
-    on which the expression is being evaluated, such as
-    <literal>"i686-linux"</literal> or
-    <literal>"x86_64-darwin"</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <!--
-  <varlistentry><term><function>currentTime</function></term>
-
-    <listitem><para>The built-in value <varname>currentTime</varname>
-    returns the current system time in seconds since 00:00:00 1/1/1970
-    UTC.  Due to the evaluation model of Nix expressions
-    (<emphasis>maximal laziness</emphasis>), it always yields the same
-    value within an execution of Nix.</para></listitem>
-
-  </varlistentry>
-  -->
-
-
-  <!--
-  <varlistentry><term><function>dependencyClosure</function></term>
-
-    <listitem><para>TODO</para></listitem>
-
-  </varlistentry>
-  -->
-
-
-  <varlistentry xml:id='builtin-deepSeq'>
-    <term><function>builtins.deepSeq</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem><para>This is like <literal>seq
-    <replaceable>e1</replaceable>
-    <replaceable>e2</replaceable></literal>, except that
-    <replaceable>e1</replaceable> is evaluated
-    <emphasis>deeply</emphasis>: if it’s a list or set, its elements
-    or attributes are also evaluated recursively.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-derivation'>
-    <term><function>derivation</function>
-    <replaceable>attrs</replaceable></term>
-    <term><function>builtins.derivation</function>
-    <replaceable>attrs</replaceable></term>
-
-    <listitem><para><function>derivation</function> is described in
-    <xref linkend='ssec-derivation' />.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-dirOf'>
-    <term><function>dirOf</function> <replaceable>s</replaceable></term>
-    <term><function>builtins.dirOf</function> <replaceable>s</replaceable></term>
-
-    <listitem><para>Return the directory part of the string
-    <replaceable>s</replaceable>, that is, everything before the final
-    slash in the string.  This is similar to the GNU
-    <command>dirname</command> command.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-div'>
-    <term><function>builtins.div</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem><para>Return the quotient of the numbers
-    <replaceable>e1</replaceable> and
-    <replaceable>e2</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-elem'>
-    <term><function>builtins.elem</function>
-    <replaceable>x</replaceable> <replaceable>xs</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if a value equal to
-    <replaceable>x</replaceable> occurs in the list
-    <replaceable>xs</replaceable>, and <literal>false</literal>
-    otherwise.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-elemAt'>
-    <term><function>builtins.elemAt</function>
-    <replaceable>xs</replaceable> <replaceable>n</replaceable></term>
-
-    <listitem><para>Return element <replaceable>n</replaceable> from
-    the list <replaceable>xs</replaceable>.  Elements are counted
-    starting from 0.  A fatal error occurs if the index is out of
-    bounds.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-fetchurl'>
-    <term><function>builtins.fetchurl</function>
-    <replaceable>url</replaceable></term>
-
-    <listitem><para>Download the specified URL and return the path of
-    the downloaded file. This function is not available if <link
-    linkend="conf-restrict-eval">restricted evaluation mode</link> is
-    enabled.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-fetchTarball'>
-    <term><function>fetchTarball</function>
-    <replaceable>url</replaceable></term>
-    <term><function>builtins.fetchTarball</function>
-    <replaceable>url</replaceable></term>
-
-    <listitem><para>Download the specified URL, unpack it and return
-    the path of the unpacked tree. The file must be a tape archive
-    (<filename>.tar</filename>) compressed with
-    <literal>gzip</literal>, <literal>bzip2</literal> or
-    <literal>xz</literal>. The top-level path component of the files
-    in the tarball is removed, so it is best if the tarball contains a
-    single directory at top level. The typical use of the function is
-    to obtain external Nix expression dependencies, such as a
-    particular version of Nixpkgs, e.g.
-
-<programlisting>
-with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {};
-
-stdenv.mkDerivation { … }
-</programlisting>
-    </para>
-
-    <para>The fetched tarball is cached for a certain amount of time
-    (1 hour by default) in <filename>~/.cache/nix/tarballs/</filename>.
-    You can change the cache timeout either on the command line with
-    <option>--option tarball-ttl <replaceable>number of seconds</replaceable></option> or
-    in the Nix configuration file with this option:
-    <literal><xref linkend="conf-tarball-ttl" /> <replaceable>number of seconds to cache</replaceable></literal>.
-    </para>
-
-    <para>Note that when obtaining the hash with <varname>nix-prefetch-url
-    </varname> the option <varname>--unpack</varname> is required.
-    </para>
-
-    <para>This function can also verify the contents against a hash.
-    In that case, the function takes a set instead of a URL. The set
-    requires the attribute <varname>url</varname> and the attribute
-    <varname>sha256</varname>, e.g.
-
-<programlisting>
-with import (fetchTarball {
-  url = https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz;
-  sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2";
-}) {};
-
-stdenv.mkDerivation { … }
-</programlisting>
-
-    </para>
-
-    <para>This function is not available if <link
-    linkend="conf-restrict-eval">restricted evaluation mode</link> is
-    enabled.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-fetchGit'>
-    <term>
-      <function>builtins.fetchGit</function>
-      <replaceable>args</replaceable>
-    </term>
-
-    <listitem>
-      <para>
-        Fetch a path from git. <replaceable>args</replaceable> can be
-        a URL, in which case the HEAD of the repo at that URL is
-        fetched. Otherwise, it can be an attribute with the following
-        attributes (all except <varname>url</varname> optional):
-      </para>
-
-      <variablelist>
-        <varlistentry>
-          <term>url</term>
-          <listitem>
-            <para>
-              The URL of the repo.
-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term>name</term>
-          <listitem>
-            <para>
-              The name of the directory the repo should be exported to
-              in the store. Defaults to the basename of the URL.
-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term>rev</term>
-          <listitem>
-            <para>
-              The git revision to fetch. Defaults to the tip of
-              <varname>ref</varname>.
-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term>ref</term>
-          <listitem>
-            <para>
-              The git ref to look for the requested revision under.
-              This is often a branch or tag name. Defaults to
-              <literal>HEAD</literal>.
-            </para>
-
-            <para>
-              By default, the <varname>ref</varname> value is prefixed
-              with <literal>refs/heads/</literal>. As of Nix 2.3.0
-              Nix will not prefix <literal>refs/heads/</literal> if
-              <varname>ref</varname> starts with <literal>refs/</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-      </variablelist>
-
-      <example>
-        <title>Fetching a private repository over SSH</title>
-        <programlisting>builtins.fetchGit {
-  url = "git@github.com:my-secret/repository.git";
-  ref = "master";
-  rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
-}</programlisting>
-      </example>
-
-      <example>
-        <title>Fetching an arbitrary ref</title>
-        <programlisting>builtins.fetchGit {
-  url = "https://github.com/NixOS/nix.git";
-  ref = "refs/heads/0.5-release";
-}</programlisting>
-      </example>
-
-      <example>
-        <title>Fetching a repository's specific commit on an arbitrary branch</title>
-        <para>
-          If the revision you're looking for is in the default branch
-          of the git repository you don't strictly need to specify
-          the branch name in the <varname>ref</varname> attribute.
-        </para>
-        <para>
-          However, if the revision you're looking for is in a future
-          branch for the non-default branch you will need to specify
-          the the <varname>ref</varname> attribute as well.
-        </para>
-        <programlisting>builtins.fetchGit {
-  url = "https://github.com/nixos/nix.git";
-  rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
-  ref = "1.11-maintenance";
-}</programlisting>
-        <note>
-          <para>
-            It is nice to always specify the branch which a revision
-            belongs to. Without the branch being specified, the
-            fetcher might fail if the default branch changes.
-            Additionally, it can be confusing to try a commit from a
-            non-default branch and see the fetch fail. If the branch
-            is specified the fault is much more obvious.
-          </para>
-        </note>
-      </example>
-
-      <example>
-        <title>Fetching a repository's specific commit on the default branch</title>
-        <para>
-          If the revision you're looking for is in the default branch
-          of the git repository you may omit the
-          <varname>ref</varname> attribute.
-        </para>
-        <programlisting>builtins.fetchGit {
-  url = "https://github.com/nixos/nix.git";
-  rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
-}</programlisting>
-      </example>
-
-      <example>
-        <title>Fetching a tag</title>
-        <programlisting>builtins.fetchGit {
-  url = "https://github.com/nixos/nix.git";
-  ref = "refs/tags/1.9";
-}</programlisting>
-      </example>
-
-      <example>
-        <title>Fetching the latest version of a remote branch</title>
-        <para>
-          <function>builtins.fetchGit</function> can behave impurely
-           fetch the latest version of a remote branch.
-        </para>
-        <note><para>Nix will refetch the branch in accordance to
-        <xref linkend="conf-tarball-ttl" />.</para></note>
-        <note><para>This behavior is disabled in
-        <emphasis>Pure evaluation mode</emphasis>.</para></note>
-        <programlisting>builtins.fetchGit {
-  url = "ssh://git@github.com/nixos/nix.git";
-  ref = "master";
-}</programlisting>
-      </example>
-    </listitem>
-  </varlistentry>
-
-
-  <varlistentry><term><function>builtins.filter</function>
-  <replaceable>f</replaceable> <replaceable>xs</replaceable></term>
-
-    <listitem><para>Return a list consisting of the elements of
-    <replaceable>xs</replaceable> for which the function
-    <replaceable>f</replaceable> returns
-    <literal>true</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-filterSource'>
-    <term><function>builtins.filterSource</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem>
-
-      <para>This function allows you to copy sources into the Nix
-      store while filtering certain files.  For instance, suppose that
-      you want to use the directory <filename>source-dir</filename> as
-      an input to a Nix expression, e.g.
-
-<programlisting>
-stdenv.mkDerivation {
-  ...
-  src = ./source-dir;
-}
-</programlisting>
-
-      However, if <filename>source-dir</filename> is a Subversion
-      working copy, then all those annoying <filename>.svn</filename>
-      subdirectories will also be copied to the store.  Worse, the
-      contents of those directories may change a lot, causing lots of
-      spurious rebuilds.  With <function>filterSource</function> you
-      can filter out the <filename>.svn</filename> directories:
-
-<programlisting>
-  src = builtins.filterSource
-    (path: type: type != "directory" || baseNameOf path != ".svn")
-    ./source-dir;
-</programlisting>
-
-      </para>
-
-      <para>Thus, the first argument <replaceable>e1</replaceable>
-      must be a predicate function that is called for each regular
-      file, directory or symlink in the source tree
-      <replaceable>e2</replaceable>.  If the function returns
-      <literal>true</literal>, the file is copied to the Nix store,
-      otherwise it is omitted.  The function is called with two
-      arguments.  The first is the full path of the file.  The second
-      is a string that identifies the type of the file, which is
-      either <literal>"regular"</literal>,
-      <literal>"directory"</literal>, <literal>"symlink"</literal> or
-      <literal>"unknown"</literal> (for other kinds of files such as
-      device nodes or fifos — but note that those cannot be copied to
-      the Nix store, so if the predicate returns
-      <literal>true</literal> for them, the copy will fail). If you
-      exclude a directory, the entire corresponding subtree of
-      <replaceable>e2</replaceable> will be excluded.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-foldl-prime'>
-    <term><function>builtins.foldl’</function>
-    <replaceable>op</replaceable> <replaceable>nul</replaceable> <replaceable>list</replaceable></term>
-
-    <listitem><para>Reduce a list by applying a binary operator, from
-    left to right, e.g. <literal>foldl’ op nul [x0 x1 x2 ...] = op (op
-    (op nul x0) x1) x2) ...</literal>. The operator is applied
-    strictly, i.e., its arguments are evaluated first. For example,
-    <literal>foldl’ (x: y: x + y) 0 [1 2 3]</literal> evaluates to
-    6.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-functionArgs'>
-    <term><function>builtins.functionArgs</function>
-    <replaceable>f</replaceable></term>
-
-    <listitem><para>
-    Return a set containing the names of the formal arguments expected
-    by the function <replaceable>f</replaceable>.
-    The value of each attribute is a Boolean denoting whether the corresponding
-    argument has a default value.  For instance,
-    <literal>functionArgs ({ x, y ? 123}: ...)  =  { x = false; y = true; }</literal>.
-    </para>
-
-    <para>"Formal argument" here refers to the attributes pattern-matched by
-    the function.  Plain lambdas are not included, e.g.
-    <literal>functionArgs (x: ...)  =  { }</literal>.
-    </para></listitem>
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-fromJSON'>
-    <term><function>builtins.fromJSON</function> <replaceable>e</replaceable></term>
-
-    <listitem><para>Convert a JSON string to a Nix
-    value. For example,
-
-<programlisting>
-builtins.fromJSON ''{"x": [1, 2, 3], "y": null}''
-</programlisting>
-
-    returns the value <literal>{ x = [ 1 2 3 ]; y = null;
-    }</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-genList'>
-    <term><function>builtins.genList</function>
-    <replaceable>generator</replaceable> <replaceable>length</replaceable></term>
-
-    <listitem><para>Generate list of size
-    <replaceable>length</replaceable>, with each element
-    <replaceable>i</replaceable> equal to the value returned by
-    <replaceable>generator</replaceable> <literal>i</literal>. For
-    example,
-
-<programlisting>
-builtins.genList (x: x * x) 5
-</programlisting>
-
-    returns the list <literal>[ 0 1 4 9 16 ]</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-getAttr'>
-    <term><function>builtins.getAttr</function>
-    <replaceable>s</replaceable> <replaceable>set</replaceable></term>
-
-    <listitem><para><function>getAttr</function> returns the attribute
-    named <replaceable>s</replaceable> from
-    <replaceable>set</replaceable>.  Evaluation aborts if the
-    attribute doesn’t exist.  This is a dynamic version of the
-    <literal>.</literal> operator, since <replaceable>s</replaceable>
-    is an expression rather than an identifier.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-getEnv'>
-    <term><function>builtins.getEnv</function>
-    <replaceable>s</replaceable></term>
-
-    <listitem><para><function>getEnv</function> returns the value of
-    the environment variable <replaceable>s</replaceable>, or an empty
-    string if the variable doesn’t exist.  This function should be
-    used with care, as it can introduce all sorts of nasty environment
-    dependencies in your Nix expression.</para>
-
-    <para><function>getEnv</function> is used in Nix Packages to
-    locate the file <filename>~/.nixpkgs/config.nix</filename>, which
-    contains user-local settings for Nix Packages.  (That is, it does
-    a <literal>getEnv "HOME"</literal> to locate the user’s home
-    directory.)</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-hasAttr'>
-    <term><function>builtins.hasAttr</function>
-    <replaceable>s</replaceable> <replaceable>set</replaceable></term>
-
-    <listitem><para><function>hasAttr</function> returns
-    <literal>true</literal> if <replaceable>set</replaceable> has an
-    attribute named <replaceable>s</replaceable>, and
-    <literal>false</literal> otherwise.  This is a dynamic version of
-    the <literal>?</literal>  operator, since
-    <replaceable>s</replaceable> is an expression rather than an
-    identifier.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-hashString'>
-    <term><function>builtins.hashString</function>
-    <replaceable>type</replaceable> <replaceable>s</replaceable></term>
-
-    <listitem><para>Return a base-16 representation of the
-    cryptographic hash of string <replaceable>s</replaceable>.  The
-    hash algorithm specified by <replaceable>type</replaceable> must
-    be one of <literal>"md5"</literal>, <literal>"sha1"</literal>,
-    <literal>"sha256"</literal> or <literal>"sha512"</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-hashFile'>
-    <term><function>builtins.hashFile</function>
-    <replaceable>type</replaceable> <replaceable>p</replaceable></term>
-
-    <listitem><para>Return a base-16 representation of the
-    cryptographic hash of the file at path <replaceable>p</replaceable>.  The
-    hash algorithm specified by <replaceable>type</replaceable> must
-    be one of <literal>"md5"</literal>, <literal>"sha1"</literal>,
-    <literal>"sha256"</literal> or <literal>"sha512"</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-head'>
-    <term><function>builtins.head</function>
-    <replaceable>list</replaceable></term>
-
-    <listitem><para>Return the first element of a list; abort
-    evaluation if the argument isn’t a list or is an empty list.  You
-    can test whether a list is empty by comparing it with
-    <literal>[]</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-import'>
-    <term><function>import</function>
-    <replaceable>path</replaceable></term>
-    <term><function>builtins.import</function>
-    <replaceable>path</replaceable></term>
-
-    <listitem><para>Load, parse and return the Nix expression in the
-    file <replaceable>path</replaceable>.  If <replaceable>path
-    </replaceable> is a directory, the file <filename>default.nix
-    </filename> in that directory is loaded.  Evaluation aborts if the
-    file doesn’t exist or contains an incorrect Nix expression.
-    <function>import</function> implements Nix’s module system: you
-    can put any Nix expression (such as a set or a function) in a
-    separate file, and use it from Nix expressions in other
-    files.</para>
-
-    <note><para>Unlike some languages, <function>import</function> is a regular
-    function in Nix. Paths using the angle bracket syntax (e.g., <function>
-    import</function> <replaceable>&lt;foo&gt;</replaceable>) are normal path
-    values (see <xref linkend='ssec-values' />).</para></note>
-
-    <para>A Nix expression loaded by <function>import</function> must
-    not contain any <emphasis>free variables</emphasis> (identifiers
-    that are not defined in the Nix expression itself and are not
-    built-in).  Therefore, it cannot refer to variables that are in
-    scope at the call site.  For instance, if you have a calling
-    expression
-
-<programlisting>
-rec {
-  x = 123;
-  y = import ./foo.nix;
-}</programlisting>
-
-    then the following <filename>foo.nix</filename> will give an
-    error:
-
-<programlisting>
-x + 456</programlisting>
-
-    since <varname>x</varname> is not in scope in
-    <filename>foo.nix</filename>.  If you want <varname>x</varname>
-    to be available in <filename>foo.nix</filename>, you should pass
-    it as a function argument:
-
-<programlisting>
-rec {
-  x = 123;
-  y = import ./foo.nix x;
-}</programlisting>
-
-    and
-
-<programlisting>
-x: x + 456</programlisting>
-
-    (The function argument doesn’t have to be called
-    <varname>x</varname> in <filename>foo.nix</filename>; any name
-    would work.)</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-intersectAttrs'>
-    <term><function>builtins.intersectAttrs</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem><para>Return a set consisting of the attributes in the
-    set <replaceable>e2</replaceable> that also exist in the set
-    <replaceable>e1</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-isAttrs'>
-    <term><function>builtins.isAttrs</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if
-    <replaceable>e</replaceable> evaluates to a set, and
-    <literal>false</literal> otherwise.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-isList'>
-    <term><function>builtins.isList</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if
-    <replaceable>e</replaceable> evaluates to a list, and
-    <literal>false</literal> otherwise.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-isFunction'><term><function>builtins.isFunction</function>
-  <replaceable>e</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if
-    <replaceable>e</replaceable> evaluates to a function, and
-    <literal>false</literal> otherwise.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-isString'>
-    <term><function>builtins.isString</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if
-    <replaceable>e</replaceable> evaluates to a string, and
-    <literal>false</literal> otherwise.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-isInt'>
-    <term><function>builtins.isInt</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if
-    <replaceable>e</replaceable> evaluates to an int, and
-    <literal>false</literal> otherwise.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-isFloat'>
-    <term><function>builtins.isFloat</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if
-    <replaceable>e</replaceable> evaluates to a float, and
-    <literal>false</literal> otherwise.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-isBool'>
-    <term><function>builtins.isBool</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if
-    <replaceable>e</replaceable> evaluates to a bool, and
-    <literal>false</literal> otherwise.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><function>builtins.isPath</function>
-  <replaceable>e</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if
-    <replaceable>e</replaceable> evaluates to a path, and
-    <literal>false</literal> otherwise.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-isNull'>
-    <term><function>isNull</function>
-    <replaceable>e</replaceable></term>
-    <term><function>builtins.isNull</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if
-    <replaceable>e</replaceable> evaluates to <literal>null</literal>,
-    and <literal>false</literal> otherwise.</para>
-
-    <warning><para>This function is <emphasis>deprecated</emphasis>;
-    just write <literal>e == null</literal> instead.</para></warning>
-
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-length'>
-    <term><function>builtins.length</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Return the length of the list
-    <replaceable>e</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-lessThan'>
-    <term><function>builtins.lessThan</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if the number
-    <replaceable>e1</replaceable> is less than the number
-    <replaceable>e2</replaceable>, and <literal>false</literal>
-    otherwise.  Evaluation aborts if either
-    <replaceable>e1</replaceable> or <replaceable>e2</replaceable>
-    does not evaluate to a number.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-listToAttrs'>
-    <term><function>builtins.listToAttrs</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Construct a set from a list specifying the names
-    and values of each attribute.  Each element of the list should be
-    a set consisting of a string-valued attribute
-    <varname>name</varname> specifying the name of the attribute, and
-    an attribute <varname>value</varname> specifying its value.
-    Example:
-
-<programlisting>
-builtins.listToAttrs
-  [ { name = "foo"; value = 123; }
-    { name = "bar"; value = 456; }
-  ]
-</programlisting>
-
-    evaluates to
-
-<programlisting>
-{ foo = 123; bar = 456; }
-</programlisting>
-
-    </para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-map'>
-    <term><function>map</function>
-    <replaceable>f</replaceable> <replaceable>list</replaceable></term>
-    <term><function>builtins.map</function>
-    <replaceable>f</replaceable> <replaceable>list</replaceable></term>
-
-    <listitem><para>Apply the function <replaceable>f</replaceable> to
-    each element in the list <replaceable>list</replaceable>.  For
-    example,
-
-<programlisting>
-map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting>
-
-    evaluates to <literal>[ "foobar" "foobla" "fooabc"
-    ]</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-match'>
-    <term><function>builtins.match</function>
-    <replaceable>regex</replaceable> <replaceable>str</replaceable></term>
-
-    <listitem><para>Returns a list if the <link
-    xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended
-    POSIX regular expression</link> <replaceable>regex</replaceable>
-    matches <replaceable>str</replaceable> precisely, otherwise returns
-    <literal>null</literal>.  Each item in the list is a regex group.
-
-<programlisting>
-builtins.match "ab" "abc"
-</programlisting>
-
-Evaluates to <literal>null</literal>.
-
-<programlisting>
-builtins.match "abc" "abc"
-</programlisting>
-
-Evaluates to <literal>[ ]</literal>.
-
-<programlisting>
-builtins.match "a(b)(c)" "abc"
-</programlisting>
-
-Evaluates to <literal>[ "b" "c" ]</literal>.
-
-<programlisting>
-builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" "  FOO   "
-</programlisting>
-
-Evaluates to <literal>[ "foo" ]</literal>.
-
-    </para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-mul'>
-    <term><function>builtins.mul</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem><para>Return the product of the numbers
-    <replaceable>e1</replaceable> and
-    <replaceable>e2</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-parseDrvName'>
-    <term><function>builtins.parseDrvName</function>
-    <replaceable>s</replaceable></term>
-
-    <listitem><para>Split the string <replaceable>s</replaceable> into
-    a package name and version.  The package name is everything up to
-    but not including the first dash followed by a digit, and the
-    version is everything following that dash.  The result is returned
-    in a set <literal>{ name, version }</literal>.  Thus,
-    <literal>builtins.parseDrvName "nix-0.12pre12876"</literal>
-    returns <literal>{ name = "nix"; version = "0.12pre12876";
-    }</literal>.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-path'>
-    <term>
-      <function>builtins.path</function>
-      <replaceable>args</replaceable>
-    </term>
-
-    <listitem>
-      <para>
-        An enrichment of the built-in path type, based on the attributes
-        present in <replaceable>args</replaceable>. All are optional
-        except <varname>path</varname>:
-      </para>
-
-      <variablelist>
-        <varlistentry>
-          <term>path</term>
-          <listitem>
-            <para>The underlying path.</para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term>name</term>
-          <listitem>
-            <para>
-              The name of the path when added to the store. This can
-              used to reference paths that have nix-illegal characters
-              in their names, like <literal>@</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term>filter</term>
-          <listitem>
-            <para>
-              A function of the type expected by
-              <link linkend="builtin-filterSource">builtins.filterSource</link>,
-              with the same semantics.
-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term>recursive</term>
-          <listitem>
-            <para>
-              When <literal>false</literal>, when
-              <varname>path</varname> is added to the store it is with a
-              flat hash, rather than a hash of the NAR serialization of
-              the file. Thus, <varname>path</varname> must refer to a
-              regular file, not a directory. This allows similar
-              behavior to <literal>fetchurl</literal>. Defaults to
-              <literal>true</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term>sha256</term>
-          <listitem>
-            <para>
-              When provided, this is the expected hash of the file at
-              the path. Evaluation will fail if the hash is incorrect,
-              and providing a hash allows
-              <literal>builtins.path</literal> to be used even when the
-              <literal>pure-eval</literal> nix config option is on.
-            </para>
-          </listitem>
-        </varlistentry>
-      </variablelist>
-    </listitem>
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-pathExists'>
-    <term><function>builtins.pathExists</function>
-    <replaceable>path</replaceable></term>
-
-    <listitem><para>Return <literal>true</literal> if the path
-    <replaceable>path</replaceable> exists at evaluation time, and
-    <literal>false</literal> otherwise.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-placeholder'>
-    <term><function>builtins.placeholder</function>
-    <replaceable>output</replaceable></term>
-
-    <listitem><para>Return a placeholder string for the specified
-    <replaceable>output</replaceable> that will be substituted by the
-    corresponding output path at build time. Typical outputs would be
-    <literal>"out"</literal>, <literal>"bin"</literal> or
-    <literal>"dev"</literal>.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-readDir'>
-    <term><function>builtins.readDir</function>
-    <replaceable>path</replaceable></term>
-
-    <listitem><para>Return the contents of the directory
-    <replaceable>path</replaceable> as a set mapping directory entries
-    to the corresponding file type. For instance, if directory
-    <filename>A</filename> contains a regular file
-    <filename>B</filename> and another directory
-    <filename>C</filename>, then <literal>builtins.readDir
-    ./A</literal> will return the set
-
-<programlisting>
-{ B = "regular"; C = "directory"; }</programlisting>
-
-    The possible values for the file type are
-    <literal>"regular"</literal>, <literal>"directory"</literal>,
-    <literal>"symlink"</literal> and
-    <literal>"unknown"</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-readFile'>
-    <term><function>builtins.readFile</function>
-    <replaceable>path</replaceable></term>
-
-    <listitem><para>Return the contents of the file
-    <replaceable>path</replaceable> as a string.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-removeAttrs'>
-    <term><function>removeAttrs</function>
-    <replaceable>set</replaceable> <replaceable>list</replaceable></term>
-    <term><function>builtins.removeAttrs</function>
-    <replaceable>set</replaceable> <replaceable>list</replaceable></term>
-
-    <listitem><para>Remove the attributes listed in
-    <replaceable>list</replaceable> from
-    <replaceable>set</replaceable>.  The attributes don’t have to
-    exist in <replaceable>set</replaceable>. For instance,
-
-<programlisting>
-removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</programlisting>
-
-    evaluates to <literal>{ y = 2; }</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-replaceStrings'>
-    <term><function>builtins.replaceStrings</function>
-    <replaceable>from</replaceable> <replaceable>to</replaceable> <replaceable>s</replaceable></term>
-
-    <listitem><para>Given string <replaceable>s</replaceable>, replace
-    every occurrence of the strings in <replaceable>from</replaceable>
-    with the corresponding string in
-    <replaceable>to</replaceable>. For example,
-
-<programlisting>
-builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar"
-</programlisting>
-
-    evaluates to <literal>"fabir"</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-seq'>
-    <term><function>builtins.seq</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem><para>Evaluate <replaceable>e1</replaceable>, then
-    evaluate and return <replaceable>e2</replaceable>. This ensures
-    that a computation is strict in the value of
-    <replaceable>e1</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-sort'>
-    <term><function>builtins.sort</function>
-    <replaceable>comparator</replaceable> <replaceable>list</replaceable></term>
-
-    <listitem><para>Return <replaceable>list</replaceable> in sorted
-    order. It repeatedly calls the function
-    <replaceable>comparator</replaceable> with two elements. The
-    comparator should return <literal>true</literal> if the first
-    element is less than the second, and <literal>false</literal>
-    otherwise. For example,
-
-<programlisting>
-builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ]
-</programlisting>
-
-    produces the list <literal>[ 42 77 147 249 483 526
-    ]</literal>.</para>
-
-    <para>This is a stable sort: it preserves the relative order of
-    elements deemed equal by the comparator.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-split'>
-    <term><function>builtins.split</function>
-    <replaceable>regex</replaceable> <replaceable>str</replaceable></term>
-
-    <listitem><para>Returns a list composed of non matched strings interleaved
-    with the lists of the <link
-    xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended
-    POSIX regular expression</link> <replaceable>regex</replaceable> matches
-    of <replaceable>str</replaceable>. Each item in the lists of matched
-    sequences is a regex group.
-
-<programlisting>
-builtins.split "(a)b" "abc"
-</programlisting>
-
-Evaluates to <literal>[ "" [ "a" ] "c" ]</literal>.
-
-<programlisting>
-builtins.split "([ac])" "abc"
-</programlisting>
-
-Evaluates to <literal>[ "" [ "a" ] "b" [ "c" ] "" ]</literal>.
-
-<programlisting>
-builtins.split "(a)|(c)" "abc"
-</programlisting>
-
-Evaluates to <literal>[ "" [ "a" null ] "b" [ null "c" ] "" ]</literal>.
-
-<programlisting>
-builtins.split "([[:upper:]]+)" "  FOO   "
-</programlisting>
-
-Evaluates to <literal>[ "  " [ "FOO" ] "   " ]</literal>.
-
-    </para></listitem>
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-splitVersion'>
-    <term><function>builtins.splitVersion</function>
-    <replaceable>s</replaceable></term>
-
-    <listitem><para>Split a string representing a version into its
-    components, by the same version splitting logic underlying the
-    version comparison in <link linkend="ssec-version-comparisons">
-    <command>nix-env -u</command></link>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-stringLength'>
-    <term><function>builtins.stringLength</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Return the length of the string
-    <replaceable>e</replaceable>.  If <replaceable>e</replaceable> is
-    not a string, evaluation is aborted.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-sub'>
-    <term><function>builtins.sub</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem><para>Return the difference between the numbers
-    <replaceable>e1</replaceable> and
-    <replaceable>e2</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-substring'>
-    <term><function>builtins.substring</function>
-    <replaceable>start</replaceable> <replaceable>len</replaceable>
-    <replaceable>s</replaceable></term>
-
-    <listitem><para>Return the substring of
-    <replaceable>s</replaceable> from character position
-    <replaceable>start</replaceable> (zero-based) up to but not
-    including <replaceable>start + len</replaceable>.  If
-    <replaceable>start</replaceable> is greater than the length of the
-    string, an empty string is returned, and if <replaceable>start +
-    len</replaceable> lies beyond the end of the string, only the
-    substring up to the end of the string is returned.
-    <replaceable>start</replaceable> must be
-    non-negative. For example,
-
-<programlisting>
-builtins.substring 0 3 "nixos"
-</programlisting>
-
-   evaluates to <literal>"nix"</literal>.
-   </para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-tail'>
-    <term><function>builtins.tail</function>
-    <replaceable>list</replaceable></term>
-
-    <listitem><para>Return the second to last elements of a list;
-    abort evaluation if the argument isn’t a list or is an empty
-    list.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-throw'>
-    <term><function>throw</function>
-    <replaceable>s</replaceable></term>
-    <term><function>builtins.throw</function>
-    <replaceable>s</replaceable></term>
-
-    <listitem><para>Throw an error message
-    <replaceable>s</replaceable>.  This usually aborts Nix expression
-    evaluation, but in <command>nix-env -qa</command> and other
-    commands that try to evaluate a set of derivations to get
-    information about those derivations, a derivation that throws an
-    error is silently skipped (which is not the case for
-    <function>abort</function>).</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-toFile'>
-    <term><function>builtins.toFile</function>
-    <replaceable>name</replaceable>
-    <replaceable>s</replaceable></term>
-
-    <listitem><para>Store the string <replaceable>s</replaceable> in a
-    file in the Nix store and return its path.  The file has suffix
-    <replaceable>name</replaceable>.  This file can be used as an
-    input to derivations.  One application is to write builders
-    “inline”.  For instance, the following Nix expression combines
-    <xref linkend='ex-hello-nix' /> and <xref
-    linkend='ex-hello-builder' /> into one file:
-
-<programlisting>
-{ stdenv, fetchurl, perl }:
-
-stdenv.mkDerivation {
-  name = "hello-2.1.1";
-
-  builder = builtins.toFile "builder.sh" "
-    source $stdenv/setup
-
-    PATH=$perl/bin:$PATH
-
-    tar xvfz $src
-    cd hello-*
-    ./configure --prefix=$out
-    make
-    make install
-  ";
-
-  src = fetchurl {
-    url = http://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
-    sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
-  };
-  inherit perl;
-}</programlisting>
-
-    </para>
-
-    <para>It is even possible for one file to refer to another, e.g.,
-
-<programlisting>
-  builder = let
-    configFile = builtins.toFile "foo.conf" "
-      # This is some dummy configuration file.
-      <replaceable>...</replaceable>
-    ";
-  in builtins.toFile "builder.sh" "
-    source $stdenv/setup
-    <replaceable>...</replaceable>
-    cp ${configFile} $out/etc/foo.conf
-  ";</programlisting>
-
-    Note that <literal>${configFile}</literal> is an antiquotation
-    (see <xref linkend='ssec-values' />), so the result of the
-    expression <literal>configFile</literal> (i.e., a path like
-    <filename>/nix/store/m7p7jfny445k...-foo.conf</filename>) will be
-    spliced into the resulting string.</para>
-
-    <para>It is however <emphasis>not</emphasis> allowed to have files
-    mutually referring to each other, like so:
-
-<programlisting>
-let
-  foo = builtins.toFile "foo" "...${bar}...";
-  bar = builtins.toFile "bar" "...${foo}...";
-in foo</programlisting>
-
-    This is not allowed because it would cause a cyclic dependency in
-    the computation of the cryptographic hashes for
-    <varname>foo</varname> and <varname>bar</varname>.</para>
-    <para>It is also not possible to reference the result of a derivation.
-    If you are using Nixpkgs, the <literal>writeTextFile</literal> function is able to
-    do that.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-toJSON'>
-    <term><function>builtins.toJSON</function> <replaceable>e</replaceable></term>
-
-    <listitem><para>Return a string containing a JSON representation
-    of <replaceable>e</replaceable>.  Strings, integers, floats, booleans,
-    nulls and lists are mapped to their JSON equivalents.  Sets
-    (except derivations) are represented as objects.  Derivations are
-    translated to a JSON string containing the derivation’s output
-    path.  Paths are copied to the store and represented as a JSON
-    string of the resulting store path.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-toPath'>
-    <term><function>builtins.toPath</function> <replaceable>s</replaceable></term>
-
-    <listitem><para> DEPRECATED. Use <literal>/. + "/path"</literal>
-    to convert a string into an absolute path. For relative paths,
-    use <literal>./. + "/path"</literal>.
-    </para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-toString'>
-    <term><function>toString</function> <replaceable>e</replaceable></term>
-    <term><function>builtins.toString</function> <replaceable>e</replaceable></term>
-
-    <listitem><para>Convert the expression
-    <replaceable>e</replaceable> to a string.
-    <replaceable>e</replaceable> can be:</para>
-    <itemizedlist>
-      <listitem><para>A string (in which case the string is returned unmodified).</para></listitem>
-      <listitem><para>A path (e.g., <literal>toString /foo/bar</literal> yields <literal>"/foo/bar"</literal>.</para></listitem>
-      <listitem><para>A set containing <literal>{ __toString = self: ...; }</literal>.</para></listitem>
-      <listitem><para>An integer.</para></listitem>
-      <listitem><para>A list, in which case the string representations of its elements are joined with spaces.</para></listitem>
-      <listitem><para>A Boolean (<literal>false</literal> yields <literal>""</literal>, <literal>true</literal> yields <literal>"1"</literal>).</para></listitem>
-      <listitem><para><literal>null</literal>, which yields the empty string.</para></listitem>
-    </itemizedlist>
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-toXML'>
-    <term><function>builtins.toXML</function> <replaceable>e</replaceable></term>
-
-    <listitem><para>Return a string containing an XML representation
-    of <replaceable>e</replaceable>.  The main application for
-    <function>toXML</function> is to communicate information with the
-    builder in a more structured format than plain environment
-    variables.</para>
-
-    <!-- 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>
-
-<programlisting><![CDATA[
-{ stdenv, fetchurl, libxslt, jira, uberwiki }:
-
-stdenv.mkDerivation (rec {
-  name = "web-server";
-
-  buildInputs = [ libxslt ];
-
-  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[
-  ";
-
-  stylesheet = builtins.toFile "stylesheet.xsl"]]> <co xml:id='ex-toxml-co-stylesheet' /> <![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='/'>
-        <Configure>
-          <xsl:for-each select='/expr/list/attrs'>
-            <Call name='addWebApplication'>
-              <Arg><xsl:value-of select=\"attr[@name = 'path']/string/@value\" /></Arg>
-              <Arg><xsl:value-of select=\"attr[@name = 'war']/path/@value\" /></Arg>
-            </Call>
-          </xsl:for-each>
-        </Configure>
-      </xsl:template>
-    </xsl:stylesheet>
-  ";
-
-  servlets = builtins.toXML []]> <co xml:id='ex-toxml-co-servlets' /> <![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>
-
-<programlisting><![CDATA[<?xml version='1.0' encoding='utf-8'?>
-<expr>
-  <list>
-    <attrs>
-      <attr name="path">
-        <string value="/bugtracker" />
-      </attr>
-      <attr name="war">
-        <path value="/nix/store/d1jh9pasa7k2...-jira/lib/atlassian-jira.war" />
-      </attr>
-    </attrs>
-    <attrs>
-      <attr name="path">
-        <string value="/wiki" />
-      </attr>
-      <attr name="war">
-        <path value="/nix/store/y6423b1yi4sx...-uberwiki/uberwiki.war" />
-      </attr>
-    </attrs>
-  </list>
-</expr>]]></programlisting>
-
-    </example>
-
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-trace'>
-    <term><function>builtins.trace</function>
-    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
-
-    <listitem><para>Evaluate <replaceable>e1</replaceable> and print its
-    abstract syntax representation on standard error.  Then return
-    <replaceable>e2</replaceable>.  This function is useful for
-    debugging.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id='builtin-tryEval'>
-    <term><function>builtins.tryEval</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Try to shallowly evaluate <replaceable>e</replaceable>.
-    Return a set containing the attributes <literal>success</literal>
-    (<literal>true</literal> if <replaceable>e</replaceable> evaluated
-    successfully, <literal>false</literal> if an error was thrown) and
-    <literal>value</literal>, equalling <replaceable>e</replaceable>
-    if successful and <literal>false</literal> otherwise. Note that this
-    doesn't evaluate <replaceable>e</replaceable> deeply, so
-    <literal>let e = { x = throw ""; }; in (builtins.tryEval e).success
-    </literal> will be <literal>true</literal>. Using <literal>builtins.deepSeq
-    </literal> one can get the expected result: <literal>let e = { x = throw "";
-    }; in (builtins.tryEval (builtins.deepSeq e e)).success</literal> will be
-    <literal>false</literal>.
-    </para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id='builtin-typeOf'>
-    <term><function>builtins.typeOf</function>
-    <replaceable>e</replaceable></term>
-
-    <listitem><para>Return a string representing the type of the value
-    <replaceable>e</replaceable>, namely <literal>"int"</literal>,
-    <literal>"bool"</literal>, <literal>"string"</literal>,
-    <literal>"path"</literal>, <literal>"null"</literal>,
-    <literal>"set"</literal>, <literal>"list"</literal>,
-    <literal>"lambda"</literal> or
-    <literal>"float"</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-</variablelist>
-
-
-</section>