2007-10-22 14:58:28 +02:00
|
|
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
2014-08-27 18:41:09 +02:00
|
|
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
|
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
|
|
|
version="5.0"
|
|
|
|
|
xml:id='ssec-builtins'>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2014-08-27 18:41:09 +02:00
|
|
|
|
<title>Built-in Functions</title>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
2013-10-24 16:41:04 +02:00
|
|
|
|
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>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
|
2007-11-01 14:28:33 +01:00
|
|
|
|
<variablelist>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-abort'>
|
|
|
|
|
<term><function>abort</function> <replaceable>s</replaceable></term>
|
2019-03-21 09:35:43 +01:00
|
|
|
|
<term><function>builtins.abort</function> <replaceable>s</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Abort Nix expression evaluation, print error
|
|
|
|
|
message <replaceable>s</replaceable>.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-add'>
|
|
|
|
|
<term><function>builtins.add</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable>
|
|
|
|
|
</term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2016-01-06 08:41:53 +01:00
|
|
|
|
<listitem><para>Return the sum of the numbers
|
2007-10-22 14:58:28 +02:00
|
|
|
|
<replaceable>e1</replaceable> and
|
|
|
|
|
<replaceable>e2</replaceable>.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-all'>
|
|
|
|
|
<term><function>builtins.all</function>
|
|
|
|
|
<replaceable>pred</replaceable> <replaceable>list</replaceable></term>
|
2015-07-23 19:23:11 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-any'>
|
|
|
|
|
<term><function>builtins.any</function>
|
|
|
|
|
<replaceable>pred</replaceable> <replaceable>list</replaceable></term>
|
2015-07-23 19:23:11 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-attrNames'>
|
|
|
|
|
<term><function>builtins.attrNames</function>
|
|
|
|
|
<replaceable>set</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2013-10-24 16:41:04 +02:00
|
|
|
|
<listitem><para>Return the names of the attributes in the set
|
2017-05-10 18:38:17 +02:00
|
|
|
|
<replaceable>set</replaceable> in an alphabetically sorted list. For instance,
|
2013-10-24 16:41:04 +02:00
|
|
|
|
<literal>builtins.attrNames { y = 1; x = "foo"; }</literal>
|
2014-10-29 16:18:03 +01:00
|
|
|
|
evaluates to <literal>[ "x" "y" ]</literal>.</para></listitem>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2014-10-29 16:18:03 +01:00
|
|
|
|
</varlistentry>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2014-10-29 16:18:03 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-attrValues'>
|
|
|
|
|
<term><function>builtins.attrValues</function>
|
|
|
|
|
<replaceable>set</replaceable></term>
|
2014-10-29 16:18:03 +01:00
|
|
|
|
|
|
|
|
|
<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>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-baseNameOf'>
|
|
|
|
|
<term><function>baseNameOf</function> <replaceable>s</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-bitAnd'>
|
|
|
|
|
<term><function>builtins.bitAnd</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2018-05-24 14:48:48 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return the bitwise AND of the integers
|
|
|
|
|
<replaceable>e1</replaceable> and
|
|
|
|
|
<replaceable>e2</replaceable>.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-bitOr'>
|
|
|
|
|
<term><function>builtins.bitOr</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2018-05-24 14:48:48 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return the bitwise OR of the integers
|
|
|
|
|
<replaceable>e1</replaceable> and
|
|
|
|
|
<replaceable>e2</replaceable>.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-bitXor'>
|
|
|
|
|
<term><function>builtins.bitXor</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2018-05-24 14:48:48 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return the bitwise XOR of the integers
|
|
|
|
|
<replaceable>e1</replaceable> and
|
|
|
|
|
<replaceable>e2</replaceable>.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-builtins'>
|
|
|
|
|
<term><varname>builtins</varname></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2013-10-24 16:41:04 +02:00
|
|
|
|
<listitem><para>The set <varname>builtins</varname> contains all
|
|
|
|
|
the built-in functions and values. You can use
|
2007-10-22 14:58:28 +02:00
|
|
|
|
<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
|
2009-04-14 15:03:27 +02:00
|
|
|
|
installations that don’t have the desired built-in
|
|
|
|
|
function.</para></listitem>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-compareVersions'>
|
|
|
|
|
<term><function>builtins.compareVersions</function>
|
|
|
|
|
<replaceable>s1</replaceable> <replaceable>s2</replaceable></term>
|
2008-11-19 18:27:52 +01:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-concatLists'>
|
|
|
|
|
<term><function>builtins.concatLists</function>
|
|
|
|
|
<replaceable>lists</replaceable></term>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
|
|
|
|
<listitem><para>Concatenate a list of lists into a single
|
|
|
|
|
list.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-concatStringsSep'>
|
|
|
|
|
<term><function>builtins.concatStringsSep</function>
|
|
|
|
|
<replaceable>separator</replaceable> <replaceable>list</replaceable></term>
|
2017-12-11 07:20:17 +01:00
|
|
|
|
|
|
|
|
|
<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>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-currentSystem'>
|
|
|
|
|
<term><varname>builtins.currentSystem</varname></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<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
|
2016-08-10 18:41:51 +02:00
|
|
|
|
<literal>"x86_64-darwin"</literal>.</para></listitem>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</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>
|
|
|
|
|
-->
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2007-10-22 14:58:28 +02:00
|
|
|
|
<!--
|
|
|
|
|
<varlistentry><term><function>dependencyClosure</function></term>
|
|
|
|
|
|
|
|
|
|
<listitem><para>TODO</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
-->
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-deepSeq'>
|
|
|
|
|
<term><function>builtins.deepSeq</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2014-10-29 16:18:03 +01:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-derivation'>
|
|
|
|
|
<term><function>derivation</function>
|
|
|
|
|
<replaceable>attrs</replaceable></term>
|
2019-03-21 09:35:43 +01:00
|
|
|
|
<term><function>builtins.derivation</function>
|
|
|
|
|
<replaceable>attrs</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para><function>derivation</function> is described in
|
|
|
|
|
<xref linkend='ssec-derivation' />.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-dirOf'>
|
|
|
|
|
<term><function>dirOf</function> <replaceable>s</replaceable></term>
|
2019-03-21 09:35:43 +01:00
|
|
|
|
<term><function>builtins.dirOf</function> <replaceable>s</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-div'>
|
|
|
|
|
<term><function>builtins.div</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2008-11-19 18:27:52 +01:00
|
|
|
|
|
2016-01-06 08:41:53 +01:00
|
|
|
|
<listitem><para>Return the quotient of the numbers
|
2008-11-19 18:27:52 +01:00
|
|
|
|
<replaceable>e1</replaceable> and
|
|
|
|
|
<replaceable>e2</replaceable>.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-elem'>
|
|
|
|
|
<term><function>builtins.elem</function>
|
|
|
|
|
<replaceable>x</replaceable> <replaceable>xs</replaceable></term>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-elemAt'>
|
|
|
|
|
<term><function>builtins.elemAt</function>
|
|
|
|
|
<replaceable>xs</replaceable> <replaceable>n</replaceable></term>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return element <replaceable>n</replaceable> from
|
|
|
|
|
the list <replaceable>xs</replaceable>. Elements are counted
|
2019-10-08 20:02:40 +02:00
|
|
|
|
starting from 0. A fatal error occurs if the index is out of
|
2012-12-04 17:15:32 +01:00
|
|
|
|
bounds.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-fetchurl'>
|
|
|
|
|
<term><function>builtins.fetchurl</function>
|
|
|
|
|
<replaceable>url</replaceable></term>
|
2015-06-01 15:14:44 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-fetchTarball'>
|
|
|
|
|
<term><function>fetchTarball</function>
|
|
|
|
|
<replaceable>url</replaceable></term>
|
2019-03-21 09:35:43 +01:00
|
|
|
|
<term><function>builtins.fetchTarball</function>
|
|
|
|
|
<replaceable>url</replaceable></term>
|
2015-06-01 15:14:44 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
2020-05-23 15:26:59 +02:00
|
|
|
|
with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz) {};
|
2015-06-01 15:14:44 +02:00
|
|
|
|
|
|
|
|
|
stdenv.mkDerivation { … }
|
|
|
|
|
</programlisting>
|
2018-05-16 17:48:36 +02:00
|
|
|
|
</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:
|
2019-05-22 04:29:23 +02:00
|
|
|
|
<literal><xref linkend="conf-tarball-ttl" /> <replaceable>number of seconds to cache</replaceable></literal>.
|
2018-05-16 17:48:36 +02:00
|
|
|
|
</para>
|
2015-06-01 15:14:44 +02:00
|
|
|
|
|
2018-05-16 17:48:36 +02:00
|
|
|
|
<para>Note that when obtaining the hash with <varname>nix-prefetch-url
|
2017-05-11 13:38:13 +02:00
|
|
|
|
</varname> the option <varname>--unpack</varname> is required.
|
2017-11-01 22:31:20 +01:00
|
|
|
|
</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
|
2017-05-11 13:38:13 +02:00
|
|
|
|
requires the attribute <varname>url</varname> and the attribute
|
|
|
|
|
<varname>sha256</varname>, e.g.
|
2017-11-01 22:31:20 +01:00
|
|
|
|
|
2017-05-11 13:38:13 +02:00
|
|
|
|
<programlisting>
|
|
|
|
|
with import (fetchTarball {
|
2020-05-23 15:26:59 +02:00
|
|
|
|
url = "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz";
|
2017-05-11 13:38:13 +02:00
|
|
|
|
sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2";
|
|
|
|
|
}) {};
|
|
|
|
|
|
|
|
|
|
stdenv.mkDerivation { … }
|
|
|
|
|
</programlisting>
|
2017-11-01 22:31:20 +01:00
|
|
|
|
|
2015-06-01 15:14:44 +02:00
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>This function is not available if <link
|
|
|
|
|
linkend="conf-restrict-eval">restricted evaluation mode</link> is
|
|
|
|
|
enabled.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
2018-03-23 00:12:11 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-fetchGit'>
|
2018-03-23 00:12:11 +01:00
|
|
|
|
<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>
|
2019-07-02 15:04:04 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
2018-03-23 00:12:11 +01:00
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
2019-10-26 11:13:08 +02:00
|
|
|
|
<varlistentry>
|
2020-04-07 13:45:17 +02:00
|
|
|
|
<term>submodules</term>
|
2019-10-26 11:13:08 +02:00
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2020-04-07 13:45:17 +02:00
|
|
|
|
A Boolean parameter that specifies whether submodules
|
2019-10-26 11:13:08 +02:00
|
|
|
|
should be checked out. Defaults to
|
|
|
|
|
<literal>false</literal>.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
2018-03-23 00:12:11 +01:00
|
|
|
|
</variablelist>
|
2018-08-31 15:32:59 +02:00
|
|
|
|
|
2020-07-23 14:10:59 +02:00
|
|
|
|
<para>Here are some examples of how to use
|
|
|
|
|
<literal>fetchGit</literal>.</para>
|
|
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>To fetch a private repository over SSH:</para>
|
|
|
|
|
|
|
|
|
|
<programlisting>builtins.fetchGit {
|
2018-09-01 01:49:56 +02:00
|
|
|
|
url = "git@github.com:my-secret/repository.git";
|
2018-08-31 15:32:59 +02:00
|
|
|
|
ref = "master";
|
|
|
|
|
rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
|
|
|
|
|
}</programlisting>
|
|
|
|
|
|
2020-07-23 14:10:59 +02:00
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>To fetch an arbitrary reference:</para>
|
|
|
|
|
|
|
|
|
|
<programlisting>builtins.fetchGit {
|
2019-09-11 14:11:37 +02:00
|
|
|
|
url = "https://github.com/NixOS/nix.git";
|
2019-07-02 15:04:04 +02:00
|
|
|
|
ref = "refs/heads/0.5-release";
|
|
|
|
|
}</programlisting>
|
2020-07-23 14:10:59 +02:00
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
|
<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 {
|
2018-08-31 15:32:59 +02:00
|
|
|
|
url = "https://github.com/nixos/nix.git";
|
|
|
|
|
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
|
|
|
|
|
ref = "1.11-maintenance";
|
|
|
|
|
}</programlisting>
|
2020-07-23 14:10:59 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem>
|
2018-08-31 15:32:59 +02:00
|
|
|
|
<para>
|
2020-07-23 14:10:59 +02:00
|
|
|
|
If the revision you're looking for is in the default branch
|
|
|
|
|
of the git repository you may omit the
|
|
|
|
|
<varname>ref</varname> attribute.
|
2018-08-31 15:32:59 +02:00
|
|
|
|
</para>
|
2020-07-23 14:10:59 +02:00
|
|
|
|
<programlisting>builtins.fetchGit {
|
2018-08-31 15:32:59 +02:00
|
|
|
|
url = "https://github.com/nixos/nix.git";
|
|
|
|
|
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
|
|
|
|
|
}</programlisting>
|
2020-07-23 14:10:59 +02:00
|
|
|
|
</listitem>
|
2018-08-31 15:32:59 +02:00
|
|
|
|
|
2020-07-23 14:10:59 +02:00
|
|
|
|
<listitem>
|
|
|
|
|
<para>To fetch a specific tag:</para>
|
|
|
|
|
<programlisting>builtins.fetchGit {
|
2018-08-31 15:32:59 +02:00
|
|
|
|
url = "https://github.com/nixos/nix.git";
|
2019-09-11 14:18:47 +02:00
|
|
|
|
ref = "refs/tags/1.9";
|
2018-08-31 15:32:59 +02:00
|
|
|
|
}</programlisting>
|
2020-07-23 14:10:59 +02:00
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>To fetch the latest version of a remote branch:</para>
|
2018-08-31 15:32:59 +02:00
|
|
|
|
<programlisting>builtins.fetchGit {
|
|
|
|
|
url = "ssh://git@github.com/nixos/nix.git";
|
|
|
|
|
ref = "master";
|
|
|
|
|
}</programlisting>
|
2020-07-23 14:10:59 +02:00
|
|
|
|
<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>
|
|
|
|
|
</listitem>
|
|
|
|
|
</itemizedlist>
|
2018-03-23 00:12:11 +01:00
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
2015-06-01 15:14:44 +02:00
|
|
|
|
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-01-25 16:05:57 +01:00
|
|
|
|
<varlistentry xml:id='builtin-filterSource'>
|
|
|
|
|
<term><function>builtins.filterSource</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2007-10-22 17:28:32 +02:00
|
|
|
|
|
|
|
|
|
<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
|
2018-05-30 18:34:41 +02:00
|
|
|
|
<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>
|
2007-10-22 17:28:32 +02:00
|
|
|
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-foldl-prime'>
|
|
|
|
|
<term><function>builtins.foldl’</function>
|
2015-07-23 17:03:02 +02:00
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-functionArgs'>
|
|
|
|
|
<term><function>builtins.functionArgs</function>
|
2015-12-30 08:42:41 +01:00
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-fromJSON'>
|
|
|
|
|
<term><function>builtins.fromJSON</function> <replaceable>e</replaceable></term>
|
2014-07-04 13:34:15 +02:00
|
|
|
|
|
|
|
|
|
<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;
|
2018-06-10 14:20:18 +02:00
|
|
|
|
}</literal>.</para></listitem>
|
2014-07-04 13:34:15 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-genList'>
|
|
|
|
|
<term><function>builtins.genList</function>
|
|
|
|
|
<replaceable>generator</replaceable> <replaceable>length</replaceable></term>
|
2015-07-28 17:27:32 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Generate list of size
|
|
|
|
|
<replaceable>length</replaceable>, with each element
|
2017-05-28 19:47:35 +02:00
|
|
|
|
<replaceable>i</replaceable> equal to the value returned by
|
2015-07-28 17:27:32 +02:00
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-getAttr'>
|
|
|
|
|
<term><function>builtins.getAttr</function>
|
|
|
|
|
<replaceable>s</replaceable> <replaceable>set</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para><function>getAttr</function> returns the attribute
|
2013-10-24 16:41:04 +02:00
|
|
|
|
named <replaceable>s</replaceable> from
|
|
|
|
|
<replaceable>set</replaceable>. Evaluation aborts if the
|
2007-10-22 14:58:28 +02:00
|
|
|
|
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>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-getEnv'>
|
|
|
|
|
<term><function>builtins.getEnv</function>
|
|
|
|
|
<replaceable>s</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-hasAttr'>
|
|
|
|
|
<term><function>builtins.hasAttr</function>
|
|
|
|
|
<replaceable>s</replaceable> <replaceable>set</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para><function>hasAttr</function> returns
|
2013-10-24 16:41:04 +02:00
|
|
|
|
<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>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
2013-03-08 01:24:59 +01:00
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-hashString'>
|
|
|
|
|
<term><function>builtins.hashString</function>
|
|
|
|
|
<replaceable>type</replaceable> <replaceable>s</replaceable></term>
|
2013-03-08 01:24:59 +01:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return a base-16 representation of the
|
|
|
|
|
cryptographic hash of string <replaceable>s</replaceable>. The
|
2019-05-03 14:30:29 +02:00
|
|
|
|
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
|
2013-03-08 01:24:59 +01:00
|
|
|
|
hash algorithm specified by <replaceable>type</replaceable> must
|
2019-03-01 14:30:30 +01:00
|
|
|
|
be one of <literal>"md5"</literal>, <literal>"sha1"</literal>,
|
|
|
|
|
<literal>"sha256"</literal> or <literal>"sha512"</literal>.</para></listitem>
|
2013-03-08 01:24:59 +01:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-head'>
|
|
|
|
|
<term><function>builtins.head</function>
|
|
|
|
|
<replaceable>list</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-import'>
|
|
|
|
|
<term><function>import</function>
|
|
|
|
|
<replaceable>path</replaceable></term>
|
2019-03-21 09:35:43 +01:00
|
|
|
|
<term><function>builtins.import</function>
|
|
|
|
|
<replaceable>path</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Load, parse and return the Nix expression in the
|
2012-08-26 20:48:47 +02:00
|
|
|
|
file <replaceable>path</replaceable>. If <replaceable>path
|
|
|
|
|
</replaceable> is a directory, the file <filename>default.nix
|
2019-10-21 22:12:41 +02:00
|
|
|
|
</filename> in that directory is loaded. Evaluation aborts if the
|
2013-10-24 16:41:04 +02:00
|
|
|
|
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>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2019-10-21 23:11:26 +02:00
|
|
|
|
<note><para>Unlike some languages, <function>import</function> is a regular
|
2019-10-21 23:16:55 +02:00
|
|
|
|
function in Nix. Paths using the angle bracket syntax (e.g., <function>
|
|
|
|
|
import</function> <replaceable><foo></replaceable>) are normal path
|
2019-10-21 23:11:26 +02:00
|
|
|
|
values (see <xref linkend='ssec-values' />).</para></note>
|
|
|
|
|
|
2007-10-22 14:58:28 +02:00
|
|
|
|
<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
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2007-10-22 14:58:28 +02:00
|
|
|
|
<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>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-intersectAttrs'>
|
|
|
|
|
<term><function>builtins.intersectAttrs</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2009-11-04 17:52:35 +01:00
|
|
|
|
|
2013-10-24 16:41:04 +02:00
|
|
|
|
<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>
|
2009-11-04 17:52:35 +01:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-isAttrs'>
|
|
|
|
|
<term><function>builtins.isAttrs</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2007-10-22 17:28:32 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return <literal>true</literal> if
|
2013-10-24 16:41:04 +02:00
|
|
|
|
<replaceable>e</replaceable> evaluates to a set, and
|
2007-10-22 17:28:32 +02:00
|
|
|
|
<literal>false</literal> otherwise.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-isList'>
|
|
|
|
|
<term><function>builtins.isList</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return <literal>true</literal> if
|
|
|
|
|
<replaceable>e</replaceable> evaluates to a list, and
|
|
|
|
|
<literal>false</literal> otherwise.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-isFunction'><term><function>builtins.isFunction</function>
|
2007-10-22 17:28:32 +02:00
|
|
|
|
<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>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-isString'>
|
|
|
|
|
<term><function>builtins.isString</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2009-02-05 20:35:44 +01:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return <literal>true</literal> if
|
|
|
|
|
<replaceable>e</replaceable> evaluates to a string, and
|
|
|
|
|
<literal>false</literal> otherwise.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-isInt'>
|
|
|
|
|
<term><function>builtins.isInt</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2009-02-05 20:35:44 +01:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return <literal>true</literal> if
|
2013-08-10 23:36:16 +02:00
|
|
|
|
<replaceable>e</replaceable> evaluates to an int, and
|
2009-02-05 20:35:44 +01:00
|
|
|
|
<literal>false</literal> otherwise.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-isFloat'>
|
|
|
|
|
<term><function>builtins.isFloat</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2017-11-02 00:00:08 +01:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return <literal>true</literal> if
|
|
|
|
|
<replaceable>e</replaceable> evaluates to a float, and
|
|
|
|
|
<literal>false</literal> otherwise.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-isBool'>
|
|
|
|
|
<term><function>builtins.isBool</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2009-02-05 20:35:44 +01:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return <literal>true</literal> if
|
|
|
|
|
<replaceable>e</replaceable> evaluates to a bool, and
|
|
|
|
|
<literal>false</literal> otherwise.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2018-01-29 13:36:59 +01:00
|
|
|
|
<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>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-isNull'>
|
|
|
|
|
<term><function>isNull</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2019-03-21 09:35:43 +01:00
|
|
|
|
<term><function>builtins.isNull</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2007-10-22 14:58:28 +02:00
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-length'>
|
|
|
|
|
<term><function>builtins.length</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2008-11-19 18:27:52 +01:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return the length of the list
|
|
|
|
|
<replaceable>e</replaceable>.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-lessThan'>
|
|
|
|
|
<term><function>builtins.lessThan</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2016-01-06 08:41:53 +01:00
|
|
|
|
<listitem><para>Return <literal>true</literal> if the number
|
|
|
|
|
<replaceable>e1</replaceable> is less than the number
|
2007-10-22 14:58:28 +02:00
|
|
|
|
<replaceable>e2</replaceable>, and <literal>false</literal>
|
|
|
|
|
otherwise. Evaluation aborts if either
|
|
|
|
|
<replaceable>e1</replaceable> or <replaceable>e2</replaceable>
|
2016-01-06 08:41:53 +01:00
|
|
|
|
does not evaluate to a number.</para></listitem>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-listToAttrs'>
|
|
|
|
|
<term><function>builtins.listToAttrs</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2007-10-22 17:28:32 +02:00
|
|
|
|
|
2013-10-24 16:41:04 +02:00
|
|
|
|
<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
|
2007-10-22 17:28:32 +02:00
|
|
|
|
<varname>name</varname> specifying the name of the attribute, and
|
|
|
|
|
an attribute <varname>value</varname> specifying its value.
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
|
|
<programlisting>
|
2011-12-30 18:39:03 +01:00
|
|
|
|
builtins.listToAttrs
|
|
|
|
|
[ { name = "foo"; value = 123; }
|
|
|
|
|
{ name = "bar"; value = 456; }
|
|
|
|
|
]
|
2007-10-22 17:28:32 +02:00
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
|
|
evaluates to
|
|
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
|
{ foo = 123; bar = 456; }
|
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
|
|
</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-map'>
|
|
|
|
|
<term><function>map</function>
|
|
|
|
|
<replaceable>f</replaceable> <replaceable>list</replaceable></term>
|
2019-03-21 09:35:43 +01:00
|
|
|
|
<term><function>builtins.map</function>
|
|
|
|
|
<replaceable>f</replaceable> <replaceable>list</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Apply the function <replaceable>f</replaceable> to
|
|
|
|
|
each element in the list <replaceable>list</replaceable>. For
|
|
|
|
|
example,
|
|
|
|
|
|
|
|
|
|
<programlisting>
|
2011-12-30 18:39:03 +01:00
|
|
|
|
map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2011-12-30 18:39:03 +01:00
|
|
|
|
evaluates to <literal>[ "foobar" "foobla" "fooabc"
|
|
|
|
|
]</literal>.</para></listitem>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2007-10-22 14:58:28 +02:00
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-match'>
|
|
|
|
|
<term><function>builtins.match</function>
|
|
|
|
|
<replaceable>regex</replaceable> <replaceable>str</replaceable></term>
|
2017-08-15 20:34:24 +02:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<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.
|
2017-08-15 20:34:24 +02:00
|
|
|
|
|
|
|
|
|
<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>.
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
</para></listitem>
|
2017-08-15 20:34:24 +02:00
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-mul'>
|
|
|
|
|
<term><function>builtins.mul</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2008-11-19 18:27:52 +01:00
|
|
|
|
|
2016-01-06 08:41:53 +01:00
|
|
|
|
<listitem><para>Return the product of the numbers
|
2008-11-19 18:27:52 +01:00
|
|
|
|
<replaceable>e1</replaceable> and
|
|
|
|
|
<replaceable>e2</replaceable>.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-parseDrvName'>
|
|
|
|
|
<term><function>builtins.parseDrvName</function>
|
|
|
|
|
<replaceable>s</replaceable></term>
|
2008-11-19 18:27:52 +01:00
|
|
|
|
|
|
|
|
|
<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
|
2013-10-24 16:41:04 +02:00
|
|
|
|
in a set <literal>{ name, version }</literal>. Thus,
|
2008-11-19 18:27:52 +01:00
|
|
|
|
<literal>builtins.parseDrvName "nix-0.12pre12876"</literal>
|
2011-12-30 18:39:03 +01:00
|
|
|
|
returns <literal>{ name = "nix"; version = "0.12pre12876";
|
|
|
|
|
}</literal>.</para></listitem>
|
2008-11-19 18:27:52 +01:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-path'>
|
2018-01-25 16:05:57 +01:00
|
|
|
|
<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>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-pathExists'>
|
|
|
|
|
<term><function>builtins.pathExists</function>
|
|
|
|
|
<replaceable>path</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return <literal>true</literal> if the path
|
2018-11-08 13:03:50 +01:00
|
|
|
|
<replaceable>path</replaceable> exists at evaluation time, and
|
2018-11-08 14:07:19 +01:00
|
|
|
|
<literal>false</literal> otherwise.</para></listitem>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2019-11-25 18:00:05 +01:00
|
|
|
|
<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>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-readDir'>
|
|
|
|
|
<term><function>builtins.readDir</function>
|
|
|
|
|
<replaceable>path</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2014-10-29 16:18:03 +01:00
|
|
|
|
<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>
|
2015-09-01 16:53:51 +02:00
|
|
|
|
{ B = "regular"; C = "directory"; }</programlisting>
|
2014-10-29 16:18:03 +01:00
|
|
|
|
|
|
|
|
|
The possible values for the file type are
|
|
|
|
|
<literal>"regular"</literal>, <literal>"directory"</literal>,
|
|
|
|
|
<literal>"symlink"</literal> and
|
|
|
|
|
<literal>"unknown"</literal>.</para></listitem>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-readFile'>
|
|
|
|
|
<term><function>builtins.readFile</function>
|
|
|
|
|
<replaceable>path</replaceable></term>
|
2007-11-21 14:49:59 +01:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return the contents of the file
|
|
|
|
|
<replaceable>path</replaceable> as a string.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-removeAttrs'>
|
|
|
|
|
<term><function>removeAttrs</function>
|
|
|
|
|
<replaceable>set</replaceable> <replaceable>list</replaceable></term>
|
2019-03-21 09:35:43 +01:00
|
|
|
|
<term><function>builtins.removeAttrs</function>
|
|
|
|
|
<replaceable>set</replaceable> <replaceable>list</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Remove the attributes listed in
|
2013-10-24 16:41:04 +02:00
|
|
|
|
<replaceable>list</replaceable> from
|
|
|
|
|
<replaceable>set</replaceable>. The attributes don’t have to
|
|
|
|
|
exist in <replaceable>set</replaceable>. For instance,
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2014-10-29 16:18:03 +01:00
|
|
|
|
<programlisting>
|
|
|
|
|
removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</programlisting>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2011-12-30 18:39:03 +01:00
|
|
|
|
evaluates to <literal>{ y = 2; }</literal>.</para></listitem>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-replaceStrings'>
|
|
|
|
|
<term><function>builtins.replaceStrings</function>
|
|
|
|
|
<replaceable>from</replaceable> <replaceable>to</replaceable> <replaceable>s</replaceable></term>
|
2015-07-24 15:32:24 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-seq'>
|
|
|
|
|
<term><function>builtins.seq</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2014-10-29 16:18:03 +01:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-sort'>
|
|
|
|
|
<term><function>builtins.sort</function>
|
|
|
|
|
<replaceable>comparator</replaceable> <replaceable>list</replaceable></term>
|
2015-07-28 18:39:00 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-split'>
|
|
|
|
|
<term><function>builtins.split</function>
|
|
|
|
|
<replaceable>regex</replaceable> <replaceable>str</replaceable></term>
|
2017-08-15 20:08:41 +02:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<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.
|
2017-08-15 20:08:41 +02:00
|
|
|
|
|
|
|
|
|
<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>.
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
</para></listitem>
|
2017-08-15 20:08:41 +02:00
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2019-09-18 00:40:49 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-stringLength'>
|
|
|
|
|
<term><function>builtins.stringLength</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2007-10-22 17:28:32 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-sub'>
|
|
|
|
|
<term><function>builtins.sub</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2007-10-22 17:28:32 +02:00
|
|
|
|
|
2016-01-06 08:41:53 +01:00
|
|
|
|
<listitem><para>Return the difference between the numbers
|
2007-10-22 17:28:32 +02:00
|
|
|
|
<replaceable>e1</replaceable> and
|
|
|
|
|
<replaceable>e2</replaceable>.</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-substring'>
|
|
|
|
|
<term><function>builtins.substring</function>
|
|
|
|
|
<replaceable>start</replaceable> <replaceable>len</replaceable>
|
|
|
|
|
<replaceable>s</replaceable></term>
|
2007-10-22 17:28:32 +02:00
|
|
|
|
|
|
|
|
|
<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
|
2016-08-11 12:32:24 +02:00
|
|
|
|
non-negative. For example,
|
|
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
|
builtins.substring 0 3 "nixos"
|
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
|
|
evaluates to <literal>"nix"</literal>.
|
|
|
|
|
</para></listitem>
|
2007-10-22 17:28:32 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-tail'>
|
|
|
|
|
<term><function>builtins.tail</function>
|
|
|
|
|
<replaceable>list</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-throw'>
|
|
|
|
|
<term><function>throw</function>
|
|
|
|
|
<replaceable>s</replaceable></term>
|
2019-03-21 09:35:43 +01:00
|
|
|
|
<term><function>builtins.throw</function>
|
|
|
|
|
<replaceable>s</replaceable></term>
|
2007-10-22 17:28:32 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-toFile'>
|
|
|
|
|
<term><function>builtins.toFile</function>
|
|
|
|
|
<replaceable>name</replaceable>
|
|
|
|
|
<replaceable>s</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
2011-12-30 18:39:03 +01:00
|
|
|
|
{ stdenv, fetchurl, perl }:
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
stdenv.mkDerivation {
|
|
|
|
|
name = "hello-2.1.1";
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2007-10-22 14:58:28 +02:00
|
|
|
|
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 {
|
2020-05-21 19:29:13 +02:00
|
|
|
|
url = "http://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
|
2017-07-15 21:06:30 +02:00
|
|
|
|
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
|
2007-10-22 14:58:28 +02:00
|
|
|
|
};
|
|
|
|
|
inherit perl;
|
|
|
|
|
}</programlisting>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2007-10-22 14:58:28 +02:00
|
|
|
|
</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
|
2018-04-03 23:26:47 +02:00
|
|
|
|
<varname>foo</varname> and <varname>bar</varname>.</para>
|
2018-08-31 15:32:59 +02:00
|
|
|
|
<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
|
2018-04-03 23:26:47 +02:00
|
|
|
|
do that.</para></listitem>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-toJSON'>
|
|
|
|
|
<term><function>builtins.toJSON</function> <replaceable>e</replaceable></term>
|
2013-11-19 00:03:11 +01:00
|
|
|
|
|
|
|
|
|
<listitem><para>Return a string containing a JSON representation
|
2016-01-06 08:41:53 +01:00
|
|
|
|
of <replaceable>e</replaceable>. Strings, integers, floats, booleans,
|
2013-11-19 00:03:11 +01:00
|
|
|
|
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>
|
|
|
|
|
|
2014-07-04 13:34:15 +02:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-toPath'>
|
|
|
|
|
<term><function>builtins.toPath</function> <replaceable>s</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
2018-11-08 13:03:50 +01:00
|
|
|
|
<listitem><para> DEPRECATED. Use <literal>/. + "/path"</literal>
|
|
|
|
|
to convert a string into an absolute path. For relative paths,
|
|
|
|
|
use <literal>./. + "/path"</literal>.
|
|
|
|
|
</para></listitem>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-toString'>
|
|
|
|
|
<term><function>toString</function> <replaceable>e</replaceable></term>
|
2019-03-21 09:35:43 +01:00
|
|
|
|
<term><function>builtins.toString</function> <replaceable>e</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<listitem><para>Convert the expression
|
|
|
|
|
<replaceable>e</replaceable> to a string.
|
2017-02-21 13:04:31 +01:00
|
|
|
|
<replaceable>e</replaceable> can be:</para>
|
2017-02-19 19:54:18 +01:00
|
|
|
|
<itemizedlist>
|
2017-02-21 13:04:31 +01:00
|
|
|
|
<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>
|
2019-10-08 20:02:40 +02:00
|
|
|
|
<listitem><para>A Boolean (<literal>false</literal> yields <literal>""</literal>, <literal>true</literal> yields <literal>"1"</literal>).</para></listitem>
|
2017-02-21 13:04:31 +01:00
|
|
|
|
<listitem><para><literal>null</literal>, which yields the empty string.</para></listitem>
|
2017-02-19 19:54:18 +01:00
|
|
|
|
</itemizedlist>
|
|
|
|
|
</listitem>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-toXML'>
|
|
|
|
|
<term><function>builtins.toXML</function> <replaceable>e</replaceable></term>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
<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 -->
|
|
|
|
|
|
2020-07-23 13:58:49 +02:00
|
|
|
|
<para>Here is an example where this is
|
|
|
|
|
the case:
|
|
|
|
|
</para>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2007-10-22 14:58:28 +02:00
|
|
|
|
<programlisting><![CDATA[
|
2011-12-30 18:39:03 +01:00
|
|
|
|
{ stdenv, fetchurl, libxslt, jira, uberwiki }:
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
stdenv.mkDerivation (rec {
|
|
|
|
|
name = "web-server";
|
|
|
|
|
|
2011-12-30 18:39:03 +01:00
|
|
|
|
buildInputs = [ libxslt ];
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2007-10-22 14:58:28 +02:00
|
|
|
|
builder = builtins.toFile "builder.sh" "
|
|
|
|
|
source $stdenv/setup
|
|
|
|
|
mkdir $out
|
2020-07-23 13:58:49 +02:00
|
|
|
|
echo "$servlets" | xsltproc ${stylesheet} - > $out/server-conf.xml]]> ① <![CDATA[
|
2007-10-22 14:58:28 +02:00
|
|
|
|
";
|
|
|
|
|
|
2020-07-23 13:58:49 +02:00
|
|
|
|
stylesheet = builtins.toFile "stylesheet.xsl"]]> ② <![CDATA[
|
2007-10-22 14:58:28 +02:00
|
|
|
|
"<?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>
|
|
|
|
|
";
|
|
|
|
|
|
2020-07-23 13:58:49 +02:00
|
|
|
|
servlets = builtins.toXML []]> ③ <![CDATA[
|
2007-10-22 14:58:28 +02:00
|
|
|
|
{ path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; }
|
|
|
|
|
{ path = "/wiki"; war = uberwiki + "/uberwiki.war"; }
|
|
|
|
|
];
|
|
|
|
|
})]]></programlisting>
|
|
|
|
|
|
2020-07-23 13:58:49 +02:00
|
|
|
|
<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>
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2007-10-22 14:58:28 +02:00
|
|
|
|
<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>
|
|
|
|
|
|
2020-07-23 13:58:49 +02:00
|
|
|
|
<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>
|
2007-10-22 14:58:28 +02:00
|
|
|
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-trace'>
|
|
|
|
|
<term><function>builtins.trace</function>
|
|
|
|
|
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
2007-10-22 17:28:32 +02:00
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-tryEval'>
|
|
|
|
|
<term><function>builtins.tryEval</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2017-04-17 11:33:53 +02:00
|
|
|
|
|
2019-09-03 07:32:44 +02:00
|
|
|
|
<listitem><para>Try to shallowly evaluate <replaceable>e</replaceable>.
|
2017-04-17 11:33:53 +02:00
|
|
|
|
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>
|
2019-09-03 07:32:44 +02:00
|
|
|
|
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>.
|
2017-04-17 11:33:53 +02:00
|
|
|
|
</para></listitem>
|
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-12-04 17:15:32 +01:00
|
|
|
|
|
2018-10-02 15:38:16 +02:00
|
|
|
|
<varlistentry xml:id='builtin-typeOf'>
|
|
|
|
|
<term><function>builtins.typeOf</function>
|
|
|
|
|
<replaceable>e</replaceable></term>
|
2013-10-24 02:56:00 +02:00
|
|
|
|
|
|
|
|
|
<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>,
|
2017-11-01 22:31:20 +01:00
|
|
|
|
<literal>"set"</literal>, <literal>"list"</literal>,
|
|
|
|
|
<literal>"lambda"</literal> or
|
|
|
|
|
<literal>"float"</literal>.</para></listitem>
|
2013-10-24 02:56:00 +02:00
|
|
|
|
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
|
|
|
2007-10-22 14:58:28 +02:00
|
|
|
|
</variablelist>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</section>
|