nixos/nix
1
1
Fork 0
mirror of https://github.com/NixOS/nix.git synced 2025-11-16 07:22:43 +01:00
Code Activity

Merge remote-tracking branch 'origin/master' into precise-gc

Browse source
This commit is contained in:
Eelco Dolstra 2020-02-12 20:41:17 +01:00
commit 488ce10b4e
287 changed files with 11311 additions and 25656 deletions
Download patch file Download diff file Expand all files Collapse all files

3
doc/manual/advanced-topics/advanced-topics.xml
View file

@ -7,5 +7,8 @@
<title>Advanced Topics</title>
<xi:include href="distributed-builds.xml" />
<xi:include href="cores-vs-jobs.xml" />
<xi:include href="diff-hook.xml" />
<xi:include href="post-build-hook.xml" />
</part>

121
doc/manual/advanced-topics/cores-vs-jobs.xml Normal file
View file

@ -0,0 +1,121 @@
<chapter 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="chap-tuning-cores-and-jobs">
<title>Tuning Cores and Jobs</title>
<para>Nix has two relevant settings with regards to how your CPU cores
will be utilized: <xref linkend="conf-cores" /> and
<xref linkend="conf-max-jobs" />. This chapter will talk about what
they are, how they interact, and their configuration trade-offs.</para>
<variablelist>
<varlistentry>
<term><xref linkend="conf-max-jobs" /></term>
<listitem><para>
Dictates how many separate derivations will be built at the same
time. If you set this to zero, the local machine will do no
builds. Nix will still substitute from binary caches, and build
remotely if remote builders are configured.
</para></listitem>
</varlistentry>
<varlistentry>
<term><xref linkend="conf-cores" /></term>
<listitem><para>
Suggests how many cores each derivation should use. Similar to
<command>make -j</command>.
</para></listitem>
</varlistentry>
</variablelist>
<para>The <xref linkend="conf-cores" /> setting determines the value of
<envar>NIX_BUILD_CORES</envar>. <envar>NIX_BUILD_CORES</envar> is equal
to <xref linkend="conf-cores" />, unless <xref linkend="conf-cores" />
equals <literal>0</literal>, in which case <envar>NIX_BUILD_CORES</envar>
will be the total number of cores in the system.</para>
<para>The maximum number of consumed cores is a simple multiplication,
<xref linkend="conf-max-jobs" /> * <envar>NIX_BUILD_CORES</envar>.</para>
<para>The balance on how to set these two independent variables depends
upon each builder's workload and hardware. Here are a few example
scenarios on a machine with 24 cores:</para>
<table>
<caption>Balancing 24 Build Cores</caption>
<thead>
<tr>
<th><xref linkend="conf-max-jobs" /></th>
<th><xref linkend="conf-cores" /></th>
<th><envar>NIX_BUILD_CORES</envar></th>
<th>Maximum Processes</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>24</td>
<td>24</td>
<td>24</td>
<td>
One derivation will be built at a time, each one can use 24
cores. Undersold if a job can’t use 24 cores.
</td>
</tr>
<tr>
<td>4</td>
<td>6</td>
<td>6</td>
<td>24</td>
<td>
Four derivations will be built at once, each given access to
six cores.
</td>
</tr>
<tr>
<td>12</td>
<td>6</td>
<td>6</td>
<td>72</td>
<td>
12 derivations will be built at once, each given access to six
cores. This configuration is over-sold. If all 12 derivations
being built simultaneously try to use all six cores, the
machine's performance will be degraded due to extensive context
switching between the 12 builds.
</td>
</tr>
<tr>
<td>24</td>
<td>1</td>
<td>1</td>
<td>24</td>
<td>
24 derivations can build at the same time, each using a single
core. Never oversold, but derivations which require many cores
will be very slow to compile.
</td>
</tr>
<tr>
<td>24</td>
<td>0</td>
<td>24</td>
<td>576</td>
<td>
24 derivations can build at the same time, each using all the
available cores of the machine. Very likely to be oversold,
and very likely to suffer context switches.
</td>
</tr>
</tbody>
</table>
<para>It is up to the derivations' build script to respect
host's requested cores-per-build by following the value of the
<envar>NIX_BUILD_CORES</envar> environment variable.</para>
</chapter>

205
doc/manual/advanced-topics/diff-hook.xml Normal file
View file

@ -0,0 +1,205 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="chap-diff-hook"
version="5.0"
>
<title>Verifying Build Reproducibility with <option linkend="conf-diff-hook">diff-hook</option></title>
<subtitle>Check build reproducibility by running builds multiple times
and comparing their results.</subtitle>
<para>Specify a program with Nix's <xref linkend="conf-diff-hook" /> to
compare build results when two builds produce different results. Note:
this hook is only executed if the results are not the same, this hook
is not used for determining if the results are the same.</para>
<para>For purposes of demonstration, we'll use the following Nix file,
<filename>deterministic.nix</filename> for testing:</para>
<programlisting>
let
inherit (import &lt;nixpkgs&gt; {}) runCommand;
in {
stable = runCommand "stable" {} ''
touch $out
'';
unstable = runCommand "unstable" {} ''
echo $RANDOM > $out
'';
}
</programlisting>
<para>Additionally, <filename>nix.conf</filename> contains:
<programlisting>
diff-hook = /etc/nix/my-diff-hook
run-diff-hook = true
</programlisting>
where <filename>/etc/nix/my-diff-hook</filename> is an executable
file containing:
<programlisting>
#!/bin/sh
exec &gt;&amp;2
echo "For derivation $3:"
/run/current-system/sw/bin/diff -r "$1" "$2"
</programlisting>
</para>
<para>The diff hook is executed by the same user and group who ran the
build. However, the diff hook does not have write access to the store
path just built.</para>
<section>
<title>
Spot-Checking Build Determinism
</title>
<para>
Verify a path which already exists in the Nix store by passing
<option>--check</option> to the build command.
</para>
<para>If the build passes and is deterministic, Nix will exit with a
status code of 0:</para>
<screen>
$ nix-build ./deterministic.nix -A stable
these derivations will be built:
/nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv
building '/nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv'...
/nix/store/yyxlzw3vqaas7wfp04g0b1xg51f2czgq-stable
$ nix-build ./deterministic.nix -A stable --check
checking outputs of '/nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv'...
/nix/store/yyxlzw3vqaas7wfp04g0b1xg51f2czgq-stable
</screen>
<para>If the build is not deterministic, Nix will exit with a status
code of 1:</para>
<screen>
$ nix-build ./deterministic.nix -A unstable
these derivations will be built:
/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv
building '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'...
/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable
$ nix-build ./deterministic.nix -A unstable --check
checking outputs of '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'...
error: derivation '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv' may not be deterministic: output '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable' differs
</screen>
<para>In the Nix daemon's log, we will now see:
<screen>
For derivation /nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv:
1c1
&lt; 8108
---
&gt; 30204
</screen>
</para>
<para>Using <option>--check</option> with <option>--keep-failed</option>
will cause Nix to keep the second build's output in a special,
<literal>.check</literal> path:</para>
<screen>
$ nix-build ./deterministic.nix -A unstable --check --keep-failed
checking outputs of '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'...
note: keeping build directory '/tmp/nix-build-unstable.drv-0'
error: derivation '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv' may not be deterministic: output '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable' differs from '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check'
</screen>
<para>In particular, notice the
<literal>/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check</literal>
output. Nix has copied the build results to that directory where you
can examine it.</para>
<note xml:id="check-dirs-are-unregistered">
<title><literal>.check</literal> paths are not registered store paths</title>
<para>Check paths are not protected against garbage collection,
and this path will be deleted on the next garbage collection.</para>
<para>The path is guaranteed to be alive for the duration of
<xref linkend="conf-diff-hook" />'s execution, but may be deleted
any time after.</para>
<para>If the comparison is performed as part of automated tooling,
please use the diff-hook or author your tooling to handle the case
where the build was not deterministic and also a check path does
not exist.</para>
</note>
<para>
<option>--check</option> is only usable if the derivation has
been built on the system already. If the derivation has not been
built Nix will fail with the error:
<screen>
error: some outputs of '/nix/store/hzi1h60z2qf0nb85iwnpvrai3j2w7rr6-unstable.drv' are not valid, so checking is not possible
</screen>
Run the build without <option>--check</option>, and then try with
<option>--check</option> again.
</para>
</section>
<section>
<title>
Automatic and Optionally Enforced Determinism Verification
</title>
<para>
Automatically verify every build at build time by executing the
build multiple times.
</para>
<para>
Setting <xref linkend="conf-repeat" /> and
<xref linkend="conf-enforce-determinism" /> in your
<filename>nix.conf</filename> permits the automated verification
of every build Nix performs.
</para>
<para>
The following configuration will run each build three times, and
will require the build to be deterministic:
<programlisting>
enforce-determinism = true
repeat = 2
</programlisting>
</para>
<para>
Setting <xref linkend="conf-enforce-determinism" /> to false as in
the following configuration will run the build multiple times,
execute the build hook, but will allow the build to succeed even
if it does not build reproducibly:
<programlisting>
enforce-determinism = false
repeat = 1
</programlisting>
</para>
<para>
An example output of this configuration:
<screen>
$ nix-build ./test.nix -A unstable
these derivations will be built:
/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv
building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 1/2)...
building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 2/2)...
output '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable' of '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' differs from '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable.check' from previous round
/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable
</screen>
</para>
</section>
</chapter>

3
doc/manual/advanced-topics/distributed-builds.xml
View file

@ -184,4 +184,7 @@ to be included. (This is the default.)</para>
the option <link linkend='conf-builders-use-substitutes'><literal>builders-use-substitutes</literal></link>
in your local <filename>nix.conf</filename>.</para>
<para>To build only on remote builders and disable building on the local machine,
you can use the option <option>--max-jobs 0</option>.</para>
</chapter>

160
doc/manual/advanced-topics/post-build-hook.xml Normal file
View file

@ -0,0 +1,160 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="chap-post-build-hook"
version="5.0"
>
<title>Using the <option linkend="conf-post-build-hook">post-build-hook</option></title>
<subtitle>Uploading to an S3-compatible binary cache after each build</subtitle>
<section xml:id="chap-post-build-hook-caveats">
<title>Implementation Caveats</title>
<para>Here we use the post-build hook to upload to a binary cache.
This is a simple and working example, but it is not suitable for all
use cases.</para>
<para>The post build hook program runs after each executed build,
and blocks the build loop. The build loop exits if the hook program
fails.</para>
<para>Concretely, this implementation will make Nix slow or unusable
when the internet is slow or unreliable.</para>
<para>A more advanced implementation might pass the store paths to a
user-supplied daemon or queue for processing the store paths outside
of the build loop.</para>
</section>
<section>
<title>Prerequisites</title>
<para>
This tutorial assumes you have configured an S3-compatible binary cache
according to the instructions at
<xref linkend="ssec-s3-substituter-authenticated-writes" />, and
that the <literal>root</literal> user's default AWS profile can
upload to the bucket.
</para>
</section>
<section>
<title>Set up a Signing Key</title>
<para>Use <command>nix-store --generate-binary-cache-key</command> to
create our public and private signing keys. We will sign paths
with the private key, and distribute the public key for verifying
the authenticity of the paths.</para>
<screen>
# nix-store --generate-binary-cache-key example-nix-cache-1 /etc/nix/key.private /etc/nix/key.public
# cat /etc/nix/key.public
example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
</screen>
<para>Then, add the public key and the cache URL to your
<filename>nix.conf</filename>'s <xref linkend="conf-trusted-public-keys" />
and <xref linkend="conf-substituters" /> like:</para>
<programlisting>
substituters = https://cache.nixos.org/ s3://example-nix-cache
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
</programlisting>
<para>we will restart the Nix daemon a later step.</para>
</section>
<section>
<title>Implementing the build hook</title>
<para>Write the following script to
<filename>/etc/nix/upload-to-cache.sh</filename>:
</para>
<programlisting>
#!/bin/sh
set -eu
set -f # disable globbing
export IFS=' '
echo "Signing paths" $OUT_PATHS
nix sign-paths --key-file /etc/nix/key.private $OUT_PATHS
echo "Uploading paths" $OUT_PATHS
exec nix copy --to 's3://example-nix-cache' $OUT_PATHS
</programlisting>
<note>
<title>Should <literal>$OUT_PATHS</literal> be quoted?</title>
<para>
The <literal>$OUT_PATHS</literal> variable is a space-separated
list of Nix store paths. In this case, we expect and want the
shell to perform word splitting to make each output path its
own argument to <command>nix sign-paths</command>. Nix guarantees
the paths will not contain any spaces, however a store path
might contain glob characters. The <command>set -f</command>
disables globbing in the shell.
</para>
</note>
<para>
Then make sure the hook program is executable by the <literal>root</literal> user:
<screen>
# chmod +x /etc/nix/upload-to-cache.sh
</screen></para>
</section>
<section>
<title>Updating Nix Configuration</title>
<para>Edit <filename>/etc/nix/nix.conf</filename> to run our hook,
by adding the following configuration snippet at the end:</para>
<programlisting>
post-build-hook = /etc/nix/upload-to-cache.sh
</programlisting>
<para>Then, restart the <command>nix-daemon</command>.</para>
</section>
<section>
<title>Testing</title>
<para>Build any derivation, for example:</para>
<screen>
$ nix-build -E '(import &lt;nixpkgs&gt; {}).writeText "example" (builtins.toString builtins.currentTime)'
these derivations will be built:
/nix/store/s4pnfbkalzy5qz57qs6yybna8wylkig6-example.drv
building '/nix/store/s4pnfbkalzy5qz57qs6yybna8wylkig6-example.drv'...
running post-build-hook '/home/grahamc/projects/github.com/NixOS/nix/post-hook.sh'...
post-build-hook: Signing paths /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example
post-build-hook: Uploading paths /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example
/nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example
</screen>
<para>Then delete the path from the store, and try substituting it from the binary cache:</para>
<screen>
$ rm ./result
$ nix-store --delete /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example
</screen>
<para>Now, copy the path back from the cache:</para>
<screen>
$ nix store --realize /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example
copying path '/nix/store/m8bmqwrch6l3h8s0k3d673xpmipcdpsa-example from 's3://example-nix-cache'...
warning: you did not specify '--add-root'; the result might be removed by the garbage collector
/nix/store/m8bmqwrch6l3h8s0k3d673xpmipcdpsa-example
</screen>
</section>
<section>
<title>Conclusion</title>
<para>
We now have a Nix installation configured to automatically sign and
upload every local build to a remote binary cache.
</para>
<para>
Before deploying this to production, be sure to consider the
implementation caveats in <xref linkend="chap-post-build-hook-caveats" />.
</para>
</section>
</chapter>

229
doc/manual/command-ref/conf-file.xml
View file

@ -1,7 +1,9 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-conf-file">
xml:id="sec-conf-file"
version="5">
<refmeta>
<refentrytitle>nix.conf</refentrytitle>
@ -236,8 +238,74 @@ false</literal>.</para>
linkend='opt-cores'>--cores</option> command line switch and
defaults to <literal>1</literal>. The value <literal>0</literal>
means that the builder should use all available CPU cores in the
system.</para></listitem>
system.</para>
<para>See also <xref linkend="chap-tuning-cores-and-jobs" />.</para></listitem>
</varlistentry>
<varlistentry xml:id="conf-diff-hook"><term><literal>diff-hook</literal></term>
<listitem>
<para>
Absolute path to an executable capable of diffing build results.
The hook executes if <xref linkend="conf-run-diff-hook" /> is
true, and the output of a build is known to not be the same.
This program is not executed to determine if two results are the
same.
</para>
<para>
The diff hook is executed by the same user and group who ran the
build. However, the diff hook does not have write access to the
store path just built.
</para>
<para>The diff hook program receives three parameters:</para>
<orderedlist>
<listitem>
<para>
A path to the previous build's results
</para>
</listitem>
<listitem>
<para>
A path to the current build's results
</para>
</listitem>
<listitem>
<para>
The path to the build's derivation
</para>
</listitem>
<listitem>
<para>
The path to the build's scratch directory. This directory
will exist only if the build was run with
<option>--keep-failed</option>.
</para>
</listitem>
</orderedlist>
<para>
The stderr and stdout output from the diff hook will not be
displayed to the user. Instead, it will print to the nix-daemon's
log.
</para>
<para>When using the Nix daemon, <literal>diff-hook</literal> must
be set in the <filename>nix.conf</filename> configuration file, and
cannot be passed at the command line.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="conf-enforce-determinism">
<term><literal>enforce-determinism</literal></term>
<listitem><para>See <xref linkend="conf-repeat" />.</para></listitem>
</varlistentry>
<varlistentry xml:id="conf-extra-sandbox-paths">
@ -365,7 +433,7 @@ builtins.fetchurl {
<varlistentry xml:id="conf-keep-env-derivations"><term><literal>keep-env-derivations</literal></term>
<listitem><para>If <literal>false</literal> (default), derivations
are not stored in Nix user environments. That is, the derivation
are not stored in Nix user environments. That is, the derivations of
any build-time-only dependencies may be garbage-collected.</para>
<para>If <literal>true</literal>, when you add a Nix derivation to
@ -415,8 +483,10 @@ builtins.fetchurl {
<varlistentry xml:id="conf-max-free"><term><literal>max-free</literal></term>
<listitem><para>This option defines after how many free bytes to stop collecting
garbage once the <literal>min-free</literal> condition gets triggered.</para></listitem>
<listitem><para>When a garbage collection is triggered by the
<literal>min-free</literal> option, it stops as soon as
<literal>max-free</literal> bytes are available. The default is
infinity (i.e. delete all garbage).</para></listitem>
</varlistentry>
@ -431,7 +501,10 @@ builtins.fetchurl {
regardless). It can be
overridden using the <option
linkend='opt-max-jobs'>--max-jobs</option> (<option>-j</option>)
command line switch.</para></listitem>
command line switch.</para>
<para>See also <xref linkend="chap-tuning-cores-and-jobs" />.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="conf-max-silent-time"><term><literal>max-silent-time</literal></term>
@ -457,9 +530,11 @@ builtins.fetchurl {
<varlistentry xml:id="conf-min-free"><term><literal>min-free</literal></term>
<listitem>
<para>When the disk reaches <literal>min-free</literal> bytes of free disk space during a build, nix
will start to garbage-collection until <literal>max-free</literal> bytes are available on the disk.
A value of <literal>0</literal> (the default) means that this feature is disabled.</para>
<para>When free disk space in <filename>/nix/store</filename>
drops below <literal>min-free</literal> during a build, Nix
performs a garbage-collection until <literal>max-free</literal>
bytes are available or there is no more garbage. A value of
<literal>0</literal> (the default) disables this feature.</para>
</listitem>
</varlistentry>
@ -589,15 +664,71 @@ password <replaceable>my-password</replaceable>
</varlistentry>
<varlistentry xml:id="conf-post-build-hook">
<term><literal>post-build-hook</literal></term>
<listitem>
<para>Optional. The path to a program to execute after each build.</para>
<para>This option is only settable in the global
<filename>nix.conf</filename>, or on the command line by trusted
users.</para>
<para>When using the nix-daemon, the daemon executes the hook as
<literal>root</literal>. If the nix-daemon is not involved, the
hook runs as the user executing the nix-build.</para>
<itemizedlist>
<listitem><para>The hook executes after an evaluation-time build.</para></listitem>
<listitem><para>The hook does not execute on substituted paths.</para></listitem>
<listitem><para>The hook's output always goes to the user's terminal.</para></listitem>
<listitem><para>If the hook fails, the build succeeds but no further builds execute.</para></listitem>
<listitem><para>The hook executes synchronously, and blocks other builds from progressing while it runs.</para></listitem>
</itemizedlist>
<para>The program executes with no arguments. The program's environment
contains the following environment variables:</para>
<variablelist>
<varlistentry>
<term><envar>DRV_PATH</envar></term>
<listitem>
<para>The derivation for the built paths.</para>
<para>Example:
<literal>/nix/store/5nihn1a7pa8b25l9zafqaqibznlvvp3f-bash-4.4-p23.drv</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><envar>OUT_PATHS</envar></term>
<listitem>
<para>Output paths of the built derivation, separated by a space character.</para>
<para>Example:
<literal>/nix/store/zf5lbh336mnzf1nlswdn11g4n2m8zh3g-bash-4.4-p23-dev
/nix/store/rjxwxwv1fpn9wa2x5ssk5phzwlcv4mna-bash-4.4-p23-doc
/nix/store/6bqvbzjkcp9695dq0dpl5y43nvy37pq1-bash-4.4-p23-info
/nix/store/r7fng3kk3vlpdlh2idnrbn37vh4imlj2-bash-4.4-p23-man
/nix/store/xfghy8ixrhz3kyy6p724iv3cxji088dx-bash-4.4-p23</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>See <xref linkend="chap-post-build-hook" /> for an example
implementation.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="conf-repeat"><term><literal>repeat</literal></term>
<listitem><para>How many times to repeat builds to check whether
they are deterministic. The default value is 0. If the value is
non-zero, every build is repeated the specified number of
times. If the contents of any of the runs differs from the
previous ones, the build is rejected and the resulting store paths
are not registered as “valid” in Nix’s database.</para></listitem>
previous ones and <xref linkend="conf-enforce-determinism" /> is
true, the build is rejected and the resulting store paths are not
registered as “valid” in Nix’s database.</para></listitem>
</varlistentry>
<varlistentry xml:id="conf-require-sigs"><term><literal>require-sigs</literal></term>
@ -628,6 +759,19 @@ password <replaceable>my-password</replaceable>
</varlistentry>
<varlistentry xml:id="conf-run-diff-hook"><term><literal>run-diff-hook</literal></term>
<listitem>
<para>
If true, enable the execution of <xref linkend="conf-diff-hook" />.
</para>
<para>
When using the Nix daemon, <literal>run-diff-hook</literal> must
be set in the <filename>nix.conf</filename> configuration file,
and cannot be passed at the command line.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="conf-sandbox"><term><literal>sandbox</literal></term>
@ -729,6 +873,14 @@ password <replaceable>my-password</replaceable>
</varlistentry>
<varlistentry xml:id="conf-stalled-download-timeout"><term><literal>stalled-download-timeout</literal></term>
<listitem>
<para>The timeout (in seconds) for receiving data from servers
during download. Nix cancels idle downloads after this timeout's
duration.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="conf-substituters"><term><literal>substituters</literal></term>
<listitem><para>A list of URLs of substituters, separated by
@ -784,6 +936,31 @@ requiredSystemFeatures = [ "kvm" ];
</varlistentry>
<varlistentry xml:id="conf-tarball-ttl"><term><literal>tarball-ttl</literal></term>
<listitem>
<para>Default: <literal>3600</literal> seconds.</para>
<para>The number of seconds a downloaded tarball is considered
fresh. If the cached tarball is stale, Nix will check whether
it is still up to date using the ETag header. Nix will download
a new version if the ETag header is unsupported, or the
cached ETag doesn't match.
</para>
<para>Setting the TTL to <literal>0</literal> forces Nix to always
check if the tarball is up to date.</para>
<para>Nix caches tarballs in
<filename>$XDG_CACHE_HOME/nix/tarballs</filename>.</para>
<para>Files fetched via <envar>NIX_PATH</envar>,
<function>fetchGit</function>, <function>fetchMercurial</function>,
<function>fetchTarball</function>, and <function>fetchurl</function>
respect this TTL.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="conf-timeout"><term><literal>timeout</literal></term>
@ -804,6 +981,34 @@ requiredSystemFeatures = [ "kvm" ];
</varlistentry>
<varlistentry xml:id="conf-trace-function-calls"><term><literal>trace-function-calls</literal></term>
<listitem>
<para>Default: <literal>false</literal>.</para>
<para>If set to <literal>true</literal>, the Nix evaluator will
trace every function call. Nix will print a log message at the
"vomit" level for every function entrance and function exit.</para>
<informalexample><screen>
function-trace entered undefined position at 1565795816999559622
function-trace exited undefined position at 1565795816999581277
function-trace entered /nix/store/.../example.nix:226:41 at 1565795253249935150
function-trace exited /nix/store/.../example.nix:226:41 at 1565795253249941684
</screen></informalexample>
<para>The <literal>undefined position</literal> means the function
call is a builtin.</para>
<para>Use the <literal>contrib/stack-collapse.py</literal> script
distributed with the Nix source code to convert the trace logs
in to a format suitable for <command>flamegraph.pl</command>.</para>
</listitem>
</varlistentry>
<varlistentry xml:id="conf-trusted-public-keys"><term><literal>trusted-public-keys</literal></term>
<listitem><para>A whitespace-separated list of public keys. When

5
doc/manual/command-ref/env-common.xml
View file

@ -14,7 +14,8 @@
<varlistentry><term><envar>IN_NIX_SHELL</envar></term>
<listitem><para>Indicator that tells if the current environment was set up by
<command>nix-shell</command>.</para></listitem>
<command>nix-shell</command>. Since Nix 2.0 the values are
<literal>"pure"</literal> and <literal>"impure"</literal></para></listitem>
</varlistentry>
@ -121,7 +122,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
<varlistentry><term><envar>NIX_LOG_DIR</envar></term>
<listitem><para>Overrides the location of the Nix log directory
(default <filename><replaceable>prefix</replaceable>/log/nix</filename>).</para></listitem>
(default <filename><replaceable>prefix</replaceable>/var/log/nix</filename>).</para></listitem>
</varlistentry>

5
doc/manual/command-ref/nix-build.xml
View file

@ -30,6 +30,7 @@
<replaceable>attrPath</replaceable>
</arg>
<arg><option>--no-out-link</option></arg>
<arg><option>--dry-run</option></arg>
<arg>
<group choice='req'>
<arg choice='plain'><option>--out-link</option></arg>
@ -98,6 +99,10 @@ also <xref linkend="sec-common-options" />.</phrase></para>
</varlistentry>
<varlistentry><term><option>--dry-run</option></term>
<listitem><para>Show what store paths would be built or downloaded.</para></listitem>
</varlistentry>
<varlistentry xml:id='opt-out-link'><term><option>--out-link</option> /
<option>-o</option> <replaceable>outlink</replaceable></term>

30
doc/manual/command-ref/nix-channel.xml
View file

@ -31,12 +31,14 @@
<refsection><title>Description</title>
<para>A Nix channel is a mechanism that allows you to automatically stay
up-to-date with a set of pre-built Nix expressions. A Nix channel is
just a URL that points to a place containing both a set of Nix
expressions and a pointer to a binary cache. <phrase
condition="manual">See also <xref linkend="sec-channels"
/>.</phrase></para>
<para>A Nix channel is a mechanism that allows you to automatically
stay up-to-date with a set of pre-built Nix expressions. A Nix
channel is just a URL that points to a place containing a set of Nix
expressions. <phrase condition="manual">See also <xref
linkend="sec-channels" />.</phrase></para>
<para>To see the list of official NixOS channels, visit <link
xlink:href="https://nixos.org/channels" />.</para>
<para>This command has the following operations:
@ -112,13 +114,13 @@ $ nix-env -iA nixpkgs.hello</screen>
<para>You can revert channel updates using <option>--rollback</option>:</para>
<screen>
$ nix-instantiate --eval -E '(import &lt;nixpkgs> {}).lib.nixpkgsVersion'
$ nix-instantiate --eval -E '(import &lt;nixpkgs> {}).lib.version'
"14.04.527.0e935f1"
$ nix-channel --rollback
switching from generation 483 to 482
$ nix-instantiate --eval -E '(import &lt;nixpkgs> {}).lib.nixpkgsVersion'
$ nix-instantiate --eval -E '(import &lt;nixpkgs> {}).lib.version'
"14.04.526.dbadfad"
</screen>
@ -172,18 +174,6 @@ following files:</para>
</varlistentry>
<varlistentry><term><filename>binary-cache-url</filename></term>
<listitem><para>A file containing the URL to a binary cache (such
as <uri>https://cache.nixos.org</uri>). Nix will automatically
check this cache for pre-built binaries, if the user has
sufficient rights to add binary caches. For instance, in a
multi-user Nix setup, the binary caches provided by the channels
of the root user are used automatically, but caches corresponding
to the channels of non-root users are ignored.</para></listitem>
</varlistentry>
</variablelist>
</refsection>

53
doc/manual/command-ref/nix-env.xml
View file

@ -221,31 +221,53 @@ also <xref linkend="sec-common-options" />.</phrase></para>
<varlistentry><term><filename>~/.nix-defexpr</filename></term>
<listitem><para>A directory that contains the default Nix
<listitem><para>The source for the default Nix
expressions used by the <option>--install</option>,
<option>--upgrade</option>, and <option>--query
--available</option> operations to obtain derivations. The
--available</option> operations to obtain derivations. The
<option>--file</option> option may be used to override this
default.</para>
<para>The Nix expressions in this directory are combined into a
single set, with each file as an attribute that has the name of
the file. Thus, if <filename>~/.nix-defexpr</filename> contains
two files, <filename>foo</filename> and <filename>bar</filename>,
<para>If <filename>~/.nix-defexpr</filename> is a file,
it is loaded as a Nix expression. If the expression
is a set, it is used as the default Nix expression.
If the expression is a function, an empty set is passed
as argument and the return value is used as
the default Nix expression.</para>
<para>If <filename>~/.nix-defexpr</filename> is a directory
containing a <filename>default.nix</filename> file, that file
is loaded as in the above paragraph.</para>
<para>If <filename>~/.nix-defexpr</filename> is a directory without
a <filename>default.nix</filename> file, then its contents
(both files and subdirectories) are loaded as Nix expressions.
The expressions are combined into a single set, each expression
under an attribute with the same name as the original file
or subdirectory.
</para>
<para>For example, if <filename>~/.nix-defexpr</filename> contains
two files, <filename>foo.nix</filename> and <filename>bar.nix</filename>,
then the default Nix expression will essentially be
<programlisting>
{
foo = import ~/.nix-defexpr/foo;
bar = import ~/.nix-defexpr/bar;
foo = import ~/.nix-defexpr/foo.nix;
bar = import ~/.nix-defexpr/bar.nix;
}</programlisting>
</para>
<para>The file <filename>manifest.nix</filename> is always ignored.
Subdirectories without a <filename>default.nix</filename> file
are traversed recursively in search of more Nix expressions,
but the names of these intermediate directories are not
added to the attribute paths of the default Nix expression.</para>
<para>The command <command>nix-channel</command> places symlinks
to the downloaded Nix expressions from each subscribed channel in
this directory.</para>
</listitem>
</varlistentry>
@ -637,7 +659,7 @@ upgrading `mozilla-1.2' to `mozilla-1.4'</screen>
<literal>gcc-3.3.1</literal> are split into two parts: the package
name (<literal>gcc</literal>), and the version
(<literal>3.3.1</literal>). The version part starts after the first
dash not following by a letter. <varname>x</varname> is considered an
dash not followed by a letter. <varname>x</varname> is considered an
upgrade of <varname>y</varname> if their package names match, and the
version of <varname>y</varname> is higher that that of
<varname>x</varname>.</para>
@ -1348,10 +1370,13 @@ profile. The generations can be a list of generation numbers, the
special value <literal>old</literal> to delete all non-current
generations, a value such as <literal>30d</literal> to delete all
generations older than the specified number of days (except for the
generation that was active at that point in time), or a value such as.
<literal>+5</literal> to only keep the specified items older than the
current generation. Periodically deleting old generations is important
to make garbage collection effective.</para>
generation that was active at that point in time), or a value such as
<literal>+5</literal> to keep the last <literal>5</literal> generations
ignoring any newer than current, e.g., if <literal>30</literal> is the current
generation <literal>+5</literal> will delete generation <literal>25</literal>
and all older generations.
Periodically deleting old generations is important to make garbage collection
effective.</para>
</refsection>

2
doc/manual/command-ref/nix-prefetch-url.xml
View file

@ -53,7 +53,7 @@ avoided.</para>
<para>If <replaceable>hash</replaceable> is specified, then a download
is not performed if the Nix store already contains a file with the
same hash and base name. Otherwise, the file is downloaded, and an
error if signaled if the actual hash of the file does not match the
error is signaled if the actual hash of the file does not match the
specified hash.</para>
<para>This command prints the hash on standard output. Additionally,

24
doc/manual/command-ref/nix-shell.xml
View file

@ -39,7 +39,12 @@
<arg choice='plain'><option>--packages</option></arg>
<arg choice='plain'><option>-p</option></arg>
</group>
<arg choice='plain' rep='repeat'><replaceable>packages</replaceable></arg>
<arg choice='plain' rep='repeat'>
<group choice='req'>
<arg choice="plain"><replaceable>packages</replaceable></arg>
<arg choice="plain"><replaceable>expressions</replaceable></arg>
</group>
</arg>
</arg>
<arg><replaceable>path</replaceable></arg>
</group>
@ -189,8 +194,8 @@ also <xref linkend="sec-common-options" />.</phrase></para>
<variablelist>
<varlistentry><term><envar>NIX_BUILD_SHELL</envar></term>
<listitem><para>Shell used to start the interactive environment.
<listitem><para>Shell used to start the interactive environment.
Defaults to the <command>bash</command> found in <envar>PATH</envar>.</para></listitem>
</varlistentry>
@ -222,8 +227,9 @@ $ nix-shell '&lt;nixpkgs>' -A pan --pure \
--command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
</screen>
Nix expressions can also be given on the command line. For instance,
the following starts a shell containing the packages
Nix expressions can also be given on the command line using the
<command>-E</command> and <command>-p</command> flags.
For instance, the following starts a shell containing the packages
<literal>sqlite</literal> and <literal>libX11</literal>:
<screen>
@ -238,6 +244,14 @@ $ nix-shell -p sqlite xorg.libX11
… -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib …
</screen>
Note that <command>-p</command> accepts multiple full nix expressions that
are valid in the <literal>buildInputs = [ ... ]</literal> shown above,
not only package names. So the following is also legal:
<screen>
$ nix-shell -p sqlite 'git.override { withManual = false; }'
</screen>
The <command>-p</command> flag looks up Nixpkgs in the Nix search
path. You can override it by passing <option>-I</option> or setting
<envar>NIX_PATH</envar>. For example, the following gives you a shell

96
doc/manual/command-ref/nix-store.xml
View file

@ -215,6 +215,48 @@ printed.)</para>
</variablelist>
<para>Special exit codes:</para>
<variablelist>
<varlistentry><term><literal>100</literal></term>
<listitem><para>Generic build failure, the builder process
returned with a non-zero exit code.</para></listitem>
</varlistentry>
<varlistentry><term><literal>101</literal></term>
<listitem><para>Build timeout, the build was aborted because it
did not complete within the specified <link
linkend='conf-timeout'><literal>timeout</literal></link>.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>102</literal></term>
<listitem><para>Hash mismatch, the build output was rejected
because it does not match the specified <link
linkend="fixed-output-drvs"><varname>outputHash</varname></link>.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>104</literal></term>
<listitem><para>Not deterministic, the build succeeded in check
mode but the resulting output is not binary reproducable.</para>
</listitem>
</varlistentry>
</variablelist>
<para>With the <option>--keep-going</option> flag it's possible for
multiple failures to occur, in this case the 1xx status codes are or combined
using binary or. <screen>
1100100
^^^^
|||`- timeout
||`-- output hash mismatch
|`--- build failure
`---- not deterministic
</screen></para>
</refsection>
@ -883,6 +925,60 @@ $ nix-store --add ./foo.c
</refsection>
<!--######################################################################-->
<refsection><title>Operation <option>--add-fixed</option></title>
<refsection><title>Synopsis</title>
<cmdsynopsis>
<command>nix-store</command>
<arg><option>--recursive</option></arg>
<arg choice='plain'><option>--add-fixed</option></arg>
<arg choice='plain'><replaceable>algorithm</replaceable></arg>
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
</cmdsynopsis>
</refsection>
<refsection><title>Description</title>
<para>The operation <option>--add-fixed</option> adds the specified paths to
the Nix store. Unlike <option>--add</option> paths are registered using the
specified hashing algorithm, resulting in the same output path as a fixed output
derivation. This can be used for sources that are not available from a public
url or broke since the download expression was written.
</para>
<para>This operation has the following options:
<variablelist>
<varlistentry><term><option>--recursive</option></term>
<listitem><para>
Use recursive instead of flat hashing mode, used when adding directories
to the store.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsection>
<refsection><title>Example</title>
<screen>
$ nix-store --add-fixed sha256 ./hello-2.10.tar.gz
/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz</screen>
</refsection>
</refsection>
<!--######################################################################-->

28
doc/manual/command-ref/opt-common.xml
View file

@ -107,14 +107,22 @@
<varlistentry xml:id="opt-max-jobs"><term><option>--max-jobs</option> / <option>-j</option>
<replaceable>number</replaceable></term>
<listitem><para>Sets the maximum number of build jobs that Nix will
<listitem>
<para>Sets the maximum number of build jobs that Nix will
perform in parallel to the specified number. Specify
<literal>auto</literal> to use the number of CPUs in the system.
The default is specified by the <link
linkend='conf-max-jobs'><literal>max-jobs</literal></link>
configuration setting, which itself defaults to
<literal>1</literal>. A higher value is useful on SMP systems or to
exploit I/O latency.</para></listitem>
exploit I/O latency.</para>
<para> Setting it to <literal>0</literal> disallows building on the local
machine, which is useful when you want builds to happen only on remote
builders.</para>
</listitem>
</varlistentry>
@ -235,9 +243,10 @@
<varlistentry><term><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
<listitem><para>This option is accepted by
<command>nix-env</command>, <command>nix-instantiate</command> and
<command>nix-build</command>. When evaluating Nix expressions, the
expression evaluator will automatically try to call functions that
<command>nix-env</command>, <command>nix-instantiate</command>,
<command>nix-shell</command> and <command>nix-build</command>.
When evaluating Nix expressions, the expression evaluator will
automatically try to call functions that
it encounters. It can automatically call functions for which every
argument has a <link linkend='ss-functions'>default value</link>
(e.g., <literal>{ <replaceable>argName</replaceable> ?
@ -314,7 +323,14 @@
Nix expressions to be parsed and evaluated, rather than as a list
of file names of Nix expressions.
(<command>nix-instantiate</command>, <command>nix-build</command>
and <command>nix-shell</command> only.)</para></listitem>
and <command>nix-shell</command> only.)</para>
<para>For <command>nix-shell</command>, this option is commonly used
to give you a shell in which you can build the packages returned
by the expression. If you want to get a shell which contain the
<emphasis>built</emphasis> packages ready for use, give your
expression to the <command>nix-shell -p</command> convenience flag
instead.</para></listitem>
</varlistentry>

39
doc/manual/expressions/advanced-attributes.xml
View file

@ -11,7 +11,7 @@ attributes.</para>
<variablelist>
<varlistentry><term><varname>allowedReferences</varname></term>
<varlistentry xml:id="adv-attr-allowedReferences"><term><varname>allowedReferences</varname></term>
<listitem><para>The optional attribute
<varname>allowedReferences</varname> specifies a list of legal
@ -32,7 +32,7 @@ allowedReferences = [];
</varlistentry>
<varlistentry><term><varname>allowedRequisites</varname></term>
<varlistentry xml:id="adv-attr-allowedRequisites"><term><varname>allowedRequisites</varname></term>
<listitem><para>This attribute is similar to
<varname>allowedReferences</varname>, but it specifies the legal
@ -50,7 +50,7 @@ allowedRequisites = [ foobar ];
</varlistentry>
<varlistentry><term><varname>disallowedReferences</varname></term>
<varlistentry xml:id="adv-attr-disallowedReferences"><term><varname>disallowedReferences</varname></term>
<listitem><para>The optional attribute
<varname>disallowedReferences</varname> specifies a list of illegal
@ -67,7 +67,7 @@ disallowedReferences = [ foo ];
</varlistentry>
<varlistentry><term><varname>disallowedRequisites</varname></term>
<varlistentry xml:id="adv-attr-disallowedRequisites"><term><varname>disallowedRequisites</varname></term>
<listitem><para>This attribute is similar to
<varname>disallowedReferences</varname>, but it specifies illegal
@ -85,7 +85,7 @@ disallowedRequisites = [ foobar ];
</varlistentry>
<varlistentry><term><varname>exportReferencesGraph</varname></term>
<varlistentry xml:id="adv-attr-exportReferencesGraph"><term><varname>exportReferencesGraph</varname></term>
<listitem><para>This attribute allows builders access to the
references graph of their inputs. The attribute is a list of
@ -124,7 +124,7 @@ derivation {
</varlistentry>
<varlistentry><term><varname>impureEnvVars</varname></term>
<varlistentry xml:id="adv-attr-impureEnvVars"><term><varname>impureEnvVars</varname></term>
<listitem><para>This attribute allows you to specify a list of
environment variables that should be passed from the environment
@ -158,9 +158,9 @@ impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ];
<varlistentry xml:id="fixed-output-drvs">
<term><varname>outputHash</varname></term>
<term><varname>outputHashAlgo</varname></term>
<term><varname>outputHashMode</varname></term>
<term xml:id="adv-attr-outputHash"><varname>outputHash</varname></term>
<term xml:id="adv-attr-outputHashAlgo"><varname>outputHashAlgo</varname></term>
<term xml:id="adv-attr-outputHashMode"><varname>outputHashMode</varname></term>
<listitem><para>These attributes declare that the derivation is a
so-called <emphasis>fixed-output derivation</emphasis>, which
@ -282,7 +282,7 @@ stdenv.mkDerivation {
</varlistentry>
<varlistentry><term><varname>passAsFile</varname></term>
<varlistentry xml:id="adv-attr-passAsFile"><term><varname>passAsFile</varname></term>
<listitem><para>A list of names of attributes that should be
passed via files rather than environment variables. For example,
@ -309,7 +309,7 @@ big = "a very long string";
</varlistentry>
<varlistentry><term><varname>preferLocalBuild</varname></term>
<varlistentry xml:id="adv-attr-preferLocalBuild"><term><varname>preferLocalBuild</varname></term>
<listitem><para>If this attribute is set to
<literal>true</literal> and <link
@ -323,14 +323,25 @@ big = "a very long string";
</varlistentry>
<varlistentry><term><varname>allowSubstitutes</varname></term>
<varlistentry xml:id="adv-attr-allowSubstitutes"><term><varname>allowSubstitutes</varname></term>
<listitem><para>If this attribute is set to
<listitem>
<para>If this attribute is set to
<literal>false</literal>, then Nix will always build this
derivation; it will not try to substitute its outputs. This is
useful for very trivial derivations (such as
<function>writeText</function> in Nixpkgs) that are cheaper to
build than to substitute from a binary cache.</para></listitem>
build than to substitute from a binary cache.</para>
<note><para>You need to have a builder configured which satisfies
the derivation’s <literal>system</literal> attribute, since the
derivation cannot be substituted. Thus it is usually a good idea
to align <literal>system</literal> with
<literal>builtins.currentSystem</literal> when setting
<literal>allowSubstitutes</literal> to <literal>false</literal>.
For most trivial derivations this should be the case.
</para></note>
</listitem>
</varlistentry>

91
doc/manual/expressions/builtins.xml
View file

@ -170,18 +170,6 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
</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-concatLists'>
<term><function>builtins.concatLists</function>
<replaceable>lists</replaceable></term>
@ -301,7 +289,7 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
<listitem><para>Return element <replaceable>n</replaceable> from
the list <replaceable>xs</replaceable>. Elements are counted
starting from 0. A fatal error occurs in the index is out of
starting from 0. A fatal error occurs if the index is out of
bounds.</para></listitem>
</varlistentry>
@ -347,7 +335,7 @@ stdenv.mkDerivation { … }
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>tarball-ttl <replaceable>number of seconds to cache</replaceable></literal>.
<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
@ -425,6 +413,13 @@ stdenv.mkDerivation { … }
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>
@ -438,6 +433,14 @@ stdenv.mkDerivation { … }
}</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>
@ -484,11 +487,8 @@ stdenv.mkDerivation { … }
<title>Fetching a tag</title>
<programlisting>builtins.fetchGit {
url = "https://github.com/nixos/nix.git";
ref = "tags/1.9";
ref = "refs/tags/1.9";
}</programlisting>
<note><para>Due to a bug (<link
xlink:href="https://github.com/NixOS/nix/issues/2385">#2385</link>),
only non-annotated tags can be fetched.</para></note>
</example>
<example>
@ -498,7 +498,7 @@ stdenv.mkDerivation { … }
fetch the latest version of a remote branch.
</para>
<note><para>Nix will refetch the branch in accordance to
<option>tarball-ttl</option>.</para></note>
<xref linkend="conf-tarball-ttl" />.</para></note>
<note><para>This behavior is disabled in
<emphasis>Pure evaluation mode</emphasis>.</para></note>
<programlisting>builtins.fetchGit {
@ -705,6 +705,19 @@ builtins.genList (x: x * x) 5
</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>
@ -733,6 +746,11 @@ builtins.genList (x: x * x) 5
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
@ -1102,6 +1120,16 @@ Evaluates to <literal>[ "foo" ]</literal>.
</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>
@ -1247,6 +1275,19 @@ 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>
@ -1440,7 +1481,7 @@ in foo</programlisting>
<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>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>
@ -1579,12 +1620,18 @@ stdenv.mkDerivation (rec {
<term><function>builtins.tryEval</function>
<replaceable>e</replaceable></term>
<listitem><para>Try to evaluate <replaceable>e</replaceable>.
<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.
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>

22
doc/manual/expressions/language-constructs.xml
View file

@ -43,7 +43,7 @@ encountered</quote>).</para></footnote>.</para>
<simplesect xml:id="sect-let-expressions"><title>Let-expressions</title>
<para>A let-expression allows you define local variables for an
<para>A let-expression allows you to define local variables for an
expression. For instance,
<programlisting>
@ -217,7 +217,25 @@ but can also be written as:
ellipsis(<literal>...</literal>) as you can access attribute names as
<literal>a</literal>, using <literal>args.a</literal>, which was given as an
additional attribute to the function.
</para></listitem>
</para>
<warning>
<para>
The <literal>args@</literal> expression is bound to the argument passed to the function which
means that attributes with defaults that aren't explicitly specified in the function call
won't cause an evaluation error, but won't exist in <literal>args</literal>.
</para>
<para>
For instance
<programlisting>
let
function = args@{ a ? 23, ... }: args;
in
function {}
</programlisting>
will evaluate to an empty attribute set.
</para>
</warning></listitem>
</itemizedlist>

103
doc/manual/expressions/language-operators.xml
View file

@ -15,13 +15,16 @@ weakest binding).</para>
<tgroup cols='3'>
<thead>
<row>
<entry>Name</entry>
<entry>Syntax</entry>
<entry>Associativity</entry>
<entry>Description</entry>
<entry>Precedence</entry>
</row>
</thead>
<tbody>
<row>
<entry>Select</entry>
<entry><replaceable>e</replaceable> <literal>.</literal>
<replaceable>attrpath</replaceable>
[ <literal>or</literal> <replaceable>def</replaceable> ]
@ -33,19 +36,25 @@ weakest binding).</para>
dot-separated list of attribute names.) If the attribute
doesn’t exist, return <replaceable>def</replaceable> if
provided, otherwise abort evaluation.</entry>
<entry>1</entry>
</row>
<row>
<entry>Application</entry>
<entry><replaceable>e1</replaceable> <replaceable>e2</replaceable></entry>
<entry>left</entry>
<entry>Call function <replaceable>e1</replaceable> with
argument <replaceable>e2</replaceable>.</entry>
<entry>2</entry>
</row>
<row>
<entry>Arithmetic Negation</entry>
<entry><literal>-</literal> <replaceable>e</replaceable></entry>
<entry>none</entry>
<entry>Arithmetic negation.</entry>
<entry>3</entry>
</row>
<row>
<entry>Has Attribute</entry>
<entry><replaceable>e</replaceable> <literal>?</literal>
<replaceable>attrpath</replaceable></entry>
<entry>none</entry>
@ -53,34 +62,69 @@ weakest binding).</para>
the attribute denoted by <replaceable>attrpath</replaceable>;
return <literal>true</literal> or
<literal>false</literal>.</entry>
<entry>4</entry>
</row>
<row>
<entry>List Concatenation</entry>
<entry><replaceable>e1</replaceable> <literal>++</literal> <replaceable>e2</replaceable></entry>
<entry>right</entry>
<entry>List concatenation.</entry>
<entry>5</entry>
</row>
<row>
<entry>Multiplication</entry>
<entry>
<replaceable>e1</replaceable> <literal>*</literal> <replaceable>e2</replaceable>,
</entry>
<entry>left</entry>
<entry>Arithmetic multiplication.</entry>
<entry>6</entry>
</row>
<row>
<entry>Division</entry>
<entry>
<replaceable>e1</replaceable> <literal>/</literal> <replaceable>e2</replaceable>
</entry>
<entry>left</entry>
<entry>Arithmetic multiplication and division.</entry>
<entry>Arithmetic division.</entry>
<entry>6</entry>
</row>
<row>
<entry>Addition</entry>
<entry>
<replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable>
</entry>
<entry>left</entry>
<entry>Arithmetic addition.</entry>
<entry>7</entry>
</row>
<row>
<entry>Subtraction</entry>
<entry>
<replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable>,
<replaceable>e1</replaceable> <literal>-</literal> <replaceable>e2</replaceable>
</entry>
<entry>left</entry>
<entry>Arithmetic addition and subtraction. String or path concatenation (only by <literal>+</literal>).</entry>
<entry>Arithmetic subtraction.</entry>
<entry>7</entry>
</row>
<row>
<entry>String Concatenation</entry>
<entry>
<replaceable>string1</replaceable> <literal>+</literal> <replaceable>string2</replaceable>
</entry>
<entry>left</entry>
<entry>String concatenation.</entry>
<entry>7</entry>
</row>
<row>
<entry>Not</entry>
<entry><literal>!</literal> <replaceable>e</replaceable></entry>
<entry>none</entry>
<entry>Boolean negation.</entry>
<entry>8</entry>
</row>
<row>
<entry>Update</entry>
<entry><replaceable>e1</replaceable> <literal>//</literal>
<replaceable>e2</replaceable></entry>
<entry>right</entry>
@ -89,47 +133,90 @@ weakest binding).</para>
<replaceable>e2</replaceable> (with the latter taking
precedence over the former in case of equally named
attributes).</entry>
<entry>9</entry>
</row>
<row>
<entry>Less Than</entry>
<entry>
<replaceable>e1</replaceable> <literal>&lt;</literal> <replaceable>e2</replaceable>,
<replaceable>e1</replaceable> <literal>&gt;</literal> <replaceable>e2</replaceable>,
<replaceable>e1</replaceable> <literal>&lt;=</literal> <replaceable>e2</replaceable>,
</entry>
<entry>none</entry>
<entry>Arithmetic comparison.</entry>
<entry>10</entry>
</row>
<row>
<entry>Less Than or Equal To</entry>
<entry>
<replaceable>e1</replaceable> <literal>&lt;=</literal> <replaceable>e2</replaceable>
</entry>
<entry>none</entry>
<entry>Arithmetic comparison.</entry>
<entry>10</entry>
</row>
<row>
<entry>Greater Than</entry>
<entry>
<replaceable>e1</replaceable> <literal>&gt;</literal> <replaceable>e2</replaceable>
</entry>
<entry>none</entry>
<entry>Arithmetic comparison.</entry>
<entry>10</entry>
</row>
<row>
<entry>Greater Than or Equal To</entry>
<entry>
<replaceable>e1</replaceable> <literal>&gt;=</literal> <replaceable>e2</replaceable>
</entry>
<entry>none</entry>
<entry>Arithmetic comparison.</entry>
<entry>10</entry>
</row>
<row>
<entry>Equality</entry>
<entry>
<replaceable>e1</replaceable> <literal>==</literal> <replaceable>e2</replaceable>
</entry>
<entry>none</entry>
<entry>Equality.</entry>
<entry>11</entry>
</row>
<row>
<entry>Inequality</entry>
<entry>
<replaceable>e1</replaceable> <literal>==</literal> <replaceable>e2</replaceable>,
<replaceable>e1</replaceable> <literal>!=</literal> <replaceable>e2</replaceable>
</entry>
<entry>none</entry>
<entry>Equality and inequality.</entry>
<entry>Inequality.</entry>
<entry>11</entry>
</row>
<row>
<entry>Logical AND</entry>
<entry><replaceable>e1</replaceable> <literal>&amp;&amp;</literal>
<replaceable>e2</replaceable></entry>
<entry>left</entry>
<entry>Logical AND.</entry>
<entry>12</entry>
</row>
<row>
<entry>Logical OR</entry>
<entry><replaceable>e1</replaceable> <literal>||</literal>
<replaceable>e2</replaceable></entry>
<entry>left</entry>
<entry>Logical OR.</entry>
<entry>13</entry>
</row>
<row>
<entry>Logical Implication</entry>
<entry><replaceable>e1</replaceable> <literal>-></literal>
<replaceable>e2</replaceable></entry>
<entry>none</entry>
<entry>Logical implication (equivalent to
<literal>!<replaceable>e1</replaceable> ||
<replaceable>e2</replaceable></literal>).</entry>
<entry>14</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>

2
doc/manual/expressions/simple-building-testing.xml
View file

@ -43,7 +43,7 @@ use <command>nix-build</command>’s <option
linkend='opt-out-link'>-o</option> switch to give the symlink another
name.</para>
<para>Nix has a transactional semantics. Once a build finishes
<para>Nix has transactional semantics. Once a build finishes
successfully, Nix makes a note of this in its database: it registers
that the path denoted by <envar>out</envar> is now
<quote>valid</quote>. If you try to build the derivation again, Nix

18
doc/manual/installation/env-variables.xml
View file

@ -67,5 +67,23 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
</screen>
</section>
<section xml:id="sec-installer-proxy-settings">
<title>Proxy Environment Variables</title>
<para>The Nix installer has special handling for these proxy-related
environment variables:
<varname>http_proxy</varname>, <varname>https_proxy</varname>,
<varname>ftp_proxy</varname>, <varname>no_proxy</varname>,
<varname>HTTP_PROXY</varname>, <varname>HTTPS_PROXY</varname>,
<varname>FTP_PROXY</varname>, <varname>NO_PROXY</varname>.
</para>
<para>If any of these variables are set when running the Nix installer,
then the installer will create an override file at
<filename>/etc/systemd/system/nix-daemon.service.d/override.conf</filename>
so <command>nix-daemon</command> will use them.
</para>
</section>
</section>
</chapter>

6
doc/manual/installation/prerequisites-source.xml
View file

@ -13,7 +13,7 @@
<listitem><para>Bash Shell. The <literal>./configure</literal> script
relies on bashisms, so Bash is required.</para></listitem>
<listitem><para>A version of GCC or Clang that supports C++14.</para></listitem>
<listitem><para>A version of GCC or Clang that supports C++17.</para></listitem>
<listitem><para><command>pkg-config</command> to locate
dependencies. If your distribution does not provide it, you can get
@ -54,6 +54,10 @@
1.66.0 or higher. It can be obtained from the official web site
<link xlink:href="https://www.boost.org/" />.</para></listitem>
<listitem><para>The <literal>editline</literal> library of version
1.14.0 or higher. It can be obtained from the its repository
<link xlink:href="https://github.com/troglobit/editline" />.</para></listitem>
<listitem><para>The <command>xmllint</command> and
<command>xsltproc</command> programs to build this manual and the
man-pages. These are part of the <literal>libxml2</literal> and

6
doc/manual/packages/basic-package-mgmt.xml
View file

@ -24,11 +24,11 @@ symlinks to the files of the active applications. </para>
<para>Components are installed from a set of <emphasis>Nix
expressions</emphasis> that tell Nix how to build those packages,
including, if necessary, their dependencies. There is a collection of
Nix expressions called the Nix Package collection that contains
Nix expressions called the Nixpkgs package collection that contains
packages ranging from basic development stuff such as GCC and Glibc,
to end-user applications like Mozilla Firefox. (Nix is however not
tied to the Nix Package collection; you could write your own Nix
expressions based on it, or completely new ones.)</para>
tied to the Nixpkgs package collection; you could write your own Nix
expressions based on Nixpkgs, or completely new ones.)</para>
<para>You can manually download the latest version of Nixpkgs from
<link xlink:href='http://nixos.org/nixpkgs/download.html'/>. However,

3
doc/manual/packages/channels.xml
View file

@ -17,6 +17,9 @@ a set of Nix expressions and a manifest. Using the command <link
linkend="sec-nix-channel"><command>nix-channel</command></link> you
can automatically stay up to date with whatever is available at that
URL.</para>
<para>To see the list of official NixOS channels, visit <link
xlink:href="https://nixos.org/channels" />.</para>
<para>You can “subscribe” to a channel using
<command>nix-channel --add</command>, e.g.,

11
doc/manual/packages/garbage-collection.xml
View file

@ -52,12 +52,13 @@ garbage collector as follows:
<screen>
$ nix-store --gc</screen>
The behaviour of the gargage collector is affected by the <literal>keep-
derivations</literal> (default: true) and <literal>keep-outputs</literal>
The behaviour of the gargage collector is affected by the
<literal>keep-derivations</literal> (default: true) and <literal>keep-outputs</literal>
(default: false) options in the Nix configuration file. The defaults will ensure
that all derivations that are not build-time dependencies of garbage collector roots
will be collected but that all output paths that are not runtime dependencies
will be collected. (This is usually what you want, but while you are developing
that all derivations that are build-time dependencies of garbage collector roots
will be kept and that all output paths that are runtime dependencies
will be kept as well. All other derivations or paths will be collected.
(This is usually what you want, but while you are developing
it may make sense to keep outputs to ensure that rebuild times are quick.)
If you are feeling uncertain, you can also first view what files would

5
doc/manual/packages/s3-substituter.xml
View file

@ -113,7 +113,7 @@ the S3 URL:</para>
exactly <uri>s3://example-nix-cache</uri>.</para>
<para>Nix will use the <link
xlink:href="https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default.">default
xlink:href="https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html">default
credential provider chain</link> for authenticating requests to
Amazon S3.</para>
@ -138,7 +138,7 @@ the S3 URL:</para>
be <uri>s3://example-nix-cache</uri>.</para>
<para>Nix will use the <link
xlink:href="https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default.">default
xlink:href="https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html">default
credential provider chain</link> for authenticating requests to
Amazon S3.</para>
@ -159,7 +159,6 @@ the S3 URL:</para>
"s3:ListBucket",
"s3:ListBucketMultipartUploads",
"s3:ListMultipartUploadParts",
"s3:ListObjects",
"s3:PutObject"
],
"Resource": [

1
doc/manual/release-notes/release-notes.xml
View file

@ -12,6 +12,7 @@
</partintro>
-->
<xi:include href="rl-2.3.xml" />
<xi:include href="rl-2.2.xml" />
<xi:include href="rl-2.1.xml" />
<xi:include href="rl-2.0.xml" />

91
doc/manual/release-notes/rl-2.3.xml Normal file
View file

@ -0,0 +1,91 @@
<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-relnotes-2.3">
<title>Release 2.3 (2019-09-04)</title>
<para>This is primarily a bug fix release. However, it makes some
incompatible changes:</para>
<itemizedlist>
<listitem>
<para>Nix now uses BSD file locks instead of POSIX file
locks. Because of this, you should not use Nix 2.3 and previous
releases at the same time on a Nix store.</para>
</listitem>
</itemizedlist>
<para>It also has the following changes:</para>
<itemizedlist>
<listitem>
<para><function>builtins.fetchGit</function>'s <varname>ref</varname>
argument now allows specifying an absolute remote ref.
Nix will automatically prefix <varname>ref</varname> with
<literal>refs/heads</literal> only if <varname>ref</varname> doesn't
already begin with <literal>refs/</literal>.
</para>
</listitem>
<listitem>
<para>The installer now enables sandboxing by default on Linux when the
system has the necessary kernel support.
</para>
</listitem>
<listitem>
<para>The <literal>max-jobs</literal> setting now defaults to 1.</para>
</listitem>
<listitem>
<para>New builtin functions:
<literal>builtins.isPath</literal>,
<literal>builtins.hashFile</literal>.
</para>
</listitem>
<listitem>
<para>The <command>nix</command> command has a new
<option>--print-build-logs</option> (<option>-L</option>) flag to
print build log output to stderr, rather than showing the last log
line in the progress bar. To distinguish between concurrent
builds, log lines are prefixed by the name of the package.
</para>
</listitem>
<listitem>
<para>Builds are now executed in a pseudo-terminal, and the
<envar>TERM</envar> environment variable is set to
<literal>xterm-256color</literal>. This allows many programs
(e.g. <command>gcc</command>, <command>clang</command>,
<command>cmake</command>) to print colorized log output.</para>
</listitem>
<listitem>
<para>Add <option>--no-net</option> convenience flag. This flag
disables substituters; sets the <literal>tarball-ttl</literal>
setting to infinity (ensuring that any previously downloaded files
are considered current); and disables retrying downloads and sets
the connection timeout to the minimum. This flag is enabled
automatically if there are no configured non-loopback network
interfaces.</para>
</listitem>
<listitem>
<para>Add a <literal>post-build-hook</literal> setting to run a
program after a build has succeeded.</para>
</listitem>
<listitem>
<para>Add a <literal>trace-function-calls</literal> setting to log
the duration of Nix function calls to stderr.</para>
</listitem>
</itemizedlist>
</section>