diff options
Diffstat (limited to 'doc/manual')
214 files changed, 10547 insertions, 18623 deletions
diff --git a/doc/manual/advanced-topics/advanced-topics.xml b/doc/manual/advanced-topics/advanced-topics.xml deleted file mode 100644 index 871b7eb1d..000000000 --- a/doc/manual/advanced-topics/advanced-topics.xml +++ /dev/null @@ -1,14 +0,0 @@ -<part xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="part-advanced-topics" - version="5.0"> - -<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> diff --git a/doc/manual/advanced-topics/cores-vs-jobs.xml b/doc/manual/advanced-topics/cores-vs-jobs.xml deleted file mode 100644 index 4d58ac7c5..000000000 --- a/doc/manual/advanced-topics/cores-vs-jobs.xml +++ /dev/null @@ -1,121 +0,0 @@ -<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> diff --git a/doc/manual/advanced-topics/diff-hook.xml b/doc/manual/advanced-topics/diff-hook.xml deleted file mode 100644 index f01ab71b3..000000000 --- a/doc/manual/advanced-topics/diff-hook.xml +++ /dev/null @@ -1,205 +0,0 @@ -<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 <nixpkgs> {}) 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 >&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 -this derivation 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 -this derivation 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 -< 8108 ---- -> 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 -this derivation 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> diff --git a/doc/manual/advanced-topics/distributed-builds.xml b/doc/manual/advanced-topics/distributed-builds.xml deleted file mode 100644 index 9ac4a92cd..000000000 --- a/doc/manual/advanced-topics/distributed-builds.xml +++ /dev/null @@ -1,190 +0,0 @@ -<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-distributed-builds'> - -<title>Remote Builds</title> - -<para>Nix supports remote builds, where a local Nix installation can -forward Nix builds to other machines. This allows multiple builds to -be performed in parallel and allows Nix to perform multi-platform -builds in a semi-transparent way. For instance, if you perform a -build for a <literal>x86_64-darwin</literal> on an -<literal>i686-linux</literal> machine, Nix can automatically forward -the build to a <literal>x86_64-darwin</literal> machine, if -available.</para> - -<para>To forward a build to a remote machine, it’s required that the -remote machine is accessible via SSH and that it has Nix -installed. You can test whether connecting to the remote Nix instance -works, e.g. - -<screen> -$ nix ping-store --store ssh://mac -</screen> - -will try to connect to the machine named <literal>mac</literal>. It is -possible to specify an SSH identity file as part of the remote store -URI, e.g. - -<screen> -$ nix ping-store --store ssh://mac?ssh-key=/home/alice/my-key -</screen> - -Since builds should be non-interactive, the key should not have a -passphrase. Alternatively, you can load identities ahead of time into -<command>ssh-agent</command> or <command>gpg-agent</command>.</para> - -<para>If you get the error - -<screen> -bash: nix-store: command not found -error: cannot connect to 'mac' -</screen> - -then you need to ensure that the <envar>PATH</envar> of -non-interactive login shells contains Nix.</para> - -<warning><para>If you are building via the Nix daemon, it is the Nix -daemon user account (that is, <literal>root</literal>) that should -have SSH access to the remote machine. If you can’t or don’t want to -configure <literal>root</literal> to be able to access to remote -machine, you can use a private Nix store instead by passing -e.g. <literal>--store ~/my-nix</literal>.</para></warning> - -<para>The list of remote machines can be specified on the command line -or in the Nix configuration file. The former is convenient for -testing. For example, the following command allows you to build a -derivation for <literal>x86_64-darwin</literal> on a Linux machine: - -<screen> -$ uname -Linux - -$ nix build \ - '(with import <nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \ - --builders 'ssh://mac x86_64-darwin' -[1/0/1 built, 0.0 MiB DL] building foo on ssh://mac - -$ cat ./result -Darwin -</screen> - -It is possible to specify multiple builders separated by a semicolon -or a newline, e.g. - -<screen> - --builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd' -</screen> -</para> - -<para>Each machine specification consists of the following elements, -separated by spaces. Only the first element is required. -To leave a field at its default, set it to <literal>-</literal>. - -<orderedlist> - - <listitem><para>The URI of the remote store in the format - <literal>ssh://[<replaceable>username</replaceable>@]<replaceable>hostname</replaceable></literal>, - e.g. <literal>ssh://nix@mac</literal> or - <literal>ssh://mac</literal>. For backward compatibility, - <literal>ssh://</literal> may be omitted. The hostname may be an - alias defined in your - <filename>~/.ssh/config</filename>.</para></listitem> - - <listitem><para>A comma-separated list of Nix platform type - identifiers, such as <literal>x86_64-darwin</literal>. It is - possible for a machine to support multiple platform types, e.g., - <literal>i686-linux,x86_64-linux</literal>. If omitted, this - defaults to the local platform type.</para></listitem> - - <listitem><para>The SSH identity file to be used to log in to the - remote machine. If omitted, SSH will use its regular - identities.</para></listitem> - - <listitem><para>The maximum number of builds that Nix will execute - in parallel on the machine. Typically this should be equal to the - number of CPU cores. For instance, the machine - <literal>itchy</literal> in the example will execute up to 8 builds - in parallel.</para></listitem> - - <listitem><para>The “speed factor”, indicating the relative speed of - the machine. If there are multiple machines of the right type, Nix - will prefer the fastest, taking load into account.</para></listitem> - - <listitem><para>A comma-separated list of <emphasis>supported - features</emphasis>. If a derivation has the - <varname>requiredSystemFeatures</varname> attribute, then Nix will - only perform the derivation on a machine that has the specified - features. For instance, the attribute - -<programlisting> -requiredSystemFeatures = [ "kvm" ]; -</programlisting> - - will cause the build to be performed on a machine that has the - <literal>kvm</literal> feature.</para></listitem> - - <listitem><para>A comma-separated list of <emphasis>mandatory - features</emphasis>. A machine will only be used to build a - derivation if all of the machine’s mandatory features appear in the - derivation’s <varname>requiredSystemFeatures</varname> - attribute..</para></listitem> - -</orderedlist> - -For example, the machine specification - -<programlisting> -nix@scratchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 1 kvm -nix@itchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 2 -nix@poochie.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 1 2 kvm benchmark -</programlisting> - -specifies several machines that can perform -<literal>i686-linux</literal> builds. However, -<literal>poochie</literal> will only do builds that have the attribute - -<programlisting> -requiredSystemFeatures = [ "benchmark" ]; -</programlisting> - -or - -<programlisting> -requiredSystemFeatures = [ "benchmark" "kvm" ]; -</programlisting> - -<literal>itchy</literal> cannot do builds that require -<literal>kvm</literal>, but <literal>scratchy</literal> does support -such builds. For regular builds, <literal>itchy</literal> will be -preferred over <literal>scratchy</literal> because it has a higher -speed factor.</para> - -<para>Remote builders can also be configured in -<filename>nix.conf</filename>, e.g. - -<programlisting> -builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd -</programlisting> - -Finally, remote builders can be configured in a separate configuration -file included in <option>builders</option> via the syntax -<literal>@<replaceable>file</replaceable></literal>. For example, - -<programlisting> -builders = @/etc/nix/machines -</programlisting> - -causes the list of machines in <filename>/etc/nix/machines</filename> -to be included. (This is the default.)</para> - -<para>If you want the builders to use caches, you likely want to set -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> diff --git a/doc/manual/advanced-topics/post-build-hook.xml b/doc/manual/advanced-topics/post-build-hook.xml deleted file mode 100644 index 6cc286ee1..000000000 --- a/doc/manual/advanced-topics/post-build-hook.xml +++ /dev/null @@ -1,160 +0,0 @@ -<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 in 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 <nixpkgs> {}).writeText "example" (builtins.toString builtins.currentTime)' -this derivation 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 --realise /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> diff --git a/doc/manual/command-ref/command-ref.xml b/doc/manual/command-ref/command-ref.xml deleted file mode 100644 index cfad9b7d7..000000000 --- a/doc/manual/command-ref/command-ref.xml +++ /dev/null @@ -1,20 +0,0 @@ -<part 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='part-command-ref'> - -<title>Command Reference</title> - -<partintro> -<para>This section lists commands and options that you can use when you -work with Nix.</para> -</partintro> - -<xi:include href="opt-common.xml" /> -<xi:include href="env-common.xml" /> -<xi:include href="main-commands.xml" /> -<xi:include href="utilities.xml" /> -<xi:include href="files.xml" /> - -</part> diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml deleted file mode 100644 index 1fa74a143..000000000 --- a/doc/manual/command-ref/conf-file.xml +++ /dev/null @@ -1,1237 +0,0 @@ -<?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" - version="5"> - -<refmeta> - <refentrytitle>nix.conf</refentrytitle> - <manvolnum>5</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix.conf</refname> - <refpurpose>Nix configuration file</refpurpose> -</refnamediv> - -<refsection><title>Description</title> - -<para>By default Nix reads settings from the following places:</para> - -<para>The system-wide configuration file -<filename><replaceable>sysconfdir</replaceable>/nix/nix.conf</filename> -(i.e. <filename>/etc/nix/nix.conf</filename> on most systems), or -<filename>$NIX_CONF_DIR/nix.conf</filename> if -<envar>NIX_CONF_DIR</envar> is set. Values loaded in this file are not forwarded to the Nix daemon. The -client assumes that the daemon has already loaded them. -</para> - -<para>User-specific configuration files:</para> - -<para> - If <envar>NIX_USER_CONF_FILES</envar> is set, then each path separated by - <literal>:</literal> will be loaded in reverse order. -</para> - -<para> - Otherwise it will look for <filename>nix/nix.conf</filename> files in - <envar>XDG_CONFIG_DIRS</envar> and <envar>XDG_CONFIG_HOME</envar>. - - The default location is <filename>$HOME/.config/nix.conf</filename> if - those environment variables are unset. -</para> - -<para>The configuration files consist of -<literal><replaceable>name</replaceable> = -<replaceable>value</replaceable></literal> pairs, one per line. Other -files can be included with a line like <literal>include -<replaceable>path</replaceable></literal>, where -<replaceable>path</replaceable> is interpreted relative to the current -conf file and a missing file is an error unless -<literal>!include</literal> is used instead. -Comments start with a <literal>#</literal> character. Here is an -example configuration file:</para> - -<programlisting> -keep-outputs = true # Nice for developers -keep-derivations = true # Idem -</programlisting> - -<para>You can override settings on the command line using the -<option>--option</option> flag, e.g. <literal>--option keep-outputs -false</literal>.</para> - -<para>The following settings are currently available: - -<variablelist> - - - <varlistentry xml:id="conf-allowed-uris"><term><literal>allowed-uris</literal></term> - - <listitem> - - <para>A list of URI prefixes to which access is allowed in - restricted evaluation mode. For example, when set to - <literal>https://github.com/NixOS</literal>, builtin functions - such as <function>fetchGit</function> are allowed to access - <literal>https://github.com/NixOS/patchelf.git</literal>.</para> - - </listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-allow-import-from-derivation"><term><literal>allow-import-from-derivation</literal></term> - - <listitem><para>By default, Nix allows you to <function>import</function> from a derivation, - allowing building at evaluation time. With this option set to false, Nix will throw an error - when evaluating an expression that uses this feature, allowing users to ensure their evaluation - will not require any builds to take place.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-allow-new-privileges"><term><literal>allow-new-privileges</literal></term> - - <listitem><para>(Linux-specific.) By default, builders on Linux - cannot acquire new privileges by calling setuid/setgid programs or - programs that have file capabilities. For example, programs such - as <command>sudo</command> or <command>ping</command> will - fail. (Note that in sandbox builds, no such programs are available - unless you bind-mount them into the sandbox via the - <option>sandbox-paths</option> option.) You can allow the - use of such programs by enabling this option. This is impure and - usually undesirable, but may be useful in certain scenarios - (e.g. to spin up containers or set up userspace network interfaces - in tests).</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-allowed-users"><term><literal>allowed-users</literal></term> - - <listitem> - - <para>A list of names of users (separated by whitespace) that - are allowed to connect to the Nix daemon. As with the - <option>trusted-users</option> option, you can specify groups by - prefixing them with <literal>@</literal>. Also, you can allow - all users by specifying <literal>*</literal>. The default is - <literal>*</literal>.</para> - - <para>Note that trusted users are always allowed to connect.</para> - - </listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-auto-optimise-store"><term><literal>auto-optimise-store</literal></term> - - <listitem><para>If set to <literal>true</literal>, Nix - automatically detects files in the store that have identical - contents, and replaces them with hard links to a single copy. - This saves disk space. If set to <literal>false</literal> (the - default), you can still run <command>nix-store - --optimise</command> to get rid of duplicate - files.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-builders"> - <term><literal>builders</literal></term> - <listitem> - <para>A list of machines on which to perform builds. <phrase - condition="manual">See <xref linkend="chap-distributed-builds" - /> for details.</phrase></para> - </listitem> - </varlistentry> - - - <varlistentry xml:id="conf-builders-use-substitutes"><term><literal>builders-use-substitutes</literal></term> - - <listitem><para>If set to <literal>true</literal>, Nix will instruct - remote build machines to use their own binary substitutes if available. In - practical terms, this means that remote hosts will fetch as many build - dependencies as possible from their own substitutes (e.g, from - <literal>cache.nixos.org</literal>), instead of waiting for this host to - upload them all. This can drastically reduce build times if the network - connection between this computer and the remote build host is slow. Defaults - to <literal>false</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-build-users-group"><term><literal>build-users-group</literal></term> - - <listitem><para>This options specifies the Unix group containing - the Nix build user accounts. In multi-user Nix installations, - builds should not be performed by the Nix account since that would - allow users to arbitrarily modify the Nix store and database by - supplying specially crafted builders; and they cannot be performed - by the calling user since that would allow him/her to influence - the build result.</para> - - <para>Therefore, if this option is non-empty and specifies a valid - group, builds will be performed under the user accounts that are a - member of the group specified here (as listed in - <filename>/etc/group</filename>). Those user accounts should not - be used for any other purpose!</para> - - <para>Nix will never run two builds under the same user account at - the same time. This is to prevent an obvious security hole: a - malicious user writing a Nix expression that modifies the build - result of a legitimate Nix expression being built by another user. - Therefore it is good to have as many Nix build user accounts as - you can spare. (Remember: uids are cheap.)</para> - - <para>The build users should have permission to create files in - the Nix store, but not delete them. Therefore, - <filename>/nix/store</filename> should be owned by the Nix - account, its group should be the group specified here, and its - mode should be <literal>1775</literal>.</para> - - <para>If the build users group is empty, builds will be performed - under the uid of the Nix process (that is, the uid of the caller - if <envar>NIX_REMOTE</envar> is empty, the uid under which the Nix - daemon runs if <envar>NIX_REMOTE</envar> is - <literal>daemon</literal>). Obviously, this should not be used in - multi-user settings with untrusted users.</para> - - </listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-compress-build-log"><term><literal>compress-build-log</literal></term> - - <listitem><para>If set to <literal>true</literal> (the default), - build logs written to <filename>/nix/var/log/nix/drvs</filename> - will be compressed on the fly using bzip2. Otherwise, they will - not be compressed.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-connect-timeout"><term><literal>connect-timeout</literal></term> - - <listitem> - - <para>The timeout (in seconds) for establishing connections in - the binary cache substituter. It corresponds to - <command>curl</command>’s <option>--connect-timeout</option> - option.</para> - - </listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-cores"><term><literal>cores</literal></term> - - <listitem><para>Sets the value of the - <envar>NIX_BUILD_CORES</envar> environment variable in the - invocation of builders. Builders can use this variable at their - discretion to control the maximum amount of parallelism. For - instance, in Nixpkgs, if the derivation attribute - <varname>enableParallelBuilding</varname> is set to - <literal>true</literal>, the builder passes the - <option>-j<replaceable>N</replaceable></option> flag to GNU Make. - It can be overridden using the <option - 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> - - <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"> - <term><literal>extra-sandbox-paths</literal></term> - - <listitem><para>A list of additional paths appended to - <option>sandbox-paths</option>. Useful if you want to extend - its default value.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-extra-platforms"><term><literal>extra-platforms</literal></term> - - <listitem><para>Platforms other than the native one which - this machine is capable of building for. This can be useful for - supporting additional architectures on compatible machines: - i686-linux can be built on x86_64-linux machines (and the default - for this setting reflects this); armv7 is backwards-compatible with - armv6 and armv5tel; some aarch64 machines can also natively run - 32-bit ARM code; and qemu-user may be used to support non-native - platforms (though this may be slow and buggy). Most values for this - are not enabled by default because build systems will often - misdetect the target platform and generate incompatible code, so you - may wish to cross-check the results of using this option against - proper natively-built versions of your - derivations.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-extra-substituters"><term><literal>extra-substituters</literal></term> - - <listitem><para>Additional binary caches appended to those - specified in <option>substituters</option>. When used by - unprivileged users, untrusted substituters (i.e. those not listed - in <option>trusted-substituters</option>) are silently - ignored.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-fallback"><term><literal>fallback</literal></term> - - <listitem><para>If set to <literal>true</literal>, Nix will fall - back to building from source if a binary substitute fails. This - is equivalent to the <option>--fallback</option> flag. The - default is <literal>false</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-fsync-metadata"><term><literal>fsync-metadata</literal></term> - - <listitem><para>If set to <literal>true</literal>, changes to the - Nix store metadata (in <filename>/nix/var/nix/db</filename>) are - synchronously flushed to disk. This improves robustness in case - of system crashes, but reduces performance. The default is - <literal>true</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-hashed-mirrors"><term><literal>hashed-mirrors</literal></term> - - <listitem><para>A list of web servers used by - <function>builtins.fetchurl</function> to obtain files by - hash. The default is - <literal>http://tarballs.nixos.org/</literal>. Given a hash type - <replaceable>ht</replaceable> and a base-16 hash - <replaceable>h</replaceable>, Nix will try to download the file - from - <literal>hashed-mirror/<replaceable>ht</replaceable>/<replaceable>h</replaceable></literal>. - This allows files to be downloaded even if they have disappeared - from their original URI. For example, given the default mirror - <literal>http://tarballs.nixos.org/</literal>, when building the derivation - -<programlisting> -builtins.fetchurl { - url = "https://example.org/foo-1.2.3.tar.xz"; - sha256 = "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"; -} -</programlisting> - - Nix will attempt to download this file from - <literal>http://tarballs.nixos.org/sha256/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae</literal> - first. If it is not available there, if will try the original URI.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-http-connections"><term><literal>http-connections</literal></term> - - <listitem><para>The maximum number of parallel TCP connections - used to fetch files from binary caches and by other downloads. It - defaults to 25. 0 means no limit.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-keep-build-log"><term><literal>keep-build-log</literal></term> - - <listitem><para>If set to <literal>true</literal> (the default), - Nix will write the build log of a derivation (i.e. the standard - output and error of its builder) to the directory - <filename>/nix/var/log/nix/drvs</filename>. The build log can be - retrieved using the command <command>nix-store -l - <replaceable>path</replaceable></command>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-keep-derivations"><term><literal>keep-derivations</literal></term> - - <listitem><para>If <literal>true</literal> (default), the garbage - collector will keep the derivations from which non-garbage store - paths were built. If <literal>false</literal>, they will be - deleted unless explicitly registered as a root (or reachable from - other roots).</para> - - <para>Keeping derivation around is useful for querying and - traceability (e.g., it allows you to ask with what dependencies or - options a store path was built), so by default this option is on. - Turn it off to save a bit of disk space (or a lot if - <literal>keep-outputs</literal> is also turned on).</para></listitem> - </varlistentry> - - <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 derivations of - any build-time-only dependencies may be garbage-collected.</para> - - <para>If <literal>true</literal>, when you add a Nix derivation to - a user environment, the path of the derivation is stored in the - user environment. Thus, the derivation will not be - garbage-collected until the user environment generation is deleted - (<command>nix-env --delete-generations</command>). To prevent - build-time-only dependencies from being collected, you should also - turn on <literal>keep-outputs</literal>.</para> - - <para>The difference between this option and - <literal>keep-derivations</literal> is that this one is - “sticky”: it applies to any user environment created while this - option was enabled, while <literal>keep-derivations</literal> - only applies at the moment the garbage collector is - run.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-keep-outputs"><term><literal>keep-outputs</literal></term> - - <listitem><para>If <literal>true</literal>, the garbage collector - will keep the outputs of non-garbage derivations. If - <literal>false</literal> (default), outputs will be deleted unless - they are GC roots themselves (or reachable from other roots).</para> - - <para>In general, outputs must be registered as roots separately. - However, even if the output of a derivation is registered as a - root, the collector will still delete store paths that are used - only at build time (e.g., the C compiler, or source tarballs - downloaded from the network). To prevent it from doing so, set - this option to <literal>true</literal>.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-max-build-log-size"><term><literal>max-build-log-size</literal></term> - - <listitem> - - <para>This option defines the maximum number of bytes that a - builder can write to its stdout/stderr. If the builder exceeds - this limit, it’s killed. A value of <literal>0</literal> (the - default) means that there is no limit.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-max-free"><term><literal>max-free</literal></term> - - <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> - - <varlistentry xml:id="conf-max-jobs"><term><literal>max-jobs</literal></term> - - <listitem><para>This option defines the maximum number of jobs - that Nix will try to build in parallel. The default is - <literal>1</literal>. The special value <literal>auto</literal> - causes Nix to use the number of CPUs in your system. <literal>0</literal> - is useful when using remote builders to prevent any local builds (except for - <literal>preferLocalBuild</literal> derivation attribute which executes locally - regardless). It can be - overridden using the <option - linkend='opt-max-jobs'>--max-jobs</option> (<option>-j</option>) - 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> - - <listitem> - - <para>This option defines the maximum number of seconds that a - builder can go without producing any data on standard output or - standard error. This is useful (for instance in an automated - build system) to catch builds that are stuck in an infinite - loop, or to catch remote builds that are hanging due to network - problems. It can be overridden using the <option - linkend="opt-max-silent-time">--max-silent-time</option> command - line switch.</para> - - <para>The value <literal>0</literal> means that there is no - timeout. This is also the default.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-min-free"><term><literal>min-free</literal></term> - - <listitem> - <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> - - <varlistentry xml:id="conf-narinfo-cache-negative-ttl"><term><literal>narinfo-cache-negative-ttl</literal></term> - - <listitem> - - <para>The TTL in seconds for negative lookups. If a store path is - queried from a substituter but was not found, there will be a - negative lookup cached in the local disk cache database for the - specified duration.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-narinfo-cache-positive-ttl"><term><literal>narinfo-cache-positive-ttl</literal></term> - - <listitem> - - <para>The TTL in seconds for positive lookups. If a store path is - queried from a substituter, the result of the query will be cached - in the local disk cache database including some of the NAR - metadata. The default TTL is a month, setting a shorter TTL for - positive lookups can be useful for binary caches that have - frequent garbage collection, in which case having a more frequent - cache invalidation would prevent trying to pull the path again and - failing with a hash mismatch if the build isn't reproducible. - </para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-netrc-file"><term><literal>netrc-file</literal></term> - - <listitem><para>If set to an absolute path to a <filename>netrc</filename> - file, Nix will use the HTTP authentication credentials in this file when - trying to download from a remote host through HTTP or HTTPS. Defaults to - <filename>$NIX_CONF_DIR/netrc</filename>.</para> - - <para>The <filename>netrc</filename> file consists of a list of - accounts in the following format: - -<screen> -machine <replaceable>my-machine</replaceable> -login <replaceable>my-username</replaceable> -password <replaceable>my-password</replaceable> -</screen> - - For the exact syntax, see <link - xlink:href="https://ec.haxx.se/usingcurl-netrc.html">the - <literal>curl</literal> documentation.</link></para> - - <note><para>This must be an absolute path, and <literal>~</literal> - is not resolved. For example, <filename>~/.netrc</filename> won't - resolve to your home directory's <filename>.netrc</filename>.</para></note> - </listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-plugin-files"> - <term><literal>plugin-files</literal></term> - <listitem> - <para> - A list of plugin files to be loaded by Nix. Each of these - files will be dlopened by Nix, allowing them to affect - execution through static initialization. In particular, these - plugins may construct static instances of RegisterPrimOp to - add new primops or constants to the expression language, - RegisterStoreImplementation to add new store implementations, - RegisterCommand to add new subcommands to the - <literal>nix</literal> command, and RegisterSetting to add new - nix config settings. See the constructors for those types for - more details. - </para> - <para> - Since these files are loaded into the same address space as - Nix itself, they must be DSOs compatible with the instance of - Nix running at the time (i.e. compiled against the same - headers, not linked to any incompatible libraries). They - should not be linked to any Nix libs directly, as those will - be available already at load time. - </para> - <para> - If an entry in the list is a directory, all files in the - directory are loaded as plugins (non-recursively). - </para> - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-pre-build-hook"><term><literal>pre-build-hook</literal></term> - - <listitem> - - - <para>If set, the path to a program that can set extra - derivation-specific settings for this system. This is used for settings - that can't be captured by the derivation model itself and are too variable - between different versions of the same system to be hard-coded into nix. - </para> - - <para>The hook is passed the derivation path and, if sandboxes are enabled, - the sandbox directory. It can then modify the sandbox and send a series of - commands to modify various settings to stdout. The currently recognized - commands are:</para> - - <variablelist> - <varlistentry xml:id="extra-sandbox-paths"> - <term><literal>extra-sandbox-paths</literal></term> - - <listitem> - - <para>Pass a list of files and directories to be included in the - sandbox for this build. One entry per line, terminated by an empty - line. Entries have the same format as - <literal>sandbox-paths</literal>.</para> - - </listitem> - - </varlistentry> - </variablelist> - </listitem> - - </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 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> - - <listitem><para>If set to <literal>true</literal> (the default), - any non-content-addressed path added or copied to the Nix store - (e.g. when substituting from a binary cache) must have a valid - signature, that is, be signed using one of the keys listed in - <option>trusted-public-keys</option> or - <option>secret-key-files</option>. Set to <literal>false</literal> - to disable signature checking.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-restrict-eval"><term><literal>restrict-eval</literal></term> - - <listitem> - - <para>If set to <literal>true</literal>, the Nix evaluator will - not allow access to any files outside of the Nix search path (as - set via the <envar>NIX_PATH</envar> environment variable or the - <option>-I</option> option), or to URIs outside of - <option>allowed-uri</option>. The default is - <literal>false</literal>.</para> - - </listitem> - - </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> - - <listitem><para>If set to <literal>true</literal>, builds will be - performed in a <emphasis>sandboxed environment</emphasis>, i.e., - they’re isolated from the normal file system hierarchy and will - only see their dependencies in the Nix store, the temporary build - directory, private versions of <filename>/proc</filename>, - <filename>/dev</filename>, <filename>/dev/shm</filename> and - <filename>/dev/pts</filename> (on Linux), and the paths configured with the - <link linkend='conf-sandbox-paths'><literal>sandbox-paths</literal> - option</link>. This is useful to prevent undeclared dependencies - on files in directories such as <filename>/usr/bin</filename>. In - addition, on Linux, builds run in private PID, mount, network, IPC - and UTS namespaces to isolate them from other processes in the - system (except that fixed-output derivations do not run in private - network namespace to ensure they can access the network).</para> - - <para>Currently, sandboxing only work on Linux and macOS. The use - of a sandbox requires that Nix is run as root (so you should use - the <link linkend='conf-build-users-group'>“build users” - feature</link> to perform the actual builds under different users - than root).</para> - - <para>If this option is set to <literal>relaxed</literal>, then - fixed-output derivations and derivations that have the - <varname>__noChroot</varname> attribute set to - <literal>true</literal> do not run in sandboxes.</para> - - <para>The default is <literal>true</literal> on Linux and - <literal>false</literal> on all other platforms.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-sandbox-dev-shm-size"><term><literal>sandbox-dev-shm-size</literal></term> - - <listitem><para>This option determines the maximum size of the - <literal>tmpfs</literal> filesystem mounted on - <filename>/dev/shm</filename> in Linux sandboxes. For the format, - see the description of the <option>size</option> option of - <literal>tmpfs</literal> in - <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The - default is <literal>50%</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-sandbox-paths"> - <term><literal>sandbox-paths</literal></term> - - <listitem><para>A list of paths bind-mounted into Nix sandbox - environments. You can use the syntax - <literal><replaceable>target</replaceable>=<replaceable>source</replaceable></literal> - to mount a path in a different location in the sandbox; for - instance, <literal>/bin=/nix-bin</literal> will mount the path - <literal>/nix-bin</literal> as <literal>/bin</literal> inside the - sandbox. If <replaceable>source</replaceable> is followed by - <literal>?</literal>, then it is not an error if - <replaceable>source</replaceable> does not exist; for example, - <literal>/dev/nvidiactl?</literal> specifies that - <filename>/dev/nvidiactl</filename> will only be mounted in the - sandbox if it exists in the host filesystem.</para> - - <para>Depending on how Nix was built, the default value for this option - may be empty or provide <filename>/bin/sh</filename> as a - bind-mount of <command>bash</command>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-secret-key-files"><term><literal>secret-key-files</literal></term> - - <listitem><para>A whitespace-separated list of files containing - secret (private) keys. These are used to sign locally-built - paths. They can be generated using <command>nix-store - --generate-binary-cache-key</command>. The corresponding public - key can be distributed to other users, who can add it to - <option>trusted-public-keys</option> in their - <filename>nix.conf</filename>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-show-trace"><term><literal>show-trace</literal></term> - - <listitem><para>Causes Nix to print out a stack trace in case of Nix - expression evaluation errors.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-substitute"><term><literal>substitute</literal></term> - - <listitem><para>If set to <literal>true</literal> (default), Nix - will use binary substitutes if available. This option can be - disabled to force building from source.</para></listitem> - - </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 - whitespace. The default is - <literal>https://cache.nixos.org</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-system"><term><literal>system</literal></term> - - <listitem><para>This option specifies the canonical Nix system - name of the current installation, such as - <literal>i686-linux</literal> or - <literal>x86_64-darwin</literal>. Nix can only build derivations - whose <literal>system</literal> attribute equals the value - specified here. In general, it never makes sense to modify this - value from its default, since you can use it to ‘lie’ about the - platform you are building on (e.g., perform a Mac OS build on a - Linux machine; the result would obviously be wrong). It only - makes sense if the Nix binaries can run on multiple platforms, - e.g., ‘universal binaries’ that run on <literal>x86_64-linux</literal> and - <literal>i686-linux</literal>.</para> - - <para>It defaults to the canonical Nix system name detected by - <filename>configure</filename> at build time.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-system-features"><term><literal>system-features</literal></term> - - <listitem><para>A set of system “features” supported by this - machine, e.g. <literal>kvm</literal>. Derivations can express a - dependency on such features through the derivation attribute - <varname>requiredSystemFeatures</varname>. For example, the - attribute - -<programlisting> -requiredSystemFeatures = [ "kvm" ]; -</programlisting> - - ensures that the derivation can only be built on a machine with - the <literal>kvm</literal> feature.</para> - - <para>This setting by default includes <literal>kvm</literal> if - <filename>/dev/kvm</filename> is accessible, and the - pseudo-features <literal>nixos-test</literal>, - <literal>benchmark</literal> and <literal>big-parallel</literal> - that are used in Nixpkgs to route builds to specific - machines.</para> - - </listitem> - - </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> - - <listitem> - - <para>This option defines the maximum number of seconds that a - builder can run. This is useful (for instance in an automated - build system) to catch builds that are stuck in an infinite loop - but keep writing to their standard output or standard error. It - can be overridden using the <option - linkend="opt-timeout">--timeout</option> command line - switch.</para> - - <para>The value <literal>0</literal> means that there is no - timeout. This is also the default.</para> - - </listitem> - - </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 - paths are copied from another Nix store (such as a binary cache), - they must be signed with one of these keys. For example: - <literal>cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= - hydra.nixos.org-1:CNHJZBh9K4tP3EKF6FkkgeVYsS3ohTl+oS0Qa8bezVs=</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-trusted-substituters"><term><literal>trusted-substituters</literal></term> - - <listitem><para>A list of URLs of substituters, separated by - whitespace. These are not used by default, but can be enabled by - users of the Nix daemon by specifying <literal>--option - substituters <replaceable>urls</replaceable></literal> on the - command line. Unprivileged users are only allowed to pass a - subset of the URLs listed in <literal>substituters</literal> and - <literal>trusted-substituters</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-trusted-users"><term><literal>trusted-users</literal></term> - - <listitem> - - <para>A list of names of users (separated by whitespace) that - have additional rights when connecting to the Nix daemon, such - as the ability to specify additional binary caches, or to import - unsigned NARs. You can also specify groups by prefixing them - with <literal>@</literal>; for instance, - <literal>@wheel</literal> means all users in the - <literal>wheel</literal> group. The default is - <literal>root</literal>.</para> - - <warning><para>Adding a user to <option>trusted-users</option> - is essentially equivalent to giving that user root access to the - system. For example, the user can set - <option>sandbox-paths</option> and thereby obtain read access to - directories that are otherwise inacessible to - them.</para></warning> - - </listitem> - - </varlistentry> - -</variablelist> -</para> - -<refsection> - <title>Deprecated Settings</title> - -<para> - -<variablelist> - - <varlistentry xml:id="conf-binary-caches"> - <term><literal>binary-caches</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>binary-caches</literal> is now an alias to - <xref linkend="conf-substituters" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-binary-cache-public-keys"> - <term><literal>binary-cache-public-keys</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>binary-cache-public-keys</literal> is now an alias to - <xref linkend="conf-trusted-public-keys" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-compress-log"> - <term><literal>build-compress-log</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-compress-log</literal> is now an alias to - <xref linkend="conf-compress-build-log" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-cores"> - <term><literal>build-cores</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-cores</literal> is now an alias to - <xref linkend="conf-cores" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-extra-chroot-dirs"> - <term><literal>build-extra-chroot-dirs</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-extra-chroot-dirs</literal> is now an alias to - <xref linkend="conf-extra-sandbox-paths" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-extra-sandbox-paths"> - <term><literal>build-extra-sandbox-paths</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-extra-sandbox-paths</literal> is now an alias to - <xref linkend="conf-extra-sandbox-paths" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-fallback"> - <term><literal>build-fallback</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-fallback</literal> is now an alias to - <xref linkend="conf-fallback" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-max-jobs"> - <term><literal>build-max-jobs</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-max-jobs</literal> is now an alias to - <xref linkend="conf-max-jobs" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-max-log-size"> - <term><literal>build-max-log-size</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-max-log-size</literal> is now an alias to - <xref linkend="conf-max-build-log-size" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-max-silent-time"> - <term><literal>build-max-silent-time</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-max-silent-time</literal> is now an alias to - <xref linkend="conf-max-silent-time" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-repeat"> - <term><literal>build-repeat</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-repeat</literal> is now an alias to - <xref linkend="conf-repeat" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-timeout"> - <term><literal>build-timeout</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-timeout</literal> is now an alias to - <xref linkend="conf-timeout" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-use-chroot"> - <term><literal>build-use-chroot</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-use-chroot</literal> is now an alias to - <xref linkend="conf-sandbox" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-use-sandbox"> - <term><literal>build-use-sandbox</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-use-sandbox</literal> is now an alias to - <xref linkend="conf-sandbox" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-use-substitutes"> - <term><literal>build-use-substitutes</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-use-substitutes</literal> is now an alias to - <xref linkend="conf-substitute" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-gc-keep-derivations"> - <term><literal>gc-keep-derivations</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>gc-keep-derivations</literal> is now an alias to - <xref linkend="conf-keep-derivations" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-gc-keep-outputs"> - <term><literal>gc-keep-outputs</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>gc-keep-outputs</literal> is now an alias to - <xref linkend="conf-keep-outputs" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-env-keep-derivations"> - <term><literal>env-keep-derivations</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>env-keep-derivations</literal> is now an alias to - <xref linkend="conf-keep-env-derivations" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-extra-binary-caches"> - <term><literal>extra-binary-caches</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>extra-binary-caches</literal> is now an alias to - <xref linkend="conf-extra-substituters" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-trusted-binary-caches"> - <term><literal>trusted-binary-caches</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>trusted-binary-caches</literal> is now an alias to - <xref linkend="conf-trusted-substituters" />.</para></listitem> - </varlistentry> -</variablelist> -</para> -</refsection> - -</refsection> - -</refentry> diff --git a/doc/manual/command-ref/env-common.xml b/doc/manual/command-ref/env-common.xml deleted file mode 100644 index 8466cc463..000000000 --- a/doc/manual/command-ref/env-common.xml +++ /dev/null @@ -1,209 +0,0 @@ -<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="sec-common-env"> - -<title>Common Environment Variables</title> - - -<para>Most Nix commands interpret the following environment variables:</para> - -<variablelist xml:id="env-common"> - -<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>. Since Nix 2.0 the values are - <literal>"pure"</literal> and <literal>"impure"</literal></para></listitem> - -</varlistentry> - -<varlistentry xml:id="env-NIX_PATH"><term><envar>NIX_PATH</envar></term> - - <listitem> - - <para>A colon-separated list of directories used to look up Nix - expressions enclosed in angle brackets (i.e., - <literal><<replaceable>path</replaceable>></literal>). For - instance, the value - - <screen> -/home/eelco/Dev:/etc/nixos</screen> - - will cause Nix to look for paths relative to - <filename>/home/eelco/Dev</filename> and - <filename>/etc/nixos</filename>, in this order. It is also - possible to match paths against a prefix. For example, the value - - <screen> -nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen> - - will cause Nix to search for - <literal><nixpkgs/<replaceable>path</replaceable>></literal> in - <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename> - and - <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.</para> - - <para>If a path in the Nix search path starts with - <literal>http://</literal> or <literal>https://</literal>, it is - interpreted as the URL of a tarball that will be downloaded and - unpacked to a temporary location. The tarball must consist of a - single top-level directory. For example, setting - <envar>NIX_PATH</envar> to - - <screen> -nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz</screen> - - tells Nix to download the latest revision in the Nixpkgs/NixOS - 15.09 channel.</para> - - <para>A following shorthand can be used to refer to the official channels: - - <screen>nixpkgs=channel:nixos-15.09</screen> - </para> - - <para>The search path can be extended using the <option - linkend="opt-I">-I</option> option, which takes precedence over - <envar>NIX_PATH</envar>.</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_IGNORE_SYMLINK_STORE</envar></term> - - <listitem> - - <para>Normally, the Nix store directory (typically - <filename>/nix/store</filename>) is not allowed to contain any - symlink components. This is to prevent “impure” builds. Builders - sometimes “canonicalise” paths by resolving all symlink components. - Thus, builds on different machines (with - <filename>/nix/store</filename> resolving to different locations) - could yield different results. This is generally not a problem, - except when builds are deployed to machines where - <filename>/nix/store</filename> resolves differently. If you are - sure that you’re not going to do that, you can set - <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para> - - <para>Note that if you’re symlinking the Nix store so that you can - put it on another file system than the root file system, on Linux - you’re better off using <literal>bind</literal> mount points, e.g., - - <screen> -$ mkdir /nix -$ mount -o bind /mnt/otherdisk/nix /nix</screen> - - Consult the <citerefentry><refentrytitle>mount</refentrytitle> - <manvolnum>8</manvolnum></citerefentry> manual page for details.</para> - - </listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_STORE_DIR</envar></term> - - <listitem><para>Overrides the location of the Nix store (default - <filename><replaceable>prefix</replaceable>/store</filename>).</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_DATA_DIR</envar></term> - - <listitem><para>Overrides the location of the Nix static data - directory (default - <filename><replaceable>prefix</replaceable>/share</filename>).</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_LOG_DIR</envar></term> - - <listitem><para>Overrides the location of the Nix log directory - (default <filename><replaceable>prefix</replaceable>/var/log/nix</filename>).</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_STATE_DIR</envar></term> - - <listitem><para>Overrides the location of the Nix state directory - (default <filename><replaceable>prefix</replaceable>/var/nix</filename>).</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_CONF_DIR</envar></term> - - <listitem><para>Overrides the location of the system Nix configuration - directory (default - <filename><replaceable>prefix</replaceable>/etc/nix</filename>).</para></listitem> - -</varlistentry> - -<varlistentry><term><envar>NIX_USER_CONF_FILES</envar></term> - - <listitem><para>Overrides the location of the user Nix configuration files - to load from (defaults to the XDG spec locations). The variable is treated - as a list separated by the <literal>:</literal> token.</para></listitem> - -</varlistentry> - -<varlistentry><term><envar>TMPDIR</envar></term> - - <listitem><para>Use the specified directory to store temporary - files. In particular, this includes temporary build directories; - these can take up substantial amounts of disk space. The default is - <filename>/tmp</filename>.</para></listitem> - -</varlistentry> - - -<varlistentry xml:id="envar-remote"><term><envar>NIX_REMOTE</envar></term> - - <listitem><para>This variable should be set to - <literal>daemon</literal> if you want to use the Nix daemon to - execute Nix operations. This is necessary in <link - linkend="ssec-multi-user">multi-user Nix installations</link>. - If the Nix daemon's Unix socket is at some non-standard path, - this variable should be set to <literal>unix://path/to/socket</literal>. - Otherwise, it should be left unset.</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_SHOW_STATS</envar></term> - - <listitem><para>If set to <literal>1</literal>, Nix will print some - evaluation statistics, such as the number of values - allocated.</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_COUNT_CALLS</envar></term> - - <listitem><para>If set to <literal>1</literal>, Nix will print how - often functions were called during Nix expression evaluation. This - is useful for profiling your Nix expressions.</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>GC_INITIAL_HEAP_SIZE</envar></term> - - <listitem><para>If Nix has been configured to use the Boehm garbage - collector, this variable sets the initial size of the heap in bytes. - It defaults to 384 MiB. Setting it to a low value reduces memory - consumption, but will increase runtime due to the overhead of - garbage collection.</para></listitem> - -</varlistentry> - - -</variablelist> - - -</chapter> diff --git a/doc/manual/command-ref/files.xml b/doc/manual/command-ref/files.xml deleted file mode 100644 index 7bbc96e89..000000000 --- a/doc/manual/command-ref/files.xml +++ /dev/null @@ -1,14 +0,0 @@ -<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='ch-files'> - -<title>Files</title> - -<para>This section lists configuration files that you can use when you -work with Nix.</para> - -<xi:include href="conf-file.xml" /> - -</chapter>
\ No newline at end of file diff --git a/doc/manual/command-ref/main-commands.xml b/doc/manual/command-ref/main-commands.xml deleted file mode 100644 index 0f4169243..000000000 --- a/doc/manual/command-ref/main-commands.xml +++ /dev/null @@ -1,17 +0,0 @@ -<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='ch-main-commands'> - -<title>Main Commands</title> - -<para>This section lists commands and options that you can use when you -work with Nix.</para> - -<xi:include href="nix-env.xml" /> -<xi:include href="nix-build.xml" /> -<xi:include href="nix-shell.xml" /> -<xi:include href="nix-store.xml" /> - -</chapter>
\ No newline at end of file diff --git a/doc/manual/command-ref/nix-build.xml b/doc/manual/command-ref/nix-build.xml deleted file mode 100644 index 886d25910..000000000 --- a/doc/manual/command-ref/nix-build.xml +++ /dev/null @@ -1,190 +0,0 @@ -<refentry 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="sec-nix-build"> - -<refmeta> - <refentrytitle>nix-build</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-build</refname> - <refpurpose>build a Nix expression</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-build</command> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> - <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr</option></arg> - <arg choice='plain'><option>-A</option></arg> - </group> - <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> - <arg choice='plain'><option>-o</option></arg> - </group> - <replaceable>outlink</replaceable> - </arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - -<refsection><title>Description</title> - -<para>The <command>nix-build</command> command builds the derivations -described by the Nix expressions in <replaceable>paths</replaceable>. -If the build succeeds, it places a symlink to the result in the -current directory. The symlink is called <filename>result</filename>. -If there are multiple Nix expressions, or the Nix expressions evaluate -to multiple derivations, multiple sequentially numbered symlinks are -created (<filename>result</filename>, <filename>result-2</filename>, -and so on).</para> - -<para>If no <replaceable>paths</replaceable> are specified, then -<command>nix-build</command> will use <filename>default.nix</filename> -in the current directory, if it exists.</para> - -<para>If an element of <replaceable>paths</replaceable> starts with -<literal>http://</literal> or <literal>https://</literal>, it is -interpreted as the URL of a tarball that will be downloaded and -unpacked to a temporary location. The tarball must include a single -top-level directory containing at least a file named -<filename>default.nix</filename>.</para> - -<para><command>nix-build</command> is essentially a wrapper around -<link -linkend="sec-nix-instantiate"><command>nix-instantiate</command></link> -(to translate a high-level Nix expression to a low-level store -derivation) and <link -linkend="rsec-nix-store-realise"><command>nix-store ---realise</command></link> (to build the store derivation).</para> - -<warning><para>The result of the build is automatically registered as -a root of the Nix garbage collector. This root disappears -automatically when the <filename>result</filename> symlink is deleted -or renamed. So don’t rename the symlink.</para></warning> - -</refsection> - - -<refsection><title>Options</title> - -<para>All options not listed here are passed to <command>nix-store ---realise</command>, except for <option>--arg</option> and -<option>--attr</option> / <option>-A</option> which are passed to -<command>nix-instantiate</command>. <phrase condition="manual">See -also <xref linkend="sec-common-options" />.</phrase></para> - -<variablelist> - - <varlistentry><term><option>--no-out-link</option></term> - - <listitem><para>Do not create a symlink to the output path. Note - that as a result the output does not become a root of the garbage - collector, and so might be deleted by <command>nix-store - --gc</command>.</para></listitem> - - </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> - - <listitem><para>Change the name of the symlink to the output path - created from <filename>result</filename> to - <replaceable>outlink</replaceable>.</para></listitem> - - </varlistentry> - -</variablelist> - -<para>The following common options are supported:</para> - -<variablelist condition="manpage"> - <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<screen> -$ nix-build '<nixpkgs>' -A firefox -store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv -/nix/store/d18hyl92g30l...-firefox-1.5.0.7 - -$ ls -l result -lrwxrwxrwx <replaceable>...</replaceable> result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7 - -$ ls ./result/bin/ -firefox firefox-config</screen> - -<para>If a derivation has multiple outputs, -<command>nix-build</command> will build the default (first) output. -You can also build all outputs: -<screen> -$ nix-build '<nixpkgs>' -A openssl.all -</screen> -This will create a symlink for each output named -<filename>result-<replaceable>outputname</replaceable></filename>. -The suffix is omitted if the output name is <literal>out</literal>. -So if <literal>openssl</literal> has outputs <literal>out</literal>, -<literal>bin</literal> and <literal>man</literal>, -<command>nix-build</command> will create symlinks -<literal>result</literal>, <literal>result-bin</literal> and -<literal>result-man</literal>. It’s also possible to build a specific -output: -<screen> -$ nix-build '<nixpkgs>' -A openssl.man -</screen> -This will create a symlink <literal>result-man</literal>.</para> - -<para>Build a Nix expression given on the command line: - -<screen> -$ nix-build -E 'with import <nixpkgs> { }; runCommand "foo" { } "echo bar > $out"' -$ cat ./result -bar -</screen> - -</para> - -<para>Build the GNU Hello package from the latest revision of the -master branch of Nixpkgs: - -<screen> -$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello -</screen> - -</para> - -</refsection> - - -<refsection condition="manpage"><title>Environment variables</title> - -<variablelist> - <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> -</variablelist> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-channel.xml b/doc/manual/command-ref/nix-channel.xml deleted file mode 100644 index ebcf56aff..000000000 --- a/doc/manual/command-ref/nix-channel.xml +++ /dev/null @@ -1,181 +0,0 @@ -<refentry 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="sec-nix-channel"> - -<refmeta> - <refentrytitle>nix-channel</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-channel</refname> - <refpurpose>manage Nix channels</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-channel</command> - <group choice='req'> - <arg choice='plain'><option>--add</option> <replaceable>url</replaceable> <arg choice='opt'><replaceable>name</replaceable></arg></arg> - <arg choice='plain'><option>--remove</option> <replaceable>name</replaceable></arg> - <arg choice='plain'><option>--list</option></arg> - <arg choice='plain'><option>--update</option> <arg rep='repeat'><replaceable>names</replaceable></arg></arg> - <arg choice='plain'><option>--rollback</option> <arg choice='opt'><replaceable>generation</replaceable></arg></arg> - </group> - </cmdsynopsis> -</refsynopsisdiv> - -<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 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: - -<variablelist> - - <varlistentry><term><option>--add</option> <replaceable>url</replaceable> [<replaceable>name</replaceable>]</term> - - <listitem><para>Adds a channel named - <replaceable>name</replaceable> with URL - <replaceable>url</replaceable> to the list of subscribed channels. - If <replaceable>name</replaceable> is omitted, it defaults to the - last component of <replaceable>url</replaceable>, with the - suffixes <literal>-stable</literal> or - <literal>-unstable</literal> removed.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--remove</option> <replaceable>name</replaceable></term> - - <listitem><para>Removes the channel named - <replaceable>name</replaceable> from the list of subscribed - channels.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--list</option></term> - - <listitem><para>Prints the names and URLs of all subscribed - channels on standard output.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--update</option> [<replaceable>names</replaceable>…]</term> - - <listitem><para>Downloads the Nix expressions of all subscribed - channels (or only those included in - <replaceable>names</replaceable> if specified) and makes them the - default for <command>nix-env</command> operations (by symlinking - them from the directory - <filename>~/.nix-defexpr</filename>).</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--rollback</option> [<replaceable>generation</replaceable>]</term> - - <listitem><para>Reverts the previous call to <command>nix-channel - --update</command>. Optionally, you can specify a specific channel - generation number to restore.</para></listitem> - - </varlistentry> - -</variablelist> - -</para> - -<para>Note that <option>--add</option> does not automatically perform -an update.</para> - -<para>The list of subscribed channels is stored in -<filename>~/.nix-channels</filename>.</para> - -</refsection> - -<refsection><title>Examples</title> - -<para>To subscribe to the Nixpkgs channel and install the GNU Hello package:</para> - -<screen> -$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable -$ nix-channel --update -$ nix-env -iA nixpkgs.hello</screen> - -<para>You can revert channel updates using <option>--rollback</option>:</para> - -<screen> -$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' -"14.04.527.0e935f1" - -$ nix-channel --rollback -switching from generation 483 to 482 - -$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' -"14.04.526.dbadfad" -</screen> - -</refsection> - -<refsection><title>Files</title> - -<variablelist> - - <varlistentry><term><filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename></term> - - <listitem><para><command>nix-channel</command> uses a - <command>nix-env</command> profile to keep track of previous - versions of the subscribed channels. Every time you run - <command>nix-channel --update</command>, a new channel generation - (that is, a symlink to the channel Nix expressions in the Nix store) - is created. This enables <command>nix-channel --rollback</command> - to revert to previous versions.</para></listitem> - - </varlistentry> - - <varlistentry><term><filename>~/.nix-defexpr/channels</filename></term> - - <listitem><para>This is a symlink to - <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename>. It - ensures that <command>nix-env</command> can find your channels. In - a multi-user installation, you may also have - <filename>~/.nix-defexpr/channels_root</filename>, which links to - the channels of the root user.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - -<refsection><title>Channel format</title> - -<para>A channel URL should point to a directory containing the -following files:</para> - -<variablelist> - - <varlistentry><term><filename>nixexprs.tar.xz</filename></term> - - <listitem><para>A tarball containing Nix expressions and files - referenced by them (such as build scripts and patches). At the - top level, the tarball should contain a single directory. That - directory must contain a file <filename>default.nix</filename> - that serves as the channel’s “entry point”.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - -</refentry> diff --git a/doc/manual/command-ref/nix-collect-garbage.xml b/doc/manual/command-ref/nix-collect-garbage.xml deleted file mode 100644 index 43e068796..000000000 --- a/doc/manual/command-ref/nix-collect-garbage.xml +++ /dev/null @@ -1,63 +0,0 @@ -<refentry 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="sec-nix-collect-garbage"> - -<refmeta> - <refentrytitle>nix-collect-garbage</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-collect-garbage</refname> - <refpurpose>delete unreachable store paths</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-collect-garbage</command> - <arg><option>--delete-old</option></arg> - <arg><option>-d</option></arg> - <arg><option>--delete-older-than</option> <replaceable>period</replaceable></arg> - <arg><option>--max-freed</option> <replaceable>bytes</replaceable></arg> - <arg><option>--dry-run</option></arg> - </cmdsynopsis> -</refsynopsisdiv> - -<refsection><title>Description</title> - -<para>The command <command>nix-collect-garbage</command> is mostly an -alias of <link linkend="rsec-nix-store-gc"><command>nix-store ---gc</command></link>, that is, it deletes all unreachable paths in -the Nix store to clean up your system. However, it provides two -additional options: <option>-d</option> (<option>--delete-old</option>), -which deletes all old generations of all profiles in -<filename>/nix/var/nix/profiles</filename> by invoking -<literal>nix-env --delete-generations old</literal> on all profiles -(of course, this makes rollbacks to previous configurations -impossible); and -<option>--delete-older-than</option> <replaceable>period</replaceable>, -where period is a value such as <literal>30d</literal>, which deletes -all generations older than the specified number of days in all profiles -in <filename>/nix/var/nix/profiles</filename> (except for the generations -that were active at that point in time). -</para> - -</refsection> - -<refsection><title>Example</title> - -<para>To delete from the Nix store everything that is not used by the -current generations of each profile, do - -<screen> -$ nix-collect-garbage -d</screen> - -</para> - -</refsection> - -</refentry> diff --git a/doc/manual/command-ref/nix-copy-closure.xml b/doc/manual/command-ref/nix-copy-closure.xml deleted file mode 100644 index e6dcf180a..000000000 --- a/doc/manual/command-ref/nix-copy-closure.xml +++ /dev/null @@ -1,169 +0,0 @@ -<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-nix-copy-closure"> - -<refmeta> - <refentrytitle>nix-copy-closure</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-copy-closure</refname> - <refpurpose>copy a closure to or from a remote machine via SSH</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-copy-closure</command> - <group> - <arg choice='plain'><option>--to</option></arg> - <arg choice='plain'><option>--from</option></arg> - </group> - <arg><option>--gzip</option></arg> - <!-- - <arg><option>- -show-progress</option></arg> - --> - <arg><option>--include-outputs</option></arg> - <group> - <arg choice='plain'><option>--use-substitutes</option></arg> - <arg choice='plain'><option>-s</option></arg> - </group> - <arg><option>-v</option></arg> - <arg choice='plain'> - <replaceable>user@</replaceable><replaceable>machine</replaceable> - </arg> - <arg choice='plain'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para><command>nix-copy-closure</command> gives you an easy and -efficient way to exchange software between machines. Given one or -more Nix store <replaceable>paths</replaceable> on the local -machine, <command>nix-copy-closure</command> computes the closure of -those paths (i.e. all their dependencies in the Nix store), and copies -all paths in the closure to the remote machine via the -<command>ssh</command> (Secure Shell) command. With the -<option>--from</option>, the direction is reversed: -the closure of <replaceable>paths</replaceable> on a remote machine is -copied to the Nix store on the local machine.</para> - -<para>This command is efficient because it only sends the store paths -that are missing on the target machine.</para> - -<para>Since <command>nix-copy-closure</command> calls -<command>ssh</command>, you may be asked to type in the appropriate -password or passphrase. In fact, you may be asked -<emphasis>twice</emphasis> because <command>nix-copy-closure</command> -currently connects twice to the remote machine, first to get the set -of paths missing on the target machine, and second to send the dump of -those paths. If this bothers you, use -<command>ssh-agent</command>.</para> - - -<refsection><title>Options</title> - -<variablelist> - - <varlistentry><term><option>--to</option></term> - - <listitem><para>Copy the closure of - <replaceable>paths</replaceable> from the local Nix store to the - Nix store on <replaceable>machine</replaceable>. This is the - default.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--from</option></term> - - <listitem><para>Copy the closure of - <replaceable>paths</replaceable> from the Nix store on - <replaceable>machine</replaceable> to the local Nix - store.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--gzip</option></term> - - <listitem><para>Enable compression of the SSH - connection.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--include-outputs</option></term> - - <listitem><para>Also copy the outputs of store derivations - included in the closure.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--use-substitutes</option> / <option>-s</option></term> - - <listitem><para>Attempt to download missing paths on the target - machine using Nix’s substitute mechanism. Any paths that cannot - be substituted on the target are still copied normally from the - source. This is useful, for instance, if the connection between - the source and target machine is slow, but the connection between - the target machine and <literal>nixos.org</literal> (the default - binary cache server) is fast.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>-v</option></term> - - <listitem><para>Show verbose output.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Environment variables</title> - -<variablelist> - - <varlistentry><term><envar>NIX_SSHOPTS</envar></term> - - <listitem><para>Additional options to be passed to - <command>ssh</command> on the command line.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>Copy Firefox with all its dependencies to a remote machine: - -<screen> -$ nix-copy-closure --to alice@itchy.labs $(type -tP firefox)</screen> - -</para> - -<para>Copy Subversion from a remote machine and then install it into a -user environment: - -<screen> -$ nix-copy-closure --from alice@itchy.labs \ - /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4 -$ nix-env -i /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4 -</screen> - -</para> - -</refsection> - - -</refsection> - -</refentry> diff --git a/doc/manual/command-ref/nix-daemon.xml b/doc/manual/command-ref/nix-daemon.xml deleted file mode 100644 index a2161f033..000000000 --- a/doc/manual/command-ref/nix-daemon.xml +++ /dev/null @@ -1,35 +0,0 @@ -<refentry 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="sec-nix-daemon"> - -<refmeta> - <refentrytitle>nix-daemon</refentrytitle> - <manvolnum>8</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-daemon</refname> - <refpurpose>Nix multi-user support daemon</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-daemon</command> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>The Nix daemon is necessary in multi-user Nix installations. It -performs build actions and other operations on the Nix store on behalf -of unprivileged users.</para> - - -</refsection> - -</refentry> diff --git a/doc/manual/command-ref/nix-env.xml b/doc/manual/command-ref/nix-env.xml deleted file mode 100644 index 55f25d959..000000000 --- a/doc/manual/command-ref/nix-env.xml +++ /dev/null @@ -1,1503 +0,0 @@ -<refentry 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="sec-nix-env"> - -<refmeta> - <refentrytitle>nix-env</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-env</refname> - <refpurpose>manipulate or query Nix user environments</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-env</command> - <xi:include href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> - <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--file</option></arg> - <arg choice='plain'><option>-f</option></arg> - </group> - <replaceable>path</replaceable> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--profile</option></arg> - <arg choice='plain'><option>-p</option></arg> - </group> - <replaceable>path</replaceable> - </arg> - <arg> - <arg choice='plain'><option>--system-filter</option></arg> - <replaceable>system</replaceable> - </arg> - <arg><option>--dry-run</option></arg> - <arg choice='plain'><replaceable>operation</replaceable></arg> - <arg rep='repeat'><replaceable>options</replaceable></arg> - <arg rep='repeat'><replaceable>arguments</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>The command <command>nix-env</command> is used to manipulate Nix -user environments. User environments are sets of software packages -available to a user at some point in time. In other words, they are a -synthesised view of the programs available in the Nix store. There -may be many user environments: different users can have different -environments, and individual users can switch between different -environments.</para> - -<para><command>nix-env</command> takes exactly one -<emphasis>operation</emphasis> flag which indicates the subcommand to -be performed. These are documented below.</para> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Selectors</title> - -<para>Several commands, such as <command>nix-env -q</command> and -<command>nix-env -i</command>, take a list of arguments that specify -the packages on which to operate. These are extended regular -expressions that must match the entire name of the package. (For -details on regular expressions, see -<citerefentry><refentrytitle>regex</refentrytitle><manvolnum>7</manvolnum></citerefentry>.) -The match is case-sensitive. The regular expression can optionally be -followed by a dash and a version number; if omitted, any version of -the package will match. Here are some examples: - -<variablelist> - - <varlistentry> - <term><literal>firefox</literal></term> - <listitem><para>Matches the package name - <literal>firefox</literal> and any version.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>firefox-32.0</literal></term> - <listitem><para>Matches the package name - <literal>firefox</literal> and version - <literal>32.0</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>gtk\\+</literal></term> - <listitem><para>Matches the package name - <literal>gtk+</literal>. The <literal>+</literal> character must - be escaped using a backslash to prevent it from being interpreted - as a quantifier, and the backslash must be escaped in turn with - another backslash to ensure that the shell passes it - on.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>.\*</literal></term> - <listitem><para>Matches any package name. This is the default for - most commands.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>'.*zip.*'</literal></term> - <listitem><para>Matches any package name containing the string - <literal>zip</literal>. Note the dots: <literal>'*zip*'</literal> - does not work, because in a regular expression, the character - <literal>*</literal> is interpreted as a - quantifier.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>'.*(firefox|chromium).*'</literal></term> - <listitem><para>Matches any package name containing the strings - <literal>firefox</literal> or - <literal>chromium</literal>.</para></listitem> - </varlistentry> - -</variablelist> - -</para> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Common options</title> - -<para>This section lists the options that are common to all -operations. These options are allowed for every subcommand, though -they may not always have an effect. <phrase condition="manual">See -also <xref linkend="sec-common-options" />.</phrase></para> - -<variablelist> - - <varlistentry><term><option>--file</option> / <option>-f</option> <replaceable>path</replaceable></term> - - <listitem><para>Specifies the Nix expression (designated below as - the <emphasis>active Nix expression</emphasis>) used by the - <option>--install</option>, <option>--upgrade</option>, and - <option>--query --available</option> operations to obtain - derivations. The default is - <filename>~/.nix-defexpr</filename>.</para> - - <para>If the argument starts with <literal>http://</literal> or - <literal>https://</literal>, it is interpreted as the URL of a - tarball that will be downloaded and unpacked to a temporary - location. The tarball must include a single top-level directory - containing at least a file named <filename>default.nix</filename>.</para> - - </listitem> - - </varlistentry> - - <varlistentry><term><option>--profile</option> / <option>-p</option> <replaceable>path</replaceable></term> - - <listitem><para>Specifies the profile to be used by those - operations that operate on a profile (designated below as the - <emphasis>active profile</emphasis>). A profile is a sequence of - user environments called <emphasis>generations</emphasis>, one of - which is the <emphasis>current - generation</emphasis>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--dry-run</option></term> - - <listitem><para>For the <option>--install</option>, - <option>--upgrade</option>, <option>--uninstall</option>, - <option>--switch-generation</option>, - <option>--delete-generations</option> and - <option>--rollback</option> operations, this flag will cause - <command>nix-env</command> to print what - <emphasis>would</emphasis> be done if this flag had not been - specified, without actually doing it.</para> - - <para><option>--dry-run</option> also prints out which paths will - be <link linkend="gloss-substitute">substituted</link> (i.e., - downloaded) and which paths will be built from source (because no - substitute is available).</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--system-filter</option> <replaceable>system</replaceable></term> - - <listitem><para>By default, operations such as <option>--query - --available</option> show derivations matching any platform. This - option allows you to use derivations for the specified platform - <replaceable>system</replaceable>.</para></listitem> - - </varlistentry> - -</variablelist> - -<variablelist condition="manpage"> - <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> -</variablelist> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Files</title> - -<variablelist> - - <varlistentry><term><filename>~/.nix-defexpr</filename></term> - - <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 - <option>--file</option> option may be used to override this - default.</para> - - <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.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> - - <varlistentry><term><filename>~/.nix-profile</filename></term> - - <listitem><para>A symbolic link to the user's current profile. By - default, this symlink points to - <filename><replaceable>prefix</replaceable>/var/nix/profiles/default</filename>. - The <envar>PATH</envar> environment variable should include - <filename>~/.nix-profile/bin</filename> for the user environment - to be visible to the user.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id="rsec-nix-env-install"><title>Operation <option>--install</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--install</option></arg> - <arg choice='plain'><option>-i</option></arg> - </group> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> - <group choice='opt'> - <arg choice='plain'><option>--preserve-installed</option></arg> - <arg choice='plain'><option>-P</option></arg> - </group> - <group choice='opt'> - <arg choice='plain'><option>--remove-all</option></arg> - <arg choice='plain'><option>-r</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>The install operation creates a new user environment, based on -the current generation of the active profile, to which a set of store -paths described by <replaceable>args</replaceable> is added. The -arguments <replaceable>args</replaceable> map to store paths in a -number of possible ways: - -<itemizedlist> - - <listitem><para>By default, <replaceable>args</replaceable> is a set - of derivation names denoting derivations in the active Nix - expression. These are realised, and the resulting output paths are - installed. Currently installed derivations with a name equal to the - name of a derivation being added are removed unless the option - <option>--preserve-installed</option> is - specified.</para> - - <para>If there are multiple derivations matching a name in - <replaceable>args</replaceable> that have the same name (e.g., - <literal>gcc-3.3.6</literal> and <literal>gcc-4.1.1</literal>), then - the derivation with the highest <emphasis>priority</emphasis> is - used. A derivation can define a priority by declaring the - <varname>meta.priority</varname> attribute. This attribute should - be a number, with a higher value denoting a lower priority. The - default priority is <literal>0</literal>.</para> - - <para>If there are multiple matching derivations with the same - priority, then the derivation with the highest version will be - installed.</para> - - <para>You can force the installation of multiple derivations with - the same name by being specific about the versions. For instance, - <literal>nix-env -i gcc-3.3.6 gcc-4.1.1</literal> will install both - version of GCC (and will probably cause a user environment - conflict!).</para></listitem> - - <listitem><para>If <link - linkend='opt-attr'><option>--attr</option></link> - (<option>-A</option>) is specified, the arguments are - <emphasis>attribute paths</emphasis> that select attributes from the - top-level Nix expression. This is faster than using derivation - names and unambiguous. To find out the attribute paths of available - packages, use <literal>nix-env -qaP</literal>.</para></listitem> - - <listitem><para>If <option>--from-profile</option> - <replaceable>path</replaceable> is given, - <replaceable>args</replaceable> is a set of names denoting installed - store paths in the profile <replaceable>path</replaceable>. This is - an easy way to copy user environment elements from one profile to - another.</para></listitem> - - <listitem><para>If <option>--from-expression</option> is given, - <replaceable>args</replaceable> are Nix <link - linkend="ss-functions">functions</link> that are called with the - active Nix expression as their single argument. The derivations - returned by those function calls are installed. This allows - derivations to be specified in an unambiguous way, which is necessary - if there are multiple derivations with the same - name.</para></listitem> - - <listitem><para>If <replaceable>args</replaceable> are store - derivations, then these are <link - linkend="rsec-nix-store-realise">realised</link>, and the resulting - output paths are installed.</para></listitem> - - <listitem><para>If <replaceable>args</replaceable> are store paths - that are not store derivations, then these are <link - linkend="rsec-nix-store-realise">realised</link> and - installed.</para></listitem> - - <listitem><para>By default all outputs are installed for each derivation. - That can be reduced by setting <literal>meta.outputsToInstall</literal>. - </para></listitem> <!-- TODO: link nixpkgs docs on the ability to override those. --> - -</itemizedlist> - -</para> - -</refsection> - - -<refsection><title>Flags</title> - -<variablelist> - - <varlistentry><term><option>--prebuilt-only</option> / <option>-b</option></term> - - <listitem><para>Use only derivations for which a substitute is - registered, i.e., there is a pre-built binary available that can - be downloaded in lieu of building the derivation. Thus, no - packages will be built from source.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--preserve-installed</option></term> - <term><option>-P</option></term> - - <listitem><para>Do not remove derivations with a name matching one - of the derivations being installed. Usually, trying to have two - versions of the same package installed in the same generation of a - profile will lead to an error in building the generation, due to - file name clashes between the two versions. However, this is not - the case for all packages.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--remove-all</option></term> - <term><option>-r</option></term> - - <listitem><para>Remove all previously installed packages first. - This is equivalent to running <literal>nix-env -e '.*'</literal> - first, except that everything happens in a single - transaction.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection xml:id='refsec-nix-env-install-examples'><title>Examples</title> - -<para>To install a specific version of <command>gcc</command> from the -active Nix expression: - -<screen> -$ nix-env --install gcc-3.3.2 -installing `gcc-3.3.2' -uninstalling `gcc-3.1'</screen> - -Note the previously installed version is removed, since -<option>--preserve-installed</option> was not specified.</para> - -<para>To install an arbitrary version: - -<screen> -$ nix-env --install gcc -installing `gcc-3.3.2'</screen> - -</para> - -<para>To install using a specific attribute: - -<screen> -$ nix-env -i -A gcc40mips -$ nix-env -i -A xorg.xorgserver</screen> - -</para> - -<para>To install all derivations in the Nix expression <filename>foo.nix</filename>: - -<screen> -$ nix-env -f ~/foo.nix -i '.*'</screen> - -</para> - -<para>To copy the store path with symbolic name <literal>gcc</literal> -from another profile: - -<screen> -$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc</screen> - -</para> - -<para>To install a specific store derivation (typically created by -<command>nix-instantiate</command>): - -<screen> -$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv</screen> - -</para> - -<para>To install a specific output path: - -<screen> -$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3</screen> - -</para> - -<para>To install from a Nix expression specified on the command-line: - -<screen> -$ nix-env -f ./foo.nix -i -E \ - 'f: (f {system = "i686-linux";}).subversionWithJava'</screen> - -I.e., this evaluates to <literal>(f: (f {system = -"i686-linux";}).subversionWithJava) (import ./foo.nix)</literal>, thus -selecting the <literal>subversionWithJava</literal> attribute from the -set returned by calling the function defined in -<filename>./foo.nix</filename>.</para> - -<para>A dry-run tells you which paths will be downloaded or built from -source: - -<screen> -$ nix-env -f '<nixpkgs>' -iA hello --dry-run -(dry run; not doing anything) -installing ‘hello-2.10’ -this path will be fetched (0.04 MiB download, 0.19 MiB unpacked): - /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10 - <replaceable>...</replaceable></screen> - -</para> - -<para>To install Firefox from the latest revision in the Nixpkgs/NixOS -14.12 channel: - -<screen> -$ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox -</screen> - -</para> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id="rsec-nix-env-upgrade"><title>Operation <option>--upgrade</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--upgrade</option></arg> - <arg choice='plain'><option>-u</option></arg> - </group> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> - <group choice='opt'> - <arg choice='plain'><option>--lt</option></arg> - <arg choice='plain'><option>--leq</option></arg> - <arg choice='plain'><option>--eq</option></arg> - <arg choice='plain'><option>--always</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>The upgrade operation creates a new user environment, based on -the current generation of the active profile, in which all store paths -are replaced for which there are newer versions in the set of paths -described by <replaceable>args</replaceable>. Paths for which there -are no newer versions are left untouched; this is not an error. It is -also not an error if an element of <replaceable>args</replaceable> -matches no installed derivations.</para> - -<para>For a description of how <replaceable>args</replaceable> is -mapped to a set of store paths, see <link -linkend="rsec-nix-env-install"><option>--install</option></link>. If -<replaceable>args</replaceable> describes multiple store paths with -the same symbolic name, only the one with the highest version is -installed.</para> - -</refsection> - -<refsection><title>Flags</title> - -<variablelist> - - <varlistentry><term><option>--lt</option></term> - - <listitem><para>Only upgrade a derivation to newer versions. This - is the default.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--leq</option></term> - - <listitem><para>In addition to upgrading to newer versions, also - “upgrade” to derivations that have the same version. Version are - not a unique identification of a derivation, so there may be many - derivations that have the same version. This flag may be useful - to force “synchronisation” between the installed and available - derivations.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--eq</option></term> - - <listitem><para><emphasis>Only</emphasis> “upgrade” to derivations - that have the same version. This may not seem very useful, but it - actually is, e.g., when there is a new release of Nixpkgs and you - want to replace installed applications with the same versions - built against newer dependencies (to reduce the number of - dependencies floating around on your system).</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--always</option></term> - - <listitem><para>In addition to upgrading to newer versions, also - “upgrade” to derivations that have the same or a lower version. - I.e., derivations may actually be downgraded depending on what is - available in the active Nix expression.</para></listitem> - - </varlistentry> - -</variablelist> - -<para>For the other flags, see <option -linkend="rsec-nix-env-install">--install</option>.</para> - -</refsection> - -<refsection><title>Examples</title> - -<screen> -$ nix-env --upgrade gcc -upgrading `gcc-3.3.1' to `gcc-3.4' - -$ nix-env -u gcc-3.3.2 --always <lineannotation>(switch to a specific version)</lineannotation> -upgrading `gcc-3.4' to `gcc-3.3.2' - -$ nix-env --upgrade pan -<lineannotation>(no upgrades available, so nothing happens)</lineannotation> - -$ nix-env -u <lineannotation>(try to upgrade everything)</lineannotation> -upgrading `hello-2.1.2' to `hello-2.1.3' -upgrading `mozilla-1.2' to `mozilla-1.4'</screen> - -</refsection> - -<refsection xml:id="ssec-version-comparisons"><title>Versions</title> - -<para>The upgrade operation determines whether a derivation -<varname>y</varname> is an upgrade of a derivation -<varname>x</varname> by looking at their respective -<literal>name</literal> attributes. The names (e.g., -<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 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> - -<para>The versions are compared by splitting them into contiguous -components of numbers and letters. E.g., <literal>3.3.1pre5</literal> -is split into <literal>[3, 3, 1, "pre", 5]</literal>. These lists are -then compared lexicographically (from left to right). Corresponding -components <varname>a</varname> and <varname>b</varname> are compared -as follows. If they are both numbers, integer comparison is used. If -<varname>a</varname> is an empty string and <varname>b</varname> is a -number, <varname>a</varname> is considered less than -<varname>b</varname>. The special string component -<literal>pre</literal> (for <emphasis>pre-release</emphasis>) is -considered to be less than other components. String components are -considered less than number components. Otherwise, they are compared -lexicographically (i.e., using case-sensitive string comparison).</para> - -<para>This is illustrated by the following examples: - -<screen> -1.0 < 2.3 -2.1 < 2.3 -2.3 = 2.3 -2.5 > 2.3 -3.1 > 2.3 -2.3.1 > 2.3 -2.3.1 > 2.3a -2.3pre1 < 2.3 -2.3pre3 < 2.3pre12 -2.3a < 2.3c -2.3pre1 < 2.3c -2.3pre1 < 2.3q</screen> - -</para> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--uninstall</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--uninstall</option></arg> - <arg choice='plain'><option>-e</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg> -</cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The uninstall operation creates a new user environment, based on -the current generation of the active profile, from which the store -paths designated by the symbolic names -<replaceable>names</replaceable> are removed.</para> - -</refsection> - -<refsection><title>Examples</title> - -<screen> -$ nix-env --uninstall gcc -$ nix-env -e '.*' <lineannotation>(remove everything)</lineannotation></screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id="rsec-nix-env-set"><title>Operation <option>--set</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <arg choice='plain'><option>--set</option></arg> - <arg choice='plain'><replaceable>drvname</replaceable></arg> -</cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The <option>--set</option> operation modifies the current generation of a -profile so that it contains exactly the specified derivation, and nothing else. -</para> - -</refsection> - -<refsection><title>Examples</title> - -<para> -The following updates a profile such that its current generation will contain -just Firefox: - -<screen> -$ nix-env -p /nix/var/nix/profiles/browser --set firefox</screen> - -</para> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id="rsec-nix-env-set-flag"><title>Operation <option>--set-flag</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <arg choice='plain'><option>--set-flag</option></arg> - <arg choice='plain'><replaceable>name</replaceable></arg> - <arg choice='plain'><replaceable>value</replaceable></arg> - <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg> -</cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The <option>--set-flag</option> operation allows meta attributes -of installed packages to be modified. There are several attributes -that can be usefully modified, because they affect the behaviour of -<command>nix-env</command> or the user environment build -script: - -<itemizedlist> - - <listitem><para><varname>priority</varname> can be changed to - resolve filename clashes. The user environment build script uses - the <varname>meta.priority</varname> attribute of derivations to - resolve filename collisions between packages. Lower priority values - denote a higher priority. For instance, the GCC wrapper package and - the Binutils package in Nixpkgs both have a file - <filename>bin/ld</filename>, so previously if you tried to install - both you would get a collision. Now, on the other hand, the GCC - wrapper declares a higher priority than Binutils, so the former’s - <filename>bin/ld</filename> is symlinked in the user - environment.</para></listitem> - - <listitem><para><varname>keep</varname> can be set to - <literal>true</literal> to prevent the package from being upgraded - or replaced. This is useful if you want to hang on to an older - version of a package.</para></listitem> - - <listitem><para><varname>active</varname> can be set to - <literal>false</literal> to “disable” the package. That is, no - symlinks will be generated to the files of the package, but it - remains part of the profile (so it won’t be garbage-collected). It - can be set back to <literal>true</literal> to re-enable the - package.</para></listitem> - -</itemizedlist> - -</para> - -</refsection> - -<refsection><title>Examples</title> - -<para>To prevent the currently installed Firefox from being upgraded: - -<screen> -$ nix-env --set-flag keep true firefox</screen> - -After this, <command>nix-env -u</command> will ignore Firefox.</para> - -<para>To disable the currently installed Firefox, then install a new -Firefox while the old remains part of the profile: - -<screen> -$ nix-env -q -firefox-2.0.0.9 <lineannotation>(the current one)</lineannotation> - -$ nix-env --preserve-installed -i firefox-2.0.0.11 -installing `firefox-2.0.0.11' -building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment' -collision between `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.11/bin/firefox' - and `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.9/bin/firefox'. -<lineannotation>(i.e., can’t have two active at the same time)</lineannotation> - -$ nix-env --set-flag active false firefox -setting flag on `firefox-2.0.0.9' - -$ nix-env --preserve-installed -i firefox-2.0.0.11 -installing `firefox-2.0.0.11' - -$ nix-env -q -firefox-2.0.0.11 <lineannotation>(the enabled one)</lineannotation> -firefox-2.0.0.9 <lineannotation>(the disabled one)</lineannotation></screen> - -</para> - -<para>To make files from <literal>binutils</literal> take precedence -over files from <literal>gcc</literal>: - -<screen> -$ nix-env --set-flag priority 5 binutils -$ nix-env --set-flag priority 10 gcc</screen> - -</para> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--query</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--query</option></arg> - <arg choice='plain'><option>-q</option></arg> - </group> - <group choice='opt'> - <arg choice='plain'><option>--installed</option></arg> - <arg choice='plain'><option>--available</option></arg> - <arg choice='plain'><option>-a</option></arg> - </group> - - <sbr /> - - <arg> - <group choice='req'> - <arg choice='plain'><option>--status</option></arg> - <arg choice='plain'><option>-s</option></arg> - </group> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr-path</option></arg> - <arg choice='plain'><option>-P</option></arg> - </group> - </arg> - <arg><option>--no-name</option></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--compare-versions</option></arg> - <arg choice='plain'><option>-c</option></arg> - </group> - </arg> - <arg><option>--system</option></arg> - <arg><option>--drv-path</option></arg> - <arg><option>--out-path</option></arg> - <arg><option>--description</option></arg> - <arg><option>--meta</option></arg> - - <sbr /> - - <arg><option>--xml</option></arg> - <arg><option>--json</option></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--prebuilt-only</option></arg> - <arg choice='plain'><option>-b</option></arg> - </group> - </arg> - - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr</option></arg> - <arg choice='plain'><option>-A</option></arg> - </group> - <replaceable>attribute-path</replaceable> - </arg> - - <sbr /> - - <arg choice='plain' rep='repeat'><replaceable>names</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>The query operation displays information about either the store -paths that are installed in the current generation of the active -profile (<option>--installed</option>), or the derivations that are -available for installation in the active Nix expression -(<option>--available</option>). It only prints information about -derivations whose symbolic name matches one of -<replaceable>names</replaceable>.</para> - -<para>The derivations are sorted by their <literal>name</literal> -attributes.</para> - -</refsection> - - -<refsection><title>Source selection</title> - -<para>The following flags specify the set of things on which the query -operates.</para> - -<variablelist> - - <varlistentry><term><option>--installed</option></term> - - <listitem><para>The query operates on the store paths that are - installed in the current generation of the active profile. This - is the default.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--available</option></term> - <term><option>-a</option></term> - - <listitem><para>The query operates on the derivations that are - available in the active Nix expression.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Queries</title> - -<para>The following flags specify what information to display about -the selected derivations. Multiple flags may be specified, in which -case the information is shown in the order given here. Note that the -name of the derivation is shown unless <option>--no-name</option> is -specified.</para> - -<!-- TODO: fix the terminology here; i.e., derivations, store paths, -user environment elements, etc. --> - -<variablelist> - - <varlistentry><term><option>--xml</option></term> - - <listitem><para>Print the result in an XML representation suitable - for automatic processing by other tools. The root element is - called <literal>items</literal>, which contains a - <literal>item</literal> element for each available or installed - derivation. The fields discussed below are all stored in - attributes of the <literal>item</literal> - elements.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--json</option></term> - - <listitem><para>Print the result in a JSON representation suitable - for automatic processing by other tools.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--prebuilt-only</option> / <option>-b</option></term> - - <listitem><para>Show only derivations for which a substitute is - registered, i.e., there is a pre-built binary available that can - be downloaded in lieu of building the derivation. Thus, this - shows all packages that probably can be installed - quickly.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--status</option></term> - <term><option>-s</option></term> - - <listitem><para>Print the <emphasis>status</emphasis> of the - derivation. The status consists of three characters. The first - is <literal>I</literal> or <literal>-</literal>, indicating - whether the derivation is currently installed in the current - generation of the active profile. This is by definition the case - for <option>--installed</option>, but not for - <option>--available</option>. The second is <literal>P</literal> - or <literal>-</literal>, indicating whether the derivation is - present on the system. This indicates whether installation of an - available derivation will require the derivation to be built. The - third is <literal>S</literal> or <literal>-</literal>, indicating - whether a substitute is available for the - derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--attr-path</option></term> - <term><option>-P</option></term> - - <listitem><para>Print the <emphasis>attribute path</emphasis> of - the derivation, which can be used to unambiguously select it using - the <link linkend="opt-attr"><option>--attr</option> option</link> - available in commands that install derivations like - <literal>nix-env --install</literal>. This option only works - together with <option>--available</option></para></listitem> - - </varlistentry> - - <varlistentry><term><option>--no-name</option></term> - - <listitem><para>Suppress printing of the <literal>name</literal> - attribute of each derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--compare-versions</option> / - <option>-c</option></term> - - <listitem><para>Compare installed versions to available versions, - or vice versa (if <option>--available</option> is given). This is - useful for quickly seeing whether upgrades for installed - packages are available in a Nix expression. A column is added - with the following meaning: - - <variablelist> - - <varlistentry><term><literal><</literal> <replaceable>version</replaceable></term> - - <listitem><para>A newer version of the package is available - or installed.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal>=</literal> <replaceable>version</replaceable></term> - - <listitem><para>At most the same version of the package is - available or installed.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal>></literal> <replaceable>version</replaceable></term> - - <listitem><para>Only older versions of the package are - available or installed.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal>- ?</literal></term> - - <listitem><para>No version of the package is available or - installed.</para></listitem> - - </varlistentry> - - </variablelist> - - </para></listitem> - - </varlistentry> - - <varlistentry><term><option>--system</option></term> - - <listitem><para>Print the <literal>system</literal> attribute of - the derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--drv-path</option></term> - - <listitem><para>Print the path of the store - derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--out-path</option></term> - - <listitem><para>Print the output path of the - derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--description</option></term> - - <listitem><para>Print a short (one-line) description of the - derivation, if available. The description is taken from the - <literal>meta.description</literal> attribute of the - derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--meta</option></term> - - <listitem><para>Print all of the meta-attributes of the - derivation. This option is only available with - <option>--xml</option> or <option>--json</option>.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>To show installed packages: - -<screen> -$ nix-env -q -bison-1.875c -docbook-xml-4.2 -firefox-1.0.4 -MPlayer-1.0pre7 -ORBit2-2.8.3 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show available packages: - -<screen> -$ nix-env -qa -firefox-1.0.7 -GConf-2.4.0.1 -MPlayer-1.0pre7 -ORBit2-2.8.3 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show the status of available packages: - -<screen> -$ nix-env -qas --P- firefox-1.0.7 <lineannotation>(not installed but present)</lineannotation> ---S GConf-2.4.0.1 <lineannotation>(not present, but there is a substitute for fast installation)</lineannotation> ---S MPlayer-1.0pre3 <lineannotation>(i.e., this is not the installed MPlayer, even though the version is the same!)</lineannotation> -IP- ORBit2-2.8.3 <lineannotation>(installed and by definition present)</lineannotation> -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show available packages in the Nix expression <filename>foo.nix</filename>: - -<screen> -$ nix-env -f ./foo.nix -qa -foo-1.2.3 -</screen> - -</para> - -<para>To compare installed versions to what’s available: - -<screen> -$ nix-env -qc -<replaceable>...</replaceable> -acrobat-reader-7.0 - ? <lineannotation>(package is not available at all)</lineannotation> -autoconf-2.59 = 2.59 <lineannotation>(same version)</lineannotation> -firefox-1.0.4 < 1.0.7 <lineannotation>(a more recent version is available)</lineannotation> -<replaceable>...</replaceable> -</screen> - -</para> - -<para>To show all packages with “<literal>zip</literal>” in the name: - -<screen> -$ nix-env -qa '.*zip.*' -bzip2-1.0.6 -gzip-1.6 -zip-3.0 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show all packages with “<literal>firefox</literal>” or -“<literal>chromium</literal>” in the name: - -<screen> -$ nix-env -qa '.*(firefox|chromium).*' -chromium-37.0.2062.94 -chromium-beta-38.0.2125.24 -firefox-32.0.3 -firefox-with-plugins-13.0.1 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show all packages in the latest revision of the Nixpkgs -repository: - -<screen> -$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa -</screen> - -</para> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--switch-profile</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--switch-profile</option></arg> - <arg choice='plain'><option>-S</option></arg> - </group> - <arg choice='req'><replaceable>path</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>This operation makes <replaceable>path</replaceable> the current -profile for the user. That is, the symlink -<filename>~/.nix-profile</filename> is made to point to -<replaceable>path</replaceable>.</para> - -</refsection> - -<refsection><title>Examples</title> - -<screen> -$ nix-env -S ~/my-profile</screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--list-generations</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <arg choice='plain'><option>--list-generations</option></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>This operation print a list of all the currently existing -generations for the active profile. These may be switched to using -the <option>--switch-generation</option> operation. It also prints -the creation date of the generation, and indicates the current -generation.</para> - -</refsection> - - -<refsection><title>Examples</title> - -<screen> -$ nix-env --list-generations - 95 2004-02-06 11:48:24 - 96 2004-02-06 11:49:01 - 97 2004-02-06 16:22:45 - 98 2004-02-06 16:24:33 (current)</screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--delete-generations</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <arg choice='plain'><option>--delete-generations</option></arg> - <arg choice='plain' rep='repeat'><replaceable>generations</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>This operation deletes the specified generations of the current -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 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> - -<refsection><title>Examples</title> - -<screen> -$ nix-env --delete-generations 3 4 8 - -$ nix-env --delete-generations +5 - -$ nix-env --delete-generations 30d - -$ nix-env -p other_profile --delete-generations old</screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--switch-generation</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--switch-generation</option></arg> - <arg choice='plain'><option>-G</option></arg> - </group> - <arg choice='req'><replaceable>generation</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>This operation makes generation number -<replaceable>generation</replaceable> the current generation of the -active profile. That is, if the -<filename><replaceable>profile</replaceable></filename> is the path to -the active profile, then the symlink -<filename><replaceable>profile</replaceable></filename> is made to -point to -<filename><replaceable>profile</replaceable>-<replaceable>generation</replaceable>-link</filename>, -which is in turn a symlink to the actual user environment in the Nix -store.</para> - -<para>Switching will fail if the specified generation does not exist.</para> - -</refsection> - - -<refsection><title>Examples</title> - -<screen> -$ nix-env -G 42 -switching from generation 50 to 42</screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--rollback</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <arg choice='plain'><option>--rollback</option></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>This operation switches to the “previous” generation of the -active profile, that is, the highest numbered generation lower than -the current generation, if it exists. It is just a convenience -wrapper around <option>--list-generations</option> and -<option>--switch-generation</option>.</para> - -</refsection> - - -<refsection><title>Examples</title> - -<screen> -$ nix-env --rollback -switching from generation 92 to 91 - -$ nix-env --rollback -error: no generation older than the current (91) exists</screen> - -</refsection> - -</refsection> - - -<refsection condition="manpage"><title>Environment variables</title> - -<variablelist> - - <varlistentry><term><envar>NIX_PROFILE</envar></term> - - <listitem><para>Location of the Nix profile. Defaults to the - target of the symlink <filename>~/.nix-profile</filename>, if it - exists, or <filename>/nix/var/nix/profiles/default</filename> - otherwise.</para></listitem> - - </varlistentry> - - <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> -</variablelist> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-hash.xml b/doc/manual/command-ref/nix-hash.xml deleted file mode 100644 index 80263e18e..000000000 --- a/doc/manual/command-ref/nix-hash.xml +++ /dev/null @@ -1,176 +0,0 @@ -<refentry 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="sec-nix-hash"> - -<refmeta> - <refentrytitle>nix-hash</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-hash</refname> - <refpurpose>compute the cryptographic hash of a path</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-hash</command> - <arg><option>--flat</option></arg> - <arg><option>--base32</option></arg> - <arg><option>--truncate</option></arg> - <arg><option>--type</option> <replaceable>hashAlgo</replaceable></arg> - <arg choice='plain' rep='repeat'><replaceable>path</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>nix-hash</command> - <arg choice='plain'><option>--to-base16</option></arg> - <arg choice='plain' rep='repeat'><replaceable>hash</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>nix-hash</command> - <arg choice='plain'><option>--to-base32</option></arg> - <arg choice='plain' rep='repeat'><replaceable>hash</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>The command <command>nix-hash</command> computes the -cryptographic hash of the contents of each -<replaceable>path</replaceable> and prints it on standard output. By -default, it computes an MD5 hash, but other hash algorithms are -available as well. The hash is printed in hexadecimal. To generate -the same hash as <command>nix-prefetch-url</command> you have to -specify multiple arguments, see below for an example.</para> - -<para>The hash is computed over a <emphasis>serialisation</emphasis> -of each path: a dump of the file system tree rooted at the path. This -allows directories and symlinks to be hashed as well as regular files. -The dump is in the <emphasis>NAR format</emphasis> produced by <link -linkend="refsec-nix-store-dump"><command>nix-store</command> -<option>--dump</option></link>. Thus, <literal>nix-hash -<replaceable>path</replaceable></literal> yields the same -cryptographic hash as <literal>nix-store --dump -<replaceable>path</replaceable> | md5sum</literal>.</para> - -</refsection> - - -<refsection><title>Options</title> - -<variablelist> - - <varlistentry><term><option>--flat</option></term> - - <listitem><para>Print the cryptographic hash of the contents of - each regular file <replaceable>path</replaceable>. That is, do - not compute the hash over the dump of - <replaceable>path</replaceable>. The result is identical to that - produced by the GNU commands <command>md5sum</command> and - <command>sha1sum</command>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--base32</option></term> - - <listitem><para>Print the hash in a base-32 representation rather - than hexadecimal. This base-32 representation is more compact and - can be used in Nix expressions (such as in calls to - <function>fetchurl</function>).</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--truncate</option></term> - - <listitem><para>Truncate hashes longer than 160 bits (such as - SHA-256) to 160 bits.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--type</option> <replaceable>hashAlgo</replaceable></term> - - <listitem><para>Use the specified cryptographic hash algorithm, - which can be one of <literal>md5</literal>, - <literal>sha1</literal>, and - <literal>sha256</literal>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--to-base16</option></term> - - <listitem><para>Don’t hash anything, but convert the base-32 hash - representation <replaceable>hash</replaceable> to - hexadecimal.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--to-base32</option></term> - - <listitem><para>Don’t hash anything, but convert the hexadecimal - hash representation <replaceable>hash</replaceable> to - base-32.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>Computing the same hash as <command>nix-prefetch-url</command>: -<screen> -$ nix-prefetch-url file://<(echo test) -1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj -$ nix-hash --type sha256 --flat --base32 <(echo test) -1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj -</screen> -</para> - -<para>Computing hashes: - -<screen> -$ mkdir test -$ echo "hello" > test/world - -$ nix-hash test/ <lineannotation>(MD5 hash; default)</lineannotation> -8179d3caeff1869b5ba1744e5a245c04 - -$ nix-store --dump test/ | md5sum <lineannotation>(for comparison)</lineannotation> -8179d3caeff1869b5ba1744e5a245c04 - - -$ nix-hash --type sha1 test/ -e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 - -$ nix-hash --type sha1 --base32 test/ -nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 - -$ nix-hash --type sha256 --flat test/ -error: reading file `test/': Is a directory - -$ nix-hash --type sha256 --flat test/world -5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03</screen> - -</para> - -<para>Converting between hexadecimal and base-32: - -<screen> -$ nix-hash --type sha1 --to-base32 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 -nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 - -$ nix-hash --type sha1 --to-base16 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 -e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6</screen> - -</para> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-instantiate.xml b/doc/manual/command-ref/nix-instantiate.xml deleted file mode 100644 index 53f06aed1..000000000 --- a/doc/manual/command-ref/nix-instantiate.xml +++ /dev/null @@ -1,266 +0,0 @@ -<refentry 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="sec-nix-instantiate"> - -<refmeta> - <refentrytitle>nix-instantiate</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-instantiate</refname> - <refpurpose>instantiate store derivations from Nix expressions</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-instantiate</command> - <group> - <arg choice='plain'><option>--parse</option></arg> - <arg choice='plain'> - <option>--eval</option> - <arg><option>--strict</option></arg> - <arg><option>--json</option></arg> - <arg><option>--xml</option></arg> - </arg> - </group> - <arg><option>--read-write-mode</option></arg> - <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr</option></arg> - <arg choice='plain'><option>-A</option></arg> - </group> - <replaceable>attrPath</replaceable> - </arg> - <arg><option>--add-root</option> <replaceable>path</replaceable></arg> - <arg><option>--indirect</option></arg> - <group> - <arg choice='plain'><option>--expr</option></arg> - <arg choice='plain'><option>-E</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>nix-instantiate</command> - <arg choice='plain'><option>--find-file</option></arg> - <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>The command <command>nix-instantiate</command> generates <link -linkend="gloss-derivation">store derivations</link> from (high-level) -Nix expressions. It evaluates the Nix expressions in each of -<replaceable>files</replaceable> (which defaults to -<replaceable>./default.nix</replaceable>). Each top-level expression -should evaluate to a derivation, a list of derivations, or a set of -derivations. The paths of the resulting store derivations are printed -on standard output.</para> - -<para>If <replaceable>files</replaceable> is the character -<literal>-</literal>, then a Nix expression will be read from standard -input.</para> - -<para condition="manual">See also <xref linkend="sec-common-options" -/> for a list of common options.</para> - -</refsection> - - -<refsection><title>Options</title> - -<variablelist> - - <varlistentry> - <term><option>--add-root</option> <replaceable>path</replaceable></term> - <term><option>--indirect</option></term> - - <listitem><para>See the <link linkend="opt-add-root">corresponding - options</link> in <command>nix-store</command>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--parse</option></term> - - <listitem><para>Just parse the input files, and print their - abstract syntax trees on standard output in ATerm - format.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--eval</option></term> - - <listitem><para>Just parse and evaluate the input files, and print - the resulting values on standard output. No instantiation of - store derivations takes place.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--find-file</option></term> - - <listitem><para>Look up the given files in Nix’s search path (as - specified by the <envar linkend="env-NIX_PATH">NIX_PATH</envar> - environment variable). If found, print the corresponding absolute - paths on standard output. For instance, if - <envar>NIX_PATH</envar> is - <literal>nixpkgs=/home/alice/nixpkgs</literal>, then - <literal>nix-instantiate --find-file nixpkgs/default.nix</literal> - will print - <literal>/home/alice/nixpkgs/default.nix</literal>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--strict</option></term> - - <listitem><para>When used with <option>--eval</option>, - recursively evaluate list elements and attributes. Normally, such - sub-expressions are left unevaluated (since the Nix expression - language is lazy).</para> - - <warning><para>This option can cause non-termination, because lazy - data structures can be infinitely large.</para></warning> - - </listitem> - - </varlistentry> - - <varlistentry><term><option>--json</option></term> - - <listitem><para>When used with <option>--eval</option>, print the resulting - value as an JSON representation of the abstract syntax tree rather - than as an ATerm.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--xml</option></term> - - <listitem><para>When used with <option>--eval</option>, print the resulting - value as an XML representation of the abstract syntax tree rather than as - an ATerm. The schema is the same as that used by the <link - linkend="builtin-toXML"><function>toXML</function> built-in</link>. - </para></listitem> - - </varlistentry> - - <varlistentry><term><option>--read-write-mode</option></term> - - <listitem><para>When used with <option>--eval</option>, perform - evaluation in read/write mode so nix language features that - require it will still work (at the cost of needing to do - instantiation of every evaluated derivation). If this option is - not enabled, there may be uninstantiated store paths in the final - output.</para> - - </listitem> - - </varlistentry> - -</variablelist> - -<variablelist condition="manpage"> - <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>Instantiating store derivations from a Nix expression, and -building them using <command>nix-store</command>: - -<screen> -$ nix-instantiate test.nix <lineannotation>(instantiate)</lineannotation> -/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv - -$ nix-store -r $(nix-instantiate test.nix) <lineannotation>(build)</lineannotation> -<replaceable>...</replaceable> -/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 <lineannotation>(output path)</lineannotation> - -$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 -dr-xr-xr-x 2 eelco users 4096 1970-01-01 01:00 lib -...</screen> - -</para> - -<para>You can also give a Nix expression on the command line: - -<screen> -$ nix-instantiate -E 'with import <nixpkgs> { }; hello' -/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv -</screen> - -This is equivalent to: - -<screen> -$ nix-instantiate '<nixpkgs>' -A hello -</screen> - -</para> - -<para>Parsing and evaluating Nix expressions: - -<screen> -$ nix-instantiate --parse -E '1 + 2' -1 + 2 - -$ nix-instantiate --eval -E '1 + 2' -3 - -$ nix-instantiate --eval --xml -E '1 + 2' -<![CDATA[<?xml version='1.0' encoding='utf-8'?> -<expr> - <int value="3" /> -</expr>]]></screen> - -</para> - -<para>The difference between non-strict and strict evaluation: - -<screen> -$ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }' -<replaceable>...</replaceable><![CDATA[ - <attr name="x"> - <string value="foo" /> - </attr> - <attr name="y"> - <unevaluated /> - </attr>]]> -<replaceable>...</replaceable></screen> - -Note that <varname>y</varname> is left unevaluated (the XML -representation doesn’t attempt to show non-normal forms). - -<screen> -$ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }' -<replaceable>...</replaceable><![CDATA[ - <attr name="x"> - <string value="foo" /> - </attr> - <attr name="y"> - <string value="foo" /> - </attr>]]> -<replaceable>...</replaceable></screen> - -</para> - -</refsection> - - -<refsection condition="manpage"><title>Environment variables</title> - -<variablelist> - <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> -</variablelist> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-prefetch-url.xml b/doc/manual/command-ref/nix-prefetch-url.xml deleted file mode 100644 index 621ded72e..000000000 --- a/doc/manual/command-ref/nix-prefetch-url.xml +++ /dev/null @@ -1,131 +0,0 @@ -<refentry 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="sec-nix-prefetch-url"> - -<refmeta> - <refentrytitle>nix-prefetch-url</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-prefetch-url</refname> - <refpurpose>copy a file from a URL into the store and print its hash</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-prefetch-url</command> - <arg><option>--version</option></arg> - <arg><option>--type</option> <replaceable>hashAlgo</replaceable></arg> - <arg><option>--print-path</option></arg> - <arg><option>--unpack</option></arg> - <arg><option>--name</option> <replaceable>name</replaceable></arg> - <arg choice='plain'><replaceable>url</replaceable></arg> - <arg><replaceable>hash</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - -<refsection><title>Description</title> - -<para>The command <command>nix-prefetch-url</command> downloads the -file referenced by the URL <replaceable>url</replaceable>, prints its -cryptographic hash, and copies it into the Nix store. The file name -in the store is -<filename><replaceable>hash</replaceable>-<replaceable>baseName</replaceable></filename>, -where <replaceable>baseName</replaceable> is everything following the -final slash in <replaceable>url</replaceable>.</para> - -<para>This command is just a convenience for Nix expression writers. -Often a Nix expression fetches some source distribution from the -network using the <literal>fetchurl</literal> expression contained in -Nixpkgs. However, <literal>fetchurl</literal> requires a -cryptographic hash. If you don't know the hash, you would have to -download the file first, and then <literal>fetchurl</literal> would -download it again when you build your Nix expression. Since -<literal>fetchurl</literal> uses the same name for the downloaded file -as <command>nix-prefetch-url</command>, the redundant download can be -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 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, -if the option <option>--print-path</option> is used, the path of the -downloaded file in the Nix store is also printed.</para> - -</refsection> - - -<refsection><title>Options</title> - -<variablelist> - - <varlistentry><term><option>--type</option> <replaceable>hashAlgo</replaceable></term> - - <listitem><para>Use the specified cryptographic hash algorithm, - which can be one of <literal>md5</literal>, - <literal>sha1</literal>, and - <literal>sha256</literal>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--print-path</option></term> - - <listitem><para>Print the store path of the downloaded file on - standard output.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--unpack</option></term> - - <listitem><para>Unpack the archive (which must be a tarball or zip - file) and add the result to the Nix store. The resulting hash can - be used with functions such as Nixpkgs’s - <varname>fetchzip</varname> or - <varname>fetchFromGitHub</varname>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--name</option> <replaceable>name</replaceable></term> - - <listitem><para>Override the name of the file in the Nix store. By - default, this is - <literal><replaceable>hash</replaceable>-<replaceable>basename</replaceable></literal>, - where <replaceable>basename</replaceable> is the last component of - <replaceable>url</replaceable>. Overriding the name is necessary - when <replaceable>basename</replaceable> contains characters that - are not allowed in Nix store paths.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<screen> -$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz -0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i - -$ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz -0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i -/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz - -$ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz -079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7 -/nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz -</screen> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml deleted file mode 100644 index 2fef323c5..000000000 --- a/doc/manual/command-ref/nix-shell.xml +++ /dev/null @@ -1,411 +0,0 @@ -<refentry 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="sec-nix-shell"> - -<refmeta> - <refentrytitle>nix-shell</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-shell</refname> - <refpurpose>start an interactive shell based on a Nix expression</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-shell</command> - <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr</option></arg> - <arg choice='plain'><option>-A</option></arg> - </group> - <replaceable>attrPath</replaceable> - </arg> - <arg><option>--command</option> <replaceable>cmd</replaceable></arg> - <arg><option>--run</option> <replaceable>cmd</replaceable></arg> - <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg> - <arg><option>--pure</option></arg> - <arg><option>--keep</option> <replaceable>name</replaceable></arg> - <group choice='req'> - <arg choice='plain'> - <group choice='req'> - <arg choice='plain'><option>--packages</option></arg> - <arg choice='plain'><option>-p</option></arg> - </group> - <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> - </cmdsynopsis> -</refsynopsisdiv> - -<refsection><title>Description</title> - -<para>The command <command>nix-shell</command> will build the -dependencies of the specified derivation, but not the derivation -itself. It will then start an interactive shell in which all -environment variables defined by the derivation -<replaceable>path</replaceable> have been set to their corresponding -values, and the script <literal>$stdenv/setup</literal> has been -sourced. This is useful for reproducing the environment of a -derivation for development.</para> - -<para>If <replaceable>path</replaceable> is not given, -<command>nix-shell</command> defaults to -<filename>shell.nix</filename> if it exists, and -<filename>default.nix</filename> otherwise.</para> - -<para>If <replaceable>path</replaceable> starts with -<literal>http://</literal> or <literal>https://</literal>, it is -interpreted as the URL of a tarball that will be downloaded and -unpacked to a temporary location. The tarball must include a single -top-level directory containing at least a file named -<filename>default.nix</filename>.</para> - -<para>If the derivation defines the variable -<varname>shellHook</varname>, it will be evaluated after -<literal>$stdenv/setup</literal> has been sourced. Since this hook is -not executed by regular Nix builds, it allows you to perform -initialisation specific to <command>nix-shell</command>. For example, -the derivation attribute - -<programlisting> -shellHook = - '' - echo "Hello shell" - ''; -</programlisting> - -will cause <command>nix-shell</command> to print <literal>Hello shell</literal>.</para> - -</refsection> - - -<refsection><title>Options</title> - -<para>All options not listed here are passed to <command>nix-store ---realise</command>, except for <option>--arg</option> and -<option>--attr</option> / <option>-A</option> which are passed to -<command>nix-instantiate</command>. <phrase condition="manual">See -also <xref linkend="sec-common-options" />.</phrase></para> - -<variablelist> - - <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term> - - <listitem><para>In the environment of the derivation, run the - shell command <replaceable>cmd</replaceable>. This command is - executed in an interactive shell. (Use <option>--run</option> to - use a non-interactive shell instead.) However, a call to - <literal>exit</literal> is implicitly added to the command, so the - shell will exit after running the command. To prevent this, add - <literal>return</literal> at the end; e.g. <literal>--command - "echo Hello; return"</literal> will print <literal>Hello</literal> - and then drop you into the interactive shell. This can be useful - for doing any additional initialisation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--run</option> <replaceable>cmd</replaceable></term> - - <listitem><para>Like <option>--command</option>, but executes the - command in a non-interactive shell. This means (among other - things) that if you hit Ctrl-C while the command is running, the - shell exits.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term> - - <listitem><para>Do not build any dependencies whose store path - matches the regular expression <replaceable>regexp</replaceable>. - This option may be specified multiple times.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--pure</option></term> - - <listitem><para>If this flag is specified, the environment is - almost entirely cleared before the interactive shell is started, - so you get an environment that more closely corresponds to the - “real” Nix build. A few variables, in particular - <envar>HOME</envar>, <envar>USER</envar> and - <envar>DISPLAY</envar>, are retained. Note that - <filename>~/.bashrc</filename> and (depending on your Bash - installation) <filename>/etc/bashrc</filename> are still sourced, - so any variables set there will affect the interactive - shell.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--packages</option> / <option>-p</option> <replaceable>packages</replaceable>…</term> - - <listitem><para>Set up an environment in which the specified - packages are present. The command line arguments are interpreted - as attribute names inside the Nix Packages collection. Thus, - <literal>nix-shell -p libjpeg openjdk</literal> will start a shell - in which the packages denoted by the attribute names - <varname>libjpeg</varname> and <varname>openjdk</varname> are - present.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>-i</option> <replaceable>interpreter</replaceable></term> - - <listitem><para>The chained script interpreter to be invoked by - <command>nix-shell</command>. Only applicable in - <literal>#!</literal>-scripts (described <link - linkend="ssec-nix-shell-shebang">below</link>).</para> - - </listitem></varlistentry> - - <varlistentry><term><option>--keep</option> <replaceable>name</replaceable></term> - - <listitem><para>When a <option>--pure</option> shell is started, - keep the listed environment variables.</para></listitem> - - </varlistentry> - -</variablelist> - -<para>The following common options are supported:</para> - -<variablelist condition="manpage"> - <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> -</variablelist> - -</refsection> - - -<refsection><title>Environment variables</title> - -<variablelist> - - <varlistentry><term><envar>NIX_BUILD_SHELL</envar></term> - - <listitem><para>Shell used to start the interactive environment. - Defaults to the <command>bash</command> found in <envar>PATH</envar>.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>To build the dependencies of the package Pan, and start an -interactive shell in which to build it: - -<screen> -$ nix-shell '<nixpkgs>' -A pan -[nix-shell]$ unpackPhase -[nix-shell]$ cd pan-* -[nix-shell]$ configurePhase -[nix-shell]$ buildPhase -[nix-shell]$ ./pan/gui/pan -</screen> - -To clear the environment first, and do some additional automatic -initialisation of the interactive shell: - -<screen> -$ nix-shell '<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 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> -$ nix-shell -E 'with import <nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""' -</screen> - -A shorter way to do the same is: - -<screen> -$ nix-shell -p sqlite xorg.libX11 -[nix-shell]$ echo $NIX_LDFLAGS -… -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 -containing the Pan package from a specific revision of Nixpkgs: - -<screen> -$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz - -[nix-shell:~]$ pan --version -Pan 0.139 -</screen> - -</para> - -</refsection> - - -<refsection xml:id="ssec-nix-shell-shebang"><title>Use as a <literal>#!</literal>-interpreter</title> - -<para>You can use <command>nix-shell</command> as a script interpreter -to allow scripts written in arbitrary languages to obtain their own -dependencies via Nix. This is done by starting the script with the -following lines: - -<programlisting> -#! /usr/bin/env nix-shell -#! nix-shell -i <replaceable>real-interpreter</replaceable> -p <replaceable>packages</replaceable> -</programlisting> - -where <replaceable>real-interpreter</replaceable> is the “real” script -interpreter that will be invoked by <command>nix-shell</command> after -it has obtained the dependencies and initialised the environment, and -<replaceable>packages</replaceable> are the attribute names of the -dependencies in Nixpkgs.</para> - -<para>The lines starting with <literal>#! nix-shell</literal> specify -<command>nix-shell</command> options (see above). Note that you cannot -write <literal>#! /usr/bin/env nix-shell -i ...</literal> because -many operating systems only allow one argument in -<literal>#!</literal> lines.</para> - -<para>For example, here is a Python script that depends on Python and -the <literal>prettytable</literal> package: - -<programlisting> -#! /usr/bin/env nix-shell -#! nix-shell -i python -p python pythonPackages.prettytable - -import prettytable - -# Print a simple table. -t = prettytable.PrettyTable(["N", "N^2"]) -for n in range(1, 10): t.add_row([n, n * n]) -print t -</programlisting> - -</para> - -<para>Similarly, the following is a Perl script that specifies that it -requires Perl and the <literal>HTML::TokeParser::Simple</literal> and -<literal>LWP</literal> packages: - -<programlisting> -#! /usr/bin/env nix-shell -#! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP - -use HTML::TokeParser::Simple; - -# Fetch nixos.org and print all hrefs. -my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/'); - -while (my $token = $p->get_tag("a")) { - my $href = $token->get_attr("href"); - print "$href\n" if $href; -} -</programlisting> - -</para> - -<para>Sometimes you need to pass a simple Nix expression to customize -a package like Terraform: - -<programlisting><![CDATA[ -#! /usr/bin/env nix-shell -#! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])" - -terraform apply -]]></programlisting> - -<note><para>You must use double quotes (<literal>"</literal>) when -passing a simple Nix expression in a nix-shell shebang.</para></note> -</para> - -<para>Finally, using the merging of multiple nix-shell shebangs the -following Haskell script uses a specific branch of Nixpkgs/NixOS (the -18.03 stable branch): - -<programlisting><![CDATA[ -#! /usr/bin/env nix-shell -#! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.HTTP ps.tagsoup])" -#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-18.03.tar.gz - -import Network.HTTP -import Text.HTML.TagSoup - --- Fetch nixos.org and print all hrefs. -main = do - resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/") - body <- getResponseBody resp - let tags = filter (isTagOpenName "a") $ parseTags body - let tags' = map (fromAttrib "href") tags - mapM_ putStrLn $ filter (/= "") tags' -]]></programlisting> - -If you want to be even more precise, you can specify a specific -revision of Nixpkgs: - -<programlisting> -#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz -</programlisting> - -</para> - -<para>The examples above all used <option>-p</option> to get -dependencies from Nixpkgs. You can also use a Nix expression to build -your own dependencies. For example, the Python example could have been -written as: - -<programlisting> -#! /usr/bin/env nix-shell -#! nix-shell deps.nix -i python -</programlisting> - -where the file <filename>deps.nix</filename> in the same directory -as the <literal>#!</literal>-script contains: - -<programlisting> -with import <nixpkgs> {}; - -runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } "" -</programlisting> - -</para> - -</refsection> - - -<refsection condition="manpage"><title>Environment variables</title> - -<variablelist> - <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> -</variablelist> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-store.xml b/doc/manual/command-ref/nix-store.xml deleted file mode 100644 index d71f9d8e4..000000000 --- a/doc/manual/command-ref/nix-store.xml +++ /dev/null @@ -1,1516 +0,0 @@ -<refentry 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="sec-nix-store"> - -<refmeta> - <refentrytitle>nix-store</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-store</refname> - <refpurpose>manipulate or query the Nix store</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-store</command> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> - <arg><option>--add-root</option> <replaceable>path</replaceable></arg> - <arg><option>--indirect</option></arg> - <arg choice='plain'><replaceable>operation</replaceable></arg> - <arg rep='repeat'><replaceable>options</replaceable></arg> - <arg rep='repeat'><replaceable>arguments</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>The command <command>nix-store</command> performs primitive -operations on the Nix store. You generally do not need to run this -command manually.</para> - -<para><command>nix-store</command> takes exactly one -<emphasis>operation</emphasis> flag which indicates the subcommand to -be performed. These are documented below.</para> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Common options</title> - -<para>This section lists the options that are common to all -operations. These options are allowed for every subcommand, though -they may not always have an effect. <phrase condition="manual">See -also <xref linkend="sec-common-options" /> for a list of common -options.</phrase></para> - -<variablelist> - - <varlistentry xml:id="opt-add-root"><term><option>--add-root</option> <replaceable>path</replaceable></term> - - <listitem><para>Causes the result of a realisation - (<option>--realise</option> and <option>--force-realise</option>) - to be registered as a root of the garbage collector<phrase - condition="manual"> (see <xref linkend="ssec-gc-roots" - />)</phrase>. The root is stored in - <replaceable>path</replaceable>, which must be inside a directory - that is scanned for roots by the garbage collector (i.e., - typically in a subdirectory of - <filename>/nix/var/nix/gcroots/</filename>) - <emphasis>unless</emphasis> the <option>--indirect</option> flag - is used.</para> - - <para>If there are multiple results, then multiple symlinks will - be created by sequentially numbering symlinks beyond the first one - (e.g., <filename>foo</filename>, <filename>foo-2</filename>, - <filename>foo-3</filename>, and so on).</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--indirect</option></term> - - <listitem> - - <para>In conjunction with <option>--add-root</option>, this option - allows roots to be stored <emphasis>outside</emphasis> of the GC - roots directory. This is useful for commands such as - <command>nix-build</command> that place a symlink to the build - result in the current directory; such a build result should not be - garbage-collected unless the symlink is removed.</para> - - <para>The <option>--indirect</option> flag causes a uniquely named - symlink to <replaceable>path</replaceable> to be stored in - <filename>/nix/var/nix/gcroots/auto/</filename>. For instance, - - <screen> -$ nix-store --add-root /home/eelco/bla/result --indirect -r <replaceable>...</replaceable> - -$ ls -l /nix/var/nix/gcroots/auto -lrwxrwxrwx 1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result - -$ ls -l /home/eelco/bla/result -lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10</screen> - - Thus, when <filename>/home/eelco/bla/result</filename> is removed, - the GC root in the <filename>auto</filename> directory becomes a - dangling symlink and will be ignored by the collector.</para> - - <warning><para>Note that it is not possible to move or rename - indirect GC roots, since the symlink in the - <filename>auto</filename> directory will still point to the old - location.</para></warning> - - </listitem> - - </varlistentry> - -</variablelist> - -<variablelist condition="manpage"> - <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> -</variablelist> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id='rsec-nix-store-realise'><title>Operation <option>--realise</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <group choice='req'> - <arg choice='plain'><option>--realise</option></arg> - <arg choice='plain'><option>-r</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - <arg><option>--dry-run</option></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--realise</option> essentially “builds” -the specified store paths. Realisation is a somewhat overloaded term: - -<itemizedlist> - - <listitem><para>If the store path is a - <emphasis>derivation</emphasis>, realisation ensures that the output - paths of the derivation are <link - linkend="gloss-validity">valid</link> (i.e., the output path and its - closure exist in the file system). This can be done in several - ways. First, it is possible that the outputs are already valid, in - which case we are done immediately. Otherwise, there may be <link - linkend="gloss-substitute">substitutes</link> that produce the - outputs (e.g., by downloading them). Finally, the outputs can be - produced by performing the build action described by the - derivation.</para></listitem> - - <listitem><para>If the store path is not a derivation, realisation - ensures that the specified path is valid (i.e., it and its closure - exist in the file system). If the path is already valid, we are - done immediately. Otherwise, the path and any missing paths in its - closure may be produced through substitutes. If there are no - (successful) subsitutes, realisation fails.</para></listitem> - -</itemizedlist> - -</para> - -<para>The output path of each derivation is printed on standard -output. (For non-derivations argument, the argument itself is -printed.)</para> - -<para>The following flags are available:</para> - -<variablelist> - - <varlistentry><term><option>--dry-run</option></term> - - <listitem><para>Print on standard error a description of what - packages would be built or downloaded, without actually performing - the operation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--ignore-unknown</option></term> - - <listitem><para>If a non-derivation path does not have a - substitute, then silently ignore it.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--check</option></term> - - <listitem><para>This option allows you to check whether a - derivation is deterministic. It rebuilds the specified derivation - and checks whether the result is bitwise-identical with the - existing outputs, printing an error if that’s not the case. The - outputs of the specified derivation must already exist. When used - with <option>-K</option>, if an output path is not identical to - the corresponding output from the previous build, the new output - path is left in - <filename>/nix/store/<replaceable>name</replaceable>.check.</filename></para> - - <para>See also the <option>build-repeat</option> configuration - option, which repeats a derivation a number of times and prevents - its outputs from being registered as “valid” in the Nix store - unless they are identical.</para></listitem> - - </varlistentry> - -</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> - - -<refsection><title>Examples</title> - -<para>This operation is typically used to build store derivations -produced by <link -linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>: - -<screen> -$ nix-store -r $(nix-instantiate ./test.nix) -/nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1</screen> - -This is essentially what <link -linkend="sec-nix-build"><command>nix-build</command></link> does.</para> - -<para>To test whether a previously-built derivation is deterministic: - -<screen> -$ nix-build '<nixpkgs>' -A hello --check -K -</screen> - -</para> - -</refsection> - - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id='rsec-nix-store-serve'><title>Operation <option>--serve</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--serve</option></arg> - <arg><option>--write</option></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--serve</option> provides access to -the Nix store over stdin and stdout, and is intended to be used -as a means of providing Nix store access to a restricted ssh user. -</para> - -<para>The following flags are available:</para> - -<variablelist> - - <varlistentry><term><option>--write</option></term> - - <listitem><para>Allow the connected client to request the realization - of derivations. In effect, this can be used to make the host act - as a remote builder.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>To turn a host into a build server, the -<filename>authorized_keys</filename> file can be used to provide build -access to a given SSH public key: - -<screen> -$ cat <<EOF >>/root/.ssh/authorized_keys -command="nice -n20 nix-store --serve --write" ssh-rsa AAAAB3NzaC1yc2EAAAA... -EOF -</screen> - -</para> - -</refsection> - - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id='rsec-nix-store-gc'><title>Operation <option>--gc</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--gc</option></arg> - <group> - <arg choice='plain'><option>--print-roots</option></arg> - <arg choice='plain'><option>--print-live</option></arg> - <arg choice='plain'><option>--print-dead</option></arg> - </group> - <arg><option>--max-freed</option> <replaceable>bytes</replaceable></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>Without additional flags, the operation <option>--gc</option> -performs a garbage collection on the Nix store. That is, all paths in -the Nix store not reachable via file system references from a set of -“roots”, are deleted.</para> - -<para>The following suboperations may be specified:</para> - -<variablelist> - - <varlistentry><term><option>--print-roots</option></term> - - <listitem><para>This operation prints on standard output the set - of roots used by the garbage collector. What constitutes a root - is described in <xref linkend="ssec-gc-roots" - />.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--print-live</option></term> - - <listitem><para>This operation prints on standard output the set - of “live” store paths, which are all the store paths reachable - from the roots. Live paths should never be deleted, since that - would break consistency — it would become possible that - applications are installed that reference things that are no - longer present in the store.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--print-dead</option></term> - - <listitem><para>This operation prints out on standard output the - set of “dead” store paths, which is just the opposite of the set - of live paths: any path in the store that is not live (with - respect to the roots) is dead.</para></listitem> - - </varlistentry> - -</variablelist> - -<para>By default, all unreachable paths are deleted. The following -options control what gets deleted and in what order: - -<variablelist> - - <varlistentry><term><option>--max-freed</option> <replaceable>bytes</replaceable></term> - - <listitem><para>Keep deleting paths until at least - <replaceable>bytes</replaceable> bytes have been deleted, then - stop. The argument <replaceable>bytes</replaceable> can be - followed by the multiplicative suffix <literal>K</literal>, - <literal>M</literal>, <literal>G</literal> or - <literal>T</literal>, denoting KiB, MiB, GiB or TiB - units.</para></listitem> - - </varlistentry> - -</variablelist> - -</para> - -<para>The behaviour of the collector is also influenced by the <link -linkend="conf-keep-outputs"><literal>keep-outputs</literal></link> -and <link -linkend="conf-keep-derivations"><literal>keep-derivations</literal></link> -variables in the Nix configuration file.</para> - -<para>By default, the collector prints the total number of freed bytes -when it finishes (or when it is interrupted). With -<option>--print-dead</option>, it prints the number of bytes that would -be freed.</para> - -</refsection> - - -<refsection><title>Examples</title> - -<para>To delete all unreachable paths, just do: - -<screen> -$ nix-store --gc -deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv' -<replaceable>...</replaceable> -8825586 bytes freed (8.42 MiB)</screen> - -</para> - -<para>To delete at least 100 MiBs of unreachable paths: - -<screen> -$ nix-store --gc --max-freed $((100 * 1024 * 1024))</screen> - -</para> - -</refsection> - - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--delete</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--delete</option></arg> - <arg><option>--ignore-liveness</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--delete</option> deletes the store paths -<replaceable>paths</replaceable> from the Nix store, but only if it is -safe to do so; that is, when the path is not reachable from a root of -the garbage collector. This means that you can only delete paths that -would also be deleted by <literal>nix-store --gc</literal>. Thus, -<literal>--delete</literal> is a more targeted version of -<literal>--gc</literal>.</para> - -<para>With the option <option>--ignore-liveness</option>, reachability -from the roots is ignored. However, the path still won’t be deleted -if there are other paths in the store that refer to it (i.e., depend -on it).</para> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store --delete /nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4 -0 bytes freed (0.00 MiB) -error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4' since it is still alive</screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id='refsec-nix-store-query'><title>Operation <option>--query</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <group choice='req'> - <arg choice='plain'><option>--query</option></arg> - <arg choice='plain'><option>-q</option></arg> - </group> - <group choice='req'> - <arg choice='plain'><option>--outputs</option></arg> - <arg choice='plain'><option>--requisites</option></arg> - <arg choice='plain'><option>-R</option></arg> - <arg choice='plain'><option>--references</option></arg> - <arg choice='plain'><option>--referrers</option></arg> - <arg choice='plain'><option>--referrers-closure</option></arg> - <arg choice='plain'><option>--deriver</option></arg> - <arg choice='plain'><option>-d</option></arg> - <arg choice='plain'><option>--graph</option></arg> - <arg choice='plain'><option>--tree</option></arg> - <arg choice='plain'><option>--binding</option> <replaceable>name</replaceable></arg> - <arg choice='plain'><option>-b</option> <replaceable>name</replaceable></arg> - <arg choice='plain'><option>--hash</option></arg> - <arg choice='plain'><option>--size</option></arg> - <arg choice='plain'><option>--roots</option></arg> - </group> - <arg><option>--use-output</option></arg> - <arg><option>-u</option></arg> - <arg><option>--force-realise</option></arg> - <arg><option>-f</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>The operation <option>--query</option> displays various bits of -information about the store paths . The queries are described below. At -most one query can be specified. The default query is -<option>--outputs</option>.</para> - -<para>The paths <replaceable>paths</replaceable> may also be symlinks -from outside of the Nix store, to the Nix store. In that case, the -query is applied to the target of the symlink.</para> - - -</refsection> - - -<refsection><title>Common query options</title> - -<variablelist> - - <varlistentry><term><option>--use-output</option></term> - <term><option>-u</option></term> - - <listitem><para>For each argument to the query that is a store - derivation, apply the query to the output path of the derivation - instead.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--force-realise</option></term> - <term><option>-f</option></term> - - <listitem><para>Realise each argument to the query first (see - <link linkend="rsec-nix-store-realise"><command>nix-store - --realise</command></link>).</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection xml:id='nixref-queries'><title>Queries</title> - -<variablelist> - - <varlistentry><term><option>--outputs</option></term> - - <listitem><para>Prints out the <link - linkend="gloss-output-path">output paths</link> of the store - derivations <replaceable>paths</replaceable>. These are the paths - that will be produced when the derivation is - built.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--requisites</option></term> - <term><option>-R</option></term> - - <listitem><para>Prints out the <link - linkend="gloss-closure">closure</link> of the store path - <replaceable>paths</replaceable>.</para> - - <para>This query has one option:</para> - - <variablelist> - - <varlistentry><term><option>--include-outputs</option></term> - - <listitem><para>Also include the output path of store - derivations, and their closures.</para></listitem> - - </varlistentry> - - </variablelist> - - <para>This query can be used to implement various kinds of - deployment. A <emphasis>source deployment</emphasis> is obtained - by distributing the closure of a store derivation. A - <emphasis>binary deployment</emphasis> is obtained by distributing - the closure of an output path. A <emphasis>cache - deployment</emphasis> (combined source/binary deployment, - including binaries of build-time-only dependencies) is obtained by - distributing the closure of a store derivation and specifying the - option <option>--include-outputs</option>.</para> - - </listitem> - - </varlistentry> - - <varlistentry><term><option>--references</option></term> - - <listitem><para>Prints the set of <link - linkend="gloss-reference">references</link> of the store paths - <replaceable>paths</replaceable>, that is, their immediate - dependencies. (For <emphasis>all</emphasis> dependencies, use - <option>--requisites</option>.)</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--referrers</option></term> - - <listitem><para>Prints the set of <emphasis>referrers</emphasis> of - the store paths <replaceable>paths</replaceable>, that is, the - store paths currently existing in the Nix store that refer to one - of <replaceable>paths</replaceable>. Note that contrary to the - references, the set of referrers is not constant; it can change as - store paths are added or removed.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--referrers-closure</option></term> - - <listitem><para>Prints the closure of the set of store paths - <replaceable>paths</replaceable> under the referrers relation; that - is, all store paths that directly or indirectly refer to one of - <replaceable>paths</replaceable>. These are all the path currently - in the Nix store that are dependent on - <replaceable>paths</replaceable>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--deriver</option></term> - <term><option>-d</option></term> - - <listitem><para>Prints the <link - linkend="gloss-deriver">deriver</link> of the store paths - <replaceable>paths</replaceable>. If the path has no deriver - (e.g., if it is a source file), or if the deriver is not known - (e.g., in the case of a binary-only deployment), the string - <literal>unknown-deriver</literal> is printed.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--graph</option></term> - - <listitem><para>Prints the references graph of the store paths - <replaceable>paths</replaceable> in the format of the - <command>dot</command> tool of AT&T's <link - xlink:href="http://www.graphviz.org/">Graphviz package</link>. - This can be used to visualise dependency graphs. To obtain a - build-time dependency graph, apply this to a store derivation. To - obtain a runtime dependency graph, apply it to an output - path.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--tree</option></term> - - <listitem><para>Prints the references graph of the store paths - <replaceable>paths</replaceable> as a nested ASCII tree. - References are ordered by descending closure size; this tends to - flatten the tree, making it more readable. The query only - recurses into a store path when it is first encountered; this - prevents a blowup of the tree representation of the - graph.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--graphml</option></term> - - <listitem><para>Prints the references graph of the store paths - <replaceable>paths</replaceable> in the <link - xlink:href="http://graphml.graphdrawing.org/">GraphML</link> file format. - This can be used to visualise dependency graphs. To obtain a - build-time dependency graph, apply this to a store derivation. To - obtain a runtime dependency graph, apply it to an output - path.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--binding</option> <replaceable>name</replaceable></term> - <term><option>-b</option> <replaceable>name</replaceable></term> - - <listitem><para>Prints the value of the attribute - <replaceable>name</replaceable> (i.e., environment variable) of - the store derivations <replaceable>paths</replaceable>. It is an - error for a derivation to not have the specified - attribute.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--hash</option></term> - - <listitem><para>Prints the SHA-256 hash of the contents of the - store paths <replaceable>paths</replaceable> (that is, the hash of - the output of <command>nix-store --dump</command> on the given - paths). Since the hash is stored in the Nix database, this is a - fast operation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--size</option></term> - - <listitem><para>Prints the size in bytes of the contents of the - store paths <replaceable>paths</replaceable> — to be precise, the - size of the output of <command>nix-store --dump</command> on the - given paths. Note that the actual disk space required by the - store paths may be higher, especially on filesystems with large - cluster sizes.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--roots</option></term> - - <listitem><para>Prints the garbage collector roots that point, - directly or indirectly, at the store paths - <replaceable>paths</replaceable>.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>Print the closure (runtime dependencies) of the -<command>svn</command> program in the current user environment: - -<screen> -$ nix-store -qR $(which svn) -/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4 -/nix/store/9lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4 -<replaceable>...</replaceable></screen> - -</para> - -<para>Print the build-time dependencies of <command>svn</command>: - -<screen> -$ nix-store -qR $(nix-store -qd $(which svn)) -/nix/store/02iizgn86m42q905rddvg4ja975bk2i4-grep-2.5.1.tar.bz2.drv -/nix/store/07a2bzxmzwz5hp58nf03pahrv2ygwgs3-gcc-wrapper.sh -/nix/store/0ma7c9wsbaxahwwl04gbw3fcd806ski4-glibc-2.3.4.drv -<replaceable>... lots of other paths ...</replaceable></screen> - -The difference with the previous example is that we ask the closure of -the derivation (<option>-qd</option>), not the closure of the output -path that contains <command>svn</command>.</para> - -<para>Show the build-time dependencies as a tree: - -<screen> -$ nix-store -q --tree $(nix-store -qd $(which svn)) -/nix/store/7i5082kfb6yjbqdbiwdhhza0am2xvh6c-subversion-1.1.4.drv -+---/nix/store/d8afh10z72n8l1cr5w42366abiblgn54-builder.sh -+---/nix/store/fmzxmpjx2lh849ph0l36snfj9zdibw67-bash-3.0.drv -| +---/nix/store/570hmhmx3v57605cqg9yfvvyh0nnb8k8-bash -| +---/nix/store/p3srsbd8dx44v2pg6nbnszab5mcwx03v-builder.sh -<replaceable>...</replaceable></screen> - -</para> - -<para>Show all paths that depend on the same OpenSSL library as -<command>svn</command>: - -<screen> -$ nix-store -q --referrers $(nix-store -q --binding openssl $(nix-store -qd $(which svn))) -/nix/store/23ny9l9wixx21632y2wi4p585qhva1q8-sylpheed-1.0.0 -/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4 -/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3 -/nix/store/l51240xqsgg8a7yrbqdx1rfzyv6l26fx-lynx-2.8.5</screen> - -</para> - -<para>Show all paths that directly or indirectly depend on the Glibc -(C library) used by <command>svn</command>: - -<screen> -$ nix-store -q --referrers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}') -/nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2 -/nix/store/15l3yi0d45prm7a82pcrknxdh6nzmxza-gawk-3.1.4 -<replaceable>...</replaceable></screen> - -Note that <command>ldd</command> is a command that prints out the -dynamic libraries used by an ELF executable.</para> - -<para>Make a picture of the runtime dependency graph of the current -user environment: - -<screen> -$ nix-store -q --graph ~/.nix-profile | dot -Tps > graph.ps -$ gv graph.ps</screen> - -</para> - -<para>Show every garbage collector root that points to a store path -that depends on <command>svn</command>: - -<screen> -$ nix-store -q --roots $(which svn) -/nix/var/nix/profiles/default-81-link -/nix/var/nix/profiles/default-82-link -/nix/var/nix/profiles/per-user/eelco/profile-97-link -</screen> - -</para> - -</refsection> - - -</refsection> - - - -<!--######################################################################--> - -<!-- -<refsection xml:id="rsec-nix-store-reg-val"><title>Operation <option>-XXX-register-validity</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>-XXX-register-validity</option></arg> -</cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>TODO</para> - -</refsection> - -</refsection> ---> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--add</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--add</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--add</option> adds the specified paths to -the Nix store. It prints the resulting paths in the Nix store on -standard output.</para> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store --add ./foo.c -/nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c</screen> - -</refsection> - -</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> - - - -<!--######################################################################--> - -<refsection xml:id='refsec-nix-store-verify'><title>Operation <option>--verify</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--verify</option></arg> - <arg><option>--check-contents</option></arg> - <arg><option>--repair</option></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--verify</option> verifies the internal -consistency of the Nix database, and the consistency between the Nix -database and the Nix store. Any inconsistencies encountered are -automatically repaired. Inconsistencies are generally the result of -the Nix store or database being modified by non-Nix tools, or of bugs -in Nix itself.</para> - -<para>This operation has the following options: - -<variablelist> - - <varlistentry><term><option>--check-contents</option></term> - - <listitem><para>Checks that the contents of every valid store path - has not been altered by computing a SHA-256 hash of the contents - and comparing it with the hash stored in the Nix database at build - time. Paths that have been modified are printed out. For large - stores, <option>--check-contents</option> is obviously quite - slow.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--repair</option></term> - - <listitem><para>If any valid path is missing from the store, or - (if <option>--check-contents</option> is given) the contents of a - valid path has been modified, then try to repair the path by - redownloading it. See <command>nix-store --repair-path</command> - for details.</para></listitem> - - </varlistentry> - -</variablelist> - -</para> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--verify-path</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--verify-path</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--verify-path</option> compares the -contents of the given store paths to their cryptographic hashes stored -in Nix’s database. For every changed path, it prints a warning -message. The exit status is 0 if no path has changed, and 1 -otherwise.</para> - -</refsection> - -<refsection><title>Example</title> - -<para>To verify the integrity of the <command>svn</command> command and all its dependencies: - -<screen> -$ nix-store --verify-path $(nix-store -qR $(which svn)) -</screen> - -</para> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--repair-path</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--repair-path</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--repair-path</option> attempts to -“repair” the specified paths by redownloading them using the available -substituters. If no substitutes are available, then repair is not -possible.</para> - -<warning><para>During repair, there is a very small time window during -which the old path (if it exists) is moved out of the way and replaced -with the new path. If repair is interrupted in between, then the -system may be left in a broken state (e.g., if the path contains a -critical system component like the GNU C Library).</para></warning> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store --verify-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13 -path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified! - expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588', - got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4' - -$ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13 -fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'... -… -</screen> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection xml:id='refsec-nix-store-dump'><title>Operation <option>--dump</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--dump</option></arg> - <arg choice='plain'><replaceable>path</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--dump</option> produces a NAR (Nix -ARchive) file containing the contents of the file system tree rooted -at <replaceable>path</replaceable>. The archive is written to -standard output.</para> - -<para>A NAR archive is like a TAR or Zip archive, but it contains only -the information that Nix considers important. For instance, -timestamps are elided because all files in the Nix store have their -timestamp set to 0 anyway. Likewise, all permissions are left out -except for the execute bit, because all files in the Nix store have -444 or 555 permission.</para> - -<para>Also, a NAR archive is <emphasis>canonical</emphasis>, meaning -that “equal” paths always produce the same NAR archive. For instance, -directory entries are always sorted so that the actual on-disk order -doesn’t influence the result. This means that the cryptographic hash -of a NAR dump of a path is usable as a fingerprint of the contents of -the path. Indeed, the hashes of store paths stored in Nix’s database -(see <link linkend="refsec-nix-store-query"><literal>nix-store -q ---hash</literal></link>) are SHA-256 hashes of the NAR dump of each -store path.</para> - -<para>NAR archives support filenames of unlimited length and 64-bit -file sizes. They can contain regular files, directories, and symbolic -links, but not other types of files (such as device nodes).</para> - -<para>A Nix archive can be unpacked using <literal>nix-store ---restore</literal>.</para> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--restore</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--restore</option></arg> - <arg choice='plain'><replaceable>path</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--restore</option> unpacks a NAR archive -to <replaceable>path</replaceable>, which must not already exist. The -archive is read from standard input.</para> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection xml:id='refsec-nix-store-export'><title>Operation <option>--export</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--export</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--export</option> writes a serialisation -of the specified store paths to standard output in a format that can -be imported into another Nix store with <command -linkend="refsec-nix-store-import">nix-store --import</command>. This -is like <command linkend="refsec-nix-store-dump">nix-store ---dump</command>, except that the NAR archive produced by that command -doesn’t contain the necessary meta-information to allow it to be -imported into another Nix store (namely, the set of references of the -path).</para> - -<para>This command does not produce a <emphasis>closure</emphasis> of -the specified paths, so if a store path references other store paths -that are missing in the target Nix store, the import will fail. To -copy a whole closure, do something like: - -<screen> -$ nix-store --export $(nix-store -qR <replaceable>paths</replaceable>) > out</screen> - -To import the whole closure again, run: - -<screen> -$ nix-store --import < out</screen> - -</para> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection xml:id='refsec-nix-store-import'><title>Operation <option>--import</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--import</option></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--import</option> reads a serialisation of -a set of store paths produced by <command -linkend="refsec-nix-store-export">nix-store --export</command> from -standard input and adds those store paths to the Nix store. Paths -that already exist in the Nix store are ignored. If a path refers to -another path that doesn’t exist in the Nix store, the import -fails.</para> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--optimise</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--optimise</option></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--optimise</option> reduces Nix store disk -space usage by finding identical files in the store and hard-linking -them to each other. It typically reduces the size of the store by -something like 25-35%. Only regular files and symlinks are -hard-linked in this manner. Files are considered identical when they -have the same NAR archive serialisation: that is, regular files must -have the same contents and permission (executable or non-executable), -and symlinks must have the same contents.</para> - -<para>After completion, or when the command is interrupted, a report -on the achieved savings is printed on standard error.</para> - -<para>Use <option>-vv</option> or <option>-vvv</option> to get some -progress indication.</para> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store --optimise -hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1' -<replaceable>...</replaceable> -541838819 bytes (516.74 MiB) freed by hard-linking 54143 files; -there are 114486 files with equal contents out of 215894 files in total -</screen> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--read-log</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <group choice='req'> - <arg choice='plain'><option>--read-log</option></arg> - <arg choice='plain'><option>-l</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--read-log</option> prints the build log -of the specified store paths on standard output. The build log is -whatever the builder of a derivation wrote to standard output and -standard error. If a store path is not a derivation, the deriver of -the store path is used.</para> - -<para>Build logs are kept in -<filename>/nix/var/log/nix/drvs</filename>. However, there is no -guarantee that a build log is available for any particular store path. -For instance, if the path was downloaded as a pre-built binary through -a substitute, then the log is unavailable.</para> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store -l $(which ktorrent) -building /nix/store/dhc73pvzpnzxhdgpimsd9sw39di66ph1-ktorrent-2.2.1 -unpacking sources -unpacking source archive /nix/store/p8n1jpqs27mgkjw07pb5269717nzf5f8-ktorrent-2.2.1.tar.gz -ktorrent-2.2.1/ -ktorrent-2.2.1/NEWS -<replaceable>...</replaceable> -</screen> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--dump-db</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--dump-db</option></arg> - <arg rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--dump-db</option> writes a dump of the -Nix database to standard output. It can be loaded into an empty Nix -store using <option>--load-db</option>. This is useful for making -backups and when migrating to different database schemas.</para> - -<para>By default, <option>--dump-db</option> will dump the entire Nix -database. When one or more store paths is passed, only the subset of -the Nix database for those store paths is dumped. As with -<option>--export</option>, the user is responsible for passing all the -store paths for a closure. See <option>--export</option> for an -example.</para> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--load-db</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--load-db</option></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--load-db</option> reads a dump of the Nix -database created by <option>--dump-db</option> from standard input and -loads it into the Nix database.</para> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--print-env</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--print-env</option></arg> - <arg choice='plain'><replaceable>drvpath</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--print-env</option> prints out the -environment of a derivation in a format that can be evaluated by a -shell. The command line arguments of the builder are placed in the -variable <envar>_args</envar>.</para> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store --print-env $(nix-instantiate '<nixpkgs>' -A firefox) -<replaceable>…</replaceable> -export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2' -export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv' -export system; system='x86_64-linux' -export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-builder.sh' -</screen> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection xml:id='rsec-nix-store-generate-binary-cache-key'><title>Operation <option>--generate-binary-cache-key</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'> - <option>--generate-binary-cache-key</option> - <option>key-name</option> - <option>secret-key-file</option> - <option>public-key-file</option> - </arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>This command generates an <link -xlink:href="http://ed25519.cr.yp.to/">Ed25519 key pair</link> that can -be used to create a signed binary cache. It takes three mandatory -parameters: - -<orderedlist> - - <listitem><para>A key name, such as - <literal>cache.example.org-1</literal>, that is used to look up keys - on the client when it verifies signatures. It can be anything, but - it’s suggested to use the host name of your cache - (e.g. <literal>cache.example.org</literal>) with a suffix denoting - the number of the key (to be incremented every time you need to - revoke a key).</para></listitem> - - <listitem><para>The file name where the secret key is to be - stored.</para></listitem> - - <listitem><para>The file name where the public key is to be - stored.</para></listitem> - -</orderedlist> - -</para> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection condition="manpage"><title>Environment variables</title> - -<variablelist> - <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> -</variablelist> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/opt-common-syn.xml b/doc/manual/command-ref/opt-common-syn.xml deleted file mode 100644 index 2660e3bb1..000000000 --- a/doc/manual/command-ref/opt-common-syn.xml +++ /dev/null @@ -1,68 +0,0 @@ -<nop xmlns="http://docbook.org/ns/docbook"> - -<arg><option>--help</option></arg> -<arg><option>--version</option></arg> -<arg rep='repeat'> - <group choice='req'> - <arg choice='plain'><option>--verbose</option></arg> - <arg choice='plain'><option>-v</option></arg> - </group> -</arg> -<arg> - <arg choice='plain'><option>--quiet</option></arg> -</arg> -<arg> - <option>--log-format</option> - <replaceable>format</replaceable> -</arg> -<arg> - <group choice='plain'> - <arg choice='plain'><option>--no-build-output</option></arg> - <arg choice='plain'><option>-Q</option></arg> - </group> -</arg> -<arg> - <group choice='req'> - <arg choice='plain'><option>--max-jobs</option></arg> - <arg choice='plain'><option>-j</option></arg> - </group> - <replaceable>number</replaceable> -</arg> -<arg> - <option>--cores</option> - <replaceable>number</replaceable> -</arg> -<arg> - <option>--max-silent-time</option> - <replaceable>number</replaceable> -</arg> -<arg> - <option>--timeout</option> - <replaceable>number</replaceable> -</arg> -<arg> - <group choice='plain'> - <arg choice='plain'><option>--keep-going</option></arg> - <arg choice='plain'><option>-k</option></arg> - </group> -</arg> -<arg> - <group choice='plain'> - <arg choice='plain'><option>--keep-failed</option></arg> - <arg choice='plain'><option>-K</option></arg> - </group> -</arg> -<arg><option>--fallback</option></arg> -<arg><option>--readonly-mode</option></arg> -<arg> - <option>-I</option> - <replaceable>path</replaceable> -</arg> -<arg> - <option>--option</option> - <replaceable>name</replaceable> - <replaceable>value</replaceable> -</arg> -<sbr /> - -</nop> diff --git a/doc/manual/command-ref/opt-common.xml b/doc/manual/command-ref/opt-common.xml deleted file mode 100644 index a68eef1d0..000000000 --- a/doc/manual/command-ref/opt-common.xml +++ /dev/null @@ -1,405 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options"> - -<title>Common Options</title> - - -<para>Most Nix commands accept the following command-line options:</para> - -<variablelist xml:id="opt-common"> - -<varlistentry><term><option>--help</option></term> - - <listitem><para>Prints out a summary of the command syntax and - exits.</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--version</option></term> - - <listitem><para>Prints out the Nix version number on standard output - and exits.</para></listitem> -</varlistentry> - - -<varlistentry><term><option>--verbose</option> / <option>-v</option></term> - - <listitem> - - <para>Increases the level of verbosity of diagnostic messages - printed on standard error. For each Nix operation, the information - printed on standard output is well-defined; any diagnostic - information is printed on standard error, never on standard - output.</para> - - <para>This option may be specified repeatedly. Currently, the - following verbosity levels exist:</para> - - <variablelist> - - <varlistentry><term>0</term> - <listitem><para>“Errors only”: only print messages - explaining why the Nix invocation failed.</para></listitem> - </varlistentry> - - <varlistentry><term>1</term> - <listitem><para>“Informational”: print - <emphasis>useful</emphasis> messages about what Nix is doing. - This is the default.</para></listitem> - </varlistentry> - - <varlistentry><term>2</term> - <listitem><para>“Talkative”: print more informational - messages.</para></listitem> - </varlistentry> - - <varlistentry><term>3</term> - <listitem><para>“Chatty”: print even more - informational messages.</para></listitem> - </varlistentry> - - <varlistentry><term>4</term> - <listitem><para>“Debug”: print debug - information.</para></listitem> - </varlistentry> - - <varlistentry><term>5</term> - <listitem><para>“Vomit”: print vast amounts of debug - information.</para></listitem> - </varlistentry> - - </variablelist> - - </listitem> - -</varlistentry> - - -<varlistentry><term><option>--quiet</option></term> - - <listitem> - - <para>Decreases the level of verbosity of diagnostic messages - printed on standard error. This is the inverse option to - <option>-v</option> / <option>--verbose</option>. - </para> - - <para>This option may be specified repeatedly. See the previous - verbosity levels list.</para> - - </listitem> - -</varlistentry> - - -<varlistentry xml:id="opt-log-format"><term><option>--log-format</option> <replaceable>format</replaceable></term> - - <listitem> - - <para>This option can be used to change the output of the log format, with - <replaceable>format</replaceable> being one of:</para> - - <variablelist> - - <varlistentry><term>raw</term> - <listitem><para>This is the raw format, as outputted by nix-build.</para></listitem> - </varlistentry> - - <varlistentry><term>internal-json</term> - <listitem><para>Outputs the logs in a structured manner. NOTE: the json schema is not guarantees to be stable between releases.</para></listitem> - </varlistentry> - - <varlistentry><term>bar</term> - <listitem><para>Only display a progress bar during the builds.</para></listitem> - </varlistentry> - - <varlistentry><term>bar-with-logs</term> - <listitem><para>Display the raw logs, with the progress bar at the bottom.</para></listitem> - </varlistentry> - - </variablelist> - - </listitem> - -</varlistentry> - -<varlistentry><term><option>--no-build-output</option> / <option>-Q</option></term> - - <listitem><para>By default, output written by builders to standard - output and standard error is echoed to the Nix command's standard - error. This option suppresses this behaviour. Note that the - builder's standard output and error are always written to a log file - in - <filename><replaceable>prefix</replaceable>/nix/var/log/nix</filename>.</para></listitem> - -</varlistentry> - - -<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 - 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> - - <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> - - -<varlistentry xml:id="opt-cores"><term><option>--cores</option></term> - - <listitem><para>Sets the value of the <envar>NIX_BUILD_CORES</envar> - environment variable in the invocation of builders. Builders can - use this variable at their discretion to control the maximum amount - of parallelism. For instance, in Nixpkgs, if the derivation - attribute <varname>enableParallelBuilding</varname> is set to - <literal>true</literal>, the builder passes the - <option>-j<replaceable>N</replaceable></option> flag to GNU Make. - It defaults to the value of the <link - linkend='conf-cores'><literal>cores</literal></link> - configuration setting, if set, or <literal>1</literal> otherwise. - The value <literal>0</literal> means that the builder should use all - available CPU cores in the system.</para></listitem> - -</varlistentry> - - -<varlistentry xml:id="opt-max-silent-time"><term><option>--max-silent-time</option></term> - - <listitem><para>Sets the maximum number of seconds that a builder - can go without producing any data on standard output or standard - error. The default is specified by the <link - linkend='conf-max-silent-time'><literal>max-silent-time</literal></link> - configuration setting. <literal>0</literal> means no - time-out.</para></listitem> - -</varlistentry> - -<varlistentry xml:id="opt-timeout"><term><option>--timeout</option></term> - - <listitem><para>Sets the maximum number of seconds that a builder - can run. The default is specified by the <link - linkend='conf-timeout'><literal>timeout</literal></link> - configuration setting. <literal>0</literal> means no - timeout.</para></listitem> - -</varlistentry> - -<varlistentry><term><option>--keep-going</option> / <option>-k</option></term> - - <listitem><para>Keep going in case of failed builds, to the - greatest extent possible. That is, if building an input of some - derivation fails, Nix will still build the other inputs, but not the - derivation itself. Without this option, Nix stops if any build - fails (except for builds of substitutes), possibly killing builds in - progress (in case of parallel or distributed builds).</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--keep-failed</option> / <option>-K</option></term> - - <listitem><para>Specifies that in case of a build failure, the - temporary directory (usually in <filename>/tmp</filename>) in which - the build takes place should not be deleted. The path of the build - directory is printed as an informational message. - </para> - </listitem> -</varlistentry> - - -<varlistentry><term><option>--fallback</option></term> - - <listitem> - - <para>Whenever Nix attempts to build a derivation for which - substitutes are known for each output path, but realising the output - paths through the substitutes fails, fall back on building the - derivation.</para> - - <para>The most common scenario in which this is useful is when we - have registered substitutes in order to perform binary distribution - from, say, a network repository. If the repository is down, the - realisation of the derivation will fail. When this option is - specified, Nix will build the derivation instead. Thus, - installation from binaries falls back on installation from source. - This option is not the default since it is generally not desirable - for a transient failure in obtaining the substitutes to lead to a - full build from source (with the related consumption of - resources).</para> - - </listitem> - -</varlistentry> - -<varlistentry><term><option>--no-build-hook</option></term> - - <listitem> - - <para>Disables the build hook mechanism. This allows to ignore remote - builders if they are setup on the machine.</para> - - <para>It's useful in cases where the bandwidth between the client and the - remote builder is too low. In that case it can take more time to upload the - sources to the remote builder and fetch back the result than to do the - computation locally.</para> - - </listitem> - -</varlistentry> - - - -<varlistentry><term><option>--readonly-mode</option></term> - - <listitem><para>When this option is used, no attempt is made to open - the Nix database. Most Nix operations do need database access, so - those operations will fail.</para></listitem> - -</varlistentry> - - -<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>, - <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> ? - <replaceable>defaultValue</replaceable> }: - <replaceable>...</replaceable></literal>). With - <option>--arg</option>, you can also call functions that have - arguments without a default value (or override a default value). - That is, if the evaluator encounters a function with an argument - named <replaceable>name</replaceable>, it will call it with value - <replaceable>value</replaceable>.</para> - - <para>For instance, the top-level <literal>default.nix</literal> in - Nixpkgs is actually a function: - -<programlisting> -{ # The system (e.g., `i686-linux') for which to build the packages. - system ? builtins.currentSystem - <replaceable>...</replaceable> -}: <replaceable>...</replaceable></programlisting> - - So if you call this Nix expression (e.g., when you do - <literal>nix-env -i <replaceable>pkgname</replaceable></literal>), - the function will be called automatically using the value <link - linkend='builtin-currentSystem'><literal>builtins.currentSystem</literal></link> - for the <literal>system</literal> argument. You can override this - using <option>--arg</option>, e.g., <literal>nix-env -i - <replaceable>pkgname</replaceable> --arg system - \"i686-freebsd\"</literal>. (Note that since the argument is a Nix - string literal, you have to escape the quotes.)</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term> - - <listitem><para>This option is like <option>--arg</option>, only the - value is not a Nix expression but a string. So instead of - <literal>--arg system \"i686-linux\"</literal> (the outer quotes are - to keep the shell happy) you can say <literal>--argstr system - i686-linux</literal>.</para></listitem> - -</varlistentry> - - -<varlistentry xml:id="opt-attr"><term><option>--attr</option> / <option>-A</option> -<replaceable>attrPath</replaceable></term> - - <listitem><para>Select an attribute from the top-level Nix - expression being evaluated. (<command>nix-env</command>, - <command>nix-instantiate</command>, <command>nix-build</command> and - <command>nix-shell</command> only.) The <emphasis>attribute - path</emphasis> <replaceable>attrPath</replaceable> is a sequence of - attribute names separated by dots. For instance, given a top-level - Nix expression <replaceable>e</replaceable>, the attribute path - <literal>xorg.xorgserver</literal> would cause the expression - <literal><replaceable>e</replaceable>.xorg.xorgserver</literal> to - be used. See <link - linkend='refsec-nix-env-install-examples'><command>nix-env - --install</command></link> for some concrete examples.</para> - - <para>In addition to attribute names, you can also specify array - indices. For instance, the attribute path - <literal>foo.3.bar</literal> selects the <literal>bar</literal> - attribute of the fourth element of the array in the - <literal>foo</literal> attribute of the top-level - expression.</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--expr</option> / <option>-E</option></term> - - <listitem><para>Interpret the command line arguments as a list of - 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> - - <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> - - -<varlistentry xml:id="opt-I"><term><option>-I</option> <replaceable>path</replaceable></term> - - <listitem><para>Add a path to the Nix expression search path. This - option may be given multiple times. See the <envar - linkend="env-NIX_PATH">NIX_PATH</envar> environment variable for - information on the semantics of the Nix search path. Paths added - through <option>-I</option> take precedence over - <envar>NIX_PATH</envar>.</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term> - - <listitem><para>Set the Nix configuration option - <replaceable>name</replaceable> to <replaceable>value</replaceable>. - This overrides settings in the Nix configuration file (see - <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--repair</option></term> - - <listitem><para>Fix corrupted or missing store paths by - redownloading or rebuilding them. Note that this is slow because it - requires computing a cryptographic hash of the contents of every - path in the closure of the build. Also note the warning under - <command>nix-store --repair-path</command>.</para></listitem> - -</varlistentry> - - -</variablelist> - - -</chapter> diff --git a/doc/manual/command-ref/opt-inst-syn.xml b/doc/manual/command-ref/opt-inst-syn.xml deleted file mode 100644 index e8c3f1ec6..000000000 --- a/doc/manual/command-ref/opt-inst-syn.xml +++ /dev/null @@ -1,22 +0,0 @@ -<nop xmlns="http://docbook.org/ns/docbook"> - - <arg> - <group choice='req'> - <arg choice='plain'><option>--prebuilt-only</option></arg> - <arg choice='plain'><option>-b</option></arg> - </group> - </arg> - - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr</option></arg> - <arg choice='plain'><option>-A</option></arg> - </group> - </arg> - - <arg><option>--from-expression</option></arg> - <arg><option>-E</option></arg> - - <arg><option>--from-profile</option> <replaceable>path</replaceable></arg> - -</nop> diff --git a/doc/manual/command-ref/utilities.xml b/doc/manual/command-ref/utilities.xml deleted file mode 100644 index 893f5b5b5..000000000 --- a/doc/manual/command-ref/utilities.xml +++ /dev/null @@ -1,20 +0,0 @@ -<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='ch-utilities'> - -<title>Utilities</title> - -<para>This section lists utilities that you can use when you -work with Nix.</para> - -<xi:include href="nix-channel.xml" /> -<xi:include href="nix-collect-garbage.xml" /> -<xi:include href="nix-copy-closure.xml" /> -<xi:include href="nix-daemon.xml" /> -<xi:include href="nix-hash.xml" /> -<xi:include href="nix-instantiate.xml" /> -<xi:include href="nix-prefetch-url.xml" /> - -</chapter> diff --git a/doc/manual/expressions/advanced-attributes.xml b/doc/manual/expressions/advanced-attributes.xml deleted file mode 100644 index 5759ff50e..000000000 --- a/doc/manual/expressions/advanced-attributes.xml +++ /dev/null @@ -1,351 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-advanced-attributes"> - -<title>Advanced Attributes</title> - -<para>Derivations can declare some infrequently used optional -attributes.</para> - -<variablelist> - - <varlistentry xml:id="adv-attr-allowedReferences"><term><varname>allowedReferences</varname></term> - - <listitem><para>The optional attribute - <varname>allowedReferences</varname> specifies a list of legal - references (dependencies) of the output of the builder. For - example, - -<programlisting> -allowedReferences = []; -</programlisting> - - enforces that the output of a derivation cannot have any runtime - dependencies on its inputs. To allow an output to have a runtime - dependency on itself, use <literal>"out"</literal> as a list item. - This is used in NixOS to check that generated files such as - initial ramdisks for booting Linux don’t have accidental - dependencies on other paths in the Nix store.</para></listitem> - - </varlistentry> - - - <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 - requisites of the whole closure, so all the dependencies - recursively. For example, - -<programlisting> -allowedRequisites = [ foobar ]; -</programlisting> - - enforces that the output of a derivation cannot have any other - runtime dependency than <varname>foobar</varname>, and in addition - it enforces that <varname>foobar</varname> itself doesn't - introduce any other dependency itself.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="adv-attr-disallowedReferences"><term><varname>disallowedReferences</varname></term> - - <listitem><para>The optional attribute - <varname>disallowedReferences</varname> specifies a list of illegal - references (dependencies) of the output of the builder. For - example, - -<programlisting> -disallowedReferences = [ foo ]; -</programlisting> - - enforces that the output of a derivation cannot have a direct runtime - dependencies on the derivation <varname>foo</varname>.</para></listitem> - - </varlistentry> - - - <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 - requisites for the whole closure, so all the dependencies - recursively. For example, - -<programlisting> -disallowedRequisites = [ foobar ]; -</programlisting> - - enforces that the output of a derivation cannot have any - runtime dependency on <varname>foobar</varname> or any other derivation - depending recursively on <varname>foobar</varname>.</para></listitem> - - </varlistentry> - - - <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 - inputs in the Nix store whose references graph the builder needs - to know. The value of this attribute should be a list of pairs - <literal>[ <replaceable>name1</replaceable> - <replaceable>path1</replaceable> <replaceable>name2</replaceable> - <replaceable>path2</replaceable> <replaceable>...</replaceable> - ]</literal>. The references graph of each - <replaceable>pathN</replaceable> will be stored in a text file - <replaceable>nameN</replaceable> in the temporary build directory. - The text files have the format used by <command>nix-store - --register-validity</command> (with the deriver fields left - empty). For example, when the following derivation is built: - -<programlisting> -derivation { - ... - exportReferencesGraph = [ "libfoo-graph" libfoo ]; -}; -</programlisting> - - the references graph of <literal>libfoo</literal> is placed in the - file <filename>libfoo-graph</filename> in the temporary build - directory.</para> - - <para><varname>exportReferencesGraph</varname> is useful for - builders that want to do something with the closure of a store - path. Examples include the builders in NixOS that generate the - initial ramdisk for booting Linux (a <command>cpio</command> - archive containing the closure of the boot script) and the - ISO-9660 image for the installation CD (which is populated with a - Nix store containing the closure of a bootable NixOS - configuration).</para></listitem> - - </varlistentry> - - - <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 - of the calling user to the builder. Usually, the environment is - cleared completely when the builder is executed, but with this - attribute you can allow specific environment variables to be - passed unmodified. For example, <function>fetchurl</function> in - Nixpkgs has the line - -<programlisting> -impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ]; -</programlisting> - - to make it use the proxy server configuration specified by the - user in the environment variables <envar>http_proxy</envar> and - friends.</para> - - <para>This attribute is only allowed in <link - linkend="fixed-output-drvs">fixed-output derivations</link>, where - impurities such as these are okay since (the hash of) the output - is known in advance. It is ignored for all other - derivations.</para> - - <warning><para><varname>impureEnvVars</varname> implementation takes - environment variables from the current builder process. When a daemon is - building its environmental variables are used. Without the daemon, the - environmental variables come from the environment of the - <command>nix-build</command>.</para></warning></listitem> - - </varlistentry> - - - <varlistentry xml:id="fixed-output-drvs"> - <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 - means that a cryptographic hash of the output is already known in - advance. When the build of a fixed-output derivation finishes, - Nix computes the cryptographic hash of the output and compares it - to the hash declared with these attributes. If there is a - mismatch, the build fails.</para> - - <para>The rationale for fixed-output derivations is derivations - such as those produced by the <function>fetchurl</function> - function. This function downloads a file from a given URL. To - ensure that the downloaded file has not been modified, the caller - must also specify a cryptographic hash of the file. For example, - -<programlisting> -fetchurl { - url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz"; - sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; -} -</programlisting> - - It sometimes happens that the URL of the file changes, e.g., - because servers are reorganised or no longer available. We then - must update the call to <function>fetchurl</function>, e.g., - -<programlisting> -fetchurl { - url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; - sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; -} -</programlisting> - - If a <function>fetchurl</function> derivation was treated like a - normal derivation, the output paths of the derivation and - <emphasis>all derivations depending on it</emphasis> would change. - For instance, if we were to change the URL of the Glibc source - distribution in Nixpkgs (a package on which almost all other - packages depend) massive rebuilds would be needed. This is - unfortunate for a change which we know cannot have a real effect - as it propagates upwards through the dependency graph.</para> - - <para>For fixed-output derivations, on the other hand, the name of - the output path only depends on the <varname>outputHash*</varname> - and <varname>name</varname> attributes, while all other attributes - are ignored for the purpose of computing the output path. (The - <varname>name</varname> attribute is included because it is part - of the path.)</para> - - <para>As an example, here is the (simplified) Nix expression for - <varname>fetchurl</varname>: - -<programlisting> -{ stdenv, curl }: # The <command>curl</command> program is used for downloading. - -{ url, sha256 }: - -stdenv.mkDerivation { - name = baseNameOf (toString url); - builder = ./builder.sh; - buildInputs = [ curl ]; - - # This is a fixed-output derivation; the output must be a regular - # file with SHA256 hash <varname>sha256</varname>. - outputHashMode = "flat"; - outputHashAlgo = "sha256"; - outputHash = sha256; - - inherit url; -} -</programlisting> - - </para> - - <para>The <varname>outputHashAlgo</varname> attribute specifies - the hash algorithm used to compute the hash. It can currently be - <literal>"sha1"</literal>, <literal>"sha256"</literal> or - <literal>"sha512"</literal>.</para> - - <para>The <varname>outputHashMode</varname> attribute determines - how the hash is computed. It must be one of the following two - values: - - <variablelist> - - <varlistentry><term><literal>"flat"</literal></term> - - <listitem><para>The output must be a non-executable regular - file. If it isn’t, the build fails. The hash is simply - computed over the contents of that file (so it’s equal to what - Unix commands like <command>sha256sum</command> or - <command>sha1sum</command> produce).</para> - - <para>This is the default.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal>"recursive"</literal></term> - - <listitem><para>The hash is computed over the NAR archive dump - of the output (i.e., the result of <link - linkend="refsec-nix-store-dump"><command>nix-store - --dump</command></link>). In this case, the output can be - anything, including a directory tree.</para></listitem> - - </varlistentry> - - </variablelist> - - </para> - - <para>The <varname>outputHash</varname> attribute, finally, must - be a string containing the hash in either hexadecimal or base-32 - notation. (See the <link - linkend="sec-nix-hash"><command>nix-hash</command> command</link> - for information about converting to and from base-32 - notation.)</para></listitem> - - </varlistentry> - - - <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, - if you have - - <programlisting> -passAsFile = ["big"]; -big = "a very long string"; - </programlisting> - - then when the builder runs, the environment variable - <envar>bigPath</envar> will contain the absolute path to a - temporary file containing <literal>a very long - string</literal>. That is, for any attribute - <replaceable>x</replaceable> listed in - <varname>passAsFile</varname>, Nix will pass an environment - variable <envar><replaceable>x</replaceable>Path</envar> holding - the path of the file containing the value of attribute - <replaceable>x</replaceable>. This is useful when you need to pass - large strings to a builder, since most operating systems impose a - limit on the size of the environment (typically, a few hundred - kilobyte).</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="adv-attr-preferLocalBuild"><term><varname>preferLocalBuild</varname></term> - - <listitem><para>If this attribute is set to - <literal>true</literal> and <link - linkend="chap-distributed-builds">distributed building is - enabled</link>, then, if possible, the derivaton will be built - locally instead of forwarded to a remote machine. This is - appropriate for trivial builders where the cost of doing a - download or remote build would exceed the cost of building - locally.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="adv-attr-allowSubstitutes"><term><varname>allowSubstitutes</varname></term> - - <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> - - <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> - - -</variablelist> - -</section> diff --git a/doc/manual/expressions/arguments-variables.xml b/doc/manual/expressions/arguments-variables.xml deleted file mode 100644 index bf60cb7ee..000000000 --- a/doc/manual/expressions/arguments-variables.xml +++ /dev/null @@ -1,121 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='sec-arguments'> - -<title>Arguments and Variables</title> - -<example xml:id='ex-hello-composition'> - -<title>Composing GNU Hello -(<filename>all-packages.nix</filename>)</title> -<programlisting> -... - -rec { <co xml:id='ex-hello-composition-co-1' /> - - hello = import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' /> { <co xml:id='ex-hello-composition-co-3' /> - inherit fetchurl stdenv perl; - }; - - perl = import ../development/interpreters/perl { <co xml:id='ex-hello-composition-co-4' /> - inherit fetchurl stdenv; - }; - - fetchurl = import ../build-support/fetchurl { - inherit stdenv; ... - }; - - stdenv = ...; - -} -</programlisting> -</example> - -<para>The Nix expression in <xref linkend='ex-hello-nix' /> is a -function; it is missing some arguments that have to be filled in -somewhere. In the Nix Packages collection this is done in the file -<filename>pkgs/top-level/all-packages.nix</filename>, where all -Nix expressions for packages are imported and called with the -appropriate arguments. <xref linkend='ex-hello-composition' /> shows -some fragments of -<filename>all-packages.nix</filename>.</para> - -<calloutlist> - - <callout arearefs='ex-hello-composition-co-1'> - - <para>This file defines a set of attributes, all of which are - concrete derivations (i.e., not functions). In fact, we define a - <emphasis>mutually recursive</emphasis> set of attributes. That - is, the attributes can refer to each other. This is precisely - what we want since we want to <quote>plug</quote> the - various packages into each other.</para> - - </callout> - - <callout arearefs='ex-hello-composition-co-2'> - - <para>Here we <emphasis>import</emphasis> the Nix expression for - GNU Hello. The import operation just loads and returns the - specified Nix expression. In fact, we could just have put the - contents of <xref linkend='ex-hello-nix' /> in - <filename>all-packages.nix</filename> at this point. That - would be completely equivalent, but it would make the file rather - bulky.</para> - - <para>Note that we refer to - <filename>../applications/misc/hello/ex-1</filename>, not - <filename>../applications/misc/hello/ex-1/default.nix</filename>. - When you try to import a directory, Nix automatically appends - <filename>/default.nix</filename> to the file name.</para> - - </callout> - - <callout arearefs='ex-hello-composition-co-3'> - - <para>This is where the actual composition takes place. Here we - <emphasis>call</emphasis> the function imported from - <filename>../applications/misc/hello/ex-1</filename> with a set - containing the things that the function expects, namely - <varname>fetchurl</varname>, <varname>stdenv</varname>, and - <varname>perl</varname>. We use inherit again to use the - attributes defined in the surrounding scope (we could also have - written <literal>fetchurl = fetchurl;</literal>, etc.).</para> - - <para>The result of this function call is an actual derivation - that can be built by Nix (since when we fill in the arguments of - the function, what we get is its body, which is the call to - <varname>stdenv.mkDerivation</varname> in <xref - linkend='ex-hello-nix' />).</para> - - <note><para>Nixpkgs has a convenience function - <function>callPackage</function> that imports and calls a - function, filling in any missing arguments by passing the - corresponding attribute from the Nixpkgs set, like this: - -<programlisting> -hello = callPackage ../applications/misc/hello/ex-1 { }; -</programlisting> - - If necessary, you can set or override arguments: - -<programlisting> -hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; }; -</programlisting> - - </para></note> - - </callout> - - <callout arearefs='ex-hello-composition-co-4'> - - <para>Likewise, we have to instantiate Perl, - <varname>fetchurl</varname>, and the standard environment.</para> - - </callout> - -</calloutlist> - -</section>
\ No newline at end of file diff --git a/doc/manual/expressions/build-script.xml b/doc/manual/expressions/build-script.xml deleted file mode 100644 index 7bad8f808..000000000 --- a/doc/manual/expressions/build-script.xml +++ /dev/null @@ -1,119 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='sec-build-script'> - -<title>Build Script</title> - -<example xml:id='ex-hello-builder'><title>Build script for GNU Hello -(<filename>builder.sh</filename>)</title> -<programlisting> -source $stdenv/setup <co xml:id='ex-hello-builder-co-1' /> - -PATH=$perl/bin:$PATH <co xml:id='ex-hello-builder-co-2' /> - -tar xvfz $src <co xml:id='ex-hello-builder-co-3' /> -cd hello-* -./configure --prefix=$out <co xml:id='ex-hello-builder-co-4' /> -make <co xml:id='ex-hello-builder-co-5' /> -make install</programlisting> -</example> - -<para><xref linkend='ex-hello-builder' /> shows the builder referenced -from Hello's Nix expression (stored in -<filename>pkgs/applications/misc/hello/ex-1/builder.sh</filename>). -The builder can actually be made a lot shorter by using the -<emphasis>generic builder</emphasis> functions provided by -<varname>stdenv</varname>, but here we write out the build steps to -elucidate what a builder does. It performs the following -steps:</para> - -<calloutlist> - - <callout arearefs='ex-hello-builder-co-1'> - - <para>When Nix runs a builder, it initially completely clears the - environment (except for the attributes declared in the - derivation). For instance, the <envar>PATH</envar> variable is - empty<footnote><para>Actually, it's initialised to - <filename>/path-not-set</filename> to prevent Bash from setting it - to a default value.</para></footnote>. This is done to prevent - undeclared inputs from being used in the build process. If for - example the <envar>PATH</envar> contained - <filename>/usr/bin</filename>, then you might accidentally use - <filename>/usr/bin/gcc</filename>.</para> - - <para>So the first step is to set up the environment. This is - done by calling the <filename>setup</filename> script of the - standard environment. The environment variable - <envar>stdenv</envar> points to the location of the standard - environment being used. (It wasn't specified explicitly as an - attribute in <xref linkend='ex-hello-nix' />, but - <varname>mkDerivation</varname> adds it automatically.)</para> - - </callout> - - <callout arearefs='ex-hello-builder-co-2'> - - <para>Since Hello needs Perl, we have to make sure that Perl is in - the <envar>PATH</envar>. The <envar>perl</envar> environment - variable points to the location of the Perl package (since it - was passed in as an attribute to the derivation), so - <filename><replaceable>$perl</replaceable>/bin</filename> is the - directory containing the Perl interpreter.</para> - - </callout> - - <callout arearefs='ex-hello-builder-co-3'> - - <para>Now we have to unpack the sources. The - <varname>src</varname> attribute was bound to the result of - fetching the Hello source tarball from the network, so the - <envar>src</envar> environment variable points to the location in - the Nix store to which the tarball was downloaded. After - unpacking, we <command>cd</command> to the resulting source - directory.</para> - - <para>The whole build is performed in a temporary directory - created in <varname>/tmp</varname>, by the way. This directory is - removed after the builder finishes, so there is no need to clean - up the sources afterwards. Also, the temporary directory is - always newly created, so you don't have to worry about files from - previous builds interfering with the current build.</para> - - </callout> - - <callout arearefs='ex-hello-builder-co-4'> - - <para>GNU Hello is a typical Autoconf-based package, so we first - have to run its <filename>configure</filename> script. In Nix - every package is stored in a separate location in the Nix store, - for instance - <filename>/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1</filename>. - Nix computes this path by cryptographically hashing all attributes - of the derivation. The path is passed to the builder through the - <envar>out</envar> environment variable. So here we give - <filename>configure</filename> the parameter - <literal>--prefix=$out</literal> to cause Hello to be installed in - the expected location.</para> - - </callout> - - <callout arearefs='ex-hello-builder-co-5'> - - <para>Finally we build Hello (<literal>make</literal>) and install - it into the location specified by <envar>out</envar> - (<literal>make install</literal>).</para> - - </callout> - -</calloutlist> - -<para>If you are wondering about the absence of error checking on the -result of various commands called in the builder: this is because the -shell script is evaluated with Bash's <option>-e</option> option, -which causes the script to be aborted if any command fails without an -error check.</para> - -</section>
\ No newline at end of file diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml deleted file mode 100644 index a18c5801a..000000000 --- a/doc/manual/expressions/builtins.xml +++ /dev/null @@ -1,1668 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='ssec-builtins'> - -<title>Built-in Functions</title> - -<para>This section lists the functions and constants built into the -Nix expression evaluator. (The built-in function -<function>derivation</function> is discussed above.) Some built-ins, -such as <function>derivation</function>, are always in scope of every -Nix expression; you can just access them right away. But to prevent -polluting the namespace too much, most built-ins are not in scope. -Instead, you can access them through the <varname>builtins</varname> -built-in value, which is a set that contains all built-in functions -and values. For instance, <function>derivation</function> is also -available as <function>builtins.derivation</function>.</para> - - -<variablelist> - - - <varlistentry xml:id='builtin-abort'> - <term><function>abort</function> <replaceable>s</replaceable></term> - <term><function>builtins.abort</function> <replaceable>s</replaceable></term> - - <listitem><para>Abort Nix expression evaluation, print error - message <replaceable>s</replaceable>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-add'> - <term><function>builtins.add</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable> - </term> - - <listitem><para>Return the sum of the numbers - <replaceable>e1</replaceable> and - <replaceable>e2</replaceable>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-all'> - <term><function>builtins.all</function> - <replaceable>pred</replaceable> <replaceable>list</replaceable></term> - - <listitem><para>Return <literal>true</literal> if the function - <replaceable>pred</replaceable> returns <literal>true</literal> - for all elements of <replaceable>list</replaceable>, - and <literal>false</literal> otherwise.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-any'> - <term><function>builtins.any</function> - <replaceable>pred</replaceable> <replaceable>list</replaceable></term> - - <listitem><para>Return <literal>true</literal> if the function - <replaceable>pred</replaceable> returns <literal>true</literal> - for at least one element of <replaceable>list</replaceable>, - and <literal>false</literal> otherwise.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-attrNames'> - <term><function>builtins.attrNames</function> - <replaceable>set</replaceable></term> - - <listitem><para>Return the names of the attributes in the set - <replaceable>set</replaceable> in an alphabetically sorted list. For instance, - <literal>builtins.attrNames { y = 1; x = "foo"; }</literal> - evaluates to <literal>[ "x" "y" ]</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-attrValues'> - <term><function>builtins.attrValues</function> - <replaceable>set</replaceable></term> - - <listitem><para>Return the values of the attributes in the set - <replaceable>set</replaceable> in the order corresponding to the - sorted attribute names.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-baseNameOf'> - <term><function>baseNameOf</function> <replaceable>s</replaceable></term> - - <listitem><para>Return the <emphasis>base name</emphasis> of the - string <replaceable>s</replaceable>, that is, everything following - the final slash in the string. This is similar to the GNU - <command>basename</command> command.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-bitAnd'> - <term><function>builtins.bitAnd</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem><para>Return the bitwise AND of the integers - <replaceable>e1</replaceable> and - <replaceable>e2</replaceable>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-bitOr'> - <term><function>builtins.bitOr</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem><para>Return the bitwise OR of the integers - <replaceable>e1</replaceable> and - <replaceable>e2</replaceable>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-bitXor'> - <term><function>builtins.bitXor</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem><para>Return the bitwise XOR of the integers - <replaceable>e1</replaceable> and - <replaceable>e2</replaceable>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-builtins'> - <term><varname>builtins</varname></term> - - <listitem><para>The set <varname>builtins</varname> contains all - the built-in functions and values. You can use - <varname>builtins</varname> to test for the availability of - features in the Nix installation, e.g., - -<programlisting> -if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting> - - This allows a Nix expression to fall back gracefully on older Nix - installations that don’t have the desired built-in - function.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-compareVersions'> - <term><function>builtins.compareVersions</function> - <replaceable>s1</replaceable> <replaceable>s2</replaceable></term> - - <listitem><para>Compare two strings representing versions and - return <literal>-1</literal> if version - <replaceable>s1</replaceable> is older than version - <replaceable>s2</replaceable>, <literal>0</literal> if they are - the same, and <literal>1</literal> if - <replaceable>s1</replaceable> is newer than - <replaceable>s2</replaceable>. The version comparison algorithm - is the same as the one used by <link - linkend="ssec-version-comparisons"><command>nix-env - -u</command></link>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-concatLists'> - <term><function>builtins.concatLists</function> - <replaceable>lists</replaceable></term> - - <listitem><para>Concatenate a list of lists into a single - list.</para></listitem> - - </varlistentry> - - <varlistentry xml:id='builtin-concatStringsSep'> - <term><function>builtins.concatStringsSep</function> - <replaceable>separator</replaceable> <replaceable>list</replaceable></term> - - <listitem><para>Concatenate a list of strings with a separator - between each element, e.g. <literal>concatStringsSep "/" - ["usr" "local" "bin"] == "usr/local/bin"</literal></para></listitem> - - </varlistentry> - - <varlistentry xml:id='builtin-currentSystem'> - <term><varname>builtins.currentSystem</varname></term> - - <listitem><para>The built-in value <varname>currentSystem</varname> - evaluates to the Nix platform identifier for the Nix installation - on which the expression is being evaluated, such as - <literal>"i686-linux"</literal> or - <literal>"x86_64-darwin"</literal>.</para></listitem> - - </varlistentry> - - - <!-- - <varlistentry><term><function>currentTime</function></term> - - <listitem><para>The built-in value <varname>currentTime</varname> - returns the current system time in seconds since 00:00:00 1/1/1970 - UTC. Due to the evaluation model of Nix expressions - (<emphasis>maximal laziness</emphasis>), it always yields the same - value within an execution of Nix.</para></listitem> - - </varlistentry> - --> - - - <!-- - <varlistentry><term><function>dependencyClosure</function></term> - - <listitem><para>TODO</para></listitem> - - </varlistentry> - --> - - - <varlistentry xml:id='builtin-deepSeq'> - <term><function>builtins.deepSeq</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem><para>This is like <literal>seq - <replaceable>e1</replaceable> - <replaceable>e2</replaceable></literal>, except that - <replaceable>e1</replaceable> is evaluated - <emphasis>deeply</emphasis>: if it’s a list or set, its elements - or attributes are also evaluated recursively.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-derivation'> - <term><function>derivation</function> - <replaceable>attrs</replaceable></term> - <term><function>builtins.derivation</function> - <replaceable>attrs</replaceable></term> - - <listitem><para><function>derivation</function> is described in - <xref linkend='ssec-derivation' />.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-dirOf'> - <term><function>dirOf</function> <replaceable>s</replaceable></term> - <term><function>builtins.dirOf</function> <replaceable>s</replaceable></term> - - <listitem><para>Return the directory part of the string - <replaceable>s</replaceable>, that is, everything before the final - slash in the string. This is similar to the GNU - <command>dirname</command> command.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-div'> - <term><function>builtins.div</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem><para>Return the quotient of the numbers - <replaceable>e1</replaceable> and - <replaceable>e2</replaceable>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id='builtin-elem'> - <term><function>builtins.elem</function> - <replaceable>x</replaceable> <replaceable>xs</replaceable></term> - - <listitem><para>Return <literal>true</literal> if a value equal to - <replaceable>x</replaceable> occurs in the list - <replaceable>xs</replaceable>, and <literal>false</literal> - otherwise.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-elemAt'> - <term><function>builtins.elemAt</function> - <replaceable>xs</replaceable> <replaceable>n</replaceable></term> - - <listitem><para>Return element <replaceable>n</replaceable> from - the list <replaceable>xs</replaceable>. Elements are counted - starting from 0. A fatal error occurs if the index is out of - bounds.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-fetchurl'> - <term><function>builtins.fetchurl</function> - <replaceable>url</replaceable></term> - - <listitem><para>Download the specified URL and return the path of - the downloaded file. This function is not available if <link - linkend="conf-restrict-eval">restricted evaluation mode</link> is - enabled.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-fetchTarball'> - <term><function>fetchTarball</function> - <replaceable>url</replaceable></term> - <term><function>builtins.fetchTarball</function> - <replaceable>url</replaceable></term> - - <listitem><para>Download the specified URL, unpack it and return - the path of the unpacked tree. The file must be a tape archive - (<filename>.tar</filename>) compressed with - <literal>gzip</literal>, <literal>bzip2</literal> or - <literal>xz</literal>. The top-level path component of the files - in the tarball is removed, so it is best if the tarball contains a - single directory at top level. The typical use of the function is - to obtain external Nix expression dependencies, such as a - particular version of Nixpkgs, e.g. - -<programlisting> -with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz) {}; - -stdenv.mkDerivation { … } -</programlisting> - </para> - - <para>The fetched tarball is cached for a certain amount of time - (1 hour by default) in <filename>~/.cache/nix/tarballs/</filename>. - You can change the cache timeout either on the command line with - <option>--option tarball-ttl <replaceable>number of seconds</replaceable></option> or - in the Nix configuration file with this option: - <literal><xref linkend="conf-tarball-ttl" /> <replaceable>number of seconds to cache</replaceable></literal>. - </para> - - <para>Note that when obtaining the hash with <varname>nix-prefetch-url - </varname> the option <varname>--unpack</varname> is required. - </para> - - <para>This function can also verify the contents against a hash. - In that case, the function takes a set instead of a URL. The set - requires the attribute <varname>url</varname> and the attribute - <varname>sha256</varname>, e.g. - -<programlisting> -with import (fetchTarball { - url = "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz"; - sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2"; -}) {}; - -stdenv.mkDerivation { … } -</programlisting> - - </para> - - <para>This function is not available if <link - linkend="conf-restrict-eval">restricted evaluation mode</link> is - enabled.</para></listitem> - - </varlistentry> - - <varlistentry xml:id='builtin-fetchGit'> - <term> - <function>builtins.fetchGit</function> - <replaceable>args</replaceable> - </term> - - <listitem> - <para> - Fetch a path from git. <replaceable>args</replaceable> can be - a URL, in which case the HEAD of the repo at that URL is - fetched. Otherwise, it can be an attribute with the following - attributes (all except <varname>url</varname> optional): - </para> - - <variablelist> - <varlistentry> - <term>url</term> - <listitem> - <para> - The URL of the repo. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>name</term> - <listitem> - <para> - The name of the directory the repo should be exported to - in the store. Defaults to the basename of the URL. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>rev</term> - <listitem> - <para> - The git revision to fetch. Defaults to the tip of - <varname>ref</varname>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>ref</term> - <listitem> - <para> - The git ref to look for the requested revision under. - This is often a branch or tag name. Defaults to - <literal>HEAD</literal>. - </para> - - <para> - By default, the <varname>ref</varname> value is prefixed - with <literal>refs/heads/</literal>. As of Nix 2.3.0 - Nix will not prefix <literal>refs/heads/</literal> if - <varname>ref</varname> starts with <literal>refs/</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>submodules</term> - <listitem> - <para> - A Boolean parameter that specifies whether submodules - should be checked out. Defaults to - <literal>false</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title>Fetching a private repository over SSH</title> - <programlisting>builtins.fetchGit { - url = "git@github.com:my-secret/repository.git"; - ref = "master"; - rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; -}</programlisting> - </example> - - <example> - <title>Fetching an arbitrary ref</title> - <programlisting>builtins.fetchGit { - url = "https://github.com/NixOS/nix.git"; - ref = "refs/heads/0.5-release"; -}</programlisting> - </example> - - <example> - <title>Fetching a repository's specific commit on an arbitrary branch</title> - <para> - If the revision you're looking for is in the default branch - of the git repository you don't strictly need to specify - the branch name in the <varname>ref</varname> attribute. - </para> - <para> - However, if the revision you're looking for is in a future - branch for the non-default branch you will need to specify - the the <varname>ref</varname> attribute as well. - </para> - <programlisting>builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; - ref = "1.11-maintenance"; -}</programlisting> - <note> - <para> - It is nice to always specify the branch which a revision - belongs to. Without the branch being specified, the - fetcher might fail if the default branch changes. - Additionally, it can be confusing to try a commit from a - non-default branch and see the fetch fail. If the branch - is specified the fault is much more obvious. - </para> - </note> - </example> - - <example> - <title>Fetching a repository's specific commit on the default branch</title> - <para> - If the revision you're looking for is in the default branch - of the git repository you may omit the - <varname>ref</varname> attribute. - </para> - <programlisting>builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; -}</programlisting> - </example> - - <example> - <title>Fetching a tag</title> - <programlisting>builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - ref = "refs/tags/1.9"; -}</programlisting> - </example> - - <example> - <title>Fetching the latest version of a remote branch</title> - <para> - <function>builtins.fetchGit</function> can behave impurely - fetch the latest version of a remote branch. - </para> - <note><para>Nix will refetch the branch in accordance to - <xref linkend="conf-tarball-ttl" />.</para></note> - <note><para>This behavior is disabled in - <emphasis>Pure evaluation mode</emphasis>.</para></note> - <programlisting>builtins.fetchGit { - url = "ssh://git@github.com/nixos/nix.git"; - ref = "master"; -}</programlisting> - </example> - </listitem> - </varlistentry> - - - <varlistentry><term><function>builtins.filter</function> - <replaceable>f</replaceable> <replaceable>xs</replaceable></term> - - <listitem><para>Return a list consisting of the elements of - <replaceable>xs</replaceable> for which the function - <replaceable>f</replaceable> returns - <literal>true</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-filterSource'> - <term><function>builtins.filterSource</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem> - - <para>This function allows you to copy sources into the Nix - store while filtering certain files. For instance, suppose that - you want to use the directory <filename>source-dir</filename> as - an input to a Nix expression, e.g. - -<programlisting> -stdenv.mkDerivation { - ... - src = ./source-dir; -} -</programlisting> - - However, if <filename>source-dir</filename> is a Subversion - working copy, then all those annoying <filename>.svn</filename> - subdirectories will also be copied to the store. Worse, the - contents of those directories may change a lot, causing lots of - spurious rebuilds. With <function>filterSource</function> you - can filter out the <filename>.svn</filename> directories: - -<programlisting> - src = builtins.filterSource - (path: type: type != "directory" || baseNameOf path != ".svn") - ./source-dir; -</programlisting> - - </para> - - <para>Thus, the first argument <replaceable>e1</replaceable> - must be a predicate function that is called for each regular - file, directory or symlink in the source tree - <replaceable>e2</replaceable>. If the function returns - <literal>true</literal>, the file is copied to the Nix store, - otherwise it is omitted. The function is called with two - arguments. The first is the full path of the file. The second - is a string that identifies the type of the file, which is - either <literal>"regular"</literal>, - <literal>"directory"</literal>, <literal>"symlink"</literal> or - <literal>"unknown"</literal> (for other kinds of files such as - device nodes or fifos — but note that those cannot be copied to - the Nix store, so if the predicate returns - <literal>true</literal> for them, the copy will fail). If you - exclude a directory, the entire corresponding subtree of - <replaceable>e2</replaceable> will be excluded.</para> - - </listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-foldl-prime'> - <term><function>builtins.foldl’</function> - <replaceable>op</replaceable> <replaceable>nul</replaceable> <replaceable>list</replaceable></term> - - <listitem><para>Reduce a list by applying a binary operator, from - left to right, e.g. <literal>foldl’ op nul [x0 x1 x2 ...] = op (op - (op nul x0) x1) x2) ...</literal>. The operator is applied - strictly, i.e., its arguments are evaluated first. For example, - <literal>foldl’ (x: y: x + y) 0 [1 2 3]</literal> evaluates to - 6.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-functionArgs'> - <term><function>builtins.functionArgs</function> - <replaceable>f</replaceable></term> - - <listitem><para> - Return a set containing the names of the formal arguments expected - by the function <replaceable>f</replaceable>. - The value of each attribute is a Boolean denoting whether the corresponding - argument has a default value. For instance, - <literal>functionArgs ({ x, y ? 123}: ...) = { x = false; y = true; }</literal>. - </para> - - <para>"Formal argument" here refers to the attributes pattern-matched by - the function. Plain lambdas are not included, e.g. - <literal>functionArgs (x: ...) = { }</literal>. - </para></listitem> - </varlistentry> - - - <varlistentry xml:id='builtin-fromJSON'> - <term><function>builtins.fromJSON</function> <replaceable>e</replaceable></term> - - <listitem><para>Convert a JSON string to a Nix - value. For example, - -<programlisting> -builtins.fromJSON ''{"x": [1, 2, 3], "y": null}'' -</programlisting> - - returns the value <literal>{ x = [ 1 2 3 ]; y = null; - }</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-genList'> - <term><function>builtins.genList</function> - <replaceable>generator</replaceable> <replaceable>length</replaceable></term> - - <listitem><para>Generate list of size - <replaceable>length</replaceable>, with each element - <replaceable>i</replaceable> equal to the value returned by - <replaceable>generator</replaceable> <literal>i</literal>. For - example, - -<programlisting> -builtins.genList (x: x * x) 5 -</programlisting> - - returns the list <literal>[ 0 1 4 9 16 ]</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-getAttr'> - <term><function>builtins.getAttr</function> - <replaceable>s</replaceable> <replaceable>set</replaceable></term> - - <listitem><para><function>getAttr</function> returns the attribute - named <replaceable>s</replaceable> from - <replaceable>set</replaceable>. Evaluation aborts if the - attribute doesn’t exist. This is a dynamic version of the - <literal>.</literal> operator, since <replaceable>s</replaceable> - is an expression rather than an identifier.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-getEnv'> - <term><function>builtins.getEnv</function> - <replaceable>s</replaceable></term> - - <listitem><para><function>getEnv</function> returns the value of - the environment variable <replaceable>s</replaceable>, or an empty - string if the variable doesn’t exist. This function should be - used with care, as it can introduce all sorts of nasty environment - dependencies in your Nix expression.</para> - - <para><function>getEnv</function> is used in Nix Packages to - locate the file <filename>~/.nixpkgs/config.nix</filename>, which - contains user-local settings for Nix Packages. (That is, it does - a <literal>getEnv "HOME"</literal> to locate the user’s home - directory.)</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-hasAttr'> - <term><function>builtins.hasAttr</function> - <replaceable>s</replaceable> <replaceable>set</replaceable></term> - - <listitem><para><function>hasAttr</function> returns - <literal>true</literal> if <replaceable>set</replaceable> has an - attribute named <replaceable>s</replaceable>, and - <literal>false</literal> otherwise. This is a dynamic version of - the <literal>?</literal> operator, since - <replaceable>s</replaceable> is an expression rather than an - identifier.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-hashString'> - <term><function>builtins.hashString</function> - <replaceable>type</replaceable> <replaceable>s</replaceable></term> - - <listitem><para>Return a base-16 representation of the - cryptographic hash of string <replaceable>s</replaceable>. The - hash algorithm specified by <replaceable>type</replaceable> must - be one of <literal>"md5"</literal>, <literal>"sha1"</literal>, - <literal>"sha256"</literal> or <literal>"sha512"</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-hashFile'> - <term><function>builtins.hashFile</function> - <replaceable>type</replaceable> <replaceable>p</replaceable></term> - - <listitem><para>Return a base-16 representation of the - cryptographic hash of the file at path <replaceable>p</replaceable>. The - hash algorithm specified by <replaceable>type</replaceable> must - be one of <literal>"md5"</literal>, <literal>"sha1"</literal>, - <literal>"sha256"</literal> or <literal>"sha512"</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-head'> - <term><function>builtins.head</function> - <replaceable>list</replaceable></term> - - <listitem><para>Return the first element of a list; abort - evaluation if the argument isn’t a list or is an empty list. You - can test whether a list is empty by comparing it with - <literal>[]</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-import'> - <term><function>import</function> - <replaceable>path</replaceable></term> - <term><function>builtins.import</function> - <replaceable>path</replaceable></term> - - <listitem><para>Load, parse and return the Nix expression in the - file <replaceable>path</replaceable>. If <replaceable>path - </replaceable> is a directory, the file <filename>default.nix - </filename> in that directory is loaded. Evaluation aborts if the - file doesn’t exist or contains an incorrect Nix expression. - <function>import</function> implements Nix’s module system: you - can put any Nix expression (such as a set or a function) in a - separate file, and use it from Nix expressions in other - files.</para> - - <note><para>Unlike some languages, <function>import</function> is a regular - function in Nix. Paths using the angle bracket syntax (e.g., <function> - import</function> <replaceable><foo></replaceable>) are normal path - values (see <xref linkend='ssec-values' />).</para></note> - - <para>A Nix expression loaded by <function>import</function> must - not contain any <emphasis>free variables</emphasis> (identifiers - that are not defined in the Nix expression itself and are not - built-in). Therefore, it cannot refer to variables that are in - scope at the call site. For instance, if you have a calling - expression - -<programlisting> -rec { - x = 123; - y = import ./foo.nix; -}</programlisting> - - then the following <filename>foo.nix</filename> will give an - error: - -<programlisting> -x + 456</programlisting> - - since <varname>x</varname> is not in scope in - <filename>foo.nix</filename>. If you want <varname>x</varname> - to be available in <filename>foo.nix</filename>, you should pass - it as a function argument: - -<programlisting> -rec { - x = 123; - y = import ./foo.nix x; -}</programlisting> - - and - -<programlisting> -x: x + 456</programlisting> - - (The function argument doesn’t have to be called - <varname>x</varname> in <filename>foo.nix</filename>; any name - would work.)</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-intersectAttrs'> - <term><function>builtins.intersectAttrs</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem><para>Return a set consisting of the attributes in the - set <replaceable>e2</replaceable> that also exist in the set - <replaceable>e1</replaceable>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-isAttrs'> - <term><function>builtins.isAttrs</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return <literal>true</literal> if - <replaceable>e</replaceable> evaluates to a set, and - <literal>false</literal> otherwise.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-isList'> - <term><function>builtins.isList</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return <literal>true</literal> if - <replaceable>e</replaceable> evaluates to a list, and - <literal>false</literal> otherwise.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-isFunction'><term><function>builtins.isFunction</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return <literal>true</literal> if - <replaceable>e</replaceable> evaluates to a function, and - <literal>false</literal> otherwise.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-isString'> - <term><function>builtins.isString</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return <literal>true</literal> if - <replaceable>e</replaceable> evaluates to a string, and - <literal>false</literal> otherwise.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-isInt'> - <term><function>builtins.isInt</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return <literal>true</literal> if - <replaceable>e</replaceable> evaluates to an int, and - <literal>false</literal> otherwise.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-isFloat'> - <term><function>builtins.isFloat</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return <literal>true</literal> if - <replaceable>e</replaceable> evaluates to a float, and - <literal>false</literal> otherwise.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-isBool'> - <term><function>builtins.isBool</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return <literal>true</literal> if - <replaceable>e</replaceable> evaluates to a bool, and - <literal>false</literal> otherwise.</para></listitem> - - </varlistentry> - - <varlistentry><term><function>builtins.isPath</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return <literal>true</literal> if - <replaceable>e</replaceable> evaluates to a path, and - <literal>false</literal> otherwise.</para></listitem> - - </varlistentry> - - <varlistentry xml:id='builtin-isNull'> - <term><function>isNull</function> - <replaceable>e</replaceable></term> - <term><function>builtins.isNull</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return <literal>true</literal> if - <replaceable>e</replaceable> evaluates to <literal>null</literal>, - and <literal>false</literal> otherwise.</para> - - <warning><para>This function is <emphasis>deprecated</emphasis>; - just write <literal>e == null</literal> instead.</para></warning> - - </listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-length'> - <term><function>builtins.length</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return the length of the list - <replaceable>e</replaceable>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-lessThan'> - <term><function>builtins.lessThan</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem><para>Return <literal>true</literal> if the number - <replaceable>e1</replaceable> is less than the number - <replaceable>e2</replaceable>, and <literal>false</literal> - otherwise. Evaluation aborts if either - <replaceable>e1</replaceable> or <replaceable>e2</replaceable> - does not evaluate to a number.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-listToAttrs'> - <term><function>builtins.listToAttrs</function> - <replaceable>e</replaceable></term> - - <listitem><para>Construct a set from a list specifying the names - and values of each attribute. Each element of the list should be - a set consisting of a string-valued attribute - <varname>name</varname> specifying the name of the attribute, and - an attribute <varname>value</varname> specifying its value. - Example: - -<programlisting> -builtins.listToAttrs - [ { name = "foo"; value = 123; } - { name = "bar"; value = 456; } - ] -</programlisting> - - evaluates to - -<programlisting> -{ foo = 123; bar = 456; } -</programlisting> - - </para></listitem> - - </varlistentry> - - <varlistentry xml:id='builtin-map'> - <term><function>map</function> - <replaceable>f</replaceable> <replaceable>list</replaceable></term> - <term><function>builtins.map</function> - <replaceable>f</replaceable> <replaceable>list</replaceable></term> - - <listitem><para>Apply the function <replaceable>f</replaceable> to - each element in the list <replaceable>list</replaceable>. For - example, - -<programlisting> -map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting> - - evaluates to <literal>[ "foobar" "foobla" "fooabc" - ]</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-match'> - <term><function>builtins.match</function> - <replaceable>regex</replaceable> <replaceable>str</replaceable></term> - - <listitem><para>Returns a list if the <link - xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended - POSIX regular expression</link> <replaceable>regex</replaceable> - matches <replaceable>str</replaceable> precisely, otherwise returns - <literal>null</literal>. Each item in the list is a regex group. - -<programlisting> -builtins.match "ab" "abc" -</programlisting> - -Evaluates to <literal>null</literal>. - -<programlisting> -builtins.match "abc" "abc" -</programlisting> - -Evaluates to <literal>[ ]</literal>. - -<programlisting> -builtins.match "a(b)(c)" "abc" -</programlisting> - -Evaluates to <literal>[ "b" "c" ]</literal>. - -<programlisting> -builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO " -</programlisting> - -Evaluates to <literal>[ "foo" ]</literal>. - - </para></listitem> - </varlistentry> - - <varlistentry xml:id='builtin-mul'> - <term><function>builtins.mul</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem><para>Return the product of the numbers - <replaceable>e1</replaceable> and - <replaceable>e2</replaceable>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-parseDrvName'> - <term><function>builtins.parseDrvName</function> - <replaceable>s</replaceable></term> - - <listitem><para>Split the string <replaceable>s</replaceable> into - a package name and version. The package name is everything up to - but not including the first dash followed by a digit, and the - version is everything following that dash. The result is returned - in a set <literal>{ name, version }</literal>. Thus, - <literal>builtins.parseDrvName "nix-0.12pre12876"</literal> - returns <literal>{ name = "nix"; version = "0.12pre12876"; - }</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id='builtin-path'> - <term> - <function>builtins.path</function> - <replaceable>args</replaceable> - </term> - - <listitem> - <para> - An enrichment of the built-in path type, based on the attributes - present in <replaceable>args</replaceable>. All are optional - except <varname>path</varname>: - </para> - - <variablelist> - <varlistentry> - <term>path</term> - <listitem> - <para>The underlying path.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>name</term> - <listitem> - <para> - The name of the path when added to the store. This can - used to reference paths that have nix-illegal characters - in their names, like <literal>@</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>filter</term> - <listitem> - <para> - A function of the type expected by - <link linkend="builtin-filterSource">builtins.filterSource</link>, - with the same semantics. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>recursive</term> - <listitem> - <para> - When <literal>false</literal>, when - <varname>path</varname> is added to the store it is with a - flat hash, rather than a hash of the NAR serialization of - the file. Thus, <varname>path</varname> must refer to a - regular file, not a directory. This allows similar - behavior to <literal>fetchurl</literal>. Defaults to - <literal>true</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>sha256</term> - <listitem> - <para> - When provided, this is the expected hash of the file at - the path. Evaluation will fail if the hash is incorrect, - and providing a hash allows - <literal>builtins.path</literal> to be used even when the - <literal>pure-eval</literal> nix config option is on. - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry xml:id='builtin-pathExists'> - <term><function>builtins.pathExists</function> - <replaceable>path</replaceable></term> - - <listitem><para>Return <literal>true</literal> if the path - <replaceable>path</replaceable> exists at evaluation time, and - <literal>false</literal> otherwise.</para></listitem> - - </varlistentry> - - <varlistentry xml:id='builtin-placeholder'> - <term><function>builtins.placeholder</function> - <replaceable>output</replaceable></term> - - <listitem><para>Return a placeholder string for the specified - <replaceable>output</replaceable> that will be substituted by the - corresponding output path at build time. Typical outputs would be - <literal>"out"</literal>, <literal>"bin"</literal> or - <literal>"dev"</literal>.</para></listitem> - </varlistentry> - - <varlistentry xml:id='builtin-readDir'> - <term><function>builtins.readDir</function> - <replaceable>path</replaceable></term> - - <listitem><para>Return the contents of the directory - <replaceable>path</replaceable> as a set mapping directory entries - to the corresponding file type. For instance, if directory - <filename>A</filename> contains a regular file - <filename>B</filename> and another directory - <filename>C</filename>, then <literal>builtins.readDir - ./A</literal> will return the set - -<programlisting> -{ B = "regular"; C = "directory"; }</programlisting> - - The possible values for the file type are - <literal>"regular"</literal>, <literal>"directory"</literal>, - <literal>"symlink"</literal> and - <literal>"unknown"</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-readFile'> - <term><function>builtins.readFile</function> - <replaceable>path</replaceable></term> - - <listitem><para>Return the contents of the file - <replaceable>path</replaceable> as a string.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-removeAttrs'> - <term><function>removeAttrs</function> - <replaceable>set</replaceable> <replaceable>list</replaceable></term> - <term><function>builtins.removeAttrs</function> - <replaceable>set</replaceable> <replaceable>list</replaceable></term> - - <listitem><para>Remove the attributes listed in - <replaceable>list</replaceable> from - <replaceable>set</replaceable>. The attributes don’t have to - exist in <replaceable>set</replaceable>. For instance, - -<programlisting> -removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</programlisting> - - evaluates to <literal>{ y = 2; }</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-replaceStrings'> - <term><function>builtins.replaceStrings</function> - <replaceable>from</replaceable> <replaceable>to</replaceable> <replaceable>s</replaceable></term> - - <listitem><para>Given string <replaceable>s</replaceable>, replace - every occurrence of the strings in <replaceable>from</replaceable> - with the corresponding string in - <replaceable>to</replaceable>. For example, - -<programlisting> -builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar" -</programlisting> - - evaluates to <literal>"fabir"</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-seq'> - <term><function>builtins.seq</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem><para>Evaluate <replaceable>e1</replaceable>, then - evaluate and return <replaceable>e2</replaceable>. This ensures - that a computation is strict in the value of - <replaceable>e1</replaceable>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-sort'> - <term><function>builtins.sort</function> - <replaceable>comparator</replaceable> <replaceable>list</replaceable></term> - - <listitem><para>Return <replaceable>list</replaceable> in sorted - order. It repeatedly calls the function - <replaceable>comparator</replaceable> with two elements. The - comparator should return <literal>true</literal> if the first - element is less than the second, and <literal>false</literal> - otherwise. For example, - -<programlisting> -builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ] -</programlisting> - - produces the list <literal>[ 42 77 147 249 483 526 - ]</literal>.</para> - - <para>This is a stable sort: it preserves the relative order of - elements deemed equal by the comparator.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-split'> - <term><function>builtins.split</function> - <replaceable>regex</replaceable> <replaceable>str</replaceable></term> - - <listitem><para>Returns a list composed of non matched strings interleaved - with the lists of the <link - xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended - POSIX regular expression</link> <replaceable>regex</replaceable> matches - of <replaceable>str</replaceable>. Each item in the lists of matched - sequences is a regex group. - -<programlisting> -builtins.split "(a)b" "abc" -</programlisting> - -Evaluates to <literal>[ "" [ "a" ] "c" ]</literal>. - -<programlisting> -builtins.split "([ac])" "abc" -</programlisting> - -Evaluates to <literal>[ "" [ "a" ] "b" [ "c" ] "" ]</literal>. - -<programlisting> -builtins.split "(a)|(c)" "abc" -</programlisting> - -Evaluates to <literal>[ "" [ "a" null ] "b" [ null "c" ] "" ]</literal>. - -<programlisting> -builtins.split "([[:upper:]]+)" " FOO " -</programlisting> - -Evaluates to <literal>[ " " [ "FOO" ] " " ]</literal>. - - </para></listitem> - </varlistentry> - - - <varlistentry xml:id='builtin-splitVersion'> - <term><function>builtins.splitVersion</function> - <replaceable>s</replaceable></term> - - <listitem><para>Split a string representing a version into its - components, by the same version splitting logic underlying the - version comparison in <link linkend="ssec-version-comparisons"> - <command>nix-env -u</command></link>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-stringLength'> - <term><function>builtins.stringLength</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return the length of the string - <replaceable>e</replaceable>. If <replaceable>e</replaceable> is - not a string, evaluation is aborted.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-sub'> - <term><function>builtins.sub</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem><para>Return the difference between the numbers - <replaceable>e1</replaceable> and - <replaceable>e2</replaceable>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-substring'> - <term><function>builtins.substring</function> - <replaceable>start</replaceable> <replaceable>len</replaceable> - <replaceable>s</replaceable></term> - - <listitem><para>Return the substring of - <replaceable>s</replaceable> from character position - <replaceable>start</replaceable> (zero-based) up to but not - including <replaceable>start + len</replaceable>. If - <replaceable>start</replaceable> is greater than the length of the - string, an empty string is returned, and if <replaceable>start + - len</replaceable> lies beyond the end of the string, only the - substring up to the end of the string is returned. - <replaceable>start</replaceable> must be - non-negative. For example, - -<programlisting> -builtins.substring 0 3 "nixos" -</programlisting> - - evaluates to <literal>"nix"</literal>. - </para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-tail'> - <term><function>builtins.tail</function> - <replaceable>list</replaceable></term> - - <listitem><para>Return the second to last elements of a list; - abort evaluation if the argument isn’t a list or is an empty - list.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-throw'> - <term><function>throw</function> - <replaceable>s</replaceable></term> - <term><function>builtins.throw</function> - <replaceable>s</replaceable></term> - - <listitem><para>Throw an error message - <replaceable>s</replaceable>. This usually aborts Nix expression - evaluation, but in <command>nix-env -qa</command> and other - commands that try to evaluate a set of derivations to get - information about those derivations, a derivation that throws an - error is silently skipped (which is not the case for - <function>abort</function>).</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-toFile'> - <term><function>builtins.toFile</function> - <replaceable>name</replaceable> - <replaceable>s</replaceable></term> - - <listitem><para>Store the string <replaceable>s</replaceable> in a - file in the Nix store and return its path. The file has suffix - <replaceable>name</replaceable>. This file can be used as an - input to derivations. One application is to write builders - “inline”. For instance, the following Nix expression combines - <xref linkend='ex-hello-nix' /> and <xref - linkend='ex-hello-builder' /> into one file: - -<programlisting> -{ stdenv, fetchurl, perl }: - -stdenv.mkDerivation { - name = "hello-2.1.1"; - - builder = builtins.toFile "builder.sh" " - source $stdenv/setup - - PATH=$perl/bin:$PATH - - tar xvfz $src - cd hello-* - ./configure --prefix=$out - make - make install - "; - - src = fetchurl { - url = "http://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; - sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; - }; - inherit perl; -}</programlisting> - - </para> - - <para>It is even possible for one file to refer to another, e.g., - -<programlisting> - builder = let - configFile = builtins.toFile "foo.conf" " - # This is some dummy configuration file. - <replaceable>...</replaceable> - "; - in builtins.toFile "builder.sh" " - source $stdenv/setup - <replaceable>...</replaceable> - cp ${configFile} $out/etc/foo.conf - ";</programlisting> - - Note that <literal>${configFile}</literal> is an antiquotation - (see <xref linkend='ssec-values' />), so the result of the - expression <literal>configFile</literal> (i.e., a path like - <filename>/nix/store/m7p7jfny445k...-foo.conf</filename>) will be - spliced into the resulting string.</para> - - <para>It is however <emphasis>not</emphasis> allowed to have files - mutually referring to each other, like so: - -<programlisting> -let - foo = builtins.toFile "foo" "...${bar}..."; - bar = builtins.toFile "bar" "...${foo}..."; -in foo</programlisting> - - This is not allowed because it would cause a cyclic dependency in - the computation of the cryptographic hashes for - <varname>foo</varname> and <varname>bar</varname>.</para> - <para>It is also not possible to reference the result of a derivation. - If you are using Nixpkgs, the <literal>writeTextFile</literal> function is able to - do that.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-toJSON'> - <term><function>builtins.toJSON</function> <replaceable>e</replaceable></term> - - <listitem><para>Return a string containing a JSON representation - of <replaceable>e</replaceable>. Strings, integers, floats, booleans, - nulls and lists are mapped to their JSON equivalents. Sets - (except derivations) are represented as objects. Derivations are - translated to a JSON string containing the derivation’s output - path. Paths are copied to the store and represented as a JSON - string of the resulting store path.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-toPath'> - <term><function>builtins.toPath</function> <replaceable>s</replaceable></term> - - <listitem><para> DEPRECATED. Use <literal>/. + "/path"</literal> - to convert a string into an absolute path. For relative paths, - use <literal>./. + "/path"</literal>. - </para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-toString'> - <term><function>toString</function> <replaceable>e</replaceable></term> - <term><function>builtins.toString</function> <replaceable>e</replaceable></term> - - <listitem><para>Convert the expression - <replaceable>e</replaceable> to a string. - <replaceable>e</replaceable> can be:</para> - <itemizedlist> - <listitem><para>A string (in which case the string is returned unmodified).</para></listitem> - <listitem><para>A path (e.g., <literal>toString /foo/bar</literal> yields <literal>"/foo/bar"</literal>.</para></listitem> - <listitem><para>A set containing <literal>{ __toString = self: ...; }</literal>.</para></listitem> - <listitem><para>An integer.</para></listitem> - <listitem><para>A list, in which case the string representations of its elements are joined with spaces.</para></listitem> - <listitem><para>A Boolean (<literal>false</literal> yields <literal>""</literal>, <literal>true</literal> yields <literal>"1"</literal>).</para></listitem> - <listitem><para><literal>null</literal>, which yields the empty string.</para></listitem> - </itemizedlist> - </listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-toXML'> - <term><function>builtins.toXML</function> <replaceable>e</replaceable></term> - - <listitem><para>Return a string containing an XML representation - of <replaceable>e</replaceable>. The main application for - <function>toXML</function> is to communicate information with the - builder in a more structured format than plain environment - variables.</para> - - <!-- TODO: more formally describe the schema of the XML - representation --> - - <para><xref linkend='ex-toxml' /> shows an example where this is - the case. The builder is supposed to generate the configuration - file for a <link xlink:href='http://jetty.mortbay.org/'>Jetty - servlet container</link>. A servlet container contains a number - of servlets (<filename>*.war</filename> files) each exported under - a specific URI prefix. So the servlet configuration is a list of - sets containing the <varname>path</varname> and - <varname>war</varname> of the servlet (<xref - linkend='ex-toxml-co-servlets' />). This kind of information is - difficult to communicate with the normal method of passing - information through an environment variable, which just - concatenates everything together into a string (which might just - work in this case, but wouldn’t work if fields are optional or - contain lists themselves). Instead the Nix expression is - converted to an XML representation with - <function>toXML</function>, which is unambiguous and can easily be - processed with the appropriate tools. For instance, in the - example an XSLT stylesheet (<xref linkend='ex-toxml-co-stylesheet' - />) is applied to it (<xref linkend='ex-toxml-co-apply' />) to - generate the XML configuration file for the Jetty server. The XML - representation produced from <xref linkend='ex-toxml-co-servlets' - /> by <function>toXML</function> is shown in <xref - linkend='ex-toxml-result' />.</para> - - <para>Note that <xref linkend='ex-toxml' /> uses the <function - linkend='builtin-toFile'>toFile</function> built-in to write the - builder and the stylesheet “inline” in the Nix expression. The - path of the stylesheet is spliced into the builder at - <literal>xsltproc ${stylesheet} - <replaceable>...</replaceable></literal>.</para> - - <example xml:id='ex-toxml'><title>Passing information to a builder - using <function>toXML</function></title> - -<programlisting><![CDATA[ -{ stdenv, fetchurl, libxslt, jira, uberwiki }: - -stdenv.mkDerivation (rec { - name = "web-server"; - - buildInputs = [ libxslt ]; - - builder = builtins.toFile "builder.sh" " - source $stdenv/setup - mkdir $out - echo "$servlets" | xsltproc ${stylesheet} - > $out/server-conf.xml]]> <co xml:id='ex-toxml-co-apply' /> <![CDATA[ - "; - - stylesheet = builtins.toFile "stylesheet.xsl"]]> <co xml:id='ex-toxml-co-stylesheet' /> <![CDATA[ - "<?xml version='1.0' encoding='UTF-8'?> - <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'> - <xsl:template match='/'> - <Configure> - <xsl:for-each select='/expr/list/attrs'> - <Call name='addWebApplication'> - <Arg><xsl:value-of select=\"attr[@name = 'path']/string/@value\" /></Arg> - <Arg><xsl:value-of select=\"attr[@name = 'war']/path/@value\" /></Arg> - </Call> - </xsl:for-each> - </Configure> - </xsl:template> - </xsl:stylesheet> - "; - - servlets = builtins.toXML []]> <co xml:id='ex-toxml-co-servlets' /> <![CDATA[ - { path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; } - { path = "/wiki"; war = uberwiki + "/uberwiki.war"; } - ]; -})]]></programlisting> - - </example> - - <example xml:id='ex-toxml-result'><title>XML representation produced by - <function>toXML</function></title> - -<programlisting><![CDATA[<?xml version='1.0' encoding='utf-8'?> -<expr> - <list> - <attrs> - <attr name="path"> - <string value="/bugtracker" /> - </attr> - <attr name="war"> - <path value="/nix/store/d1jh9pasa7k2...-jira/lib/atlassian-jira.war" /> - </attr> - </attrs> - <attrs> - <attr name="path"> - <string value="/wiki" /> - </attr> - <attr name="war"> - <path value="/nix/store/y6423b1yi4sx...-uberwiki/uberwiki.war" /> - </attr> - </attrs> - </list> -</expr>]]></programlisting> - - </example> - - </listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-trace'> - <term><function>builtins.trace</function> - <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - - <listitem><para>Evaluate <replaceable>e1</replaceable> and print its - abstract syntax representation on standard error. Then return - <replaceable>e2</replaceable>. This function is useful for - debugging.</para></listitem> - - </varlistentry> - - <varlistentry xml:id='builtin-tryEval'> - <term><function>builtins.tryEval</function> - <replaceable>e</replaceable></term> - - <listitem><para>Try to shallowly evaluate <replaceable>e</replaceable>. - Return a set containing the attributes <literal>success</literal> - (<literal>true</literal> if <replaceable>e</replaceable> evaluated - successfully, <literal>false</literal> if an error was thrown) and - <literal>value</literal>, equalling <replaceable>e</replaceable> - if successful and <literal>false</literal> otherwise. Note that this - doesn't evaluate <replaceable>e</replaceable> deeply, so - <literal>let e = { x = throw ""; }; in (builtins.tryEval e).success - </literal> will be <literal>true</literal>. Using <literal>builtins.deepSeq - </literal> one can get the expected result: <literal>let e = { x = throw ""; - }; in (builtins.tryEval (builtins.deepSeq e e)).success</literal> will be - <literal>false</literal>. - </para></listitem> - - </varlistentry> - - - <varlistentry xml:id='builtin-typeOf'> - <term><function>builtins.typeOf</function> - <replaceable>e</replaceable></term> - - <listitem><para>Return a string representing the type of the value - <replaceable>e</replaceable>, namely <literal>"int"</literal>, - <literal>"bool"</literal>, <literal>"string"</literal>, - <literal>"path"</literal>, <literal>"null"</literal>, - <literal>"set"</literal>, <literal>"list"</literal>, - <literal>"lambda"</literal> or - <literal>"float"</literal>.</para></listitem> - - </varlistentry> - - -</variablelist> - - -</section> diff --git a/doc/manual/expressions/derivations.xml b/doc/manual/expressions/derivations.xml deleted file mode 100644 index 6f6297565..000000000 --- a/doc/manual/expressions/derivations.xml +++ /dev/null @@ -1,211 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-derivation"> - -<title>Derivations</title> - -<para>The most important built-in function is -<function>derivation</function>, which is used to describe a single -derivation (a build action). It takes as input a set, the attributes -of which specify the inputs of the build.</para> - -<itemizedlist> - - <listitem xml:id="attr-system"><para>There must be an attribute named - <varname>system</varname> whose value must be a string specifying a - Nix platform identifier, such as <literal>"i686-linux"</literal> or - <literal>"x86_64-darwin"</literal><footnote><para>To figure out - your platform identifier, look at the line <quote>Checking for the - canonical Nix system name</quote> in the output of Nix's - <filename>configure</filename> script.</para></footnote> The build - can only be performed on a machine and operating system matching the - platform identifier. (Nix can automatically forward builds for - other platforms by forwarding them to other machines; see <xref - linkend='chap-distributed-builds' />.)</para></listitem> - - <listitem><para>There must be an attribute named - <varname>name</varname> whose value must be a string. This is used - as a symbolic name for the package by <command>nix-env</command>, - and it is appended to the output paths of the - derivation.</para></listitem> - - <listitem><para>There must be an attribute named - <varname>builder</varname> that identifies the program that is - executed to perform the build. It can be either a derivation or a - source (a local file reference, e.g., - <filename>./builder.sh</filename>).</para></listitem> - - <listitem><para>Every attribute is passed as an environment variable - to the builder. Attribute values are translated to environment - variables as follows: - - <itemizedlist> - - <listitem><para>Strings and numbers are just passed - verbatim.</para></listitem> - - <listitem><para>A <emphasis>path</emphasis> (e.g., - <filename>../foo/sources.tar</filename>) causes the referenced - file to be copied to the store; its location in the store is put - in the environment variable. The idea is that all sources - should reside in the Nix store, since all inputs to a derivation - should reside in the Nix store.</para></listitem> - - <listitem><para>A <emphasis>derivation</emphasis> causes that - derivation to be built prior to the present derivation; its - default output path is put in the environment - variable.</para></listitem> - - <listitem><para>Lists of the previous types are also allowed. - They are simply concatenated, separated by - spaces.</para></listitem> - - <listitem><para><literal>true</literal> is passed as the string - <literal>1</literal>, <literal>false</literal> and - <literal>null</literal> are passed as an empty string. - </para></listitem> - </itemizedlist> - - </para></listitem> - - <listitem><para>The optional attribute <varname>args</varname> - specifies command-line arguments to be passed to the builder. It - should be a list.</para></listitem> - - <listitem><para>The optional attribute <varname>outputs</varname> - specifies a list of symbolic outputs of the derivation. By default, - a derivation produces a single output path, denoted as - <literal>out</literal>. However, derivations can produce multiple - output paths. This is useful because it allows outputs to be - downloaded or garbage-collected separately. For instance, imagine a - library package that provides a dynamic library, header files, and - documentation. A program that links against the library doesn’t - need the header files and documentation at runtime, and it doesn’t - need the documentation at build time. Thus, the library package - could specify: -<programlisting> -outputs = [ "lib" "headers" "doc" ]; -</programlisting> - This will cause Nix to pass environment variables - <literal>lib</literal>, <literal>headers</literal> and - <literal>doc</literal> to the builder containing the intended store - paths of each output. The builder would typically do something like -<programlisting> -./configure --libdir=$lib/lib --includedir=$headers/include --docdir=$doc/share/doc -</programlisting> - for an Autoconf-style package. You can refer to each output of a - derivation by selecting it as an attribute, e.g. -<programlisting> -buildInputs = [ pkg.lib pkg.headers ]; -</programlisting> - The first element of <varname>outputs</varname> determines the - <emphasis>default output</emphasis>. Thus, you could also write -<programlisting> -buildInputs = [ pkg pkg.headers ]; -</programlisting> - since <literal>pkg</literal> is equivalent to - <literal>pkg.lib</literal>.</para></listitem> - -</itemizedlist> - -<para>The function <function>mkDerivation</function> in the Nixpkgs -standard environment is a wrapper around -<function>derivation</function> that adds a default value for -<varname>system</varname> and always uses Bash as the builder, to -which the supplied builder is passed as a command-line argument. See -the Nixpkgs manual for details.</para> - -<para>The builder is executed as follows: - -<itemizedlist> - - <listitem><para>A temporary directory is created under the directory - specified by <envar>TMPDIR</envar> (default - <filename>/tmp</filename>) where the build will take place. The - current directory is changed to this directory.</para></listitem> - - <listitem><para>The environment is cleared and set to the derivation - attributes, as specified above.</para></listitem> - - <listitem><para>In addition, the following variables are set: - - <itemizedlist> - - <listitem><para><envar>NIX_BUILD_TOP</envar> contains the path of - the temporary directory for this build.</para></listitem> - - <listitem><para>Also, <envar>TMPDIR</envar>, - <envar>TEMPDIR</envar>, <envar>TMP</envar>, <envar>TEMP</envar> - are set to point to the temporary directory. This is to prevent - the builder from accidentally writing temporary files anywhere - else. Doing so might cause interference by other - processes.</para></listitem> - - <listitem><para><envar>PATH</envar> is set to - <filename>/path-not-set</filename> to prevent shells from - initialising it to their built-in default value.</para></listitem> - - <listitem><para><envar>HOME</envar> is set to - <filename>/homeless-shelter</filename> to prevent programs from - using <filename>/etc/passwd</filename> or the like to find the - user's home directory, which could cause impurity. Usually, when - <envar>HOME</envar> is set, it is used as the location of the home - directory, even if it points to a non-existent - path.</para></listitem> - - <listitem><para><envar>NIX_STORE</envar> is set to the path of the - top-level Nix store directory (typically, - <filename>/nix/store</filename>).</para></listitem> - - <listitem><para>For each output declared in - <varname>outputs</varname>, the corresponding environment variable - is set to point to the intended path in the Nix store for that - output. Each output path is a concatenation of the cryptographic - hash of all build inputs, the <varname>name</varname> attribute - and the output name. (The output name is omitted if it’s - <literal>out</literal>.)</para></listitem> - - </itemizedlist> - - </para></listitem> - - <listitem><para>If an output path already exists, it is removed. - Also, locks are acquired to prevent multiple Nix instances from - performing the same build at the same time.</para></listitem> - - <listitem><para>A log of the combined standard output and error is - written to <filename>/nix/var/log/nix</filename>.</para></listitem> - - <listitem><para>The builder is executed with the arguments specified - by the attribute <varname>args</varname>. If it exits with exit - code 0, it is considered to have succeeded.</para></listitem> - - <listitem><para>The temporary directory is removed (unless the - <option>-K</option> option was specified).</para></listitem> - - <listitem><para>If the build was successful, Nix scans each output - path for references to input paths by looking for the hash parts of - the input paths. Since these are potential runtime dependencies, - Nix registers them as dependencies of the output - paths.</para></listitem> - - <listitem><para>After the build, Nix sets the last-modified - timestamp on all files in the build result to 1 (00:00:01 1/1/1970 - UTC), sets the group to the default group, and sets the mode of the - file to 0444 or 0555 (i.e., read-only, with execute permission - enabled if the file was originally executable). Note that possible - <literal>setuid</literal> and <literal>setgid</literal> bits are - cleared. Setuid and setgid programs are not currently supported by - Nix. This is because the Nix archives used in deployment have no - concept of ownership information, and because it makes the build - result dependent on the user performing the build.</para></listitem> - -</itemizedlist> - -</para> - -<xi:include href="advanced-attributes.xml" /> - -</section> diff --git a/doc/manual/expressions/expression-language.xml b/doc/manual/expressions/expression-language.xml deleted file mode 100644 index 240ef80f1..000000000 --- a/doc/manual/expressions/expression-language.xml +++ /dev/null @@ -1,30 +0,0 @@ -<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="ch-expression-language"> - -<title>Nix Expression Language</title> - -<para>The Nix expression language is a pure, lazy, functional -language. Purity means that operations in the language don't have -side-effects (for instance, there is no variable assignment). -Laziness means that arguments to functions are evaluated only when -they are needed. Functional means that functions are -<quote>normal</quote> values that can be passed around and manipulated -in interesting ways. The language is not a full-featured, general -purpose language. Its main job is to describe packages, -compositions of packages, and the variability within -packages.</para> - -<para>This section presents the various features of the -language.</para> - -<xi:include href="language-values.xml" /> -<xi:include href="language-constructs.xml" /> -<xi:include href="language-operators.xml" /> -<xi:include href="derivations.xml" /> -<xi:include href="builtins.xml" /> - - -</chapter> diff --git a/doc/manual/expressions/expression-syntax.xml b/doc/manual/expressions/expression-syntax.xml deleted file mode 100644 index a3de20713..000000000 --- a/doc/manual/expressions/expression-syntax.xml +++ /dev/null @@ -1,148 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='sec-expression-syntax'> - -<title>Expression Syntax</title> - -<example xml:id='ex-hello-nix'><title>Nix expression for GNU Hello -(<filename>default.nix</filename>)</title> -<programlisting> -{ stdenv, fetchurl, perl }: <co xml:id='ex-hello-nix-co-1' /> - -stdenv.mkDerivation { <co xml:id='ex-hello-nix-co-2' /> - name = "hello-2.1.1"; <co xml:id='ex-hello-nix-co-3' /> - builder = ./builder.sh; <co xml:id='ex-hello-nix-co-4' /> - src = fetchurl { <co xml:id='ex-hello-nix-co-5' /> - url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; - sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; - }; - inherit perl; <co xml:id='ex-hello-nix-co-6' /> -}</programlisting> -</example> - -<para><xref linkend='ex-hello-nix' /> shows a Nix expression for GNU -Hello. It's actually already in the Nix Packages collection in -<filename>pkgs/applications/misc/hello/ex-1/default.nix</filename>. -It is customary to place each package in a separate directory and call -the single Nix expression in that directory -<filename>default.nix</filename>. The file has the following elements -(referenced from the figure by number): - -<calloutlist> - - <callout arearefs='ex-hello-nix-co-1'> - - <para>This states that the expression is a - <emphasis>function</emphasis> that expects to be called with three - arguments: <varname>stdenv</varname>, <varname>fetchurl</varname>, - and <varname>perl</varname>. They are needed to build Hello, but - we don't know how to build them here; that's why they are function - arguments. <varname>stdenv</varname> is a package that is used - by almost all Nix Packages packages; it provides a - <quote>standard</quote> environment consisting of the things you - would expect in a basic Unix environment: a C/C++ compiler (GCC, - to be precise), the Bash shell, fundamental Unix tools such as - <command>cp</command>, <command>grep</command>, - <command>tar</command>, etc. <varname>fetchurl</varname> is a - function that downloads files. <varname>perl</varname> is the - Perl interpreter.</para> - - <para>Nix functions generally have the form <literal>{ x, y, ..., - z }: e</literal> where <varname>x</varname>, <varname>y</varname>, - etc. are the names of the expected arguments, and where - <replaceable>e</replaceable> is the body of the function. So - here, the entire remainder of the file is the body of the - function; when given the required arguments, the body should - describe how to build an instance of the Hello package.</para> - - </callout> - - <callout arearefs='ex-hello-nix-co-2'> - - <para>So we have to build a package. Building something from - other stuff is called a <emphasis>derivation</emphasis> in Nix (as - opposed to sources, which are built by humans instead of - computers). We perform a derivation by calling - <varname>stdenv.mkDerivation</varname>. - <varname>mkDerivation</varname> is a function provided by - <varname>stdenv</varname> that builds a package from a set of - <emphasis>attributes</emphasis>. A set is just a list of - key/value pairs where each key is a string and each value is an - arbitrary Nix expression. They take the general form <literal>{ - <replaceable>name1</replaceable> = - <replaceable>expr1</replaceable>; <replaceable>...</replaceable> - <replaceable>nameN</replaceable> = - <replaceable>exprN</replaceable>; }</literal>.</para> - - </callout> - - <callout arearefs='ex-hello-nix-co-3'> - - <para>The attribute <varname>name</varname> specifies the symbolic - name and version of the package. Nix doesn't really care about - these things, but they are used by for instance <command>nix-env - -q</command> to show a <quote>human-readable</quote> name for - packages. This attribute is required by - <varname>mkDerivation</varname>.</para> - - </callout> - - <callout arearefs='ex-hello-nix-co-4'> - - <para>The attribute <varname>builder</varname> specifies the - builder. This attribute can sometimes be omitted, in which case - <varname>mkDerivation</varname> will fill in a default builder - (which does a <literal>configure; make; make install</literal>, in - essence). Hello is sufficiently simple that the default builder - would suffice, but in this case, we will show an actual builder - for educational purposes. The value - <command>./builder.sh</command> refers to the shell script shown - in <xref linkend='ex-hello-builder' />, discussed below.</para> - - </callout> - - <callout arearefs='ex-hello-nix-co-5'> - - <para>The builder has to know what the sources of the package - are. Here, the attribute <varname>src</varname> is bound to the - result of a call to the <command>fetchurl</command> function. - Given a URL and a SHA-256 hash of the expected contents of the file - at that URL, this function builds a derivation that downloads the - file and checks its hash. So the sources are a dependency that - like all other dependencies is built before Hello itself is - built.</para> - - <para>Instead of <varname>src</varname> any other name could have - been used, and in fact there can be any number of sources (bound - to different attributes). However, <varname>src</varname> is - customary, and it's also expected by the default builder (which we - don't use in this example).</para> - - </callout> - - <callout arearefs='ex-hello-nix-co-6'> - - <para>Since the derivation requires Perl, we have to pass the - value of the <varname>perl</varname> function argument to the - builder. All attributes in the set are actually passed as - environment variables to the builder, so declaring an attribute - - <programlisting> -perl = perl;</programlisting> - - will do the trick: it binds an attribute <varname>perl</varname> - to the function argument which also happens to be called - <varname>perl</varname>. However, it looks a bit silly, so there - is a shorter syntax. The <literal>inherit</literal> keyword - causes the specified attributes to be bound to whatever variables - with the same name happen to be in scope.</para> - - </callout> - -</calloutlist> - -</para> - -</section> diff --git a/doc/manual/expressions/generic-builder.xml b/doc/manual/expressions/generic-builder.xml deleted file mode 100644 index db7ff405d..000000000 --- a/doc/manual/expressions/generic-builder.xml +++ /dev/null @@ -1,98 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='sec-generic-builder'> - -<title>Generic Builder Syntax</title> - -<para>Recall from <xref linkend='ex-hello-builder' /> that the builder -looked something like this: - -<programlisting> -PATH=$perl/bin:$PATH -tar xvfz $src -cd hello-* -./configure --prefix=$out -make -make install</programlisting> - -The builders for almost all Unix packages look like this — set up some -environment variables, unpack the sources, configure, build, and -install. For this reason the standard environment provides some Bash -functions that automate the build process. A builder using the -generic build facilities in shown in <xref linkend='ex-hello-builder2' -/>.</para> - -<example xml:id='ex-hello-builder2'><title>Build script using the generic -build functions</title> -<programlisting> -buildInputs="$perl" <co xml:id='ex-hello-builder2-co-1' /> - -source $stdenv/setup <co xml:id='ex-hello-builder2-co-2' /> - -genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting> -</example> - -<calloutlist> - - <callout arearefs='ex-hello-builder2-co-1'> - - <para>The <envar>buildInputs</envar> variable tells - <filename>setup</filename> to use the indicated packages as - <quote>inputs</quote>. This means that if a package provides a - <filename>bin</filename> subdirectory, it's added to - <envar>PATH</envar>; if it has a <filename>include</filename> - subdirectory, it's added to GCC's header search path; and so - on.<footnote><para>How does it work? <filename>setup</filename> - tries to source the file - <filename><replaceable>pkg</replaceable>/nix-support/setup-hook</filename> - of all dependencies. These “setup hooks” can then set up whatever - environment variables they want; for instance, the setup hook for - Perl sets the <envar>PERL5LIB</envar> environment variable to - contain the <filename>lib/site_perl</filename> directories of all - inputs.</para></footnote> - </para> - - </callout> - - <callout arearefs='ex-hello-builder2-co-2'> - - <para>The function <function>genericBuild</function> is defined in - the file <literal>$stdenv/setup</literal>.</para> - - </callout> - - <callout arearefs='ex-hello-builder2-co-3'> - - <para>The final step calls the shell function - <function>genericBuild</function>, which performs the steps that - were done explicitly in <xref linkend='ex-hello-builder' />. The - generic builder is smart enough to figure out whether to unpack - the sources using <command>gzip</command>, - <command>bzip2</command>, etc. It can be customised in many ways; - see the Nixpkgs manual for details.</para> - - </callout> - -</calloutlist> - -<para>Discerning readers will note that the -<envar>buildInputs</envar> could just as well have been set in the Nix -expression, like this: - -<programlisting> - buildInputs = [ perl ];</programlisting> - -The <varname>perl</varname> attribute can then be removed, and the -builder becomes even shorter: - -<programlisting> -source $stdenv/setup -genericBuild</programlisting> - -In fact, <varname>mkDerivation</varname> provides a default builder -that looks exactly like that, so it is actually possible to omit the -builder for Hello entirely.</para> - -</section> diff --git a/doc/manual/expressions/language-constructs.xml b/doc/manual/expressions/language-constructs.xml deleted file mode 100644 index 0d0cbbe15..000000000 --- a/doc/manual/expressions/language-constructs.xml +++ /dev/null @@ -1,409 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-constructs"> - -<title>Language Constructs</title> - -<simplesect><title>Recursive sets</title> - -<para>Recursive sets are just normal sets, but the attributes can -refer to each other. For example, - -<programlisting> -rec { - x = y; - y = 123; -}.x -</programlisting> - -evaluates to <literal>123</literal>. Note that without -<literal>rec</literal> the binding <literal>x = y;</literal> would -refer to the variable <varname>y</varname> in the surrounding scope, -if one exists, and would be invalid if no such variable exists. That -is, in a normal (non-recursive) set, attributes are not added to the -lexical scope; in a recursive set, they are.</para> - -<para>Recursive sets of course introduce the danger of infinite -recursion. For example, - -<programlisting> -rec { - x = y; - y = x; -}.x</programlisting> - -does not terminate<footnote><para>Actually, Nix detects infinite -recursion in this case and aborts (<quote>infinite recursion -encountered</quote>).</para></footnote>.</para> - -</simplesect> - - -<simplesect xml:id="sect-let-expressions"><title>Let-expressions</title> - -<para>A let-expression allows you to define local variables for an -expression. For instance, - -<programlisting> -let - x = "foo"; - y = "bar"; -in x + y</programlisting> - -evaluates to <literal>"foobar"</literal>. - -</para> - -</simplesect> - - -<simplesect><title>Inheriting attributes</title> - -<para>When defining a set or in a let-expression it is often convenient to copy variables -from the surrounding lexical scope (e.g., when you want to propagate -attributes). This can be shortened using the -<literal>inherit</literal> keyword. For instance, - -<programlisting> -let x = 123; in -{ inherit x; - y = 456; -}</programlisting> - -is equivalent to - -<programlisting> -let x = 123; in -{ x = x; - y = 456; -}</programlisting> - -and both evaluate to <literal>{ x = 123; y = 456; }</literal>. (Note that -this works because <varname>x</varname> is added to the lexical scope -by the <literal>let</literal> construct.) It is also possible to -inherit attributes from another set. For instance, in this fragment -from <filename>all-packages.nix</filename>, - -<programlisting> - graphviz = (import ../tools/graphics/graphviz) { - inherit fetchurl stdenv libpng libjpeg expat x11 yacc; - inherit (xlibs) libXaw; - }; - - xlibs = { - libX11 = ...; - libXaw = ...; - ... - } - - libpng = ...; - libjpg = ...; - ...</programlisting> - -the set used in the function call to the function defined in -<filename>../tools/graphics/graphviz</filename> inherits a number of -variables from the surrounding scope (<varname>fetchurl</varname> -... <varname>yacc</varname>), but also inherits -<varname>libXaw</varname> (the X Athena Widgets) from the -<varname>xlibs</varname> (X11 client-side libraries) set.</para> - -<para> -Summarizing the fragment - -<programlisting> -... -inherit x y z; -inherit (src-set) a b c; -...</programlisting> - -is equivalent to - -<programlisting> -... -x = x; y = y; z = z; -a = src-set.a; b = src-set.b; c = src-set.c; -...</programlisting> - -when used while defining local variables in a let-expression or -while defining a set.</para> - -</simplesect> - - -<simplesect xml:id="ss-functions"><title>Functions</title> - -<para>Functions have the following form: - -<programlisting> -<replaceable>pattern</replaceable>: <replaceable>body</replaceable></programlisting> - -The pattern specifies what the argument of the function must look -like, and binds variables in the body to (parts of) the -argument. There are three kinds of patterns:</para> - -<itemizedlist> - - - <listitem><para>If a pattern is a single identifier, then the - function matches any argument. Example: - - <programlisting> -let negate = x: !x; - concat = x: y: x + y; -in if negate true then concat "foo" "bar" else ""</programlisting> - - Note that <function>concat</function> is a function that takes one - argument and returns a function that takes another argument. This - allows partial parameterisation (i.e., only filling some of the - arguments of a function); e.g., - - <programlisting> -map (concat "foo") [ "bar" "bla" "abc" ]</programlisting> - - evaluates to <literal>[ "foobar" "foobla" - "fooabc" ]</literal>.</para></listitem> - - - <listitem><para>A <emphasis>set pattern</emphasis> of the form - <literal>{ name1, name2, …, nameN }</literal> matches a set - containing the listed attributes, and binds the values of those - attributes to variables in the function body. For example, the - function - -<programlisting> -{ x, y, z }: z + y + x</programlisting> - - can only be called with a set containing exactly the attributes - <varname>x</varname>, <varname>y</varname> and - <varname>z</varname>. No other attributes are allowed. If you want - to allow additional arguments, you can use an ellipsis - (<literal>...</literal>): - -<programlisting> -{ x, y, z, ... }: z + y + x</programlisting> - - This works on any set that contains at least the three named - attributes.</para> - - <para>It is possible to provide <emphasis>default values</emphasis> - for attributes, in which case they are allowed to be missing. A - default value is specified by writing - <literal><replaceable>name</replaceable> ? - <replaceable>e</replaceable></literal>, where - <replaceable>e</replaceable> is an arbitrary expression. For example, - -<programlisting> -{ x, y ? "foo", z ? "bar" }: z + y + x</programlisting> - - specifies a function that only requires an attribute named - <varname>x</varname>, but optionally accepts <varname>y</varname> - and <varname>z</varname>.</para></listitem> - - - <listitem><para>An <literal>@</literal>-pattern provides a means of referring - to the whole value being matched: - -<programlisting> args@{ x, y, z, ... }: z + y + x + args.a</programlisting> - -but can also be written as: - -<programlisting> { x, y, z, ... } @ args: z + y + x + args.a</programlisting> - - Here <varname>args</varname> is bound to the entire argument, which - is further matched against the pattern <literal>{ x, y, z, - ... }</literal>. <literal>@</literal>-pattern makes mainly sense with an - 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> - - <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> - -<para>Note that functions do not have names. If you want to give them -a name, you can bind them to an attribute, e.g., - -<programlisting> -let concat = { x, y }: x + y; -in concat { x = "foo"; y = "bar"; }</programlisting> - -</para> - -</simplesect> - - -<simplesect><title>Conditionals</title> - -<para>Conditionals look like this: - -<programlisting> -if <replaceable>e1</replaceable> then <replaceable>e2</replaceable> else <replaceable>e3</replaceable></programlisting> - -where <replaceable>e1</replaceable> is an expression that should -evaluate to a Boolean value (<literal>true</literal> or -<literal>false</literal>).</para> - -</simplesect> - - -<simplesect><title>Assertions</title> - -<para>Assertions are generally used to check that certain requirements -on or between features and dependencies hold. They look like this: - -<programlisting> -assert <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting> - -where <replaceable>e1</replaceable> is an expression that should -evaluate to a Boolean value. If it evaluates to -<literal>true</literal>, <replaceable>e2</replaceable> is returned; -otherwise expression evaluation is aborted and a backtrace is printed.</para> - -<example xml:id='ex-subversion-nix'><title>Nix expression for Subversion</title> -<programlisting> -{ localServer ? false -, httpServer ? false -, sslSupport ? false -, pythonBindings ? false -, javaSwigBindings ? false -, javahlBindings ? false -, stdenv, fetchurl -, openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null -}: - -assert localServer -> db4 != null; <co xml:id='ex-subversion-nix-co-1' /> -assert httpServer -> httpd != null && httpd.expat == expat; <co xml:id='ex-subversion-nix-co-2' /> -assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); <co xml:id='ex-subversion-nix-co-3' /> -assert pythonBindings -> swig != null && swig.pythonSupport; -assert javaSwigBindings -> swig != null && swig.javaSupport; -assert javahlBindings -> j2sdk != null; - -stdenv.mkDerivation { - name = "subversion-1.1.1"; - ... - openssl = if sslSupport then openssl else null; <co xml:id='ex-subversion-nix-co-4' /> - ... -}</programlisting> -</example> - -<para><xref linkend='ex-subversion-nix' /> show how assertions are -used in the Nix expression for Subversion.</para> - -<calloutlist> - - <callout arearefs='ex-subversion-nix-co-1'> - <para>This assertion states that if Subversion is to have support - for local repositories, then Berkeley DB is needed. So if the - Subversion function is called with the - <varname>localServer</varname> argument set to - <literal>true</literal> but the <varname>db4</varname> argument - set to <literal>null</literal>, then the evaluation fails.</para> - </callout> - - <callout arearefs='ex-subversion-nix-co-2'> - <para>This is a more subtle condition: if Subversion is built with - Apache (<literal>httpServer</literal>) support, then the Expat - library (an XML library) used by Subversion should be same as the - one used by Apache. This is because in this configuration - Subversion code ends up being linked with Apache code, and if the - Expat libraries do not match, a build- or runtime link error or - incompatibility might occur.</para> - </callout> - - <callout arearefs='ex-subversion-nix-co-3'> - <para>This assertion says that in order for Subversion to have SSL - support (so that it can access <literal>https</literal> URLs), an - OpenSSL library must be passed. Additionally, it says that - <emphasis>if</emphasis> Apache support is enabled, then Apache's - OpenSSL should match Subversion's. (Note that if Apache support - is not enabled, we don't care about Apache's OpenSSL.)</para> - </callout> - - <callout arearefs='ex-subversion-nix-co-4'> - <para>The conditional here is not really related to assertions, - but is worth pointing out: it ensures that if SSL support is - disabled, then the Subversion derivation is not dependent on - OpenSSL, even if a non-<literal>null</literal> value was passed. - This prevents an unnecessary rebuild of Subversion if OpenSSL - changes.</para> - </callout> - -</calloutlist> - -</simplesect> - - - -<simplesect><title>With-expressions</title> - -<para>A <emphasis>with-expression</emphasis>, - -<programlisting> -with <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting> - -introduces the set <replaceable>e1</replaceable> into the lexical -scope of the expression <replaceable>e2</replaceable>. For instance, - -<programlisting> -let as = { x = "foo"; y = "bar"; }; -in with as; x + y</programlisting> - -evaluates to <literal>"foobar"</literal> since the -<literal>with</literal> adds the <varname>x</varname> and -<varname>y</varname> attributes of <varname>as</varname> to the -lexical scope in the expression <literal>x + y</literal>. The most -common use of <literal>with</literal> is in conjunction with the -<function>import</function> function. E.g., - -<programlisting> -with (import ./definitions.nix); ...</programlisting> - -makes all attributes defined in the file -<filename>definitions.nix</filename> available as if they were defined -locally in a <literal>let</literal>-expression.</para> - -<para>The bindings introduced by <literal>with</literal> do not shadow bindings -introduced by other means, e.g. - -<programlisting> -let a = 3; in with { a = 1; }; let a = 4; in with { a = 2; }; ...</programlisting> - -establishes the same scope as - -<programlisting> -let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...</programlisting> - -</para> - -</simplesect> - - -<simplesect><title>Comments</title> - -<para>Comments can be single-line, started with a <literal>#</literal> -character, or inline/multi-line, enclosed within <literal>/* -... */</literal>.</para> - -</simplesect> - - -</section> diff --git a/doc/manual/expressions/language-operators.xml b/doc/manual/expressions/language-operators.xml deleted file mode 100644 index 4f11bf529..000000000 --- a/doc/manual/expressions/language-operators.xml +++ /dev/null @@ -1,222 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-language-operators"> - -<title>Operators</title> - -<para><xref linkend='table-operators' /> lists the operators in the -Nix expression language, in order of precedence (from strongest to -weakest binding).</para> - -<table xml:id='table-operators'> - <title>Operators</title> - <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> ] - </entry> - <entry>none</entry> - <entry>Select attribute denoted by the attribute path - <replaceable>attrpath</replaceable> from set - <replaceable>e</replaceable>. (An attribute path is a - 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> - <entry>Test whether set <replaceable>e</replaceable> contains - 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 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> - </entry> - <entry>left</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> - <entry>Return a set consisting of the attributes in - <replaceable>e1</replaceable> and - <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><</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><=</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>></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>>=</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> - </entry> - <entry>none</entry> - <entry>Inequality.</entry> - <entry>11</entry> - </row> - <row> - <entry>Logical AND</entry> - <entry><replaceable>e1</replaceable> <literal>&&</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> diff --git a/doc/manual/expressions/language-values.xml b/doc/manual/expressions/language-values.xml deleted file mode 100644 index bb2090c88..000000000 --- a/doc/manual/expressions/language-values.xml +++ /dev/null @@ -1,313 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='ssec-values'> - -<title>Values</title> - - -<simplesect><title>Simple Values</title> - -<para>Nix has the following basic data types: - -<itemizedlist> - - <listitem> - - <para><emphasis>Strings</emphasis> can be written in three - ways.</para> - - <para>The most common way is to enclose the string between double - quotes, e.g., <literal>"foo bar"</literal>. Strings can span - multiple lines. The special characters <literal>"</literal> and - <literal>\</literal> and the character sequence - <literal>${</literal> must be escaped by prefixing them with a - backslash (<literal>\</literal>). Newlines, carriage returns and - tabs can be written as <literal>\n</literal>, - <literal>\r</literal> and <literal>\t</literal>, - respectively.</para> - - <para>You can include the result of an expression into a string by - enclosing it in - <literal>${<replaceable>...</replaceable>}</literal>, a feature - known as <emphasis>antiquotation</emphasis>. The enclosed - expression must evaluate to something that can be coerced into a - string (meaning that it must be a string, a path, or a - derivation). For instance, rather than writing - -<programlisting> -"--with-freetype2-library=" + freetype + "/lib"</programlisting> - - (where <varname>freetype</varname> is a derivation), you can - instead write the more natural - -<programlisting> -"--with-freetype2-library=${freetype}/lib"</programlisting> - - The latter is automatically translated to the former. A more - complicated example (from the Nix expression for <link - xlink:href='http://www.trolltech.com/products/qt'>Qt</link>): - -<programlisting> -configureFlags = " - -system-zlib -system-libpng -system-libjpeg - ${if openglSupport then "-dlopen-opengl - -L${mesa}/lib -I${mesa}/include - -L${libXmu}/lib -I${libXmu}/include" else ""} - ${if threadSupport then "-thread" else "-no-thread"} -";</programlisting> - - Note that Nix expressions and strings can be arbitrarily nested; - in this case the outer string contains various antiquotations that - themselves contain strings (e.g., <literal>"-thread"</literal>), - some of which in turn contain expressions (e.g., - <literal>${mesa}</literal>).</para> - - <para>The second way to write string literals is as an - <emphasis>indented string</emphasis>, which is enclosed between - pairs of <emphasis>double single-quotes</emphasis>, like so: - -<programlisting> -'' - This is the first line. - This is the second line. - This is the third line. -''</programlisting> - - This kind of string literal intelligently strips indentation from - the start of each line. To be precise, it strips from each line a - number of spaces equal to the minimal indentation of the string as - a whole (disregarding the indentation of empty lines). For - instance, the first and second line are indented two space, while - the third line is indented four spaces. Thus, two spaces are - stripped from each line, so the resulting string is - -<programlisting> -"This is the first line.\nThis is the second line.\n This is the third line.\n"</programlisting> - - </para> - - <para>Note that the whitespace and newline following the opening - <literal>''</literal> is ignored if there is no non-whitespace - text on the initial line.</para> - - <para>Antiquotation - (<literal>${<replaceable>expr</replaceable>}</literal>) is - supported in indented strings.</para> - - <para>Since <literal>${</literal> and <literal>''</literal> have - special meaning in indented strings, you need a way to quote them. - <literal>$</literal> can be escaped by prefixing it with - <literal>''</literal> (that is, two single quotes), i.e., - <literal>''$</literal>. <literal>''</literal> can be escaped by - prefixing it with <literal>'</literal>, i.e., - <literal>'''</literal>. <literal>$</literal> removes any special meaning - from the following <literal>$</literal>. Linefeed, carriage-return and tab - characters can be written as <literal>''\n</literal>, - <literal>''\r</literal>, <literal>''\t</literal>, and <literal>''\</literal> - escapes any other character. - - </para> - - <para>Indented strings are primarily useful in that they allow - multi-line string literals to follow the indentation of the - enclosing Nix expression, and that less escaping is typically - necessary for strings representing languages such as shell scripts - and configuration files because <literal>''</literal> is much less - common than <literal>"</literal>. Example: - -<programlisting> -stdenv.mkDerivation { - <replaceable>...</replaceable> - postInstall = - '' - mkdir $out/bin $out/etc - cp foo $out/bin - echo "Hello World" > $out/etc/foo.conf - ${if enableBar then "cp bar $out/bin" else ""} - ''; - <replaceable>...</replaceable> -} -</programlisting> - - </para> - - <para>Finally, as a convenience, <emphasis>URIs</emphasis> as - defined in appendix B of <link - xlink:href='http://www.ietf.org/rfc/rfc2396.txt'>RFC 2396</link> - can be written <emphasis>as is</emphasis>, without quotes. For - instance, the string - <literal>"http://example.org/foo.tar.bz2"</literal> - can also be written as - <literal>http://example.org/foo.tar.bz2</literal>.</para> - - </listitem> - - <listitem><para>Numbers, which can be <emphasis>integers</emphasis> (like - <literal>123</literal>) or <emphasis>floating point</emphasis> (like - <literal>123.43</literal> or <literal>.27e13</literal>).</para> - - <para>Numbers are type-compatible: pure integer operations will always - return integers, whereas any operation involving at least one floating point - number will have a floating point number as a result.</para></listitem> - - <listitem><para><emphasis>Paths</emphasis>, e.g., - <filename>/bin/sh</filename> or <filename>./builder.sh</filename>. - A path must contain at least one slash to be recognised as such; for - instance, <filename>builder.sh</filename> is not a - path<footnote><para>It's parsed as an expression that selects the - attribute <varname>sh</varname> from the variable - <varname>builder</varname>.</para></footnote>. If the file name is - relative, i.e., if it does not begin with a slash, it is made - absolute at parse time relative to the directory of the Nix - expression that contained it. For instance, if a Nix expression in - <filename>/foo/bar/bla.nix</filename> refers to - <filename>../xyzzy/fnord.nix</filename>, the absolute path is - <filename>/foo/xyzzy/fnord.nix</filename>.</para> - - <para>If the first component of a path is a <literal>~</literal>, - it is interpreted as if the rest of the path were relative to the - user's home directory. e.g. <filename>~/foo</filename> would be - equivalent to <filename>/home/edolstra/foo</filename> for a user - whose home directory is <filename>/home/edolstra</filename>. - </para> - - <para>Paths can also be specified between angle brackets, e.g. - <literal><nixpkgs></literal>. This means that the directories - listed in the environment variable - <envar linkend="env-NIX_PATH">NIX_PATH</envar> will be searched - for the given file or directory name. - </para> - - </listitem> - - <listitem><para><emphasis>Booleans</emphasis> with values - <literal>true</literal> and - <literal>false</literal>.</para></listitem> - - <listitem><para>The null value, denoted as - <literal>null</literal>.</para></listitem> - -</itemizedlist> - -</para> - -</simplesect> - - -<simplesect><title>Lists</title> - -<para>Lists are formed by enclosing a whitespace-separated list of -values between square brackets. For example, - -<programlisting> -[ 123 ./foo.nix "abc" (f { x = y; }) ]</programlisting> - -defines a list of four elements, the last being the result of a call -to the function <varname>f</varname>. Note that function calls have -to be enclosed in parentheses. If they had been omitted, e.g., - -<programlisting> -[ 123 ./foo.nix "abc" f { x = y; } ]</programlisting> - -the result would be a list of five elements, the fourth one being a -function and the fifth being a set.</para> - -<para>Note that lists are only lazy in values, and they are strict in length. -</para> - -</simplesect> - - -<simplesect><title>Sets</title> - -<para>Sets are really the core of the language, since ultimately the -Nix language is all about creating derivations, which are really just -sets of attributes to be passed to build scripts.</para> - -<para>Sets are just a list of name/value pairs (called -<emphasis>attributes</emphasis>) enclosed in curly brackets, where -each value is an arbitrary expression terminated by a semicolon. For -example: - -<programlisting> -{ x = 123; - text = "Hello"; - y = f { bla = 456; }; -}</programlisting> - -This defines a set with attributes named <varname>x</varname>, -<varname>text</varname>, <varname>y</varname>. The order of the -attributes is irrelevant. An attribute name may only occur -once.</para> - -<para>Attributes can be selected from a set using the -<literal>.</literal> operator. For instance, - -<programlisting> -{ a = "Foo"; b = "Bar"; }.a</programlisting> - -evaluates to <literal>"Foo"</literal>. It is possible to provide a -default value in an attribute selection using the -<literal>or</literal> keyword. For example, - -<programlisting> -{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"</programlisting> - -will evaluate to <literal>"Xyzzy"</literal> because there is no -<varname>c</varname> attribute in the set.</para> - -<para>You can use arbitrary double-quoted strings as attribute -names: - -<programlisting> -{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}" -</programlisting> - -This will evaluate to <literal>123</literal> (Assuming -<literal>bar</literal> is antiquotable). In the case where an -attribute name is just a single antiquotation, the quotes can be -dropped: - -<programlisting> -{ foo = 123; }.${bar} or 456 </programlisting> - -This will evaluate to <literal>123</literal> if -<literal>bar</literal> evaluates to <literal>"foo"</literal> when -coerced to a string and <literal>456</literal> otherwise (again -assuming <literal>bar</literal> is antiquotable).</para> - -<para>In the special case where an attribute name inside of a set declaration -evaluates to <literal>null</literal> (which is normally an error, as -<literal>null</literal> is not antiquotable), that attribute is simply not -added to the set: - -<programlisting> -{ ${if foo then "bar" else null} = true; }</programlisting> - -This will evaluate to <literal>{}</literal> if <literal>foo</literal> -evaluates to <literal>false</literal>.</para> - -<para>A set that has a <literal>__functor</literal> attribute whose value -is callable (i.e. is itself a function or a set with a -<literal>__functor</literal> attribute whose value is callable) can be -applied as if it were a function, with the set itself passed in first -, e.g., - -<programlisting> -let add = { __functor = self: x: x + self.x; }; - inc = add // { x = 1; }; -in inc 1 -</programlisting> - -evaluates to <literal>2</literal>. This can be used to attach metadata to a -function without the caller needing to treat it specially, or to implement -a form of object-oriented programming, for example. - -</para> - -</simplesect> - - -</section> diff --git a/doc/manual/expressions/simple-building-testing.xml b/doc/manual/expressions/simple-building-testing.xml deleted file mode 100644 index ce0a1636d..000000000 --- a/doc/manual/expressions/simple-building-testing.xml +++ /dev/null @@ -1,76 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='sec-building-simple'> - -<title>Building and Testing</title> - -<para>You can now try to build Hello. Of course, you could do -<literal>nix-env -i hello</literal>, but you may not want to install a -possibly broken package just yet. The best way to test the package is by -using the command <command linkend="sec-nix-build">nix-build</command>, -which builds a Nix expression and creates a symlink named -<filename>result</filename> in the current directory: - -<screen> -$ nix-build -A hello -building path `/nix/store/632d2b22514d...-hello-2.1.1' -hello-2.1.1/ -hello-2.1.1/intl/ -hello-2.1.1/intl/ChangeLog -<replaceable>...</replaceable> - -$ ls -l result -lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1 - -$ ./result/bin/hello -Hello, world!</screen> - -The <link linkend='opt-attr'><option>-A</option></link> option selects -the <literal>hello</literal> attribute. This is faster than using the -symbolic package name specified by the <literal>name</literal> -attribute (which also happens to be <literal>hello</literal>) and is -unambiguous (there can be multiple packages with the symbolic name -<literal>hello</literal>, but there can be only one attribute in a set -named <literal>hello</literal>).</para> - -<para><command>nix-build</command> registers the -<filename>./result</filename> symlink as a garbage collection root, so -unless and until you delete the <filename>./result</filename> symlink, -the output of the build will be safely kept on your system. You can -use <command>nix-build</command>’s <option -linkend='opt-out-link'>-o</option> switch to give the symlink another -name.</para> - -<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 -will see that the path is already valid and finish immediately. If a -build fails, either because it returns a non-zero exit code, because -Nix or the builder are killed, or because the machine crashes, then -the output paths will not be registered as valid. If you try to build -the derivation again, Nix will remove the output paths if they exist -(e.g., because the builder died half-way through <literal>make -install</literal>) and try again. Note that there is no -<quote>negative caching</quote>: Nix doesn't remember that a build -failed, and so a failed build can always be repeated. This is because -Nix cannot distinguish between permanent failures (e.g., a compiler -error due to a syntax error in the source) and transient failures -(e.g., a disk full condition).</para> - -<para>Nix also performs locking. If you run multiple Nix builds -simultaneously, and they try to build the same derivation, the first -Nix instance that gets there will perform the build, while the others -block (or perform other derivations if available) until the build -finishes: - -<screen> -$ nix-build -A hello -waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x'</screen> - -So it is always safe to run multiple instances of Nix in parallel -(which isn’t the case with, say, <command>make</command>).</para> - -</section> diff --git a/doc/manual/expressions/simple-expression.xml b/doc/manual/expressions/simple-expression.xml deleted file mode 100644 index 29fd872ee..000000000 --- a/doc/manual/expressions/simple-expression.xml +++ /dev/null @@ -1,47 +0,0 @@ -<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="ch-simple-expression"> - -<title>A Simple Nix Expression</title> - -<para>This section shows how to add and test the <link -xlink:href='http://www.gnu.org/software/hello/hello.html'>GNU Hello -package</link> to the Nix Packages collection. Hello is a program -that prints out the text <quote>Hello, world!</quote>.</para> - -<para>To add a package to the Nix Packages collection, you generally -need to do three things: - -<orderedlist> - - <listitem><para>Write a Nix expression for the package. This is a - file that describes all the inputs involved in building the package, - such as dependencies, sources, and so on.</para></listitem> - - <listitem><para>Write a <emphasis>builder</emphasis>. This is a - shell script<footnote><para>In fact, it can be written in any - language, but typically it's a <command>bash</command> shell - script.</para></footnote> that actually builds the package from - the inputs.</para></listitem> - - <listitem><para>Add the package to the file - <filename>pkgs/top-level/all-packages.nix</filename>. The Nix - expression written in the first step is a - <emphasis>function</emphasis>; it requires other packages in order - to build it. In this step you put it all together, i.e., you call - the function with the right arguments to build the actual - package.</para></listitem> - -</orderedlist> - -</para> - -<xi:include href="expression-syntax.xml" /> -<xi:include href="build-script.xml" /> -<xi:include href="arguments-variables.xml" /> -<xi:include href="simple-building-testing.xml" /> -<xi:include href="generic-builder.xml" /> - -</chapter> diff --git a/doc/manual/expressions/writing-nix-expressions.xml b/doc/manual/expressions/writing-nix-expressions.xml deleted file mode 100644 index 6646dddf0..000000000 --- a/doc/manual/expressions/writing-nix-expressions.xml +++ /dev/null @@ -1,26 +0,0 @@ -<part 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-writing-nix-expressions'> - -<title>Writing Nix Expressions</title> - -<partintro> -<para>This chapter shows you how to write Nix expressions, which -instruct Nix how to build packages. It starts with a -simple example (a Nix expression for GNU Hello), and then moves -on to a more in-depth look at the Nix expression language.</para> - -<note><para>This chapter is mostly about the Nix expression language. -For more extensive information on adding packages to the Nix Packages -collection (such as functions in the standard environment and coding -conventions), please consult <link -xlink:href="http://nixos.org/nixpkgs/manual/">its -manual</link>.</para></note> -</partintro> - -<xi:include href="simple-expression.xml" /> -<xi:include href="expression-language.xml" /> - -</part> diff --git a/doc/manual/glossary/glossary.xml b/doc/manual/glossary/glossary.xml deleted file mode 100644 index e3162ed8d..000000000 --- a/doc/manual/glossary/glossary.xml +++ /dev/null @@ -1,199 +0,0 @@ -<appendix xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xml:id="part-glossary"> - -<title>Glossary</title> - - -<glosslist> - - -<glossentry xml:id="gloss-derivation"><glossterm>derivation</glossterm> - - <glossdef><para>A description of a build action. The result of a - derivation is a store object. Derivations are typically specified - in Nix expressions using the <link - linkend="ssec-derivation"><function>derivation</function> - primitive</link>. These are translated into low-level - <emphasis>store derivations</emphasis> (implicitly by - <command>nix-env</command> and <command>nix-build</command>, or - explicitly by <command>nix-instantiate</command>).</para></glossdef> - -</glossentry> - - -<glossentry><glossterm>store</glossterm> - - <glossdef><para>The location in the file system where store objects - live. Typically <filename>/nix/store</filename>.</para></glossdef> - -</glossentry> - - -<glossentry><glossterm>store path</glossterm> - - <glossdef><para>The location in the file system of a store object, - i.e., an immediate child of the Nix store - directory.</para></glossdef> - -</glossentry> - - -<glossentry><glossterm>store object</glossterm> - - <glossdef><para>A file that is an immediate child of the Nix store - directory. These can be regular files, but also entire directory - trees. Store objects can be sources (objects copied from outside of - the store), derivation outputs (objects produced by running a build - action), or derivations (files describing a build - action).</para></glossdef> - -</glossentry> - - -<glossentry xml:id="gloss-substitute"><glossterm>substitute</glossterm> - - <glossdef><para>A substitute is a command invocation stored in the - Nix database that describes how to build a store object, bypassing - the normal build mechanism (i.e., derivations). Typically, the - substitute builds the store object by downloading a pre-built - version of the store object from some server.</para></glossdef> - -</glossentry> - - -<glossentry><glossterm>purity</glossterm> - - <glossdef><para>The assumption that equal Nix derivations when run - always produce the same output. This cannot be guaranteed in - general (e.g., a builder can rely on external inputs such as the - network or the system time) but the Nix model assumes - it.</para></glossdef> - -</glossentry> - - -<glossentry><glossterm>Nix expression</glossterm> - - <glossdef><para>A high-level description of software packages and - compositions thereof. Deploying software using Nix entails writing - Nix expressions for your packages. Nix expressions are translated - to derivations that are stored in the Nix store. These derivations - can then be built.</para></glossdef> - -</glossentry> - - -<glossentry xml:id="gloss-reference"><glossterm>reference</glossterm> - - <glossdef> - <para>A store path <varname>P</varname> is said to have a - reference to a store path <varname>Q</varname> if the store object - at <varname>P</varname> contains the path <varname>Q</varname> - somewhere. The <emphasis>references</emphasis> of a store path are - the set of store paths to which it has a reference. - </para> - <para>A derivation can reference other derivations and sources - (but not output paths), whereas an output path only references other - output paths. - </para> - </glossdef> - -</glossentry> - -<glossentry xml:id="gloss-reachable"><glossterm>reachable</glossterm> - - <glossdef><para>A store path <varname>Q</varname> is reachable from - another store path <varname>P</varname> if <varname>Q</varname> is in the - <link linkend="gloss-closure">closure</link> of the - <link linkend="gloss-reference">references</link> relation. - </para></glossdef> -</glossentry> - -<glossentry xml:id="gloss-closure"><glossterm>closure</glossterm> - - <glossdef><para>The closure of a store path is the set of store - paths that are directly or indirectly “reachable” from that store - path; that is, it’s the closure of the path under the <link - linkend="gloss-reference">references</link> relation. For a package, the - closure of its derivation is equivalent to the build-time - dependencies, while the closure of its output path is equivalent to its - runtime dependencies. For correct deployment it is necessary to deploy whole - closures, since otherwise at runtime files could be missing. The command - <command>nix-store -qR</command> prints out closures of store paths. - </para> - <para>As an example, if the store object at path <varname>P</varname> contains - a reference to path <varname>Q</varname>, then <varname>Q</varname> is - in the closure of <varname>P</varname>. Further, if <varname>Q</varname> - references <varname>R</varname> then <varname>R</varname> is also in - the closure of <varname>P</varname>. - </para></glossdef> - -</glossentry> - - -<glossentry xml:id="gloss-output-path"><glossterm>output path</glossterm> - - <glossdef><para>A store path produced by a derivation.</para></glossdef> - -</glossentry> - - -<glossentry xml:id="gloss-deriver"><glossterm>deriver</glossterm> - - <glossdef><para>The deriver of an <link - linkend="gloss-output-path">output path</link> is the store - derivation that built it.</para></glossdef> - -</glossentry> - - -<glossentry xml:id="gloss-validity"><glossterm>validity</glossterm> - - <glossdef><para>A store path is considered - <emphasis>valid</emphasis> if it exists in the file system, is - listed in the Nix database as being valid, and if all paths in its - closure are also valid.</para></glossdef> - -</glossentry> - - -<glossentry xml:id="gloss-user-env"><glossterm>user environment</glossterm> - - <glossdef><para>An automatically generated store object that - consists of a set of symlinks to “active” applications, i.e., other - store paths. These are generated automatically by <link - linkend="sec-nix-env"><command>nix-env</command></link>. See <xref - linkend="sec-profiles" />.</para> - - </glossdef> - -</glossentry> - - -<glossentry xml:id="gloss-profile"><glossterm>profile</glossterm> - - <glossdef><para>A symlink to the current <link - linkend="gloss-user-env">user environment</link> of a user, e.g., - <filename>/nix/var/nix/profiles/default</filename>.</para></glossdef> - -</glossentry> - - -<glossentry xml:id="gloss-nar"><glossterm>NAR</glossterm> - - <glossdef><para>A <emphasis>N</emphasis>ix - <emphasis>AR</emphasis>chive. This is a serialisation of a path in - the Nix store. It can contain regular files, directories and - symbolic links. NARs are generated and unpacked using - <command>nix-store --dump</command> and <command>nix-store - --restore</command>.</para></glossdef> - -</glossentry> - - - -</glosslist> - - -</appendix> diff --git a/doc/manual/hacking.xml b/doc/manual/hacking.xml deleted file mode 100644 index d25d4b84a..000000000 --- a/doc/manual/hacking.xml +++ /dev/null @@ -1,74 +0,0 @@ -<appendix xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xml:id="chap-hacking"> - -<title>Hacking</title> - -<para>This section provides some notes on how to hack on Nix. To get -the latest version of Nix from GitHub: -<screen> -$ git clone https://github.com/NixOS/nix.git -$ cd nix -</screen> -</para> - -<para>To build Nix for the current operating system/architecture use - -<screen> -$ nix-build -</screen> - -or if you have a flakes-enabled nix: - -<screen> -$ nix build -</screen> - -This will build <literal>defaultPackage</literal> attribute defined in the <literal>flake.nix</literal> file. - -To build for other platforms add one of the following suffixes to it: aarch64-linux, -i686-linux, x86_64-darwin, x86_64-linux. - -i.e. - -<screen> -nix-build -A defaultPackage.x86_64-linux -</screen> - -</para> - -<para>To build all dependencies and start a shell in which all -environment variables are set up so that those dependencies can be -found: -<screen> -$ nix-shell -</screen> -To build Nix itself in this shell: -<screen> -[nix-shell]$ ./bootstrap.sh -[nix-shell]$ ./configure $configureFlags -[nix-shell]$ make -j $NIX_BUILD_CORES -</screen> -To install it in <literal>$(pwd)/inst</literal> and test it: -<screen> -[nix-shell]$ make install -[nix-shell]$ make installcheck -[nix-shell]$ ./inst/bin/nix --version -nix (Nix) 2.4 -</screen> - -If you have a flakes-enabled nix you can replace: - -<screen> -$ nix-shell -</screen> - -by: - -<screen> -$ nix develop -</screen> - -</para> - -</appendix> diff --git a/doc/manual/installation/building-source.xml b/doc/manual/installation/building-source.xml deleted file mode 100644 index 772cda9cc..000000000 --- a/doc/manual/installation/building-source.xml +++ /dev/null @@ -1,49 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-building-source"> - -<title>Building Nix from Source</title> - -<para>After unpacking or checking out the Nix sources, issue the -following commands: - -<screen> -$ ./configure <replaceable>options...</replaceable> -$ make -$ make install</screen> - -Nix requires GNU Make so you may need to invoke -<command>gmake</command> instead.</para> - -<para>When building from the Git repository, these should be preceded -by the command: - -<screen> -$ ./bootstrap.sh</screen> - -</para> - -<para>The installation path can be specified by passing the -<option>--prefix=<replaceable>prefix</replaceable></option> to -<command>configure</command>. The default installation directory is -<filename>/usr/local</filename>. You can change this to any location -you like. You must have write permission to the -<replaceable>prefix</replaceable> path.</para> - -<para>Nix keeps its <emphasis>store</emphasis> (the place where -packages are stored) in <filename>/nix/store</filename> by default. -This can be changed using -<option>--with-store-dir=<replaceable>path</replaceable></option>.</para> - -<warning><para>It is best <emphasis>not</emphasis> to change the Nix -store from its default, since doing so makes it impossible to use -pre-built binaries from the standard Nixpkgs channels — that is, all -packages will need to be built from source.</para></warning> - -<para>Nix keeps state (such as its database and log files) in -<filename>/nix/var</filename> by default. This can be changed using -<option>--localstatedir=<replaceable>path</replaceable></option>.</para> - -</section> diff --git a/doc/manual/installation/env-variables.xml b/doc/manual/installation/env-variables.xml deleted file mode 100644 index cc52f5b4a..000000000 --- a/doc/manual/installation/env-variables.xml +++ /dev/null @@ -1,89 +0,0 @@ -<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="ch-env-variables"> - -<title>Environment Variables</title> - -<para>To use Nix, some environment variables should be set. In -particular, <envar>PATH</envar> should contain the directories -<filename><replaceable>prefix</replaceable>/bin</filename> and -<filename>~/.nix-profile/bin</filename>. The first directory contains -the Nix tools themselves, while <filename>~/.nix-profile</filename> is -a symbolic link to the current <emphasis>user environment</emphasis> -(an automatically generated package consisting of symlinks to -installed packages). The simplest way to set the required environment -variables is to include the file -<filename><replaceable>prefix</replaceable>/etc/profile.d/nix.sh</filename> -in your <filename>~/.profile</filename> (or similar), like this:</para> - -<screen> -source <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen> - -<section xml:id="sec-nix-ssl-cert-file"> - -<title><envar>NIX_SSL_CERT_FILE</envar></title> - -<para>If you need to specify a custom certificate bundle to account -for an HTTPS-intercepting man in the middle proxy, you must specify -the path to the certificate bundle in the environment variable -<envar>NIX_SSL_CERT_FILE</envar>.</para> - - -<para>If you don't specify a <envar>NIX_SSL_CERT_FILE</envar> -manually, Nix will install and use its own certificate -bundle.</para> - -<procedure> - <step><para>Set the environment variable and install Nix</para> - <screen> -$ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt -$ sh <(curl -L https://nixos.org/nix/install) -</screen></step> - - <step><para>In the shell profile and rc files (for example, - <filename>/etc/bashrc</filename>, <filename>/etc/zshrc</filename>), - add the following line:</para> -<programlisting> -export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt -</programlisting> -</step> -</procedure> - -<note><para>You must not add the export and then do the install, as -the Nix installer will detect the presense of Nix configuration, and -abort.</para></note> - -<section xml:id="sec-nix-ssl-cert-file-with-nix-daemon-and-macos"> -<title><envar>NIX_SSL_CERT_FILE</envar> with macOS and the Nix daemon</title> - -<para>On macOS you must specify the environment variable for the Nix -daemon service, then restart it:</para> - -<screen> -$ sudo launchctl setenv NIX_SSL_CERT_FILE /etc/ssl/my-certificate-bundle.crt -$ 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> diff --git a/doc/manual/installation/installation.xml b/doc/manual/installation/installation.xml deleted file mode 100644 index 878959352..000000000 --- a/doc/manual/installation/installation.xml +++ /dev/null @@ -1,34 +0,0 @@ -<part 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-installation"> - -<title>Installation</title> - -<partintro> -<para>This section describes how to install and configure Nix for first-time use.</para> -</partintro> - -<xi:include href="supported-platforms.xml" /> -<xi:include href="installing-binary.xml" /> -<xi:include href="installing-source.xml" /> -<xi:include href="nix-security.xml" /> -<xi:include href="env-variables.xml" /> - -<!-- TODO: should be updated -<section><title>Upgrading Nix through Nix</title> - -<para>You can install the latest stable version of Nix through Nix -itself by subscribing to the channel <link -xlink:href="http://nixos.org/releases/nix/channels/nix-stable" />, -or the latest unstable version by subscribing to the channel <link -xlink:href="http://nixos.org/releases/nix/channels/nix-unstable" />. -You can also do a <link linkend="sec-one-click">one-click -installation</link> by clicking on the package links at <link -xlink:href="http://nixos.org/releases/full-index-nix.html" />.</para> - -</section> ---> - -</part> diff --git a/doc/manual/installation/installing-binary.xml b/doc/manual/installation/installing-binary.xml deleted file mode 100644 index 64c7a37fb..000000000 --- a/doc/manual/installation/installing-binary.xml +++ /dev/null @@ -1,469 +0,0 @@ -<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="ch-installing-binary"> - -<title>Installing a Binary Distribution</title> - -<para> - If you are using Linux or macOS versions up to 10.14 (Mojave), the - easiest way to install Nix is to run the following command: -</para> - -<screen> - $ sh <(curl -L https://nixos.org/nix/install) -</screen> - -<para> - If you're using macOS 10.15 (Catalina) or newer, consult - <link linkend="sect-macos-installation">the macOS installation instructions</link> - before installing. -</para> - -<para> - As of Nix 2.1.0, the Nix installer will always default to creating a - single-user installation, however opting in to the multi-user - installation is highly recommended. - <!-- TODO: this explains *neither* why the default version is - single-user, nor why we'd recommend multi-user over the default. - True prospective users don't have much basis for evaluating this. - What's it to me? Who should pick which? Why? What if I pick wrong? - --> -</para> - -<section xml:id="sect-single-user-installation"> - <title>Single User Installation</title> - - <para> - To explicitly select a single-user installation on your system: - - <screen> - sh <(curl -L https://nixos.org/nix/install) --no-daemon -</screen> - </para> - -<para> -This will perform a single-user installation of Nix, meaning that -<filename>/nix</filename> is owned by the invoking user. You should -run this under your usual user account, <emphasis>not</emphasis> as -root. The script will invoke <command>sudo</command> to create -<filename>/nix</filename> if it doesn’t already exist. If you don’t -have <command>sudo</command>, you should manually create -<filename>/nix</filename> first as root, e.g.: - -<screen> -$ mkdir /nix -$ chown alice /nix -</screen> - -The install script will modify the first writable file from amongst -<filename>.bash_profile</filename>, <filename>.bash_login</filename> -and <filename>.profile</filename> to source -<filename>~/.nix-profile/etc/profile.d/nix.sh</filename>. You can set -the <envar>NIX_INSTALLER_NO_MODIFY_PROFILE</envar> environment -variable before executing the install script to disable this -behaviour. -</para> - - -<para>You can uninstall Nix simply by running: - -<screen> -$ rm -rf /nix -</screen> - -</para> -</section> - -<section xml:id="sect-multi-user-installation"> - <title>Multi User Installation</title> - <para> - The multi-user Nix installation creates system users, and a system - service for the Nix daemon. - </para> - - <itemizedlist> - <title>Supported Systems</title> - - <listitem> - <para>Linux running systemd, with SELinux disabled</para> - </listitem> - <listitem><para>macOS</para></listitem> - </itemizedlist> - - <para> - You can instruct the installer to perform a multi-user - installation on your system: - </para> - - <screen>sh <(curl -L https://nixos.org/nix/install) --daemon</screen> - - <para> - The multi-user installation of Nix will create build users between - the user IDs 30001 and 30032, and a group with the group ID 30000. - - You should run this under your usual user account, - <emphasis>not</emphasis> as root. The script will invoke - <command>sudo</command> as needed. - </para> - - <note><para> - If you need Nix to use a different group ID or user ID set, you - will have to download the tarball manually and <link - linkend="sect-nix-install-binary-tarball">edit the install - script</link>. - </para></note> - - <para> - The installer will modify <filename>/etc/bashrc</filename>, and - <filename>/etc/zshrc</filename> if they exist. The installer will - first back up these files with a - <literal>.backup-before-nix</literal> extension. The installer - will also create <filename>/etc/profile.d/nix.sh</filename>. - </para> - - <para>You can uninstall Nix with the following commands: - -<screen> -sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels - -# If you are on Linux with systemd, you will need to run: -sudo systemctl stop nix-daemon.socket -sudo systemctl stop nix-daemon.service -sudo systemctl disable nix-daemon.socket -sudo systemctl disable nix-daemon.service -sudo systemctl daemon-reload - -# If you are on macOS, you will need to run: -sudo launchctl unload /Library/LaunchDaemons/org.nixos.nix-daemon.plist -sudo rm /Library/LaunchDaemons/org.nixos.nix-daemon.plist -</screen> - - There may also be references to Nix in - <filename>/etc/profile</filename>, - <filename>/etc/bashrc</filename>, and - <filename>/etc/zshrc</filename> which you may remove. - </para> - -</section> - -<section xml:id="sect-macos-installation"> - <title>macOS Installation</title> - - <para> - Starting with macOS 10.15 (Catalina), the root filesystem is read-only. - This means <filename>/nix</filename> can no longer live on your system - volume, and that you'll need a workaround to install Nix. - </para> - - <para> - The recommended approach, which creates an unencrypted APFS volume - for your Nix store and a "synthetic" empty directory to mount it - over at <filename>/nix</filename>, is least likely to impair Nix - or your system. - </para> - - <note><para> - With all separate-volume approaches, it's possible something on - your system (particularly daemons/services and restored apps) may - need access to your Nix store before the volume is mounted. Adding - additional encryption makes this more likely. - </para></note> - - <para> - If you're using a recent Mac with a - <link xlink:href="https://www.apple.com/euro/mac/shared/docs/Apple_T2_Security_Chip_Overview.pdf">T2 chip</link>, - your drive will still be encrypted at rest (in which case "unencrypted" - is a bit of a misnomer). To use this approach, just install Nix with: - </para> - - <screen>$ sh <(curl -L https://nixos.org/nix/install) --darwin-use-unencrypted-nix-store-volume</screen> - - <para> - If you don't like the sound of this, you'll want to weigh the - other approaches and tradeoffs detailed in this section. - </para> - - <note> - <title>Eventual solutions?</title> - <para> - All of the known workarounds have drawbacks, but we hope - better solutions will be available in the future. Some that - we have our eye on are: - </para> - <orderedlist> - <listitem> - <para> - A true firmlink would enable the Nix store to live on the - primary data volume without the build problems caused by - the symlink approach. End users cannot currently - create true firmlinks. - </para> - </listitem> - <listitem> - <para> - If the Nix store volume shared FileVault encryption - with the primary data volume (probably by using the same - volume group and role), FileVault encryption could be - easily supported by the installer without requiring - manual setup by each user. - </para> - </listitem> - </orderedlist> - </note> - - <section xml:id="sect-macos-installation-change-store-prefix"> - <title>Change the Nix store path prefix</title> - <para> - Changing the default prefix for the Nix store is a simple - approach which enables you to leave it on your root volume, - where it can take full advantage of FileVault encryption if - enabled. Unfortunately, this approach also opts your device out - of some benefits that are enabled by using the same prefix - across systems: - - <itemizedlist> - <listitem> - <para> - Your system won't be able to take advantage of the binary - cache (unless someone is able to stand up and support - duplicate caching infrastructure), which means you'll - spend more time waiting for builds. - </para> - </listitem> - <listitem> - <para> - It's harder to build and deploy packages to Linux systems. - </para> - </listitem> - <!-- TODO: may be more here --> - </itemizedlist> - - <!-- TODO: Yes, but how?! --> - - It would also possible (and often requested) to just apply this - change ecosystem-wide, but it's an intrusive process that has - side effects we want to avoid for now. - <!-- magnificent hand-wavy gesture --> - </para> - <para> - </para> - </section> - - <section xml:id="sect-macos-installation-encrypted-volume"> - <title>Use a separate encrypted volume</title> - <para> - If you like, you can also add encryption to the recommended - approach taken by the installer. You can do this by pre-creating - an encrypted volume before you run the installer--or you can - run the installer and encrypt the volume it creates later. - <!-- TODO: see later note about whether this needs both add-encryption and from-scratch directions --> - </para> - <para> - In either case, adding encryption to a second volume isn't quite - as simple as enabling FileVault for your boot volume. Before you - dive in, there are a few things to weigh: - </para> - <orderedlist> - <listitem> - <para> - The additional volume won't be encrypted with your existing - FileVault key, so you'll need another mechanism to decrypt - the volume. - </para> - </listitem> - <listitem> - <para> - You can store the password in Keychain to automatically - decrypt the volume on boot--but it'll have to wait on Keychain - and may not mount before your GUI apps restore. If any of - your launchd agents or apps depend on Nix-installed software - (for example, if you use a Nix-installed login shell), the - restore may fail or break. - </para> - <para> - On a case-by-case basis, you may be able to work around this - problem by using <command>wait4path</command> to block - execution until your executable is available. - </para> - <para> - It's also possible to decrypt and mount the volume earlier - with a login hook--but this mechanism appears to be - deprecated and its future is unclear. - </para> - </listitem> - <listitem> - <para> - You can hard-code the password in the clear, so that your - store volume can be decrypted before Keychain is available. - </para> - </listitem> - </orderedlist> - <para> - If you are comfortable navigating these tradeoffs, you can encrypt the volume with - something along the lines of: - <!-- TODO: - I don't know if this also needs from-scratch instructions? - can we just recommend use-the-installer-and-then-encrypt? - --> - </para> - <!-- - TODO: it looks like this option can be encryptVolume|encrypt|enableFileVault - - It may be more clear to use encryptVolume, here? FileVault seems - heavily associated with the boot-volume behavior; I worry - a little that it can mislead here, especially as it gets - copied around minus doc context...? - --> - <screen>alice$ diskutil apfs enableFileVault /nix -user disk</screen> - - <!-- TODO: and then go into detail on the mount/decrypt approaches? --> - </section> - - <section xml:id="sect-macos-installation-symlink"> - <!-- - Maybe a good razor is: if we'd hate having to support someone who - installed Nix this way, it shouldn't even be detailed? - --> - <title>Symlink the Nix store to a custom location</title> - <para> - Another simple approach is using <filename>/etc/synthetic.conf</filename> - to symlink the Nix store to the data volume. This option also - enables your store to share any configured FileVault encryption. - Unfortunately, builds that resolve the symlink may leak the - canonical path or even fail. - </para> - <para> - Because of these downsides, we can't recommend this approach. - </para> - <!-- Leaving out instructions for this one. --> - </section> - - <section xml:id="sect-macos-installation-recommended-notes"> - <title>Notes on the recommended approach</title> - <para> - This section goes into a little more detail on the recommended - approach. You don't need to understand it to run the installer, - but it can serve as a helpful reference if you run into trouble. - </para> - <orderedlist> - <listitem> - <para> - In order to compose user-writable locations into the new - read-only system root, Apple introduced a new concept called - <literal>firmlinks</literal>, which it describes as a - "bi-directional wormhole" between two filesystems. You can - see the current firmlinks in <filename>/usr/share/firmlinks</filename>. - Unfortunately, firmlinks aren't (currently?) user-configurable. - </para> - - <para> - For special cases like NFS mount points or package manager roots, - <link xlink:href="https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man5/synthetic.conf.5.html">synthetic.conf(5)</link> - supports limited user-controlled file-creation (of symlinks, - and synthetic empty directories) at <filename>/</filename>. - To create a synthetic empty directory for mounting at <filename>/nix</filename>, - add the following line to <filename>/etc/synthetic.conf</filename> - (create it if necessary): - </para> - - <screen>nix</screen> - </listitem> - - <listitem> - <para> - This configuration is applied at boot time, but you can use - <command>apfs.util</command> to trigger creation (not deletion) - of new entries without a reboot: - </para> - - <screen>alice$ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B</screen> - </listitem> - - <listitem> - <para> - Create the new APFS volume with diskutil: - </para> - - <screen>alice$ sudo diskutil apfs addVolume diskX APFS 'Nix Store' -mountpoint /nix</screen> - </listitem> - - <listitem> - <para> - Using <command>vifs</command>, add the new mount to - <filename>/etc/fstab</filename>. If it doesn't already have - other entries, it should look something like: - </para> - -<screen> -# -# Warning - this file should only be modified with vifs(8) -# -# Failure to do so is unsupported and may be destructive. -# -LABEL=Nix\040Store /nix apfs rw,nobrowse -</screen> - - <para> - The nobrowse setting will keep Spotlight from indexing this - volume, and keep it from showing up on your desktop. - </para> - </listitem> - </orderedlist> - </section> - -</section> - -<section xml:id="sect-nix-install-pinned-version-url"> - <title>Installing a pinned Nix version from a URL</title> - - <para> - NixOS.org hosts version-specific installation URLs for all Nix - versions since 1.11.16, at - <literal>https://releases.nixos.org/nix/nix-<replaceable>version</replaceable>/install</literal>. - </para> - - <para> - These install scripts can be used the same as the main - NixOS.org installation script: - - <screen> - sh <(curl -L https://nixos.org/nix/install) -</screen> - </para> - - <para> - In the same directory of the install script are sha256 sums, and - gpg signature files. - </para> -</section> - -<section xml:id="sect-nix-install-binary-tarball"> - <title>Installing from a binary tarball</title> - - <para> - You can also download a binary tarball that contains Nix and all - its dependencies. (This is what the install script at - <uri>https://nixos.org/nix/install</uri> does automatically.) You - should unpack it somewhere (e.g. in <filename>/tmp</filename>), - and then run the script named <command>install</command> inside - the binary tarball: - - -<screen> -alice$ cd /tmp -alice$ tar xfj nix-1.8-x86_64-darwin.tar.bz2 -alice$ cd nix-1.8-x86_64-darwin -alice$ ./install -</screen> - </para> - - <para> - If you need to edit the multi-user installation script to use - different group ID or a different user ID range, modify the - variables set in the file named - <filename>install-multi-user</filename>. - </para> -</section> -</chapter> diff --git a/doc/manual/installation/installing-source.xml b/doc/manual/installation/installing-source.xml deleted file mode 100644 index c261a109d..000000000 --- a/doc/manual/installation/installing-source.xml +++ /dev/null @@ -1,16 +0,0 @@ -<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="ch-installing-source"> - -<title>Installing Nix from Source</title> - -<para>If no binary package is available, you can download and compile -a source distribution.</para> - -<xi:include href="prerequisites-source.xml" /> -<xi:include href="obtaining-source.xml" /> -<xi:include href="building-source.xml" /> - -</chapter> diff --git a/doc/manual/installation/multi-user.xml b/doc/manual/installation/multi-user.xml deleted file mode 100644 index 69ae1ef27..000000000 --- a/doc/manual/installation/multi-user.xml +++ /dev/null @@ -1,107 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-multi-user"> - -<title>Multi-User Mode</title> - -<para>To allow a Nix store to be shared safely among multiple users, -it is important that users are not able to run builders that modify -the Nix store or database in arbitrary ways, or that interfere with -builds started by other users. If they could do so, they could -install a Trojan horse in some package and compromise the accounts of -other users.</para> - -<para>To prevent this, the Nix store and database are owned by some -privileged user (usually <literal>root</literal>) and builders are -executed under special user accounts (usually named -<literal>nixbld1</literal>, <literal>nixbld2</literal>, etc.). When a -unprivileged user runs a Nix command, actions that operate on the Nix -store (such as builds) are forwarded to a <emphasis>Nix -daemon</emphasis> running under the owner of the Nix store/database -that performs the operation.</para> - -<note><para>Multi-user mode has one important limitation: only -<systemitem class="username">root</systemitem> and a set of trusted -users specified in <filename>nix.conf</filename> can specify arbitrary -binary caches. So while unprivileged users may install packages from -arbitrary Nix expressions, they may not get pre-built -binaries.</para></note> - - -<simplesect> - -<title>Setting up the build users</title> - -<para>The <emphasis>build users</emphasis> are the special UIDs under -which builds are performed. They should all be members of the -<emphasis>build users group</emphasis> <literal>nixbld</literal>. -This group should have no other members. The build users should not -be members of any other group. On Linux, you can create the group and -users as follows: - -<screen> -$ groupadd -r nixbld -$ for n in $(seq 1 10); do useradd -c "Nix build user $n" \ - -d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \ - nixbld$n; done -</screen> - -This creates 10 build users. There can never be more concurrent builds -than the number of build users, so you may want to increase this if -you expect to do many builds at the same time.</para> - -</simplesect> - - -<simplesect> - -<title>Running the daemon</title> - -<para>The <link linkend="sec-nix-daemon">Nix daemon</link> should be -started as follows (as <literal>root</literal>): - -<screen> -$ nix-daemon</screen> - -You’ll want to put that line somewhere in your system’s boot -scripts.</para> - -<para>To let unprivileged users use the daemon, they should set the -<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment -variable</link> to <literal>daemon</literal>. So you should put a -line like - -<programlisting> -export NIX_REMOTE=daemon</programlisting> - -into the users’ login scripts.</para> - -</simplesect> - - -<simplesect> - -<title>Restricting access</title> - -<para>To limit which users can perform Nix operations, you can use the -permissions on the directory -<filename>/nix/var/nix/daemon-socket</filename>. For instance, if you -want to restrict the use of Nix to the members of a group called -<literal>nix-users</literal>, do - -<screen> -$ chgrp nix-users /nix/var/nix/daemon-socket -$ chmod ug=rwx,o= /nix/var/nix/daemon-socket -</screen> - -This way, users who are not in the <literal>nix-users</literal> group -cannot connect to the Unix domain socket -<filename>/nix/var/nix/daemon-socket/socket</filename>, so they cannot -perform Nix operations.</para> - -</simplesect> - - -</section> diff --git a/doc/manual/installation/nix-security.xml b/doc/manual/installation/nix-security.xml deleted file mode 100644 index d888ff14d..000000000 --- a/doc/manual/installation/nix-security.xml +++ /dev/null @@ -1,27 +0,0 @@ -<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="ch-nix-security"> - -<title>Security</title> - -<para>Nix has two basic security models. First, it can be used in -“single-user mode”, which is similar to what most other package -management tools do: there is a single user (typically <systemitem -class="username">root</systemitem>) who performs all package -management operations. All other users can then use the installed -packages, but they cannot perform package management operations -themselves.</para> - -<para>Alternatively, you can configure Nix in “multi-user mode”. In -this model, all users can perform package management operations — for -instance, every user can install software without requiring root -privileges. Nix ensures that this is secure. For instance, it’s not -possible for one user to overwrite a package used by another user with -a Trojan horse.</para> - -<xi:include href="single-user.xml" /> -<xi:include href="multi-user.xml" /> - -</chapter>
\ No newline at end of file diff --git a/doc/manual/installation/obtaining-source.xml b/doc/manual/installation/obtaining-source.xml deleted file mode 100644 index 968822cc0..000000000 --- a/doc/manual/installation/obtaining-source.xml +++ /dev/null @@ -1,30 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-obtaining-source"> - -<title>Obtaining a Source Distribution</title> - -<para>The source tarball of the most recent stable release can be -downloaded from the <link -xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>. -You can also grab the <link -xlink:href="http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents">most -recent development release</link>.</para> - -<para>Alternatively, the most recent sources of Nix can be obtained -from its <link -xlink:href="https://github.com/NixOS/nix">Git -repository</link>. For example, the following command will check out -the latest revision into a directory called -<filename>nix</filename>:</para> - -<screen> -$ git clone https://github.com/NixOS/nix</screen> - -<para>Likewise, specific releases can be obtained from the <link -xlink:href="https://github.com/NixOS/nix/tags">tags</link> of the -repository.</para> - -</section>
\ No newline at end of file diff --git a/doc/manual/installation/prerequisites-source.xml b/doc/manual/installation/prerequisites-source.xml deleted file mode 100644 index fa6da9b1e..000000000 --- a/doc/manual/installation/prerequisites-source.xml +++ /dev/null @@ -1,113 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-prerequisites-source"> - -<title>Prerequisites</title> - -<itemizedlist> - - <listitem><para>GNU Autoconf - (<link xlink:href="https://www.gnu.org/software/autoconf/"/>) - and the autoconf-archive macro collection - (<link xlink:href="https://www.gnu.org/software/autoconf-archive/"/>). - These are only needed to run the bootstrap script, and are not necessary - if your source distribution came with a pre-built - <literal>./configure</literal> script.</para></listitem> - - <listitem><para>GNU Make.</para></listitem> - - <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++17.</para></listitem> - - <listitem><para><command>pkg-config</command> to locate - dependencies. If your distribution does not provide it, you can get - it from <link - xlink:href="http://www.freedesktop.org/wiki/Software/pkg-config" - />.</para></listitem> - - <listitem><para>The OpenSSL library to calculate cryptographic hashes. - If your distribution does not provide it, you can get it from <link - xlink:href="https://www.openssl.org"/>.</para></listitem> - - <listitem><para>The <literal>libbrotlienc</literal> and - <literal>libbrotlidec</literal> libraries to provide implementation - of the Brotli compression algorithm. They are available for download - from the official repository <link - xlink:href="https://github.com/google/brotli" />.</para></listitem> - - <listitem><para>The bzip2 compressor program and the - <literal>libbz2</literal> library. Thus you must have bzip2 - installed, including development headers and libraries. If your - distribution does not provide these, you can obtain bzip2 from <link - xlink:href="https://web.archive.org/web/20180624184756/http://www.bzip.org/" - />.</para></listitem> - - <listitem><para><literal>liblzma</literal>, which is provided by - XZ Utils. If your distribution does not provide this, you can - get it from <link xlink:href="https://tukaani.org/xz/"/>.</para></listitem> - - <listitem><para>cURL and its library. If your distribution does not - provide it, you can get it from <link - xlink:href="https://curl.haxx.se/"/>.</para></listitem> - - <listitem><para>The SQLite embedded database library, version 3.6.19 - or higher. If your distribution does not provide it, please install - it from <link xlink:href="http://www.sqlite.org/" />.</para></listitem> - - <listitem><para>The <link - xlink:href="http://www.hboehm.info/gc/">Boehm - garbage collector</link> to reduce the evaluator’s memory - consumption (optional). To enable it, install - <literal>pkgconfig</literal> and the Boehm garbage collector, and - pass the flag <option>--enable-gc</option> to - <command>configure</command>.</para></listitem> - - <listitem><para>The <literal>boost</literal> library of version - 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 - <literal>libxslt</literal> packages, respectively. You also need - the <link - xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook - XSL stylesheets</link> and optionally the <link - xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG - schemas</link>. Note that these are only required if you modify the - manual sources or when you are building from the Git - repository.</para></listitem> - - <listitem><para>Recent versions of Bison and Flex to build the - parser. (This is because Nix needs GLR support in Bison and - reentrancy support in Flex.) For Bison, you need version 2.6, which - can be obtained from the <link - xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP - server</link>. For Flex, you need version 2.5.35, which is - available on <link - xlink:href="http://lex.sourceforge.net/">SourceForge</link>. - Slightly older versions may also work, but ancient versions like the - ubiquitous 2.5.4a won't. Note that these are only required if you - modify the parser or when you are building from the Git - repository.</para></listitem> - - <listitem><para>The <literal>libseccomp</literal> is used to provide - syscall filtering on Linux. This is an optional dependency and can - be disabled passing a <option>--disable-seccomp-sandboxing</option> - option to the <command>configure</command> script (Not recommended - unless your system doesn't support - <literal>libseccomp</literal>). To get the library, visit <link - xlink:href="https://github.com/seccomp/libseccomp" - />.</para></listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/installation/single-user.xml b/doc/manual/installation/single-user.xml deleted file mode 100644 index 09cdaa5d4..000000000 --- a/doc/manual/installation/single-user.xml +++ /dev/null @@ -1,21 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-single-user"> - -<title>Single-User Mode</title> - -<para>In single-user mode, all Nix operations that access the database -in <filename><replaceable>prefix</replaceable>/var/nix/db</filename> -or modify the Nix store in -<filename><replaceable>prefix</replaceable>/store</filename> must be -performed under the user ID that owns those directories. This is -typically <systemitem class="username">root</systemitem>. (If you -install from RPM packages, that’s in fact the default ownership.) -However, on single-user machines, it is often convenient to -<command>chown</command> those directories to your normal user account -so that you don’t have to <command>su</command> to <systemitem -class="username">root</systemitem> all the time.</para> - -</section>
\ No newline at end of file diff --git a/doc/manual/installation/supported-platforms.xml b/doc/manual/installation/supported-platforms.xml deleted file mode 100644 index 3e74be49d..000000000 --- a/doc/manual/installation/supported-platforms.xml +++ /dev/null @@ -1,36 +0,0 @@ -<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="ch-supported-platforms"> - -<title>Supported Platforms</title> - -<para>Nix is currently supported on the following platforms: - -<itemizedlist> - - <listitem><para>Linux (i686, x86_64, aarch64).</para></listitem> - - <listitem><para>macOS (x86_64).</para></listitem> - - <!-- - <listitem><para>FreeBSD (only tested on Intel).</para></listitem> - --> - - <!-- - <listitem><para>Windows through <link - xlink:href="http://www.cygwin.com/">Cygwin</link>.</para> - - <warning><para>On Cygwin, Nix <emphasis>must</emphasis> be installed - on an NTFS partition. It will not work correctly on a FAT - partition.</para></warning> - - </listitem> - --> - -</itemizedlist> - -</para> - -</chapter> diff --git a/doc/manual/installation/upgrading.xml b/doc/manual/installation/upgrading.xml deleted file mode 100644 index 592f63895..000000000 --- a/doc/manual/installation/upgrading.xml +++ /dev/null @@ -1,27 +0,0 @@ -<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="ch-upgrading-nix"> - - <title>Upgrading Nix</title> - - <para> - Multi-user Nix users on macOS can upgrade Nix by running: - <command>sudo -i sh -c 'nix-channel --update && - nix-env -iA nixpkgs.nix && - launchctl remove org.nixos.nix-daemon && - launchctl load /Library/LaunchDaemons/org.nixos.nix-daemon.plist'</command> - </para> - - - <para> - Single-user installations of Nix should run this: - <command>nix-channel --update; nix-env -iA nixpkgs.nix nixpkgs.cacert</command> - </para> - - <para> - Multi-user Nix users on Linux should run this with sudo: - <command>nix-channel --update; nix-env -iA nixpkgs.nix nixpkgs.cacert; systemctl daemon-reload; systemctl restart nix-daemon</command> - </para> -</chapter> diff --git a/doc/manual/introduction/about-nix.xml b/doc/manual/introduction/about-nix.xml deleted file mode 100644 index c21ed34dd..000000000 --- a/doc/manual/introduction/about-nix.xml +++ /dev/null @@ -1,268 +0,0 @@ -<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="ch-about-nix"> - -<title>About Nix</title> - -<para>Nix is a <emphasis>purely functional package manager</emphasis>. -This means that it treats packages like values in purely functional -programming languages such as Haskell — they are built by functions -that don’t have side-effects, and they never change after they have -been built. Nix stores packages in the <emphasis>Nix -store</emphasis>, usually the directory -<filename>/nix/store</filename>, where each package has its own unique -subdirectory such as - -<programlisting> -/nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/ -</programlisting> - -where <literal>b6gvzjyb2pg0…</literal> is a unique identifier for the -package that captures all its dependencies (it’s a cryptographic hash -of the package’s build dependency graph). This enables many powerful -features.</para> - - -<simplesect><title>Multiple versions</title> - -<para>You can have multiple versions or variants of a package -installed at the same time. This is especially important when -different applications have dependencies on different versions of the -same package — it prevents the “DLL hell”. Because of the hashing -scheme, different versions of a package end up in different paths in -the Nix store, so they don’t interfere with each other.</para> - -<para>An important consequence is that operations like upgrading or -uninstalling an application cannot break other applications, since -these operations never “destructively” update or delete files that are -used by other packages.</para> - -</simplesect> - - -<simplesect><title>Complete dependencies</title> - -<para>Nix helps you make sure that package dependency specifications -are complete. In general, when you’re making a package for a package -management system like RPM, you have to specify for each package what -its dependencies are, but there are no guarantees that this -specification is complete. If you forget a dependency, then the -package will build and work correctly on <emphasis>your</emphasis> -machine if you have the dependency installed, but not on the end -user's machine if it's not there.</para> - -<para>Since Nix on the other hand doesn’t install packages in “global” -locations like <filename>/usr/bin</filename> but in package-specific -directories, the risk of incomplete dependencies is greatly reduced. -This is because tools such as compilers don’t search in per-packages -directories such as -<filename>/nix/store/5lbfaxb722zp…-openssl-0.9.8d/include</filename>, -so if a package builds correctly on your system, this is because you -specified the dependency explicitly. This takes care of the build-time -dependencies.</para> - -<para>Once a package is built, runtime dependencies are found by -scanning binaries for the hash parts of Nix store paths (such as -<literal>r8vvq9kq…</literal>). This sounds risky, but it works -extremely well.</para> - -</simplesect> - - -<simplesect><title>Multi-user support</title> - -<para>Nix has multi-user support. This means that non-privileged -users can securely install software. Each user can have a different -<emphasis>profile</emphasis>, a set of packages in the Nix store that -appear in the user’s <envar>PATH</envar>. If a user installs a -package that another user has already installed previously, the -package won’t be built or downloaded a second time. At the same time, -it is not possible for one user to inject a Trojan horse into a -package that might be used by another user.</para> - -</simplesect> - - -<simplesect><title>Atomic upgrades and rollbacks</title> - -<para>Since package management operations never overwrite packages in -the Nix store but just add new versions in different paths, they are -<emphasis>atomic</emphasis>. So during a package upgrade, there is no -time window in which the package has some files from the old version -and some files from the new version — which would be bad because a -program might well crash if it’s started during that period.</para> - -<para>And since packages aren’t overwritten, the old versions are still -there after an upgrade. This means that you can <emphasis>roll -back</emphasis> to the old version:</para> - -<screen> -$ nix-env --upgrade <replaceable>some-packages</replaceable> -$ nix-env --rollback -</screen> - -</simplesect> - - -<simplesect><title>Garbage collection</title> - -<para>When you uninstall a package like this… - -<screen> -$ nix-env --uninstall firefox -</screen> - -the package isn’t deleted from the system right away (after all, you -might want to do a rollback, or it might be in the profiles of other -users). Instead, unused packages can be deleted safely by running the -<emphasis>garbage collector</emphasis>: - -<screen> -$ nix-collect-garbage -</screen> - -This deletes all packages that aren’t in use by any user profile or by -a currently running program.</para> - -</simplesect> - - -<simplesect><title>Functional package language</title> - -<para>Packages are built from <emphasis>Nix expressions</emphasis>, -which is a simple functional language. A Nix expression describes -everything that goes into a package build action (a “derivation”): -other packages, sources, the build script, environment variables for -the build script, etc. Nix tries very hard to ensure that Nix -expressions are <emphasis>deterministic</emphasis>: building a Nix -expression twice should yield the same result.</para> - -<para>Because it’s a functional language, it’s easy to support -building variants of a package: turn the Nix expression into a -function and call it any number of times with the appropriate -arguments. Due to the hashing scheme, variants don’t conflict with -each other in the Nix store.</para> - -</simplesect> - - -<simplesect><title>Transparent source/binary deployment</title> - -<para>Nix expressions generally describe how to build a package from -source, so an installation action like - -<screen> -$ nix-env --install firefox -</screen> - -<emphasis>could</emphasis> cause quite a bit of build activity, as not -only Firefox but also all its dependencies (all the way up to the C -library and the compiler) would have to built, at least if they are -not already in the Nix store. This is a <emphasis>source deployment -model</emphasis>. For most users, building from source is not very -pleasant as it takes far too long. However, Nix can automatically -skip building from source and instead use a <emphasis>binary -cache</emphasis>, a web server that provides pre-built binaries. For -instance, when asked to build -<literal>/nix/store/b6gvzjyb2pg0…-firefox-33.1</literal> from source, -Nix would first check if the file -<uri>https://cache.nixos.org/b6gvzjyb2pg0….narinfo</uri> exists, and -if so, fetch the pre-built binary referenced from there; otherwise, it -would fall back to building from source.</para> - -</simplesect> - - -<!-- -<simplesect><title>Binary patching</title> - -<para>In addition to downloading binaries automatically if they’re -available, Nix can download binary deltas that patch an existing -package in the Nix store into a new version. This speeds up -upgrades.</para> - -</simplesect> ---> - - -<simplesect><title>Nix Packages collection</title> - -<para>We provide a large set of Nix expressions containing hundreds of -existing Unix packages, the <emphasis>Nix Packages -collection</emphasis> (Nixpkgs).</para> - -</simplesect> - - -<simplesect><title>Managing build environments</title> - -<para>Nix is extremely useful for developers as it makes it easy to -automatically set up the build environment for a package. Given a -Nix expression that describes the dependencies of your package, the -command <command>nix-shell</command> will build or download those -dependencies if they’re not already in your Nix store, and then start -a Bash shell in which all necessary environment variables (such as -compiler search paths) are set.</para> - -<para>For example, the following command gets all dependencies of the -Pan newsreader, as described by <link -xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix">its -Nix expression</link>:</para> - -<screen> -$ nix-shell '<nixpkgs>' -A pan -</screen> - -<para>You’re then dropped into a shell where you can edit, build and test -the package:</para> - -<screen> -[nix-shell]$ tar xf $src -[nix-shell]$ cd pan-* -[nix-shell]$ ./configure -[nix-shell]$ make -[nix-shell]$ ./pan/gui/pan -</screen> - -<!-- -<para>Since Nix packages are reproducible and have complete dependency -specifications, Nix makes an excellent basis for <a -href="[%root%]hydra">a continuous build system</a>.</para> ---> - -</simplesect> - - -<simplesect><title>Portability</title> - -<para>Nix runs on Linux and macOS.</para> - -</simplesect> - - -<simplesect><title>NixOS</title> - -<para>NixOS is a Linux distribution based on Nix. It uses Nix not -just for package management but also to manage the system -configuration (e.g., to build configuration files in -<filename>/etc</filename>). This means, among other things, that it -is easy to roll back the entire configuration of the system to an -earlier state. Also, users can install software without root -privileges. For more information and downloads, see the <link -xlink:href="http://nixos.org/">NixOS homepage</link>.</para> - -</simplesect> - - -<simplesect><title>License</title> - -<para>Nix is released under the terms of the <link -xlink:href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">GNU -LGPLv2.1 or (at your option) any later version</link>.</para> - -</simplesect> - - -</chapter> diff --git a/doc/manual/introduction/introduction.xml b/doc/manual/introduction/introduction.xml deleted file mode 100644 index 12b2cc761..000000000 --- a/doc/manual/introduction/introduction.xml +++ /dev/null @@ -1,12 +0,0 @@ -<part 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-introduction"> - -<title>Introduction</title> - -<xi:include href="about-nix.xml" /> -<xi:include href="quick-start.xml" /> - -</part> diff --git a/doc/manual/introduction/quick-start.xml b/doc/manual/introduction/quick-start.xml deleted file mode 100644 index 1992c14ed..000000000 --- a/doc/manual/introduction/quick-start.xml +++ /dev/null @@ -1,124 +0,0 @@ -<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-quick-start"> - -<title>Quick Start</title> - -<para>This chapter is for impatient people who don't like reading -documentation. For more in-depth information you are kindly referred -to subsequent chapters.</para> - -<procedure> - -<step><para>Install single-user Nix by running the following: - -<screen> -$ bash <(curl -L https://nixos.org/nix/install) -</screen> - -This will install Nix in <filename>/nix</filename>. The install script -will create <filename>/nix</filename> using <command>sudo</command>, -so make sure you have sufficient rights. (For other installation -methods, see <xref linkend="chap-installation"/>.)</para></step> - -<step><para>See what installable packages are currently available -in the channel: - -<screen> -$ nix-env -qa -docbook-xml-4.3 -docbook-xml-4.5 -firefox-33.0.2 -hello-2.9 -libxslt-1.1.28 -<replaceable>...</replaceable></screen> - -</para></step> - -<step><para>Install some packages from the channel: - -<screen> -$ nix-env -i hello</screen> - -This should download pre-built packages; it should not build them -locally (if it does, something went wrong).</para></step> - -<step><para>Test that they work: - -<screen> -$ which hello -/home/eelco/.nix-profile/bin/hello -$ hello -Hello, world! -</screen> - -</para></step> - -<step><para>Uninstall a package: - -<screen> -$ nix-env -e hello</screen> - -</para></step> - -<step><para>You can also test a package without installing it: - -<screen> -$ nix-shell -p hello -</screen> - -This builds or downloads GNU Hello and its dependencies, then drops -you into a Bash shell where the <command>hello</command> command is -present, all without affecting your normal environment: - -<screen> -[nix-shell:~]$ hello -Hello, world! - -[nix-shell:~]$ exit - -$ hello -hello: command not found -</screen> - -</para></step> - -<step><para>To keep up-to-date with the channel, do: - -<screen> -$ nix-channel --update nixpkgs -$ nix-env -u '*'</screen> - -The latter command will upgrade each installed package for which there -is a “newer” version (as determined by comparing the version -numbers).</para></step> - -<step><para>If you're unhappy with the result of a -<command>nix-env</command> action (e.g., an upgraded package turned -out not to work properly), you can go back: - -<screen> -$ nix-env --rollback</screen> - -</para></step> - -<step><para>You should periodically run the Nix garbage collector -to get rid of unused packages, since uninstalls or upgrades don't -actually delete them: - -<screen> -$ nix-collect-garbage -d</screen> - -<!-- -The first command deletes old “generations” of your profile (making -rollbacks impossible, but also making the packages in those old -generations available for garbage collection), while the second -command actually deletes them.--> - -</para></step> - -</procedure> - -</chapter> diff --git a/doc/manual/local.mk b/doc/manual/local.mk index ce05c6234..2d730a60e 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -1,42 +1,6 @@ - ifeq ($(doc_generate),yes) -XSLTPROC = $(xsltproc) --nonet $(xmlflags) \ - --param section.autolabel 1 \ - --param section.label.includes.component.label 1 \ - --param xref.with.number.and.title 1 \ - --param toc.section.depth 3 \ - --param admon.style \'\' \ - --param callout.graphics 0 \ - --param contrib.inline.enabled 0 \ - --stringparam generate.toc "book toc" \ - --param keep.relative.image.uris 0 - -docbookxsl = http://docbook.sourceforge.net/release/xsl-ns/current -docbookrng = http://docbook.org/xml/5.0/rng/docbook.rng - -MANUAL_SRCS := $(call rwildcard, $(d), *.xml) - - -# Do XInclude processing / RelaxNG validation -$(d)/manual.xmli: $(d)/manual.xml $(MANUAL_SRCS) $(d)/version.txt - $(trace-gen) $(xmllint) --nonet --xinclude $< -o $@.tmp - @mv $@.tmp $@ - -$(d)/version.txt: - $(trace-gen) echo -n $(PACKAGE_VERSION) > $@ - -# Note: RelaxNG validation requires xmllint >= 2.7.4. -$(d)/manual.is-valid: $(d)/manual.xmli - $(trace-gen) $(XSLTPROC) --novalid --stringparam profile.condition manual \ - $(docbookxsl)/profiling/profile.xsl $< 2> /dev/null | \ - $(xmllint) --nonet --noout --relaxng $(docbookrng) - - @touch $@ - -clean-files += $(d)/manual.xmli $(d)/version.txt $(d)/manual.is-valid - -dist-files += $(d)/manual.xmli $(d)/version.txt $(d)/manual.is-valid - +MANUAL_SRCS := $(call rwildcard, $(d)/src, *.md) # Generate man pages. man-pages := $(foreach n, \ @@ -47,38 +11,23 @@ man-pages := $(foreach n, \ nix.conf.5 nix-daemon.8, \ $(d)/$(n)) -$(firstword $(man-pages)): $(d)/manual.xmli $(d)/manual.is-valid - $(trace-gen) $(XSLTPROC) --novalid --stringparam profile.condition manpage \ - $(docbookxsl)/profiling/profile.xsl $< 2> /dev/null | \ - (cd doc/manual && $(XSLTPROC) $(docbookxsl)/manpages/docbook.xsl -) - -$(wordlist 2, $(words $(man-pages)), $(man-pages)): $(firstword $(man-pages)) - clean-files += $(d)/*.1 $(d)/*.5 $(d)/*.8 dist-files += $(man-pages) +$(d)/%.1: $(d)/src/command-ref/%.md + $(trace-gen) lowdown -sT man $^ -o $@ -# Generate the HTML manual. -$(d)/manual.html: $(d)/manual.xml $(MANUAL_SRCS) $(d)/manual.is-valid - $(trace-gen) $(XSLTPROC) --xinclude --stringparam profile.condition manual \ - $(docbookxsl)/profiling/profile.xsl $< | \ - $(XSLTPROC) --output $@ $(docbookxsl)/xhtml/docbook.xsl - - -$(foreach file, $(d)/manual.html, $(eval $(call install-data-in, $(file), $(docdir)/manual))) - -$(foreach file, $(wildcard $(d)/figures/*.png), $(eval $(call install-data-in, $(file), $(docdir)/manual/figures))) - -$(eval $(call install-symlink, manual.html, $(docdir)/manual/index.html)) +$(d)/%.8: $(d)/src/command-ref/%.md + $(trace-gen) lowdown -sT man $^ -o $@ +$(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md + $(trace-gen) lowdown -sT man $^ -o $@ -all: $(d)/manual.html - - - -clean-files += $(d)/manual.html - -dist-files += $(d)/manual.html +# Generate the HTML manual. +install: $(docdir)/manual/index.html +$(docdir)/manual/index.html: $(MANUAL_SRCS) + $(trace-gen) mdbook build doc/manual -d $(docdir)/manual endif diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml deleted file mode 100644 index 87d9de28a..000000000 --- a/doc/manual/manual.xml +++ /dev/null @@ -1,52 +0,0 @@ -<book 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"> - - <info> - <title>Nix Package Manager Guide</title> - <subtitle>Version <xi:include href="version.txt" parse="text" /></subtitle> - - <author> - <personname> - <firstname>Eelco</firstname> - <surname>Dolstra</surname> - </personname> - <contrib>Author</contrib> - </author> - - <copyright> - <year>2004-2018</year> - <holder>Eelco Dolstra</holder> - </copyright> - - </info> - - <!-- - <preface> - <title>Preface</title> - <para>This manual describes how to set up and use the Nix package - manager.</para> - </preface> - --> - - <xi:include href="introduction/introduction.xml" /> - <xi:include href="installation/installation.xml" /> - <xi:include href="installation/upgrading.xml" /> - <xi:include href="packages/package-management.xml" /> - <xi:include href="expressions/writing-nix-expressions.xml" /> - <xi:include href="advanced-topics/advanced-topics.xml" /> - <xi:include href="command-ref/command-ref.xml" /> - <xi:include href="glossary/glossary.xml" /> - <xi:include href="hacking.xml" /> - <xi:include href="release-notes/release-notes.xml" /> - -<!-- -<appendix> - <title>Nix Release Notes</title> - <xi:include href="release-notes/release-notes.xml" - xpointer="xmlns(x=http://docbook.org/ns/docbook)xpointer(x:article/x:section)" /> - </appendix> ---> - -</book> diff --git a/doc/manual/nix-lang-ref.xml b/doc/manual/nix-lang-ref.xml deleted file mode 100644 index 86273ac3d..000000000 --- a/doc/manual/nix-lang-ref.xml +++ /dev/null @@ -1,182 +0,0 @@ -<appendix> - <title>Nix Language Reference</title> - - <sect1> - <title>Grammar</title> - - <productionset> - <title>Expressions</title> - - <production id="nix.expr"> - <lhs>Expr</lhs> - <rhs> - <nonterminal def="#nix.expr_function" /> - </rhs> - </production> - - <production id="nix.expr_function"> - <lhs>ExprFunction</lhs> - <rhs> - '{' <nonterminal def="#nix.formals" /> '}' ':' <nonterminal def="#nix.expr_function" /> - <sbr />| - <nonterminal def="#nix.expr_assert" /> - </rhs> - </production> - - <production id="nix.expr_assert"> - <lhs>ExprAssert</lhs> - <rhs> - 'assert' <nonterminal def="#nix.expr" /> ';' <nonterminal def="#nix.expr_assert" /> - <sbr />| - <nonterminal def="#nix.expr_if" /> - </rhs> - </production> - - <production id="nix.expr_if"> - <lhs>ExprIf</lhs> - <rhs> - 'if' <nonterminal def="#nix.expr" /> 'then' <nonterminal def="#nix.expr" /> - 'else' <nonterminal def="#nix.expr" /> - <sbr />| - <nonterminal def="#nix.expr_op" /> - </rhs> - </production> - - <production id="nix.expr_op"> - <lhs>ExprOp</lhs> - <rhs> - '!' <nonterminal def="#nix.expr_op" /> - <sbr />| - <nonterminal def="#nix.expr_op" /> '==' <nonterminal def="#nix.expr_op" /> - <sbr />| - <nonterminal def="#nix.expr_op" /> '!=' <nonterminal def="#nix.expr_op" /> - <sbr />| - <nonterminal def="#nix.expr_op" /> '&&' <nonterminal def="#nix.expr_op" /> - <sbr />| - <nonterminal def="#nix.expr_op" /> '||' <nonterminal def="#nix.expr_op" /> - <sbr />| - <nonterminal def="#nix.expr_op" /> '->' <nonterminal def="#nix.expr_op" /> - <sbr />| - <nonterminal def="#nix.expr_op" /> '//' <nonterminal def="#nix.expr_op" /> - <sbr />| - <nonterminal def="#nix.expr_op" /> '~' <nonterminal def="#nix.expr_op" /> - <sbr />| - <nonterminal def="#nix.expr_op" /> '?' <nonterminal def="#nix.id" /> - <sbr />| - <nonterminal def="#nix.expr_app" /> - </rhs> - </production> - - <production id="nix.expr_app"> - <lhs>ExprApp</lhs> - <rhs> - <nonterminal def="#nix.expr_app" /> '.' <nonterminal def="#nix.expr_select" /> - <sbr />| - <nonterminal def="#nix.expr_select" /> - </rhs> - </production> - - <production id="nix.expr_select"> - <lhs>ExprSelect</lhs> - <rhs> - <nonterminal def="#nix.expr_select" /> <nonterminal def="#nix.id" /> - <sbr />| - <nonterminal def="#nix.expr_simple" /> - </rhs> - </production> - - <production id="nix.expr_simple"> - <lhs>ExprSimple</lhs> - <rhs> - <nonterminal def="#nix.id" /> | - <nonterminal def="#nix.int" /> | - <nonterminal def="#nix.str" /> | - <nonterminal def="#nix.path" /> | - <nonterminal def="#nix.uri" /> - <sbr />| - 'true' | 'false' | 'null' - <sbr />| - '(' <nonterminal def="#nix.expr" /> ')' - <sbr />| - '{' <nonterminal def="#nix.bind" />* '}' - <sbr />| - 'let' '{' <nonterminal def="#nix.bind" />* '}' - <sbr />| - 'rec' '{' <nonterminal def="#nix.bind" />* '}' - <sbr />| - '[' <nonterminal def="#nix.expr_select" />* ']' - </rhs> - </production> - - <production id="nix.bind"> - <lhs>Bind</lhs> - <rhs> - <nonterminal def="#nix.id" /> '=' <nonterminal def="#nix.expr" /> ';' - <sbr />| - 'inherit' ('(' <nonterminal def="#nix.expr" /> ')')? <nonterminal def="#nix.id" />* ';' - </rhs> - </production> - - <production id="nix.formals"> - <lhs>Formals</lhs> - <rhs> - <nonterminal def="#nix.formal" /> ',' <nonterminal def="#nix.formals" /> - | <nonterminal def="#nix.formal" /> - </rhs> - </production> - - <production id="nix.formal"> - <lhs>Formal</lhs> - <rhs> - <nonterminal def="#nix.id" /> - <sbr />| - <nonterminal def="#nix.id" /> '?' <nonterminal def="#nix.expr" /> - </rhs> - </production> - - </productionset> - - <productionset> - <title>Terminals</title> - - <production id="nix.id"> - <lhs>Id</lhs> - <rhs>[a-zA-Z\_][a-zA-Z0-9\_\']*</rhs> - </production> - - <production id="nix.int"> - <lhs>Int</lhs> - <rhs>[0-9]+</rhs> - </production> - - <production id="nix.str"> - <lhs>Str</lhs> - <rhs>\"[^\n\"]*\"</rhs> - </production> - - <production id="nix.path"> - <lhs>Path</lhs> - <rhs>[a-zA-Z0-9\.\_\-\+]*(\/[a-zA-Z0-9\.\_\-\+]+)+</rhs> - </production> - - <production id="nix.uri"> - <lhs>Uri</lhs> - <rhs>[a-zA-Z][a-zA-Z0-9\+\-\.]*\:[a-zA-Z0-9\%\/\?\:\@\&\=\+\$\,\-\_\.\!\~\*\']+</rhs> - </production> - - <production id="nix.ws"> - <lhs>Whitespace</lhs> - <rhs> - [ \t\n]+ - <sbr />| - \#[^\n]* - <sbr />| - \/\*(.|\n)*\*\/ - </rhs> - </production> - - </productionset> - - </sect1> - -</appendix> diff --git a/doc/manual/packages/basic-package-mgmt.xml b/doc/manual/packages/basic-package-mgmt.xml deleted file mode 100644 index 0f21297f3..000000000 --- a/doc/manual/packages/basic-package-mgmt.xml +++ /dev/null @@ -1,194 +0,0 @@ -<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="ch-basic-package-mgmt"> - -<title>Basic Package Management</title> - -<para>The main command for package management is <link -linkend="sec-nix-env"><command>nix-env</command></link>. You can use -it to install, upgrade, and erase packages, and to query what -packages are installed or are available for installation.</para> - -<para>In Nix, different users can have different “views” -on the set of installed applications. That is, there might be lots of -applications present on the system (possibly in many different -versions), but users can have a specific selection of those active — -where “active” just means that it appears in a directory -in the user’s <envar>PATH</envar>. Such a view on the set of -installed applications is called a <emphasis>user -environment</emphasis>, which is just a directory tree consisting of -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 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 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, -it’s much more convenient to use the Nixpkgs -<emphasis>channel</emphasis>, since it makes it easy to stay up to -date with new versions of Nixpkgs. (Channels are described in more -detail in <xref linkend="sec-channels"/>.) Nixpkgs is automatically -added to your list of “subscribed” channels when you install -Nix. If this is not the case for some reason, you can add it as -follows: - -<screen> -$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable -$ nix-channel --update -</screen> - -</para> - -<note><para>On NixOS, you’re automatically subscribed to a NixOS -channel corresponding to your NixOS major release -(e.g. <uri>http://nixos.org/channels/nixos-14.12</uri>). A NixOS -channel is identical to the Nixpkgs channel, except that it contains -only Linux binaries and is updated only if a set of regression tests -succeed.</para></note> - -<para>You can view the set of available packages in Nixpkgs: - -<screen> -$ nix-env -qa -aterm-2.2 -bash-3.0 -binutils-2.15 -bison-1.875d -blackdown-1.4.2 -bzip2-1.0.2 -…</screen> - -The flag <option>-q</option> specifies a query operation, and -<option>-a</option> means that you want to show the “available” (i.e., -installable) packages, as opposed to the installed packages. If you -downloaded Nixpkgs yourself, or if you checked it out from GitHub, -then you need to pass the path to your Nixpkgs tree using the -<option>-f</option> flag: - -<screen> -$ nix-env -qaf <replaceable>/path/to/nixpkgs</replaceable> -</screen> - -where <replaceable>/path/to/nixpkgs</replaceable> is where you’ve -unpacked or checked out Nixpkgs.</para> - -<para>You can select specific packages by name: - -<screen> -$ nix-env -qa firefox -firefox-34.0.5 -firefox-with-plugins-34.0.5 -</screen> - -and using regular expressions: - -<screen> -$ nix-env -qa 'firefox.*' -</screen> - -</para> - -<para>It is also possible to see the <emphasis>status</emphasis> of -available packages, i.e., whether they are installed into the user -environment and/or present in the system: - -<screen> -$ nix-env -qas -… --PS bash-3.0 ---S binutils-2.15 -IPS bison-1.875d -…</screen> - -The first character (<literal>I</literal>) indicates whether the -package is installed in your current user environment. The second -(<literal>P</literal>) indicates whether it is present on your system -(in which case installing it into your user environment would be a -very quick operation). The last one (<literal>S</literal>) indicates -whether there is a so-called <emphasis>substitute</emphasis> for the -package, which is Nix’s mechanism for doing binary deployment. It -just means that Nix knows that it can fetch a pre-built package from -somewhere (typically a network server) instead of building it -locally.</para> - -<para>You can install a package using <literal>nix-env -i</literal>. -For instance, - -<screen> -$ nix-env -i subversion</screen> - -will install the package called <literal>subversion</literal> (which -is, of course, the <link -xlink:href='http://subversion.tigris.org/'>Subversion version -management system</link>).</para> - -<note><para>When you ask Nix to install a package, it will first try -to get it in pre-compiled form from a <emphasis>binary -cache</emphasis>. By default, Nix will use the binary cache -<uri>https://cache.nixos.org</uri>; it contains binaries for most -packages in Nixpkgs. Only if no binary is available in the binary -cache, Nix will build the package from source. So if <literal>nix-env --i subversion</literal> results in Nix building stuff from source, -then either the package is not built for your platform by the Nixpkgs -build servers, or your version of Nixpkgs is too old or too new. For -instance, if you have a very recent checkout of Nixpkgs, then the -Nixpkgs build servers may not have had a chance to build everything -and upload the resulting binaries to -<uri>https://cache.nixos.org</uri>. The Nixpkgs channel is only -updated after all binaries have been uploaded to the cache, so if you -stick to the Nixpkgs channel (rather than using a Git checkout of the -Nixpkgs tree), you will get binaries for most packages.</para></note> - -<para>Naturally, packages can also be uninstalled: - -<screen> -$ nix-env -e subversion</screen> - -</para> - -<para>Upgrading to a new version is just as easy. If you have a new -release of Nix Packages, you can do: - -<screen> -$ nix-env -u subversion</screen> - -This will <emphasis>only</emphasis> upgrade Subversion if there is a -“newer” version in the new set of Nix expressions, as -defined by some pretty arbitrary rules regarding ordering of version -numbers (which generally do what you’d expect of them). To just -unconditionally replace Subversion with whatever version is in the Nix -expressions, use <parameter>-i</parameter> instead of -<parameter>-u</parameter>; <parameter>-i</parameter> will remove -whatever version is already installed.</para> - -<para>You can also upgrade all packages for which there are newer -versions: - -<screen> -$ nix-env -u</screen> - -</para> - -<para>Sometimes it’s useful to be able to ask what -<command>nix-env</command> would do, without actually doing it. For -instance, to find out what packages would be upgraded by -<literal>nix-env -u</literal>, you can do - -<screen> -$ nix-env -u --dry-run -(dry run; not doing anything) -upgrading `libxslt-1.1.0' to `libxslt-1.1.10' -upgrading `graphviz-1.10' to `graphviz-1.12' -upgrading `coreutils-5.0' to `coreutils-5.2.1'</screen> - -</para> - -</chapter> diff --git a/doc/manual/packages/binary-cache-substituter.xml b/doc/manual/packages/binary-cache-substituter.xml deleted file mode 100644 index c6ceb9c80..000000000 --- a/doc/manual/packages/binary-cache-substituter.xml +++ /dev/null @@ -1,70 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-binary-cache-substituter"> - -<title>Serving a Nix store via HTTP</title> - -<para>You can easily share the Nix store of a machine via HTTP. This -allows other machines to fetch store paths from that machine to speed -up installations. It uses the same <emphasis>binary cache</emphasis> -mechanism that Nix usually uses to fetch pre-built binaries from -<uri>https://cache.nixos.org</uri>.</para> - -<para>The daemon that handles binary cache requests via HTTP, -<command>nix-serve</command>, is not part of the Nix distribution, but -you can install it from Nixpkgs: - -<screen> -$ nix-env -i nix-serve -</screen> - -You can then start the server, listening for HTTP connections on -whatever port you like: - -<screen> -$ nix-serve -p 8080 -</screen> - -To check whether it works, try the following on the client: - -<screen> -$ curl http://avalon:8080/nix-cache-info -</screen> - -which should print something like: - -<screen> -StoreDir: /nix/store -WantMassQuery: 1 -Priority: 30 -</screen> - -</para> - -<para>On the client side, you can tell Nix to use your binary cache -using <option>--option extra-binary-caches</option>, e.g.: - -<screen> -$ nix-env -i firefox --option extra-binary-caches http://avalon:8080/ -</screen> - -The option <option>extra-binary-caches</option> tells Nix to use this -binary cache in addition to your default caches, such as -<uri>https://cache.nixos.org</uri>. Thus, for any path in the closure -of Firefox, Nix will first check if the path is available on the -server <literal>avalon</literal> or another binary caches. If not, it -will fall back to building from source.</para> - -<para>You can also tell Nix to always use your binary cache by adding -a line to the <filename linkend="sec-conf-file">nix.conf</filename> -configuration file like this: - -<programlisting> -binary-caches = http://avalon:8080/ https://cache.nixos.org/ -</programlisting> - -</para> - -</section> diff --git a/doc/manual/packages/channels.xml b/doc/manual/packages/channels.xml deleted file mode 100644 index 1ed2bba52..000000000 --- a/doc/manual/packages/channels.xml +++ /dev/null @@ -1,60 +0,0 @@ -<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="sec-channels"> - -<title>Channels</title> - -<para>If you want to stay up to date with a set of packages, it’s not -very convenient to manually download the latest set of Nix expressions -for those packages and upgrade using <command>nix-env</command>. -Fortunately, there’s a better way: <emphasis>Nix -channels</emphasis>.</para> - -<para>A Nix channel is just a URL that points to a place that contains -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., - -<screen> -$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable</screen> - -subscribes you to a channel that always contains that latest version -of the Nix Packages collection. (Subscribing really just means that -the URL is added to the file <filename>~/.nix-channels</filename>, -where it is read by subsequent calls to <command>nix-channel ---update</command>.) You can “unsubscribe” using <command>nix-channel ---remove</command>: - -<screen> -$ nix-channel --remove nixpkgs -</screen> -</para> - -<para>To obtain the latest Nix expressions available in a channel, do - -<screen> -$ nix-channel --update</screen> - -This downloads and unpacks the Nix expressions in every channel -(downloaded from <literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal>). -It also makes the union of each channel’s Nix expressions available by -default to <command>nix-env</command> operations (via the symlink -<filename>~/.nix-defexpr/channels</filename>). Consequently, you can -then say - -<screen> -$ nix-env -u</screen> - -to upgrade all packages in your profile to the latest versions -available in the subscribed channels.</para> - -</chapter> diff --git a/doc/manual/packages/copy-closure.xml b/doc/manual/packages/copy-closure.xml deleted file mode 100644 index 012030e3e..000000000 --- a/doc/manual/packages/copy-closure.xml +++ /dev/null @@ -1,50 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-copy-closure"> - -<title>Copying Closures Via SSH</title> - -<para>The command <command -linkend="sec-nix-copy-closure">nix-copy-closure</command> copies a Nix -store path along with all its dependencies to or from another machine -via the SSH protocol. It doesn’t copy store paths that are already -present on the target machine. For example, the following command -copies Firefox with all its dependencies: - -<screen> -$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)</screen> - -See <xref linkend='sec-nix-copy-closure' /> for details.</para> - -<para>With <command linkend='refsec-nix-store-export'>nix-store ---export</command> and <command -linkend='refsec-nix-store-import'>nix-store --import</command> you can -write the closure of a store path (that is, the path and all its -dependencies) to a file, and then unpack that file into another Nix -store. For example, - -<screen> -$ nix-store --export $(nix-store -qR $(type -p firefox)) > firefox.closure</screen> - -writes the closure of Firefox to a file. You can then copy this file -to another machine and install the closure: - -<screen> -$ nix-store --import < firefox.closure</screen> - -Any store paths in the closure that are already present in the target -store are ignored. It is also possible to pipe the export into -another command, e.g. to copy and install a closure directly to/on -another machine: - -<screen> -$ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \ - ssh alice@itchy.example.org "bunzip2 | nix-store --import"</screen> - -However, <command>nix-copy-closure</command> is generally more -efficient because it only copies paths that are not already present in -the target Nix store.</para> - -</section> diff --git a/doc/manual/packages/garbage-collection.xml b/doc/manual/packages/garbage-collection.xml deleted file mode 100644 index b506f22b0..000000000 --- a/doc/manual/packages/garbage-collection.xml +++ /dev/null @@ -1,86 +0,0 @@ -<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='sec-garbage-collection'> - -<title>Garbage Collection</title> - -<para><command>nix-env</command> operations such as upgrades -(<option>-u</option>) and uninstall (<option>-e</option>) never -actually delete packages from the system. All they do (as shown -above) is to create a new user environment that no longer contains -symlinks to the “deleted” packages.</para> - -<para>Of course, since disk space is not infinite, unused packages -should be removed at some point. You can do this by running the Nix -garbage collector. It will remove from the Nix store any package -not used (directly or indirectly) by any generation of any -profile.</para> - -<para>Note however that as long as old generations reference a -package, it will not be deleted. After all, we wouldn’t be able to -do a rollback otherwise. So in order for garbage collection to be -effective, you should also delete (some) old generations. Of course, -this should only be done if you are certain that you will not need to -roll back.</para> - -<para>To delete all old (non-current) generations of your current -profile: - -<screen> -$ nix-env --delete-generations old</screen> - -Instead of <literal>old</literal> you can also specify a list of -generations, e.g., - -<screen> -$ nix-env --delete-generations 10 11 14</screen> - -To delete all generations older than a specified number of days -(except the current generation), use the <literal>d</literal> -suffix. For example, - -<screen> -$ nix-env --delete-generations 14d</screen> - -deletes all generations older than two weeks.</para> - -<para>After removing appropriate old generations you can run the -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> -(default: false) options in the Nix configuration file. The defaults will ensure -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 -be deleted: - -<screen> -$ nix-store --gc --print-dead</screen> - -Likewise, the option <option>--print-live</option> will show the paths -that <emphasis>won’t</emphasis> be deleted.</para> - -<para>There is also a convenient little utility -<command>nix-collect-garbage</command>, which when invoked with the -<option>-d</option> (<option>--delete-old</option>) switch deletes all -old generations of all profiles in -<filename>/nix/var/nix/profiles</filename>. So - -<screen> -$ nix-collect-garbage -d</screen> - -is a quick and easy way to clean up your system.</para> - -<xi:include href="garbage-collector-roots.xml" /> - -</chapter> diff --git a/doc/manual/packages/garbage-collector-roots.xml b/doc/manual/packages/garbage-collector-roots.xml deleted file mode 100644 index 8338e5392..000000000 --- a/doc/manual/packages/garbage-collector-roots.xml +++ /dev/null @@ -1,29 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-gc-roots"> - -<title>Garbage Collector Roots</title> - -<para>The roots of the garbage collector are all store paths to which -there are symlinks in the directory -<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>. -For instance, the following command makes the path -<filename>/nix/store/d718ef...-foo</filename> a root of the collector: - -<screen> -$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar</screen> - -That is, after this command, the garbage collector will not remove -<filename>/nix/store/d718ef...-foo</filename> or any of its -dependencies.</para> - -<para>Subdirectories of -<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename> -are also searched for symlinks. Symlinks to non-store paths are -followed and searched for roots, but symlinks to non-store paths -<emphasis>inside</emphasis> the paths reached in that way are not -followed to prevent infinite recursion.</para> - -</section>
\ No newline at end of file diff --git a/doc/manual/packages/package-management.xml b/doc/manual/packages/package-management.xml deleted file mode 100644 index 61e55faeb..000000000 --- a/doc/manual/packages/package-management.xml +++ /dev/null @@ -1,23 +0,0 @@ -<part 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-package-management'> - -<title>Package Management</title> - -<partintro> -<para>This chapter discusses how to do package management with Nix, -i.e., how to obtain, install, upgrade, and erase packages. This is -the “user’s” perspective of the Nix system — people -who want to <emphasis>create</emphasis> packages should consult -<xref linkend='chap-writing-nix-expressions' />.</para> -</partintro> - -<xi:include href="basic-package-mgmt.xml" /> -<xi:include href="profiles.xml" /> -<xi:include href="garbage-collection.xml" /> -<xi:include href="channels.xml" /> -<xi:include href="sharing-packages.xml" /> - -</part> diff --git a/doc/manual/packages/profiles.xml b/doc/manual/packages/profiles.xml deleted file mode 100644 index 4d10319ab..000000000 --- a/doc/manual/packages/profiles.xml +++ /dev/null @@ -1,158 +0,0 @@ -<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="sec-profiles"> - -<title>Profiles</title> - -<para>Profiles and user environments are Nix’s mechanism for -implementing the ability to allow different users to have different -configurations, and to do atomic upgrades and rollbacks. To -understand how they work, it’s useful to know a bit about how Nix -works. In Nix, packages are stored in unique locations in the -<emphasis>Nix store</emphasis> (typically, -<filename>/nix/store</filename>). For instance, a particular version -of the Subversion package might be stored in a directory -<filename>/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/</filename>, -while another version might be stored in -<filename>/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2</filename>. -The long strings prefixed to the directory names are cryptographic -hashes<footnote><para>160-bit truncations of SHA-256 hashes encoded in -a base-32 notation, to be precise.</para></footnote> of -<emphasis>all</emphasis> inputs involved in building the package — -sources, dependencies, compiler flags, and so on. So if two -packages differ in any way, they end up in different locations in -the file system, so they don’t interfere with each other. <xref -linkend='fig-user-environments' /> shows a part of a typical Nix -store.</para> - -<figure xml:id='fig-user-environments'><title>User environments</title> - <mediaobject> - <imageobject> - <imagedata fileref='../figures/user-environments.png' format='PNG' /> - </imageobject> - </mediaobject> -</figure> - -<para>Of course, you wouldn’t want to type - -<screen> -$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn</screen> - -every time you want to run Subversion. Of course we could set up the -<envar>PATH</envar> environment variable to include the -<filename>bin</filename> directory of every package we want to use, -but this is not very convenient since changing <envar>PATH</envar> -doesn’t take effect for already existing processes. The solution Nix -uses is to create directory trees of symlinks to -<emphasis>activated</emphasis> packages. These are called -<emphasis>user environments</emphasis> and they are packages -themselves (though automatically generated by -<command>nix-env</command>), so they too reside in the Nix store. For -instance, in <xref linkend='fig-user-environments' /> the user -environment <filename>/nix/store/0c1p5z4kda11...-user-env</filename> -contains a symlink to just Subversion 1.1.2 (arrows in the figure -indicate symlinks). This would be what we would obtain if we had done - -<screen> -$ nix-env -i subversion</screen> - -on a set of Nix expressions that contained Subversion 1.1.2.</para> - -<para>This doesn’t in itself solve the problem, of course; you -wouldn’t want to type -<filename>/nix/store/0c1p5z4kda11...-user-env/bin/svn</filename> -either. That’s why there are symlinks outside of the store that point -to the user environments in the store; for instance, the symlinks -<filename>default-42-link</filename> and -<filename>default-43-link</filename> in the example. These are called -<emphasis>generations</emphasis> since every time you perform a -<command>nix-env</command> operation, a new user environment is -generated based on the current one. For instance, generation 43 was -created from generation 42 when we did - -<screen> -$ nix-env -i subversion firefox</screen> - -on a set of Nix expressions that contained Firefox and a new version -of Subversion.</para> - -<para>Generations are grouped together into -<emphasis>profiles</emphasis> so that different users don’t interfere -with each other if they don’t want to. For example: - -<screen> -$ ls -l /nix/var/nix/profiles/ -... -lrwxrwxrwx 1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env -lrwxrwxrwx 1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env -lrwxrwxrwx 1 eelco ... default -> default-43-link</screen> - -This shows a profile called <filename>default</filename>. The file -<filename>default</filename> itself is actually a symlink that points -to the current generation. When we do a <command>nix-env</command> -operation, a new user environment and generation link are created -based on the current one, and finally the <filename>default</filename> -symlink is made to point at the new generation. This last step is -atomic on Unix, which explains how we can do atomic upgrades. (Note -that the building/installing of new packages doesn’t interfere in -any way with old packages, since they are stored in different -locations in the Nix store.)</para> - -<para>If you find that you want to undo a <command>nix-env</command> -operation, you can just do - -<screen> -$ nix-env --rollback</screen> - -which will just make the current generation link point at the previous -link. E.g., <filename>default</filename> would be made to point at -<filename>default-42-link</filename>. You can also switch to a -specific generation: - -<screen> -$ nix-env --switch-generation 43</screen> - -which in this example would roll forward to generation 43 again. You -can also see all available generations: - -<screen> -$ nix-env --list-generations</screen></para> - -<para>You generally wouldn’t have -<filename>/nix/var/nix/profiles/<replaceable>some-profile</replaceable>/bin</filename> -in your <envar>PATH</envar>. Rather, there is a symlink -<filename>~/.nix-profile</filename> that points to your current -profile. This means that you should put -<filename>~/.nix-profile/bin</filename> in your <envar>PATH</envar> -(and indeed, that’s what the initialisation script -<filename>/nix/etc/profile.d/nix.sh</filename> does). This makes it -easier to switch to a different profile. You can do that using the -command <command>nix-env --switch-profile</command>: - -<screen> -$ nix-env --switch-profile /nix/var/nix/profiles/my-profile - -$ nix-env --switch-profile /nix/var/nix/profiles/default</screen> - -These commands switch to the <filename>my-profile</filename> and -default profile, respectively. If the profile doesn’t exist, it will -be created automatically. You should be careful about storing a -profile in another location than the <filename>profiles</filename> -directory, since otherwise it might not be used as a root of the -garbage collector (see <xref linkend='sec-garbage-collection' -/>).</para> - -<para>All <command>nix-env</command> operations work on the profile -pointed to by <command>~/.nix-profile</command>, but you can override -this using the <option>--profile</option> option (abbreviation -<option>-p</option>): - -<screen> -$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion</screen> - -This will <emphasis>not</emphasis> change the -<command>~/.nix-profile</command> symlink.</para> - -</chapter> diff --git a/doc/manual/packages/s3-substituter.xml b/doc/manual/packages/s3-substituter.xml deleted file mode 100644 index 868b5a66d..000000000 --- a/doc/manual/packages/s3-substituter.xml +++ /dev/null @@ -1,182 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<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-s3-substituter"> - -<title>Serving a Nix store via AWS S3 or S3-compatible Service</title> - -<para>Nix has built-in support for storing and fetching store paths -from Amazon S3 and S3 compatible services. This uses the same -<emphasis>binary</emphasis> cache mechanism that Nix usually uses to -fetch prebuilt binaries from <uri>cache.nixos.org</uri>.</para> - -<para>The following options can be specified as URL parameters to -the S3 URL:</para> - -<variablelist> - <varlistentry><term><literal>profile</literal></term> - <listitem> - <para> - The name of the AWS configuration profile to use. By default - Nix will use the <literal>default</literal> profile. - </para> - </listitem> - </varlistentry> - - <varlistentry><term><literal>region</literal></term> - <listitem> - <para> - The region of the S3 bucket. <literal>us–east-1</literal> by - default. - </para> - - <para> - If your bucket is not in <literal>us–east-1</literal>, you - should always explicitly specify the region parameter. - </para> - </listitem> - </varlistentry> - - <varlistentry><term><literal>endpoint</literal></term> - <listitem> - <para> - The URL to your S3-compatible service, for when not using - Amazon S3. Do not specify this value if you're using Amazon - S3. - </para> - <note><para>This endpoint must support HTTPS and will use - path-based addressing instead of virtual host based - addressing.</para></note> - </listitem> - </varlistentry> - - <varlistentry><term><literal>scheme</literal></term> - <listitem> - <para> - The scheme used for S3 requests, <literal>https</literal> - (default) or <literal>http</literal>. This option allows you to - disable HTTPS for binary caches which don't support it. - </para> - <note><para>HTTPS should be used if the cache might contain - sensitive information.</para></note> - </listitem> - </varlistentry> -</variablelist> - -<para>In this example we will use the bucket named -<literal>example-nix-cache</literal>.</para> - -<section xml:id="ssec-s3-substituter-anonymous-reads"> - <title>Anonymous Reads to your S3-compatible binary cache</title> - - <para>If your binary cache is publicly accessible and does not - require authentication, the simplest and easiest way to use Nix with - your S3 compatible binary cache is to use the HTTP URL for that - cache.</para> - - <para>For AWS S3 the binary cache URL for example bucket will be - exactly <uri>https://example-nix-cache.s3.amazonaws.com</uri> or - <uri>s3://example-nix-cache</uri>. For S3 compatible binary caches, - consult that cache's documentation.</para> - - <para>Your bucket will need the following bucket policy:</para> - - <programlisting><![CDATA[ -{ - "Id": "DirectReads", - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "AllowDirectReads", - "Action": [ - "s3:GetObject", - "s3:GetBucketLocation" - ], - "Effect": "Allow", - "Resource": [ - "arn:aws:s3:::example-nix-cache", - "arn:aws:s3:::example-nix-cache/*" - ], - "Principal": "*" - } - ] -} -]]></programlisting> -</section> - -<section xml:id="ssec-s3-substituter-authenticated-reads"> - <title>Authenticated Reads to your S3 binary cache</title> - - <para>For AWS S3 the binary cache URL for example bucket will be - exactly <uri>s3://example-nix-cache</uri>.</para> - - <para>Nix will use the <link - 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> - - <para>Nix supports authenticated reads from Amazon S3 and S3 - compatible binary caches.</para> - - <para>Your bucket will need a bucket policy allowing the desired - users to perform the <literal>s3:GetObject</literal> and - <literal>s3:GetBucketLocation</literal> action on all objects in the - bucket. The anonymous policy in <xref - linkend="ssec-s3-substituter-anonymous-reads" /> can be updated to - have a restricted <literal>Principal</literal> to support - this.</para> -</section> - - -<section xml:id="ssec-s3-substituter-authenticated-writes"> - <title>Authenticated Writes to your S3-compatible binary cache</title> - - <para>Nix support fully supports writing to Amazon S3 and S3 - compatible buckets. The binary cache URL for our example bucket will - be <uri>s3://example-nix-cache</uri>.</para> - - <para>Nix will use the <link - 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> - - <para>Your account will need the following IAM policy to - upload to the cache:</para> - - <programlisting><![CDATA[ -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "UploadToCache", - "Effect": "Allow", - "Action": [ - "s3:AbortMultipartUpload", - "s3:GetBucketLocation", - "s3:GetObject", - "s3:ListBucket", - "s3:ListBucketMultipartUploads", - "s3:ListMultipartUploadParts", - "s3:PutObject" - ], - "Resource": [ - "arn:aws:s3:::example-nix-cache", - "arn:aws:s3:::example-nix-cache/*" - ] - } - ] -} -]]></programlisting> - - - <example><title>Uploading with a specific credential profile for Amazon S3</title> - <para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&region=eu-west-2' nixpkgs.hello</command></para> - </example> - - <example><title>Uploading to an S3-Compatible Binary Cache</title> - <para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' nixpkgs.hello</command></para> - </example> -</section> -</section> diff --git a/doc/manual/packages/sharing-packages.xml b/doc/manual/packages/sharing-packages.xml deleted file mode 100644 index bb6c52b8f..000000000 --- a/doc/manual/packages/sharing-packages.xml +++ /dev/null @@ -1,20 +0,0 @@ -<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="sec-sharing-packages"> - -<title>Sharing Packages Between Machines</title> - -<para>Sometimes you want to copy a package from one machine to -another. Or, you want to install some packages and you know that -another machine already has some or all of those packages or their -dependencies. In that case there are mechanisms to quickly copy -packages between machines.</para> - -<xi:include href="binary-cache-substituter.xml" /> -<xi:include href="copy-closure.xml" /> -<xi:include href="ssh-substituter.xml" /> -<xi:include href="s3-substituter.xml" /> - -</chapter> diff --git a/doc/manual/packages/ssh-substituter.xml b/doc/manual/packages/ssh-substituter.xml deleted file mode 100644 index 8db3f9662..000000000 --- a/doc/manual/packages/ssh-substituter.xml +++ /dev/null @@ -1,73 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-ssh-substituter"> - -<title>Serving a Nix store via SSH</title> - -<para>You can tell Nix to automatically fetch needed binaries from a -remote Nix store via SSH. For example, the following installs Firefox, -automatically fetching any store paths in Firefox’s closure if they -are available on the server <literal>avalon</literal>: - -<screen> -$ nix-env -i firefox --substituters ssh://alice@avalon -</screen> - -This works similar to the binary cache substituter that Nix usually -uses, only using SSH instead of HTTP: if a store path -<literal>P</literal> is needed, Nix will first check if it’s available -in the Nix store on <literal>avalon</literal>. If not, it will fall -back to using the binary cache substituter, and then to building from -source.</para> - -<note><para>The SSH substituter currently does not allow you to enter -an SSH passphrase interactively. Therefore, you should use -<command>ssh-add</command> to load the decrypted private key into -<command>ssh-agent</command>.</para></note> - -<para>You can also copy the closure of some store path, without -installing it into your profile, e.g. - -<screen> -$ nix-store -r /nix/store/m85bxg…-firefox-34.0.5 --substituters ssh://alice@avalon -</screen> - -This is essentially equivalent to doing - -<screen> -$ nix-copy-closure --from alice@avalon /nix/store/m85bxg…-firefox-34.0.5 -</screen> - -</para> - -<para>You can use SSH’s <emphasis>forced command</emphasis> feature to -set up a restricted user account for SSH substituter access, allowing -read-only access to the local Nix store, but nothing more. For -example, add the following lines to <filename>sshd_config</filename> -to restrict the user <literal>nix-ssh</literal>: - -<programlisting> -Match User nix-ssh - AllowAgentForwarding no - AllowTcpForwarding no - PermitTTY no - PermitTunnel no - X11Forwarding no - ForceCommand nix-store --serve -Match All -</programlisting> - -On NixOS, you can accomplish the same by adding the following to your -<filename>configuration.nix</filename>: - -<programlisting> -nix.sshServe.enable = true; -nix.sshServe.keys = [ "ssh-dss AAAAB3NzaC1k... bob@example.org" ]; -</programlisting> - -where the latter line lists the public keys of users that are allowed -to connect.</para> - -</section> diff --git a/doc/manual/release-notes/release-notes.xml b/doc/manual/release-notes/release-notes.xml deleted file mode 100644 index 2655d68e3..000000000 --- a/doc/manual/release-notes/release-notes.xml +++ /dev/null @@ -1,51 +0,0 @@ -<appendix 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="sec-relnotes"> - -<title>Nix Release Notes</title> - -<!-- -<partintro> -<para>This section lists the release notes for each stable version of Nix.</para> -</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" /> -<xi:include href="rl-1.11.10.xml" /> -<xi:include href="rl-1.11.xml" /> -<xi:include href="rl-1.10.xml" /> -<xi:include href="rl-1.9.xml" /> -<xi:include href="rl-1.8.xml" /> -<xi:include href="rl-1.7.xml" /> -<xi:include href="rl-1.6.1.xml" /> -<xi:include href="rl-1.6.xml" /> -<xi:include href="rl-1.5.2.xml" /> -<xi:include href="rl-1.5.xml" /> -<xi:include href="rl-1.4.xml" /> -<xi:include href="rl-1.3.xml" /> -<xi:include href="rl-1.2.xml" /> -<xi:include href="rl-1.1.xml" /> -<xi:include href="rl-1.0.xml" /> -<xi:include href="rl-0.16.xml" /> -<xi:include href="rl-0.15.xml" /> -<xi:include href="rl-0.14.xml" /> -<xi:include href="rl-0.13.xml" /> -<xi:include href="rl-0.12.xml" /> -<xi:include href="rl-0.11.xml" /> -<xi:include href="rl-0.10.1.xml" /> -<xi:include href="rl-0.10.xml" /> -<xi:include href="rl-0.9.2.xml" /> -<xi:include href="rl-0.9.1.xml" /> -<xi:include href="rl-0.9.xml" /> -<xi:include href="rl-0.8.1.xml" /> -<xi:include href="rl-0.8.xml" /> -<xi:include href="rl-0.7.xml" /> -<xi:include href="rl-0.6.xml" /> -<xi:include href="rl-0.5.xml" /> - -</appendix> diff --git a/doc/manual/release-notes/rl-0.10.1.xml b/doc/manual/release-notes/rl-0.10.1.xml deleted file mode 100644 index 95829323d..000000000 --- a/doc/manual/release-notes/rl-0.10.1.xml +++ /dev/null @@ -1,13 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-relnotes-0.10.1"> - -<title>Release 0.10.1 (2006-10-11)</title> - -<para>This release fixes two somewhat obscure bugs that occur when -evaluating Nix expressions that are stored inside the Nix store -(<literal>NIX-67</literal>). These do not affect most users.</para> - -</section> diff --git a/doc/manual/release-notes/rl-0.10.xml b/doc/manual/release-notes/rl-0.10.xml deleted file mode 100644 index 9afec4de9..000000000 --- a/doc/manual/release-notes/rl-0.10.xml +++ /dev/null @@ -1,323 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-relnotes-0.10"> - -<title>Release 0.10 (2006-10-06)</title> - -<note><para>This version of Nix uses Berkeley DB 4.4 instead of 4.3. -The database is upgraded automatically, but you should be careful not -to use old versions of Nix that still use Berkeley DB 4.3. In -particular, if you use a Nix installed through Nix, you should run - -<screen> -$ nix-store --clear-substitutes</screen> - -first.</para></note> - -<warning><para>Also, the database schema has changed slighted to fix a -performance issue (see below). When you run any Nix 0.10 command for -the first time, the database will be upgraded automatically. This is -irreversible.</para></warning> - -<itemizedlist> - - - <!-- Usability / features --> - - - <listitem><para><command>nix-env</command> usability improvements: - - <itemizedlist> - - <listitem><para>An option <option>--compare-versions</option> - (or <option>-c</option>) has been added to <command>nix-env - --query</command> to allow you to compare installed versions of - packages to available versions, or vice versa. An easy way to - see if you are up to date with what’s in your subscribed - channels is <literal>nix-env -qc \*</literal>.</para></listitem> - - <listitem><para><literal>nix-env --query</literal> now takes as - arguments a list of package names about which to show - information, just like <option>--install</option>, etc.: for - example, <literal>nix-env -q gcc</literal>. Note that to show - all derivations, you need to specify - <literal>\*</literal>.</para></listitem> - - <listitem><para><literal>nix-env -i - <replaceable>pkgname</replaceable></literal> will now install - the highest available version of - <replaceable>pkgname</replaceable>, rather than installing all - available versions (which would probably give collisions) - (<literal>NIX-31</literal>).</para></listitem> - - <listitem><para><literal>nix-env (-i|-u) --dry-run</literal> now - shows exactly which missing paths will be built or - substituted.</para></listitem> - - <listitem><para><literal>nix-env -qa --description</literal> - shows human-readable descriptions of packages, provided that - they have a <literal>meta.description</literal> attribute (which - most packages in Nixpkgs don’t have yet).</para></listitem> - - </itemizedlist> - - </para></listitem> - - - <listitem><para>New language features: - - <itemizedlist> - - <listitem><para>Reference scanning (which happens after each - build) is much faster and takes a constant amount of - memory.</para></listitem> - - <listitem><para>String interpolation. Expressions like - -<programlisting> -"--with-freetype2-library=" + freetype + "/lib"</programlisting> - - can now be written as - -<programlisting> -"--with-freetype2-library=${freetype}/lib"</programlisting> - - You can write arbitrary expressions within - <literal>${<replaceable>...</replaceable>}</literal>, not just - identifiers.</para></listitem> - - <listitem><para>Multi-line string literals.</para></listitem> - - <listitem><para>String concatenations can now involve - derivations, as in the example <code>"--with-freetype2-library=" - + freetype + "/lib"</code>. This was not previously possible - because we need to register that a derivation that uses such a - string is dependent on <literal>freetype</literal>. The - evaluator now properly propagates this information. - Consequently, the subpath operator (<literal>~</literal>) has - been deprecated.</para></listitem> - - <listitem><para>Default values of function arguments can now - refer to other function arguments; that is, all arguments are in - scope in the default values - (<literal>NIX-45</literal>).</para></listitem> - - <!-- - <listitem><para>TODO: domain checks (r5895).</para></listitem> - --> - - <listitem><para>Lots of new built-in primitives, such as - functions for list manipulation and integer arithmetic. See the - manual for a complete list. All primops are now available in - the set <varname>builtins</varname>, allowing one to test for - the availability of primop in a backwards-compatible - way.</para></listitem> - - <listitem><para>Real let-expressions: <literal>let x = ...; - ... z = ...; in ...</literal>.</para></listitem> - - </itemizedlist> - - </para></listitem> - - - <listitem><para>New commands <command>nix-pack-closure</command> and - <command>nix-unpack-closure</command> than can be used to easily - transfer a store path with all its dependencies to another machine. - Very convenient whenever you have some package on your machine and - you want to copy it somewhere else.</para></listitem> - - - <listitem><para>XML support: - - <itemizedlist> - - <listitem><para><literal>nix-env -q --xml</literal> prints the - installed or available packages in an XML representation for - easy processing by other tools.</para></listitem> - - <listitem><para><literal>nix-instantiate --eval-only - --xml</literal> prints an XML representation of the resulting - term. (The new flag <option>--strict</option> forces ‘deep’ - evaluation of the result, i.e., list elements and attributes are - evaluated recursively.)</para></listitem> - - <listitem><para>In Nix expressions, the primop - <function>builtins.toXML</function> converts a term to an XML - representation. This is primarily useful for passing structured - information to builders.</para></listitem> - - </itemizedlist> - - </para></listitem> - - - <listitem><para>You can now unambiguously specify which derivation to - build or install in <command>nix-env</command>, - <command>nix-instantiate</command> and <command>nix-build</command> - using the <option>--attr</option> / <option>-A</option> flags, which - takes an attribute name as argument. (Unlike symbolic package names - such as <literal>subversion-1.4.0</literal>, attribute names in an - attribute set are unique.) For instance, a quick way to perform a - test build of a package in Nixpkgs is <literal>nix-build - pkgs/top-level/all-packages.nix -A - <replaceable>foo</replaceable></literal>. <literal>nix-env -q - --attr</literal> shows the attribute names corresponding to each - derivation.</para></listitem> - - - <listitem><para>If the top-level Nix expression used by - <command>nix-env</command>, <command>nix-instantiate</command> or - <command>nix-build</command> evaluates to a function whose arguments - all have default values, the function will be called automatically. - Also, the new command-line switch <option>--arg - <replaceable>name</replaceable> - <replaceable>value</replaceable></option> can be used to specify - function arguments on the command line.</para></listitem> - - - <listitem><para><literal>nix-install-package --url - <replaceable>URL</replaceable></literal> allows a package to be - installed directly from the given URL.</para></listitem> - - - <listitem><para>Nix now works behind an HTTP proxy server; just set - the standard environment variables <envar>http_proxy</envar>, - <envar>https_proxy</envar>, <envar>ftp_proxy</envar> or - <envar>all_proxy</envar> appropriately. Functions such as - <function>fetchurl</function> in Nixpkgs also respect these - variables.</para></listitem> - - - <listitem><para><literal>nix-build -o - <replaceable>symlink</replaceable></literal> allows the symlink to - the build result to be named something other than - <literal>result</literal>.</para></listitem> - - - <!-- Stability / performance / etc. --> - - - <listitem><para>Platform support: - - <itemizedlist> - - <listitem><para>Support for 64-bit platforms, provided a <link - xlink:href="http://bugzilla.sen.cwi.nl:8080/show_bug.cgi?id=606">suitably - patched ATerm library</link> is used. Also, files larger than 2 - GiB are now supported.</para></listitem> - - <listitem><para>Added support for Cygwin (Windows, - <literal>i686-cygwin</literal>), Mac OS X on Intel - (<literal>i686-darwin</literal>) and Linux on PowerPC - (<literal>powerpc-linux</literal>).</para></listitem> - - <listitem><para>Users of SMP and multicore machines will - appreciate that the number of builds to be performed in parallel - can now be specified in the configuration file in the - <literal>build-max-jobs</literal> setting.</para></listitem> - - </itemizedlist> - - </para></listitem> - - - <listitem><para>Garbage collector improvements: - - <itemizedlist> - - <listitem><para>Open files (such as running programs) are now - used as roots of the garbage collector. This prevents programs - that have been uninstalled from being garbage collected while - they are still running. The script that detects these - additional runtime roots - (<filename>find-runtime-roots.pl</filename>) is inherently - system-specific, but it should work on Linux and on all - platforms that have the <command>lsof</command> - utility.</para></listitem> - - <listitem><para><literal>nix-store --gc</literal> - (a.k.a. <command>nix-collect-garbage</command>) prints out the - number of bytes freed on standard output. <literal>nix-store - --gc --print-dead</literal> shows how many bytes would be freed - by an actual garbage collection.</para></listitem> - - <listitem><para><literal>nix-collect-garbage -d</literal> - removes all old generations of <emphasis>all</emphasis> profiles - before calling the actual garbage collector (<literal>nix-store - --gc</literal>). This is an easy way to get rid of all old - packages in the Nix store.</para></listitem> - - <listitem><para><command>nix-store</command> now has an - operation <option>--delete</option> to delete specific paths - from the Nix store. It won’t delete reachable (non-garbage) - paths unless <option>--ignore-liveness</option> is - specified.</para></listitem> - - </itemizedlist> - - </para></listitem> - - - <listitem><para>Berkeley DB 4.4’s process registry feature is used - to recover from crashed Nix processes.</para></listitem> - - <!-- <listitem><para>TODO: shared stores.</para></listitem> --> - - <listitem><para>A performance issue has been fixed with the - <literal>referer</literal> table, which stores the inverse of the - <literal>references</literal> table (i.e., it tells you what store - paths refer to a given path). Maintaining this table could take a - quadratic amount of time, as well as a quadratic amount of Berkeley - DB log file space (in particular when running the garbage collector) - (<literal>NIX-23</literal>).</para></listitem> - - <listitem><para>Nix now catches the <literal>TERM</literal> and - <literal>HUP</literal> signals in addition to the - <literal>INT</literal> signal. So you can now do a <literal>killall - nix-store</literal> without triggering a database - recovery.</para></listitem> - - <listitem><para><command>bsdiff</command> updated to version - 4.3.</para></listitem> - - <listitem><para>Substantial performance improvements in expression - evaluation and <literal>nix-env -qa</literal>, all thanks to <link - xlink:href="http://valgrind.org/">Valgrind</link>. Memory use has - been reduced by a factor 8 or so. Big speedup by memoisation of - path hashing.</para></listitem> - - <listitem><para>Lots of bug fixes, notably: - - <itemizedlist> - - <listitem><para>Make sure that the garbage collector can run - successfully when the disk is full - (<literal>NIX-18</literal>).</para></listitem> - - <listitem><para><command>nix-env</command> now locks the profile - to prevent races between concurrent <command>nix-env</command> - operations on the same profile - (<literal>NIX-7</literal>).</para></listitem> - - <listitem><para>Removed misleading messages from - <literal>nix-env -i</literal> (e.g., <literal>installing - `foo'</literal> followed by <literal>uninstalling - `foo'</literal>) (<literal>NIX-17</literal>).</para></listitem> - - </itemizedlist> - - </para></listitem> - - <listitem><para>Nix source distributions are a lot smaller now since - we no longer include a full copy of the Berkeley DB source - distribution (but only the bits we need).</para></listitem> - - <listitem><para>Header files are now installed so that external - programs can use the Nix libraries.</para></listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-0.11.xml b/doc/manual/release-notes/rl-0.11.xml deleted file mode 100644 index 7ad0ab5b7..000000000 --- a/doc/manual/release-notes/rl-0.11.xml +++ /dev/null @@ -1,261 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-0.11"> - -<title>Release 0.11 (2007-12-31)</title> - -<para>Nix 0.11 has many improvements over the previous stable release. -The most important improvement is secure multi-user support. It also -features many usability enhancements and language extensions, many of -them prompted by NixOS, the purely functional Linux distribution based -on Nix. Here is an (incomplete) list:</para> - - -<itemizedlist> - - - <listitem><para>Secure multi-user support. A single Nix store can - now be shared between multiple (possible untrusted) users. This is - an important feature for NixOS, where it allows non-root users to - install software. The old setuid method for sharing a store between - multiple users has been removed. Details for setting up a - multi-user store can be found in the manual.</para></listitem> - - - <listitem><para>The new command <command>nix-copy-closure</command> - gives you an easy and efficient way to exchange software between - machines. It copies the missing parts of the closure of a set of - store path to or from a remote machine via - <command>ssh</command>.</para></listitem> - - - <listitem><para>A new kind of string literal: strings between double - single-quotes (<literal>''</literal>) have indentation - “intelligently” removed. This allows large strings (such as shell - scripts or configuration file fragments in NixOS) to cleanly follow - the indentation of the surrounding expression. It also requires - much less escaping, since <literal>''</literal> is less common in - most languages than <literal>"</literal>.</para></listitem> - - - <listitem><para><command>nix-env</command> <option>--set</option> - modifies the current generation of a profile so that it contains - exactly the specified derivation, and nothing else. For example, - <literal>nix-env -p /nix/var/nix/profiles/browser --set - firefox</literal> lets the profile named - <filename>browser</filename> contain just Firefox.</para></listitem> - - - <listitem><para><command>nix-env</command> now maintains - meta-information about installed packages in profiles. The - meta-information is the contents of the <varname>meta</varname> - attribute of derivations, such as <varname>description</varname> or - <varname>homepage</varname>. The command <literal>nix-env -q --xml - --meta</literal> shows all meta-information.</para></listitem> - - - <listitem><para><command>nix-env</command> now uses the - <varname>meta.priority</varname> attribute of derivations to resolve - filename collisions between packages. Lower priority values denote - a higher priority. For instance, the GCC wrapper package and the - Binutils package in Nixpkgs both have a file - <filename>bin/ld</filename>, so previously if you tried to install - both you would get a collision. Now, on the other hand, the GCC - wrapper declares a higher priority than Binutils, so the former’s - <filename>bin/ld</filename> is symlinked in the user - environment.</para></listitem> - - - <listitem><para><command>nix-env -i / -u</command>: instead of - breaking package ties by version, break them by priority and version - number. That is, if there are multiple packages with the same name, - then pick the package with the highest priority, and only use the - version if there are multiple packages with the same - priority.</para> - - <para>This makes it possible to mark specific versions/variant in - Nixpkgs more or less desirable than others. A typical example would - be a beta version of some package (e.g., - <literal>gcc-4.2.0rc1</literal>) which should not be installed even - though it is the highest version, except when it is explicitly - selected (e.g., <literal>nix-env -i - gcc-4.2.0rc1</literal>).</para></listitem> - - - <listitem><para><command>nix-env --set-flag</command> allows meta - attributes of installed packages to be modified. There are several - attributes that can be usefully modified, because they affect the - behaviour of <command>nix-env</command> or the user environment - build script: - - <itemizedlist> - - <listitem><para><varname>meta.priority</varname> can be changed - to resolve filename clashes (see above).</para></listitem> - - <listitem><para><varname>meta.keep</varname> can be set to - <literal>true</literal> to prevent the package from being - upgraded or replaced. Useful if you want to hang on to an older - version of a package.</para></listitem> - - <listitem><para><varname>meta.active</varname> can be set to - <literal>false</literal> to “disable” the package. That is, no - symlinks will be generated to the files of the package, but it - remains part of the profile (so it won’t be garbage-collected). - Set it back to <literal>true</literal> to re-enable the - package.</para></listitem> - - </itemizedlist> - - </para></listitem> - - - <listitem><para><command>nix-env -q</command> now has a flag - <option>--prebuilt-only</option> (<option>-b</option>) that causes - <command>nix-env</command> to show only those derivations whose - output is already in the Nix store or that can be substituted (i.e., - downloaded from somewhere). In other words, it shows the packages - that can be installed “quickly”, i.e., don’t need to be built from - source. The <option>-b</option> flag is also available in - <command>nix-env -i</command> and <command>nix-env -u</command> to - filter out derivations for which no pre-built binary is - available.</para></listitem> - - - <listitem><para>The new option <option>--argstr</option> (in - <command>nix-env</command>, <command>nix-instantiate</command> and - <command>nix-build</command>) is like <option>--arg</option>, except - that the value is a string. For example, <literal>--argstr system - i686-linux</literal> is equivalent to <literal>--arg system - \"i686-linux\"</literal> (note that <option>--argstr</option> - prevents annoying quoting around shell arguments).</para></listitem> - - - <listitem><para><command>nix-store</command> has a new operation - <option>--read-log</option> (<option>-l</option>) - <parameter>paths</parameter> that shows the build log of the given - paths.</para></listitem> - - - <!-- - <listitem><para>TODO: semantic cleanups of string concatenation - etc. (mostly in r6740).</para></listitem> - --> - - - <listitem><para>Nix now uses Berkeley DB 4.5. The database is - upgraded automatically, but you should be careful not to use old - versions of Nix that still use Berkeley DB 4.4.</para></listitem> - - - <!-- foo - <listitem><para>TODO: option <option>- -reregister</option> in - <command>nix-store - -register-validity</command>.</para></listitem> - --> - - - <listitem><para>The option <option>--max-silent-time</option> - (corresponding to the configuration setting - <literal>build-max-silent-time</literal>) allows you to set a - timeout on builds — if a build produces no output on - <literal>stdout</literal> or <literal>stderr</literal> for the given - number of seconds, it is terminated. This is useful for recovering - automatically from builds that are stuck in an infinite - loop.</para></listitem> - - - <listitem><para><command>nix-channel</command>: each subscribed - channel is its own attribute in the top-level expression generated - for the channel. This allows disambiguation (e.g. <literal>nix-env - -i -A nixpkgs_unstable.firefox</literal>).</para></listitem> - - - <listitem><para>The substitutes table has been removed from the - database. This makes operations such as <command>nix-pull</command> - and <command>nix-channel --update</command> much, much - faster.</para></listitem> - - - <listitem><para><command>nix-pull</command> now supports - bzip2-compressed manifests. This speeds up - channels.</para></listitem> - - - <listitem><para><command>nix-prefetch-url</command> now has a - limited form of caching. This is used by - <command>nix-channel</command> to prevent unnecessary downloads when - the channel hasn’t changed.</para></listitem> - - - <listitem><para><command>nix-prefetch-url</command> now by default - computes the SHA-256 hash of the file instead of the MD5 hash. In - calls to <function>fetchurl</function> you should pass the - <literal>sha256</literal> attribute instead of - <literal>md5</literal>. You can pass either a hexadecimal or a - base-32 encoding of the hash.</para></listitem> - - - <listitem><para>Nix can now perform builds in an automatically - generated “chroot”. This prevents a builder from accessing stuff - outside of the Nix store, and thus helps ensure purity. This is an - experimental feature.</para></listitem> - - - <listitem><para>The new command <command>nix-store - --optimise</command> reduces Nix store disk space usage by finding - identical files in the store and hard-linking them to each other. - It typically reduces the size of the store by something like - 25-35%.</para></listitem> - - - <listitem><para><filename>~/.nix-defexpr</filename> can now be a - directory, in which case the Nix expressions in that directory are - combined into an attribute set, with the file names used as the - names of the attributes. The command <command>nix-env - --import</command> (which set the - <filename>~/.nix-defexpr</filename> symlink) is - removed.</para></listitem> - - - <listitem><para>Derivations can specify the new special attribute - <varname>allowedReferences</varname> to enforce that the references - in the output of a derivation are a subset of a declared set of - paths. For example, if <varname>allowedReferences</varname> is an - empty list, then the output must not have any references. This is - used in NixOS to check that generated files such as initial ramdisks - for booting Linux don’t have any dependencies.</para></listitem> - - - <listitem><para>The new attribute - <varname>exportReferencesGraph</varname> allows builders access to - the references graph of their inputs. This is used in NixOS for - tasks such as generating ISO-9660 images that contain a Nix store - populated with the closure of certain paths.</para></listitem> - - - <listitem><para>Fixed-output derivations (like - <function>fetchurl</function>) can define the attribute - <varname>impureEnvVars</varname> to allow external environment - variables to be passed to builders. This is used in Nixpkgs to - support proxy configuration, among other things.</para></listitem> - - - <listitem><para>Several new built-in functions: - <function>builtins.attrNames</function>, - <function>builtins.filterSource</function>, - <function>builtins.isAttrs</function>, - <function>builtins.isFunction</function>, - <function>builtins.listToAttrs</function>, - <function>builtins.stringLength</function>, - <function>builtins.sub</function>, - <function>builtins.substring</function>, - <function>throw</function>, - <function>builtins.trace</function>, - <function>builtins.readFile</function>.</para></listitem> - - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-0.12.xml b/doc/manual/release-notes/rl-0.12.xml deleted file mode 100644 index fdba8c4d5..000000000 --- a/doc/manual/release-notes/rl-0.12.xml +++ /dev/null @@ -1,175 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-0.12"> - -<title>Release 0.12 (2008-11-20)</title> - -<itemizedlist> - - <listitem> - <para>Nix no longer uses Berkeley DB to store Nix store metadata. - The principal advantages of the new storage scheme are: it works - properly over decent implementations of NFS (allowing Nix stores - to be shared between multiple machines); no recovery is needed - when a Nix process crashes; no write access is needed for - read-only operations; no more running out of Berkeley DB locks on - certain operations.</para> - - <para>You still need to compile Nix with Berkeley DB support if - you want Nix to automatically convert your old Nix store to the - new schema. If you don’t need this, you can build Nix with the - <filename>configure</filename> option - <option>--disable-old-db-compat</option>.</para> - - <para>After the automatic conversion to the new schema, you can - delete the old Berkeley DB files: - - <screen> -$ cd /nix/var/nix/db -$ rm __db* log.* derivers references referrers reserved validpaths DB_CONFIG</screen> - - The new metadata is stored in the directories - <filename>/nix/var/nix/db/info</filename> and - <filename>/nix/var/nix/db/referrer</filename>. Though the - metadata is stored in human-readable plain-text files, they are - not intended to be human-editable, as Nix is rather strict about - the format.</para> - - <para>The new storage schema may or may not require less disk - space than the Berkeley DB environment, mostly depending on the - cluster size of your file system. With 1 KiB clusters (which - seems to be the <literal>ext3</literal> default nowadays) it - usually takes up much less space.</para> - </listitem> - - <listitem><para>There is a new substituter that copies paths - directly from other (remote) Nix stores mounted somewhere in the - filesystem. For instance, you can speed up an installation by - mounting some remote Nix store that already has the packages in - question via NFS or <literal>sshfs</literal>. The environment - variable <envar>NIX_OTHER_STORES</envar> specifies the locations of - the remote Nix directories, - e.g. <literal>/mnt/remote-fs/nix</literal>.</para></listitem> - - <listitem><para>New <command>nix-store</command> operations - <option>--dump-db</option> and <option>--load-db</option> to dump - and reload the Nix database.</para></listitem> - - <listitem><para>The garbage collector has a number of new options to - allow only some of the garbage to be deleted. The option - <option>--max-freed <replaceable>N</replaceable></option> tells the - collector to stop after at least <replaceable>N</replaceable> bytes - have been deleted. The option <option>--max-links - <replaceable>N</replaceable></option> tells it to stop after the - link count on <filename>/nix/store</filename> has dropped below - <replaceable>N</replaceable>. This is useful for very large Nix - stores on filesystems with a 32000 subdirectories limit (like - <literal>ext3</literal>). The option <option>--use-atime</option> - causes store paths to be deleted in order of ascending last access - time. This allows non-recently used stuff to be deleted. The - option <option>--max-atime <replaceable>time</replaceable></option> - specifies an upper limit to the last accessed time of paths that may - be deleted. For instance, - - <screen> - $ nix-store --gc -v --max-atime $(date +%s -d "2 months ago")</screen> - - deletes everything that hasn’t been accessed in two months.</para></listitem> - - <listitem><para><command>nix-env</command> now uses optimistic - profile locking when performing an operation like installing or - upgrading, instead of setting an exclusive lock on the profile. - This allows multiple <command>nix-env -i / -u / -e</command> - operations on the same profile in parallel. If a - <command>nix-env</command> operation sees at the end that the profile - was changed in the meantime by another process, it will just - restart. This is generally cheap because the build results are - still in the Nix store.</para></listitem> - - <listitem><para>The option <option>--dry-run</option> is now - supported by <command>nix-store -r</command> and - <command>nix-build</command>.</para></listitem> - - <listitem><para>The information previously shown by - <option>--dry-run</option> (i.e., which derivations will be built - and which paths will be substituted) is now always shown by - <command>nix-env</command>, <command>nix-store -r</command> and - <command>nix-build</command>. The total download size of - substitutable paths is now also shown. For instance, a build will - show something like - - <screen> -the following derivations will be built: - /nix/store/129sbxnk5n466zg6r1qmq1xjv9zymyy7-activate-configuration.sh.drv - /nix/store/7mzy971rdm8l566ch8hgxaf89x7lr7ik-upstart-jobs.drv - ... -the following paths will be downloaded/copied (30.02 MiB): - /nix/store/4m8pvgy2dcjgppf5b4cj5l6wyshjhalj-samba-3.2.4 - /nix/store/7h1kwcj29ip8vk26rhmx6bfjraxp0g4l-libunwind-0.98.6 - ...</screen> - - </para></listitem> - - <listitem><para>Language features: - - <itemizedlist> - - <listitem><para>@-patterns as in Haskell. For instance, in a - function definition - - <programlisting>f = args @ {x, y, z}: <replaceable>...</replaceable>;</programlisting> - - <varname>args</varname> refers to the argument as a whole, which - is further pattern-matched against the attribute set pattern - <literal>{x, y, z}</literal>.</para></listitem> - - <listitem><para>“<literal>...</literal>” (ellipsis) patterns. - An attribute set pattern can now say <literal>...</literal> at - the end of the attribute name list to specify that the function - takes <emphasis>at least</emphasis> the listed attributes, while - ignoring additional attributes. For instance, - - <programlisting>{stdenv, fetchurl, fuse, ...}: <replaceable>...</replaceable></programlisting> - - defines a function that accepts any attribute set that includes - at least the three listed attributes.</para></listitem> - - <listitem><para>New primops: - <varname>builtins.parseDrvName</varname> (split a package name - string like <literal>"nix-0.12pre12876"</literal> into its name - and version components, e.g. <literal>"nix"</literal> and - <literal>"0.12pre12876"</literal>), - <varname>builtins.compareVersions</varname> (compare two version - strings using the same algorithm that <command>nix-env</command> - uses), <varname>builtins.length</varname> (efficiently compute - the length of a list), <varname>builtins.mul</varname> (integer - multiplication), <varname>builtins.div</varname> (integer - division). - <!-- <varname>builtins.genericClosure</varname> --> - </para></listitem> - - </itemizedlist> - - </para></listitem> - - <listitem><para><command>nix-prefetch-url</command> now supports - <literal>mirror://</literal> URLs, provided that the environment - variable <envar>NIXPKGS_ALL</envar> points at a Nixpkgs - tree.</para></listitem> - - <listitem><para>Removed the commands - <command>nix-pack-closure</command> and - <command>nix-unpack-closure</command>. You can do almost the same - thing but much more efficiently by doing <literal>nix-store --export - $(nix-store -qR <replaceable>paths</replaceable>) > closure</literal> and - <literal>nix-store --import < - closure</literal>.</para></listitem> - - <listitem><para>Lots of bug fixes, including a big performance bug in - the handling of <literal>with</literal>-expressions.</para></listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-0.13.xml b/doc/manual/release-notes/rl-0.13.xml deleted file mode 100644 index cce2e4a26..000000000 --- a/doc/manual/release-notes/rl-0.13.xml +++ /dev/null @@ -1,106 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-0.13"> - -<title>Release 0.13 (2009-11-05)</title> - -<para>This is primarily a bug fix release. It has some new -features:</para> - -<itemizedlist> - - <listitem> - <para>Syntactic sugar for writing nested attribute sets. Instead of - -<programlisting> -{ - foo = { - bar = 123; - xyzzy = true; - }; - a = { b = { c = "d"; }; }; -} -</programlisting> - - you can write - -<programlisting> -{ - foo.bar = 123; - foo.xyzzy = true; - a.b.c = "d"; -} -</programlisting> - - This is useful, for instance, in NixOS configuration files.</para> - - </listitem> - - <listitem> - <para>Support for Nix channels generated by Hydra, the Nix-based - continuous build system. (Hydra generates NAR archives on the - fly, so the size and hash of these archives isn’t known in - advance.)</para> - </listitem> - - <listitem> - <para>Support <literal>i686-linux</literal> builds directly on - <literal>x86_64-linux</literal> Nix installations. This is - implemented using the <function>personality()</function> syscall, - which causes <command>uname</command> to return - <literal>i686</literal> in child processes.</para> - </listitem> - - <listitem> - <para>Various improvements to the <literal>chroot</literal> - support. Building in a <literal>chroot</literal> works quite well - now.</para> - </listitem> - - <listitem> - <para>Nix no longer blocks if it tries to build a path and another - process is already building the same path. Instead it tries to - build another buildable path first. This improves - parallelism.</para> - </listitem> - - <listitem> - <para>Support for large (> 4 GiB) files in NAR archives.</para> - </listitem> - - <listitem> - <para>Various (performance) improvements to the remote build - mechanism.</para> - </listitem> - - <listitem> - <para>New primops: <varname>builtins.addErrorContext</varname> (to - add a string to stack traces — useful for debugging), - <varname>builtins.isBool</varname>, - <varname>builtins.isString</varname>, - <varname>builtins.isInt</varname>, - <varname>builtins.intersectAttrs</varname>.</para> - </listitem> - - <listitem> - <para>OpenSolaris support (Sander van der Burg).</para> - </listitem> - - <listitem> - <para>Stack traces are no longer displayed unless the - <option>--show-trace</option> option is used.</para> - </listitem> - - <listitem> - <para>The scoping rules for <literal>inherit - (<replaceable>e</replaceable>) ...</literal> in recursive - attribute sets have changed. The expression - <replaceable>e</replaceable> can now refer to the attributes - defined in the containing set.</para> - </listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-0.14.xml b/doc/manual/release-notes/rl-0.14.xml deleted file mode 100644 index e5fe9da78..000000000 --- a/doc/manual/release-notes/rl-0.14.xml +++ /dev/null @@ -1,46 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-0.14"> - -<title>Release 0.14 (2010-02-04)</title> - -<para>This release has the following improvements:</para> - -<itemizedlist> - - <listitem> - <para>The garbage collector now starts deleting garbage much - faster than before. It no longer determines liveness of all paths - in the store, but does so on demand.</para> - </listitem> - - <listitem> - <para>Added a new operation, <command>nix-store --query - --roots</command>, that shows the garbage collector roots that - directly or indirectly point to the given store paths.</para> - </listitem> - - <listitem> - <para>Removed support for converting Berkeley DB-based Nix - databases to the new schema.</para> - </listitem> - - <listitem> - <para>Removed the <option>--use-atime</option> and - <option>--max-atime</option> garbage collector options. They were - not very useful in practice.</para> - </listitem> - - <listitem> - <para>On Windows, Nix now requires Cygwin 1.7.x.</para> - </listitem> - - <listitem> - <para>A few bug fixes.</para> - </listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-0.15.xml b/doc/manual/release-notes/rl-0.15.xml deleted file mode 100644 index 9f58a8efc..000000000 --- a/doc/manual/release-notes/rl-0.15.xml +++ /dev/null @@ -1,14 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-0.15"> - -<title>Release 0.15 (2010-03-17)</title> - -<para>This is a bug-fix release. Among other things, it fixes -building on Mac OS X (Snow Leopard), and improves the contents of -<filename>/etc/passwd</filename> and <filename>/etc/group</filename> -in <literal>chroot</literal> builds.</para> - -</section> diff --git a/doc/manual/release-notes/rl-0.16.xml b/doc/manual/release-notes/rl-0.16.xml deleted file mode 100644 index af1edc0eb..000000000 --- a/doc/manual/release-notes/rl-0.16.xml +++ /dev/null @@ -1,55 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-0.16"> - -<title>Release 0.16 (2010-08-17)</title> - -<para>This release has the following improvements:</para> - -<itemizedlist> - - <listitem> - <para>The Nix expression evaluator is now much faster in most - cases: typically, <link - xlink:href="http://www.mail-archive.com/nix-dev@cs.uu.nl/msg04113.html">3 - to 8 times compared to the old implementation</link>. It also - uses less memory. It no longer depends on the ATerm - library.</para> - </listitem> - - <listitem> - <para> - Support for configurable parallelism inside builders. Build - scripts have always had the ability to perform multiple build - actions in parallel (for instance, by running <command>make -j - 2</command>), but this was not desirable because the number of - actions to be performed in parallel was not configurable. Nix - now has an option <option>--cores - <replaceable>N</replaceable></option> as well as a configuration - setting <varname>build-cores = - <replaceable>N</replaceable></varname> that causes the - environment variable <envar>NIX_BUILD_CORES</envar> to be set to - <replaceable>N</replaceable> when the builder is invoked. The - builder can use this at its discretion to perform a parallel - build, e.g., by calling <command>make -j - <replaceable>N</replaceable></command>. In Nixpkgs, this can be - enabled on a per-package basis by setting the derivation - attribute <varname>enableParallelBuilding</varname> to - <literal>true</literal>. - </para> - </listitem> - - <listitem> - <para><command>nix-store -q</command> now supports XML output - through the <option>--xml</option> flag.</para> - </listitem> - - <listitem> - <para>Several bug fixes.</para> - </listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-0.5.xml b/doc/manual/release-notes/rl-0.5.xml deleted file mode 100644 index e9f8bf270..000000000 --- a/doc/manual/release-notes/rl-0.5.xml +++ /dev/null @@ -1,11 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-relnotes-0.5"> - -<title>Release 0.5 and earlier</title> - -<para>Please refer to the Subversion commit log messages.</para> - -</section> diff --git a/doc/manual/release-notes/rl-0.6.xml b/doc/manual/release-notes/rl-0.6.xml deleted file mode 100644 index 6dc6521d3..000000000 --- a/doc/manual/release-notes/rl-0.6.xml +++ /dev/null @@ -1,122 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-relnotes-0.6"> - -<title>Release 0.6 (2004-11-14)</title> - -<itemizedlist> - - <listitem> - <para>Rewrite of the normalisation engine. - - <itemizedlist> - - <listitem><para>Multiple builds can now be performed in parallel - (option <option>-j</option>).</para></listitem> - - <listitem><para>Distributed builds. Nix can now call a shell - script to forward builds to Nix installations on remote - machines, which may or may not be of the same platform - type.</para></listitem> - - <listitem><para>Option <option>--fallback</option> allows - recovery from broken substitutes.</para></listitem> - - <listitem><para>Option <option>--keep-going</option> causes - building of other (unaffected) derivations to continue if one - failed.</para></listitem> - - </itemizedlist> - - </para> - - </listitem> - - <listitem><para>Improvements to the garbage collector (i.e., it - should actually work now).</para></listitem> - - <listitem><para>Setuid Nix installations allow a Nix store to be - shared among multiple users.</para></listitem> - - <listitem><para>Substitute registration is much faster - now.</para></listitem> - - <listitem><para>A utility <command>nix-build</command> to build a - Nix expression and create a symlink to the result int the current - directory; useful for testing Nix derivations.</para></listitem> - - <listitem><para>Manual updates.</para></listitem> - - <listitem> - - <para><command>nix-env</command> changes: - - <itemizedlist> - - <listitem><para>Derivations for other platforms are filtered out - (which can be overridden using - <option>--system-filter</option>).</para></listitem> - - <listitem><para><option>--install</option> by default now - uninstall previous derivations with the same - name.</para></listitem> - - <listitem><para><option>--upgrade</option> allows upgrading to a - specific version.</para></listitem> - - <listitem><para>New operation - <option>--delete-generations</option> to remove profile - generations (necessary for effective garbage - collection).</para></listitem> - - <listitem><para>Nicer output (sorted, - columnised).</para></listitem> - - </itemizedlist> - - </para> - - </listitem> - - <listitem><para>More sensible verbosity levels all around (builder - output is now shown always, unless <option>-Q</option> is - given).</para></listitem> - - <listitem> - - <para>Nix expression language changes: - - <itemizedlist> - - <listitem><para>New language construct: <literal>with - <replaceable>E1</replaceable>; - <replaceable>E2</replaceable></literal> brings all attributes - defined in the attribute set <replaceable>E1</replaceable> in - scope in <replaceable>E2</replaceable>.</para></listitem> - - <listitem><para>Added a <function>map</function> - function.</para></listitem> - - <listitem><para>Various new operators (e.g., string - concatenation).</para></listitem> - - </itemizedlist> - - </para> - - </listitem> - - <listitem><para>Expression evaluation is much - faster.</para></listitem> - - <listitem><para>An Emacs mode for editing Nix expressions (with - syntax highlighting and indentation) has been - added.</para></listitem> - - <listitem><para>Many bug fixes.</para></listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-0.7.xml b/doc/manual/release-notes/rl-0.7.xml deleted file mode 100644 index 6f95db436..000000000 --- a/doc/manual/release-notes/rl-0.7.xml +++ /dev/null @@ -1,35 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-relnotes-0.7"> - -<title>Release 0.7 (2005-01-12)</title> - -<itemizedlist> - - <listitem><para>Binary patching. When upgrading components using - pre-built binaries (through nix-pull / nix-channel), Nix can - automatically download and apply binary patches to already installed - components instead of full downloads. Patching is “smart”: if there - is a <emphasis>sequence</emphasis> of patches to an installed - component, Nix will use it. Patches are currently generated - automatically between Nixpkgs (pre-)releases.</para></listitem> - - <listitem><para>Simplifications to the substitute - mechanism.</para></listitem> - - <listitem><para>Nix-pull now stores downloaded manifests in - <filename>/nix/var/nix/manifests</filename>.</para></listitem> - - <listitem><para>Metadata on files in the Nix store is canonicalised - after builds: the last-modified timestamp is set to 0 (00:00:00 - 1/1/1970), the mode is set to 0444 or 0555 (readable and possibly - executable by all; setuid/setgid bits are dropped), and the group is - set to the default. This ensures that the result of a build and an - installation through a substitute is the same; and that timestamp - dependencies are revealed.</para></listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-0.8.1.xml b/doc/manual/release-notes/rl-0.8.1.xml deleted file mode 100644 index f7ffca0f8..000000000 --- a/doc/manual/release-notes/rl-0.8.1.xml +++ /dev/null @@ -1,21 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-relnotes-0.8.1"> - -<title>Release 0.8.1 (2005-04-13)</title> - -<para>This is a bug fix release.</para> - -<itemizedlist> - - <listitem><para>Patch downloading was broken.</para></listitem> - - <listitem><para>The garbage collector would not delete paths that - had references from invalid (but substitutable) - paths.</para></listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-0.8.xml b/doc/manual/release-notes/rl-0.8.xml deleted file mode 100644 index 825798fa9..000000000 --- a/doc/manual/release-notes/rl-0.8.xml +++ /dev/null @@ -1,246 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-relnotes-0.8"> - -<title>Release 0.8 (2005-04-11)</title> - -<para>NOTE: the hashing scheme in Nix 0.8 changed (as detailed below). -As a result, <command>nix-pull</command> manifests and channels built -for Nix 0.7 and below will not work anymore. However, the Nix -expression language has not changed, so you can still build from -source. Also, existing user environments continue to work. Nix 0.8 -will automatically upgrade the database schema of previous -installations when it is first run.</para> - -<para>If you get the error message - -<screen> -you have an old-style manifest `/nix/var/nix/manifests/[...]'; please -delete it</screen> - -you should delete previously downloaded manifests: - -<screen> -$ rm /nix/var/nix/manifests/*</screen> - -If <command>nix-channel</command> gives the error message - -<screen> -manifest `http://catamaran.labs.cs.uu.nl/dist/nix/channels/[channel]/MANIFEST' -is too old (i.e., for Nix <= 0.7)</screen> - -then you should unsubscribe from the offending channel -(<command>nix-channel --remove -<replaceable>URL</replaceable></command>; leave out -<literal>/MANIFEST</literal>), and subscribe to the same URL, with -<literal>channels</literal> replaced by <literal>channels-v3</literal> -(e.g., <link -xlink:href='http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable' -/>).</para> - -<para>Nix 0.8 has the following improvements: - -<itemizedlist> - - <listitem><para>The cryptographic hashes used in store paths are now - 160 bits long, but encoded in base-32 so that they are still only 32 - characters long (e.g., - <filename>/nix/store/csw87wag8bqlqk7ipllbwypb14xainap-atk-1.9.0</filename>). - (This is actually a 160 bit truncation of a SHA-256 - hash.)</para></listitem> - - <listitem><para>Big cleanups and simplifications of the basic store - semantics. The notion of “closure store expressions” is gone (and - so is the notion of “successors”); the file system references of a - store path are now just stored in the database.</para> - - <para>For instance, given any store path, you can query its closure: - - <screen> -$ nix-store -qR $(which firefox) -... lots of paths ...</screen> - - Also, Nix now remembers for each store path the derivation that - built it (the “deriver”): - - <screen> -$ nix-store -qR $(which firefox) -/nix/store/4b0jx7vq80l9aqcnkszxhymsf1ffa5jd-firefox-1.0.1.drv</screen> - - So to see the build-time dependencies, you can do - - <screen> -$ nix-store -qR $(nix-store -qd $(which firefox))</screen> - - or, in a nicer format: - - <screen> -$ nix-store -q --tree $(nix-store -qd $(which firefox))</screen> - - </para> - - <para>File system references are also stored in reverse. For - instance, you can query all paths that directly or indirectly use a - certain Glibc: - - <screen> -$ nix-store -q --referrers-closure \ - /nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4</screen> - - </para> - - </listitem> - - <listitem><para>The concept of fixed-output derivations has been - formalised. Previously, functions such as - <function>fetchurl</function> in Nixpkgs used a hack (namely, - explicitly specifying a store path hash) to prevent changes to, say, - the URL of the file from propagating upwards through the dependency - graph, causing rebuilds of everything. This can now be done cleanly - by specifying the <varname>outputHash</varname> and - <varname>outputHashAlgo</varname> attributes. Nix itself checks - that the content of the output has the specified hash. (This is - important for maintaining certain invariants necessary for future - work on secure shared stores.)</para></listitem> - - <listitem><para>One-click installation :-) It is now possible to - install any top-level component in Nixpkgs directly, through the web - — see, e.g., <link - xlink:href='http://catamaran.labs.cs.uu.nl/dist/nixpkgs-0.8/' />. - All you have to do is associate - <filename>/nix/bin/nix-install-package</filename> with the MIME type - <literal>application/nix-package</literal> (or the extension - <filename>.nixpkg</filename>), and clicking on a package link will - cause it to be installed, with all appropriate dependencies. If you - just want to install some specific application, this is easier than - subscribing to a channel.</para></listitem> - - <listitem><para><command>nix-store -r - <replaceable>PATHS</replaceable></command> now builds all the - derivations PATHS in parallel. Previously it did them sequentially - (though exploiting possible parallelism between subderivations). - This is nice for build farms.</para></listitem> - - <listitem><para><command>nix-channel</command> has new operations - <option>--list</option> and - <option>--remove</option>.</para></listitem> - - <listitem><para>New ways of installing components into user - environments: - - <itemizedlist> - - <listitem><para>Copy from another user environment: - - <screen> -$ nix-env -i --from-profile .../other-profile firefox</screen> - - </para></listitem> - - <listitem><para>Install a store derivation directly (bypassing the - Nix expression language entirely): - - <screen> -$ nix-env -i /nix/store/z58v41v21xd3...-aterm-2.3.1.drv</screen> - - (This is used to implement <command>nix-install-package</command>, - which is therefore immune to evolution in the Nix expression - language.)</para></listitem> - - <listitem><para>Install an already built store path directly: - - <screen> -$ nix-env -i /nix/store/hsyj5pbn0d9i...-aterm-2.3.1</screen> - - </para></listitem> - - <listitem><para>Install the result of a Nix expression specified - as a command-line argument: - - <screen> -$ nix-env -f .../i686-linux.nix -i -E 'x: x.firefoxWrapper'</screen> - - The difference with the normal installation mode is that - <option>-E</option> does not use the <varname>name</varname> - attributes of derivations. Therefore, this can be used to - disambiguate multiple derivations with the same - name.</para></listitem> - - </itemizedlist></para></listitem> - - <listitem><para>A hash of the contents of a store path is now stored - in the database after a successful build. This allows you to check - whether store paths have been tampered with: <command>nix-store - --verify --check-contents</command>.</para></listitem> - - <listitem> - - <para>Implemented a concurrent garbage collector. It is now - always safe to run the garbage collector, even if other Nix - operations are happening simultaneously.</para> - - <para>However, there can still be GC races if you use - <command>nix-instantiate</command> and <command>nix-store - --realise</command> directly to build things. To prevent races, - use the <option>--add-root</option> flag of those commands.</para> - - </listitem> - - <listitem><para>The garbage collector now finally deletes paths in - the right order (i.e., topologically sorted under the “references” - relation), thus making it safe to interrupt the collector without - risking a store that violates the closure - invariant.</para></listitem> - - <listitem><para>Likewise, the substitute mechanism now downloads - files in the right order, thus preserving the closure invariant at - all times.</para></listitem> - - <listitem><para>The result of <command>nix-build</command> is now - registered as a root of the garbage collector. If the - <filename>./result</filename> link is deleted, the GC root - disappears automatically.</para></listitem> - - <listitem> - - <para>The behaviour of the garbage collector can be changed - globally by setting options in - <filename>/nix/etc/nix/nix.conf</filename>. - - <itemizedlist> - - <listitem><para><literal>gc-keep-derivations</literal> specifies - whether deriver links should be followed when searching for live - paths.</para></listitem> - - <listitem><para><literal>gc-keep-outputs</literal> specifies - whether outputs of derivations should be followed when searching - for live paths.</para></listitem> - - <listitem><para><literal>env-keep-derivations</literal> - specifies whether user environments should store the paths of - derivations when they are added (thus keeping the derivations - alive).</para></listitem> - - </itemizedlist> - - </para></listitem> - - <listitem><para>New <command>nix-env</command> query flags - <option>--drv-path</option> and - <option>--out-path</option>.</para></listitem> - - <listitem><para><command>fetchurl</command> allows SHA-1 and SHA-256 - in addition to MD5. Just specify the attribute - <varname>sha1</varname> or <varname>sha256</varname> instead of - <varname>md5</varname>.</para></listitem> - - <listitem><para>Manual updates.</para></listitem> - -</itemizedlist> - -</para> - -</section> diff --git a/doc/manual/release-notes/rl-0.9.1.xml b/doc/manual/release-notes/rl-0.9.1.xml deleted file mode 100644 index 85d11f416..000000000 --- a/doc/manual/release-notes/rl-0.9.1.xml +++ /dev/null @@ -1,13 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-relnotes-0.9.1"> - -<title>Release 0.9.1 (2005-09-20)</title> - -<para>This bug fix release addresses a problem with the ATerm library -when the <option>--with-aterm</option> flag in -<command>configure</command> was <emphasis>not</emphasis> used.</para> - -</section> diff --git a/doc/manual/release-notes/rl-0.9.2.xml b/doc/manual/release-notes/rl-0.9.2.xml deleted file mode 100644 index cb705e98a..000000000 --- a/doc/manual/release-notes/rl-0.9.2.xml +++ /dev/null @@ -1,28 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-relnotes-0.9.2"> - -<title>Release 0.9.2 (2005-09-21)</title> - -<para>This bug fix release fixes two problems on Mac OS X: - -<itemizedlist> - - <listitem><para>If Nix was linked against statically linked versions - of the ATerm or Berkeley DB library, there would be dynamic link - errors at runtime.</para></listitem> - - <listitem><para><command>nix-pull</command> and - <command>nix-push</command> intermittently failed due to race - conditions involving pipes and child processes with error messages - such as <literal>open2: open(GLOB(0x180b2e4), >&=9) failed: Bad - file descriptor at /nix/bin/nix-pull line 77</literal> (issue - <literal>NIX-14</literal>).</para></listitem> - -</itemizedlist> - -</para> - -</section> diff --git a/doc/manual/release-notes/rl-0.9.xml b/doc/manual/release-notes/rl-0.9.xml deleted file mode 100644 index fd1e633f7..000000000 --- a/doc/manual/release-notes/rl-0.9.xml +++ /dev/null @@ -1,98 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ch-relnotes-0.9"> - -<title>Release 0.9 (2005-09-16)</title> - -<para>NOTE: this version of Nix uses Berkeley DB 4.3 instead of 4.2. -The database is upgraded automatically, but you should be careful not -to use old versions of Nix that still use Berkeley DB 4.2. In -particular, if you use a Nix installed through Nix, you should run - -<screen> -$ nix-store --clear-substitutes</screen> - -first.</para> - - -<itemizedlist> - - <listitem><para>Unpacking of patch sequences is much faster now - since we no longer do redundant unpacking and repacking of - intermediate paths.</para></listitem> - - <listitem><para>Nix now uses Berkeley DB 4.3.</para></listitem> - - <listitem><para>The <function>derivation</function> primitive is - lazier. Attributes of dependent derivations can mutually refer to - each other (as long as there are no data dependencies on the - <varname>outPath</varname> and <varname>drvPath</varname> attributes - computed by <function>derivation</function>).</para> - - <para>For example, the expression <literal>derivation - attrs</literal> now evaluates to (essentially) - - <programlisting> -attrs // { - type = "derivation"; - outPath = derivation! attrs; - drvPath = derivation! attrs; -}</programlisting> - - where <function>derivation!</function> is a primop that does the - actual derivation instantiation (i.e., it does what - <function>derivation</function> used to do). The advantage is that - it allows commands such as <command>nix-env -qa</command> and - <command>nix-env -i</command> to be much faster since they no longer - need to instantiate all derivations, just the - <varname>name</varname> attribute.</para> - - <para>Also, it allows derivations to cyclically reference each - other, for example, - - <programlisting> -webServer = derivation { - ... - hostName = "svn.cs.uu.nl"; - services = [svnService]; -}; -  -svnService = derivation { - ... - hostName = webServer.hostName; -};</programlisting> - - Previously, this would yield a black hole (infinite recursion).</para> - - </listitem> - - <listitem><para><command>nix-build</command> now defaults to using - <filename>./default.nix</filename> if no Nix expression is - specified.</para></listitem> - - <listitem><para><command>nix-instantiate</command>, when applied to - a Nix expression that evaluates to a function, will call the - function automatically if all its arguments have - defaults.</para></listitem> - - <listitem><para>Nix now uses libtool to build dynamic libraries. - This reduces the size of executables.</para></listitem> - - <listitem><para>A new list concatenation operator - <literal>++</literal>. For example, <literal>[1 2 3] ++ [4 5 - 6]</literal> evaluates to <literal>[1 2 3 4 5 - 6]</literal>.</para></listitem> - - <listitem><para>Some currently undocumented primops to support - low-level build management using Nix (i.e., using Nix as a Make - replacement). See the commit messages for <literal>r3578</literal> - and <literal>r3580</literal>.</para></listitem> - - <listitem><para>Various bug fixes and performance - improvements.</para></listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-1.0.xml b/doc/manual/release-notes/rl-1.0.xml deleted file mode 100644 index ff11168d0..000000000 --- a/doc/manual/release-notes/rl-1.0.xml +++ /dev/null @@ -1,119 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.0"> - -<title>Release 1.0 (2012-05-11)</title> - -<para>There have been numerous improvements and bug fixes since the -previous release. Here are the most significant:</para> - -<itemizedlist> - - <listitem> - <para>Nix can now optionally use the Boehm garbage collector. - This significantly reduces the Nix evaluator’s memory footprint, - especially when evaluating large NixOS system configurations. It - can be enabled using the <option>--enable-gc</option> configure - option.</para> - </listitem> - - <listitem> - <para>Nix now uses SQLite for its database. This is faster and - more flexible than the old <emphasis>ad hoc</emphasis> format. - SQLite is also used to cache the manifests in - <filename>/nix/var/nix/manifests</filename>, resulting in a - significant speedup.</para> - </listitem> - - <listitem> - <para>Nix now has an search path for expressions. The search path - is set using the environment variable <envar>NIX_PATH</envar> and - the <option>-I</option> command line option. In Nix expressions, - paths between angle brackets are used to specify files that must - be looked up in the search path. For instance, the expression - <literal><nixpkgs/default.nix></literal> looks for a file - <filename>nixpkgs/default.nix</filename> relative to every element - in the search path.</para> - </listitem> - - <listitem> - <para>The new command <command>nix-build --run-env</command> - builds all dependencies of a derivation, then starts a shell in an - environment containing all variables from the derivation. This is - useful for reproducing the environment of a derivation for - development.</para> - </listitem> - - <listitem> - <para>The new command <command>nix-store --verify-path</command> - verifies that the contents of a store path have not - changed.</para> - </listitem> - - <listitem> - <para>The new command <command>nix-store --print-env</command> - prints out the environment of a derivation in a format that can be - evaluated by a shell.</para> - </listitem> - - <listitem> - <para>Attribute names can now be arbitrary strings. For instance, - you can write <literal>{ "foo-1.2" = …; "bla bla" = …; }."bla - bla"</literal>.</para> - </listitem> - - <listitem> - <para>Attribute selection can now provide a default value using - the <literal>or</literal> operator. For instance, the expression - <literal>x.y.z or e</literal> evaluates to the attribute - <literal>x.y.z</literal> if it exists, and <literal>e</literal> - otherwise.</para> - </listitem> - - <listitem> - <para>The right-hand side of the <literal>?</literal> operator can - now be an attribute path, e.g., <literal>attrs ? - a.b.c</literal>.</para> - </listitem> - - <listitem> - <para>On Linux, Nix will now make files in the Nix store immutable - on filesystems that support it. This prevents accidental - modification of files in the store by the root user.</para> - </listitem> - - <listitem> - <para>Nix has preliminary support for derivations with multiple - outputs. This is useful because it allows parts of a package to - be deployed and garbage-collected separately. For instance, - development parts of a package such as header files or static - libraries would typically not be part of the closure of an - application, resulting in reduced disk usage and installation - time.</para> - </listitem> - - <listitem> - <para>The Nix store garbage collector is faster and holds the - global lock for a shorter amount of time.</para> - </listitem> - - <listitem> - <para>The option <option>--timeout</option> (corresponding to the - configuration setting <literal>build-timeout</literal>) allows you - to set an absolute timeout on builds — if a build runs for more than - the given number of seconds, it is terminated. This is useful for - recovering automatically from builds that are stuck in an infinite - loop but keep producing output, and for which - <literal>--max-silent-time</literal> is ineffective.</para> - </listitem> - - <listitem> - <para>Nix development has moved to GitHub (<link - xlink:href="https://github.com/NixOS/nix" />).</para> - </listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-1.1.xml b/doc/manual/release-notes/rl-1.1.xml deleted file mode 100644 index 2f26e7a24..000000000 --- a/doc/manual/release-notes/rl-1.1.xml +++ /dev/null @@ -1,100 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.1"> - -<title>Release 1.1 (2012-07-18)</title> - -<para>This release has the following improvements:</para> - -<itemizedlist> - - <listitem> - <para>On Linux, when doing a chroot build, Nix now uses various - namespace features provided by the Linux kernel to improve - build isolation. Namely: - <itemizedlist> - <listitem><para>The private network namespace ensures that - builders cannot talk to the outside world (or vice versa): each - build only sees a private loopback interface. This also means - that two concurrent builds can listen on the same port (e.g. as - part of a test) without conflicting with each - other.</para></listitem> - <listitem><para>The PID namespace causes each build to start as - PID 1. Processes outside of the chroot are not visible to those - on the inside. On the other hand, processes inside the chroot - <emphasis>are</emphasis> visible from the outside (though with - different PIDs).</para></listitem> - <listitem><para>The IPC namespace prevents the builder from - communicating with outside processes using SysV IPC mechanisms - (shared memory, message queues, semaphores). It also ensures - that all IPC objects are destroyed when the builder - exits.</para></listitem> - <listitem><para>The UTS namespace ensures that builders see a - hostname of <literal>localhost</literal> rather than the actual - hostname.</para></listitem> - <listitem><para>The private mount namespace was already used by - Nix to ensure that the bind-mounts used to set up the chroot are - cleaned up automatically.</para></listitem> - </itemizedlist> - </para> - </listitem> - - <listitem> - <para>Build logs are now compressed using - <command>bzip2</command>. The command <command>nix-store - -l</command> decompresses them on the fly. This can be disabled - by setting the option <literal>build-compress-log</literal> to - <literal>false</literal>.</para> - </listitem> - - <listitem> - <para>The creation of build logs in - <filename>/nix/var/log/nix/drvs</filename> can be disabled by - setting the new option <literal>build-keep-log</literal> to - <literal>false</literal>. This is useful, for instance, for Hydra - build machines.</para> - </listitem> - - <listitem> - <para>Nix now reserves some space in - <filename>/nix/var/nix/db/reserved</filename> to ensure that the - garbage collector can run successfully if the disk is full. This - is necessary because SQLite transactions fail if the disk is - full.</para> - </listitem> - - <listitem> - <para>Added a basic <function>fetchurl</function> function. This - is not intended to replace the <function>fetchurl</function> in - Nixpkgs, but is useful for bootstrapping; e.g., it will allow us - to get rid of the bootstrap binaries in the Nixpkgs source tree - and download them instead. You can use it by doing - <literal>import <nix/fetchurl.nix> { url = - <replaceable>url</replaceable>; sha256 = - "<replaceable>hash</replaceable>"; }</literal>. (Shea Levy)</para> - </listitem> - - <listitem> - <para>Improved RPM spec file. (Michel Alexandre Salim)</para> - </listitem> - - <listitem> - <para>Support for on-demand socket-based activation in the Nix - daemon with <command>systemd</command>.</para> - </listitem> - - <listitem> - <para>Added a manpage for - <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </listitem> - - <listitem> - <para>When using the Nix daemon, the <option>-s</option> flag in - <command>nix-env -qa</command> is now much faster.</para> - </listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-1.10.xml b/doc/manual/release-notes/rl-1.10.xml deleted file mode 100644 index 689a95466..000000000 --- a/doc/manual/release-notes/rl-1.10.xml +++ /dev/null @@ -1,64 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.10"> - -<title>Release 1.10 (2015-09-03)</title> - -<para>This is primarily a bug fix release. It also has a number of new -features:</para> - -<itemizedlist> - - <listitem> - <para>A number of builtin functions have been added to reduce - Nixpkgs/NixOS evaluation time and memory consumption: - <function>all</function>, - <function>any</function>, - <function>concatStringsSep</function>, - <function>foldl’</function>, - <function>genList</function>, - <function>replaceStrings</function>, - <function>sort</function>. - </para> - </listitem> - - <listitem> - <para>The garbage collector is more robust when the disk is full.</para> - </listitem> - - <listitem> - <para>Nix supports a new API for building derivations that doesn’t - require a <literal>.drv</literal> file to be present on disk; it - only requires an in-memory representation of the derivation. This - is used by the Hydra continuous build system to make remote builds - more efficient.</para> - </listitem> - - <listitem> - <para>The function <literal><nix/fetchurl.nix></literal> now - uses a <emphasis>builtin</emphasis> builder (i.e. it doesn’t - require starting an external process; the download is performed by - Nix itself). This ensures that derivation paths don’t change when - Nix is upgraded, and obviates the need for ugly hacks to support - chroot execution.</para> - </listitem> - - <listitem> - <para><option>--version -v</option> now prints some configuration - information, in particular what compile-time optional features are - enabled, and the paths of various directories.</para> - </listitem> - - <listitem> - <para>Build users have their supplementary groups set correctly.</para> - </listitem> - -</itemizedlist> - -<para>This release has contributions from Eelco Dolstra, Guillaume -Maudoux, Iwan Aucamp, Jaka Hudoklin, Kirill Elagin, Ludovic Courtès, -Manolis Ragkousis, Nicolas B. Pierron and Shea Levy.</para> - -</section> diff --git a/doc/manual/release-notes/rl-1.11.10.xml b/doc/manual/release-notes/rl-1.11.10.xml deleted file mode 100644 index 415388b3e..000000000 --- a/doc/manual/release-notes/rl-1.11.10.xml +++ /dev/null @@ -1,31 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.11.10"> - -<title>Release 1.11.10 (2017-06-12)</title> - -<para>This release fixes a security bug in Nix’s “build user” build -isolation mechanism. Previously, Nix builders had the ability to -create setuid binaries owned by a <literal>nixbld</literal> -user. Such a binary could then be used by an attacker to assume a -<literal>nixbld</literal> identity and interfere with subsequent -builds running under the same UID.</para> - -<para>To prevent this issue, Nix now disallows builders to create -setuid and setgid binaries. On Linux, this is done using a seccomp BPF -filter. Note that this imposes a small performance penalty (e.g. 1% -when building GNU Hello). Using seccomp, we now also prevent the -creation of extended attributes and POSIX ACLs since these cannot be -represented in the NAR format and (in the case of POSIX ACLs) allow -bypassing regular Nix store permissions. On macOS, the restriction is -implemented using the existing sandbox mechanism, which now uses a -minimal “allow all except the creation of setuid/setgid binaries” -profile when regular sandboxing is disabled. On other platforms, the -“build user” mechanism is now disabled.</para> - -<para>Thanks go to Linus Heckemann for discovering and reporting this -bug.</para> - -</section> diff --git a/doc/manual/release-notes/rl-1.11.xml b/doc/manual/release-notes/rl-1.11.xml deleted file mode 100644 index fe422dd1f..000000000 --- a/doc/manual/release-notes/rl-1.11.xml +++ /dev/null @@ -1,141 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.11"> - -<title>Release 1.11 (2016-01-19)</title> - -<para>This is primarily a bug fix release. It also has a number of new -features:</para> - -<itemizedlist> - - <listitem> - <para><command>nix-prefetch-url</command> can now download URLs - specified in a Nix expression. For example, - -<screen> -$ nix-prefetch-url -A hello.src -</screen> - - will prefetch the file specified by the - <function>fetchurl</function> call in the attribute - <literal>hello.src</literal> from the Nix expression in the - current directory, and print the cryptographic hash of the - resulting file on stdout. This differs from <literal>nix-build -A - hello.src</literal> in that it doesn't verify the hash, and is - thus useful when you’re updating a Nix expression.</para> - - <para>You can also prefetch the result of functions that unpack a - tarball, such as <function>fetchFromGitHub</function>. For example: - -<screen> -$ nix-prefetch-url --unpack https://github.com/NixOS/patchelf/archive/0.8.tar.gz -</screen> - - or from a Nix expression: - -<screen> -$ nix-prefetch-url -A nix-repl.src -</screen> - - </para> - - </listitem> - - <listitem> - <para>The builtin function - <function><nix/fetchurl.nix></function> now supports - downloading and unpacking NARs. This removes the need to have - multiple downloads in the Nixpkgs stdenv bootstrap process (like a - separate busybox binary for Linux, or curl/mkdir/sh/bzip2 for - Darwin). Now all those files can be combined into a single NAR, - optionally compressed using <command>xz</command>.</para> - </listitem> - - <listitem> - <para>Nix now supports SHA-512 hashes for verifying fixed-output - derivations, and in <function>builtins.hashString</function>.</para> - </listitem> - - <listitem> - <para> - The new flag <option>--option build-repeat - <replaceable>N</replaceable></option> will cause every build to - be executed <replaceable>N</replaceable>+1 times. If the build - output differs between any round, the build is rejected, and the - output paths are not registered as valid. This is primarily - useful to verify build determinism. (We already had a - <option>--check</option> option to repeat a previously succeeded - build. However, with <option>--check</option>, non-deterministic - builds are registered in the DB. Preventing that is useful for - Hydra to ensure that non-deterministic builds don't end up - getting published to the binary cache.) - </para> - </listitem> - - <listitem> - <para> - The options <option>--check</option> and <option>--option - build-repeat <replaceable>N</replaceable></option>, if they - detect a difference between two runs of the same derivation and - <option>-K</option> is given, will make the output of the other - run available under - <filename><replaceable>store-path</replaceable>-check</filename>. This - makes it easier to investigate the non-determinism using tools - like <command>diffoscope</command>, e.g., - -<screen> -$ nix-build pkgs/stdenv/linux -A stage1.pkgs.zlib --check -K -error: derivation ‘/nix/store/l54i8wlw2265…-zlib-1.2.8.drv’ may not -be deterministic: output ‘/nix/store/11a27shh6n2i…-zlib-1.2.8’ -differs from ‘/nix/store/11a27shh6n2i…-zlib-1.2.8-check’ - -$ diffoscope /nix/store/11a27shh6n2i…-zlib-1.2.8 /nix/store/11a27shh6n2i…-zlib-1.2.8-check -… -├── lib/libz.a -│ ├── metadata -│ │ @@ -1,15 +1,15 @@ -│ │ -rw-r--r-- 30001/30000 3096 Jan 12 15:20 2016 adler32.o -… -│ │ +rw-r--r-- 30001/30000 3096 Jan 12 15:28 2016 adler32.o -… -</screen> - - </para></listitem> - - <listitem> - <para>Improved FreeBSD support.</para> - </listitem> - - <listitem> - <para><command>nix-env -qa --xml --meta</command> now prints - license information.</para> - </listitem> - - <listitem> - <para>The maximum number of parallel TCP connections that the - binary cache substituter will use has been decreased from 150 to - 25. This should prevent upsetting some broken NAT routers, and - also improves performance.</para> - </listitem> - - <listitem> - <para>All "chroot"-containing strings got renamed to "sandbox". - In particular, some Nix options got renamed, but the old names - are still accepted as lower-priority aliases. - </para> - </listitem> - -</itemizedlist> - -<para>This release has contributions from Anders Claesson, Anthony -Cowley, Bjørn Forsman, Brian McKenna, Danny Wilson, davidak, Eelco Dolstra, -Fabian Schmitthenner, FrankHB, Ilya Novoselov, janus, Jim Garrison, John -Ericson, Jude Taylor, Ludovic Courtès, Manuel Jacob, Mathnerd314, -Pascal Wittmann, Peter Simons, Philip Potter, Preston Bennes, Rommel -M. Martinez, Sander van der Burg, Shea Levy, Tim Cuthbertson, Tuomas -Tynkkynen, Utku Demir and Vladimír Čunát.</para> - -</section> diff --git a/doc/manual/release-notes/rl-1.2.xml b/doc/manual/release-notes/rl-1.2.xml deleted file mode 100644 index 748fd9e67..000000000 --- a/doc/manual/release-notes/rl-1.2.xml +++ /dev/null @@ -1,157 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.2"> - -<title>Release 1.2 (2012-12-06)</title> - -<para>This release has the following improvements and changes:</para> - -<itemizedlist> - - <listitem> - <para>Nix has a new binary substituter mechanism: the - <emphasis>binary cache</emphasis>. A binary cache contains - pre-built binaries of Nix packages. Whenever Nix wants to build a - missing Nix store path, it will check a set of binary caches to - see if any of them has a pre-built binary of that path. The - configuration setting <option>binary-caches</option> contains a - list of URLs of binary caches. For instance, doing -<screen> -$ nix-env -i thunderbird --option binary-caches http://cache.nixos.org -</screen> - will install Thunderbird and its dependencies, using the available - pre-built binaries in <uri>http://cache.nixos.org</uri>. - The main advantage over the old “manifest”-based method of getting - pre-built binaries is that you don’t have to worry about your - manifest being in sync with the Nix expressions you’re installing - from; i.e., you don’t need to run <command>nix-pull</command> to - update your manifest. It’s also more scalable because you don’t - need to redownload a giant manifest file every time. - </para> - - <para>A Nix channel can provide a binary cache URL that will be - used automatically if you subscribe to that channel. If you use - the Nixpkgs or NixOS channels - (<uri>http://nixos.org/channels</uri>) you automatically get the - cache <uri>http://cache.nixos.org</uri>.</para> - - <para>Binary caches are created using <command>nix-push</command>. - For details on the operation and format of binary caches, see the - <command>nix-push</command> manpage. More details are provided in - <link xlink:href="https://nixos.org/nix-dev/2012-September/009826.html">this - nix-dev posting</link>.</para> - </listitem> - - <listitem> - <para>Multiple output support should now be usable. A derivation - can declare that it wants to produce multiple store paths by - saying something like -<programlisting> -outputs = [ "lib" "headers" "doc" ]; -</programlisting> - This will cause Nix to pass the intended store path of each output - to the builder through the environment variables - <literal>lib</literal>, <literal>headers</literal> and - <literal>doc</literal>. Other packages can refer to a specific - output by referring to - <literal><replaceable>pkg</replaceable>.<replaceable>output</replaceable></literal>, - e.g. -<programlisting> -buildInputs = [ pkg.lib pkg.headers ]; -</programlisting> - If you install a package with multiple outputs using - <command>nix-env</command>, each output path will be symlinked - into the user environment.</para> - </listitem> - - <listitem> - <para>Dashes are now valid as part of identifiers and attribute - names.</para> - </listitem> - - <listitem> - <para>The new operation <command>nix-store --repair-path</command> - allows corrupted or missing store paths to be repaired by - redownloading them. <command>nix-store --verify --check-contents - --repair</command> will scan and repair all paths in the Nix - store. Similarly, <command>nix-env</command>, - <command>nix-build</command>, <command>nix-instantiate</command> - and <command>nix-store --realise</command> have a - <option>--repair</option> flag to detect and fix bad paths by - rebuilding or redownloading them.</para> - </listitem> - - <listitem> - <para>Nix no longer sets the immutable bit on files in the Nix - store. Instead, the recommended way to guard the Nix store - against accidental modification on Linux is to make it a read-only - bind mount, like this: - -<screen> -$ mount --bind /nix/store /nix/store -$ mount -o remount,ro,bind /nix/store -</screen> - - Nix will automatically make <filename>/nix/store</filename> - writable as needed (using a private mount namespace) to allow - modifications.</para> - </listitem> - - <listitem> - <para>Store optimisation (replacing identical files in the store - with hard links) can now be done automatically every time a path - is added to the store. This is enabled by setting the - configuration option <literal>auto-optimise-store</literal> to - <literal>true</literal> (disabled by default).</para> - </listitem> - - <listitem> - <para>Nix now supports <command>xz</command> compression for NARs - in addition to <command>bzip2</command>. It compresses about 30% - better on typical archives and decompresses about twice as - fast.</para> - </listitem> - - <listitem> - <para>Basic Nix expression evaluation profiling: setting the - environment variable <envar>NIX_COUNT_CALLS</envar> to - <literal>1</literal> will cause Nix to print how many times each - primop or function was executed.</para> - </listitem> - - <listitem> - <para>New primops: <varname>concatLists</varname>, - <varname>elem</varname>, <varname>elemAt</varname> and - <varname>filter</varname>.</para> - </listitem> - - <listitem> - <para>The command <command>nix-copy-closure</command> has a new - flag <option>--use-substitutes</option> (<option>-s</option>) to - download missing paths on the target machine using the substitute - mechanism.</para> - </listitem> - - <listitem> - <para>The command <command>nix-worker</command> has been renamed - to <command>nix-daemon</command>. Support for running the Nix - worker in “slave” mode has been removed.</para> - </listitem> - - <listitem> - <para>The <option>--help</option> flag of every Nix command now - invokes <command>man</command>.</para> - </listitem> - - <listitem> - <para>Chroot builds are now supported on systemd machines.</para> - </listitem> - -</itemizedlist> - -<para>This release has contributions from Eelco Dolstra, Florian -Friesdorf, Mats Erik Andersson and Shea Levy.</para> - -</section> diff --git a/doc/manual/release-notes/rl-1.3.xml b/doc/manual/release-notes/rl-1.3.xml deleted file mode 100644 index e2009ee3b..000000000 --- a/doc/manual/release-notes/rl-1.3.xml +++ /dev/null @@ -1,19 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.3"> - -<title>Release 1.3 (2013-01-04)</title> - -<para>This is primarily a bug fix release. When this version is first -run on Linux, it removes any immutable bits from the Nix store and -increases the schema version of the Nix store. (The previous release -removed support for setting the immutable bit; this release clears any -remaining immutable bits to make certain operations more -efficient.)</para> - -<para>This release has contributions from Eelco Dolstra and Stuart -Pernsteiner.</para> - -</section> diff --git a/doc/manual/release-notes/rl-1.4.xml b/doc/manual/release-notes/rl-1.4.xml deleted file mode 100644 index aefb22f2b..000000000 --- a/doc/manual/release-notes/rl-1.4.xml +++ /dev/null @@ -1,39 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.4"> - -<title>Release 1.4 (2013-02-26)</title> - -<para>This release fixes a security bug in multi-user operation. It -was possible for derivations to cause the mode of files outside of the -Nix store to be changed to 444 (read-only but world-readable) by -creating hard links to those files (<link -xlink:href="https://github.com/NixOS/nix/commit/5526a282b5b44e9296e61e07d7d2626a79141ac4">details</link>).</para> - -<para>There are also the following improvements:</para> - -<itemizedlist> - - <listitem><para>New built-in function: - <function>builtins.hashString</function>.</para></listitem> - - <listitem><para>Build logs are now stored in - <filename>/nix/var/log/nix/drvs/<replaceable>XX</replaceable>/</filename>, - where <replaceable>XX</replaceable> is the first two characters of - the derivation. This is useful on machines that keep a lot of build - logs (such as Hydra servers).</para></listitem> - - <listitem><para>The function <function>corepkgs/fetchurl</function> - can now make the downloaded file executable. This will allow - getting rid of all bootstrap binaries in the Nixpkgs source - tree.</para></listitem> - - <listitem><para>Language change: The expression <literal>"${./path} - ..."</literal> now evaluates to a string instead of a - path.</para></listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-1.5.1.xml b/doc/manual/release-notes/rl-1.5.1.xml deleted file mode 100644 index 035c8dbcb..000000000 --- a/doc/manual/release-notes/rl-1.5.1.xml +++ /dev/null @@ -1,12 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.5.1"> - -<title>Release 1.5.1 (2013-02-28)</title> - -<para>The bug fix to the bug fix had a bug itself, of course. But -this time it will work for sure!</para> - -</section> diff --git a/doc/manual/release-notes/rl-1.5.2.xml b/doc/manual/release-notes/rl-1.5.2.xml deleted file mode 100644 index 7e81dd243..000000000 --- a/doc/manual/release-notes/rl-1.5.2.xml +++ /dev/null @@ -1,12 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.5.2"> - -<title>Release 1.5.2 (2013-05-13)</title> - -<para>This is primarily a bug fix release. It has contributions from -Eelco Dolstra, Lluís Batlle i Rossell and Shea Levy.</para> - -</section> diff --git a/doc/manual/release-notes/rl-1.5.xml b/doc/manual/release-notes/rl-1.5.xml deleted file mode 100644 index 8e279d769..000000000 --- a/doc/manual/release-notes/rl-1.5.xml +++ /dev/null @@ -1,12 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.5"> - -<title>Release 1.5 (2013-02-27)</title> - -<para>This is a brown paper bag release to fix a regression introduced -by the hard link security fix in 1.4.</para> - -</section> diff --git a/doc/manual/release-notes/rl-1.6.1.xml b/doc/manual/release-notes/rl-1.6.1.xml deleted file mode 100644 index 9ecc52734..000000000 --- a/doc/manual/release-notes/rl-1.6.1.xml +++ /dev/null @@ -1,69 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.6.1"> - -<title>Release 1.6.1 (2013-10-28)</title> - -<para>This is primarily a bug fix release. Changes of interest -are:</para> - -<itemizedlist> - - <listitem> - <para>Nix 1.6 accidentally changed the semantics of antiquoted - paths in strings, such as <literal>"${/foo}/bar"</literal>. This - release reverts to the Nix 1.5.3 behaviour.</para> - </listitem> - - <listitem> - <para>Previously, Nix optimised expressions such as - <literal>"${<replaceable>expr</replaceable>}"</literal> to - <replaceable>expr</replaceable>. Thus it neither checked whether - <replaceable>expr</replaceable> could be coerced to a string, nor - applied such coercions. This meant that - <literal>"${123}"</literal> evaluatued to <literal>123</literal>, - and <literal>"${./foo}"</literal> evaluated to - <literal>./foo</literal> (even though - <literal>"${./foo} "</literal> evaluates to - <literal>"/nix/store/<replaceable>hash</replaceable>-foo "</literal>). - Nix now checks the type of antiquoted expressions and - applies coercions.</para> - </listitem> - - <listitem> - <para>Nix now shows the exact position of undefined variables. In - particular, undefined variable errors in a <literal>with</literal> - previously didn't show <emphasis>any</emphasis> position - information, so this makes it a lot easier to fix such - errors.</para> - </listitem> - - <listitem> - <para>Undefined variables are now treated consistently. - Previously, the <function>tryEval</function> function would catch - undefined variables inside a <literal>with</literal> but not - outside. Now <function>tryEval</function> never catches undefined - variables.</para> - </listitem> - - <listitem> - <para>Bash completion in <command>nix-shell</command> now works - correctly.</para> - </listitem> - - <listitem> - <para>Stack traces are less verbose: they no longer show calls to - builtin functions and only show a single line for each derivation - on the call stack.</para> - </listitem> - - <listitem> - <para>New built-in function: <function>builtins.typeOf</function>, - which returns the type of its argument as a string.</para> - </listitem> - -</itemizedlist> - -</section> diff --git a/doc/manual/release-notes/rl-1.6.xml b/doc/manual/release-notes/rl-1.6.xml deleted file mode 100644 index 580563420..000000000 --- a/doc/manual/release-notes/rl-1.6.xml +++ /dev/null @@ -1,127 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.6.0"> - -<title>Release 1.6 (2013-09-10)</title> - -<para>In addition to the usual bug fixes, this release has several new -features:</para> - -<itemizedlist> - - <listitem> - <para>The command <command>nix-build --run-env</command> has been - renamed to <command>nix-shell</command>.</para> - </listitem> - - <listitem> - <para><command>nix-shell</command> now sources - <filename>$stdenv/setup</filename> <emphasis>inside</emphasis> the - interactive shell, rather than in a parent shell. This ensures - that shell functions defined by <literal>stdenv</literal> can be - used in the interactive shell.</para> - </listitem> - - <listitem> - <para><command>nix-shell</command> has a new flag - <option>--pure</option> to clear the environment, so you get an - environment that more closely corresponds to the “real” Nix build. - </para> - </listitem> - - <listitem> - <para><command>nix-shell</command> now sets the shell prompt - (<envar>PS1</envar>) to ensure that Nix shells are distinguishable - from your regular shells.</para> - </listitem> - - <listitem> - <para><command>nix-env</command> no longer requires a - <literal>*</literal> argument to match all packages, so - <literal>nix-env -qa</literal> is equivalent to <literal>nix-env - -qa '*'</literal>.</para> - </listitem> - - <listitem> - <para><command>nix-env -i</command> has a new flag - <option>--remove-all</option> (<option>-r</option>) to remove all - previous packages from the profile. This makes it easier to do - declarative package management similar to NixOS’s - <option>environment.systemPackages</option>. For instance, if you - have a specification <filename>my-packages.nix</filename> like this: - -<programlisting> -with import <nixpkgs> {}; -[ thunderbird - geeqie - ... -] -</programlisting> - - then after any change to this file, you can run: - -<screen> -$ nix-env -f my-packages.nix -ir -</screen> - - to update your profile to match the specification.</para> - </listitem> - - <listitem> - <para>The ‘<literal>with</literal>’ language construct is now more - lazy. It only evaluates its argument if a variable might actually - refer to an attribute in the argument. For instance, this now - works: - -<programlisting> -let - pkgs = with pkgs; { foo = "old"; bar = foo; } // overrides; - overrides = { foo = "new"; }; -in pkgs.bar -</programlisting> - - This evaluates to <literal>"new"</literal>, while previously it - gave an “infinite recursion” error.</para> - </listitem> - - <listitem> - <para>Nix now has proper integer arithmetic operators. For - instance, you can write <literal>x + y</literal> instead of - <literal>builtins.add x y</literal>, or <literal>x < - y</literal> instead of <literal>builtins.lessThan x y</literal>. - The comparison operators also work on strings.</para> - </listitem> - - <listitem> - <para>On 64-bit systems, Nix integers are now 64 bits rather than - 32 bits.</para> - </listitem> - - <listitem> - <para>When using the Nix daemon, the <command>nix-daemon</command> - worker process now runs on the same CPU as the client, on systems - that support setting CPU affinity. This gives a significant speedup - on some systems.</para> - </listitem> - - <listitem> - <para>If a stack overflow occurs in the Nix evaluator, you now get - a proper error message (rather than “Segmentation fault”) on some - systems.</para> - </listitem> - - <listitem> - <para>In addition to directories, you can now bind-mount regular - files in chroots through the (now misnamed) option - <option>build-chroot-dirs</option>.</para> - </listitem> - -</itemizedlist> - -<para>This release has contributions from Domen Kožar, Eelco Dolstra, -Florian Friesdorf, Gergely Risko, Ivan Kozik, Ludovic Courtès and Shea -Levy.</para> - -</section> diff --git a/doc/manual/release-notes/rl-1.7.xml b/doc/manual/release-notes/rl-1.7.xml deleted file mode 100644 index 44ecaa78d..000000000 --- a/doc/manual/release-notes/rl-1.7.xml +++ /dev/null @@ -1,263 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.7"> - -<title>Release 1.7 (2014-04-11)</title> - -<para>In addition to the usual bug fixes, this release has the -following new features:</para> - -<itemizedlist> - - <listitem> - <para>Antiquotation is now allowed inside of quoted attribute - names (e.g. <literal>set."${foo}"</literal>). In the case where - the attribute name is just a single antiquotation, the quotes can - be dropped (e.g. the above example can be written - <literal>set.${foo}</literal>). If an attribute name inside of a - set declaration evaluates to <literal>null</literal> (e.g. - <literal>{ ${null} = false; }</literal>), then that attribute is - not added to the set.</para> - </listitem> - - <listitem> - <para>Experimental support for cryptographically signed binary - caches. See <link - xlink:href="https://github.com/NixOS/nix/commit/0fdf4da0e979f992db75cc17376e455ddc5a96d8">the - commit for details</link>.</para> - </listitem> - - <listitem> - <para>An experimental new substituter, - <command>download-via-ssh</command>, that fetches binaries from - remote machines via SSH. Specifying the flags <literal>--option - use-ssh-substituter true --option ssh-substituter-hosts - <replaceable>user@hostname</replaceable></literal> will cause Nix - to download binaries from the specified machine, if it has - them.</para> - </listitem> - - <listitem> - <para><command>nix-store -r</command> and - <command>nix-build</command> have a new flag, - <option>--check</option>, that builds a previously built - derivation again, and prints an error message if the output is not - exactly the same. This helps to verify whether a derivation is - truly deterministic. For example: - -<screen> -$ nix-build '<nixpkgs>' -A patchelf -<replaceable>…</replaceable> -$ nix-build '<nixpkgs>' -A patchelf --check -<replaceable>…</replaceable> -error: derivation `/nix/store/1ipvxs…-patchelf-0.6' may not be deterministic: - hash mismatch in output `/nix/store/4pc1dm…-patchelf-0.6.drv' -</screen> - - </para> - - </listitem> - - <listitem> - <para>The <command>nix-instantiate</command> flags - <option>--eval-only</option> and <option>--parse-only</option> - have been renamed to <option>--eval</option> and - <option>--parse</option>, respectively.</para> - </listitem> - - <listitem> - <para><command>nix-instantiate</command>, - <command>nix-build</command> and <command>nix-shell</command> now - have a flag <option>--expr</option> (or <option>-E</option>) that - allows you to specify the expression to be evaluated as a command - line argument. For instance, <literal>nix-instantiate --eval -E - '1 + 2'</literal> will print <literal>3</literal>.</para> - </listitem> - - <listitem> - <para><command>nix-shell</command> improvements:</para> - - <itemizedlist> - - <listitem> - <para>It has a new flag, <option>--packages</option> (or - <option>-p</option>), that sets up a build environment - containing the specified packages from Nixpkgs. For example, - the command - -<screen> -$ nix-shell -p sqlite xorg.libX11 hello -</screen> - - will start a shell in which the given packages are - present.</para> - </listitem> - - <listitem> - <para>It now uses <filename>shell.nix</filename> as the - default expression, falling back to - <filename>default.nix</filename> if the former doesn’t - exist. This makes it convenient to have a - <filename>shell.nix</filename> in your project to set up a - nice development environment.</para> - </listitem> - - <listitem> - <para>It evaluates the derivation attribute - <varname>shellHook</varname>, if set. Since - <literal>stdenv</literal> does not normally execute this hook, - it allows you to do <command>nix-shell</command>-specific - setup.</para> - </listitem> - - <listitem> - <para>It preserves the user’s timezone setting.</para> - </listitem> - - </itemizedlist> - - </listitem> - - <listitem> - <para>In chroots, Nix now sets up a <filename>/dev</filename> - containing only a minimal set of devices (such as - <filename>/dev/null</filename>). Note that it only does this if - you <emphasis>don’t</emphasis> have <filename>/dev</filename> - listed in your <option>build-chroot-dirs</option> setting; - otherwise, it will bind-mount the <literal>/dev</literal> from - outside the chroot.</para> - - <para>Similarly, if you don’t have <filename>/dev/pts</filename> listed - in <option>build-chroot-dirs</option>, Nix will mount a private - <literal>devpts</literal> filesystem on the chroot’s - <filename>/dev/pts</filename>.</para> - - </listitem> - - <listitem> - <para>New built-in function: <function>builtins.toJSON</function>, - which returns a JSON representation of a value.</para> - </listitem> - - <listitem> - <para><command>nix-env -q</command> has a new flag - <option>--json</option> to print a JSON representation of the - installed or available packages.</para> - </listitem> - - <listitem> - <para><command>nix-env</command> now supports meta attributes with - more complex values, such as attribute sets.</para> - </listitem> - - <listitem> - <para>The <option>-A</option> flag now allows attribute names with - dots in them, e.g. - -<screen> -$ nix-instantiate --eval '<nixos>' -A 'config.systemd.units."nscd.service".text' -</screen> - - </para> - </listitem> - - <listitem> - <para>The <option>--max-freed</option> option to - <command>nix-store --gc</command> now accepts a unit - specifier. For example, <literal>nix-store --gc --max-freed - 1G</literal> will free up to 1 gigabyte of disk space.</para> - </listitem> - - <listitem> - <para><command>nix-collect-garbage</command> has a new flag - <option>--delete-older-than</option> - <replaceable>N</replaceable><literal>d</literal>, which deletes - all user environment generations older than - <replaceable>N</replaceable> days. Likewise, <command>nix-env - --delete-generations</command> accepts a - <replaceable>N</replaceable><literal>d</literal> age limit.</para> - </listitem> - - <listitem> - <para>Nix now heuristically detects whether a build failure was - due to a disk-full condition. In that case, the build is not - flagged as “permanently failed”. This is mostly useful for Hydra, - which needs to distinguish between permanent and transient build - failures.</para> - </listitem> - - <listitem> - <para>There is a new symbol <literal>__curPos</literal> that - expands to an attribute set containing its file name and line and - column numbers, e.g. <literal>{ file = "foo.nix"; line = 10; - column = 5; }</literal>. There also is a new builtin function, - <varname>unsafeGetAttrPos</varname>, that returns the position of - an attribute. This is used by Nixpkgs to provide location - information in error messages, e.g. - -<screen> -$ nix-build '<nixpkgs>' -A libreoffice --argstr system x86_64-darwin -error: the package ‘libreoffice-4.0.5.2’ in ‘.../applications/office/libreoffice/default.nix:263’ - is not supported on ‘x86_64-darwin’ -</screen> - - </para> - </listitem> - - <listitem> - <para>The garbage collector is now more concurrent with other Nix - processes because it releases certain locks earlier.</para> - </listitem> - - <listitem> - <para>The binary tarball installer has been improved. You can now - install Nix by running: - -<screen> -$ bash <(curl https://nixos.org/nix/install) -</screen> - - </para> - </listitem> - - <listitem> - <para>More evaluation errors include position information. For - instance, selecting a missing attribute will print something like - -<screen> -error: attribute `nixUnstabl' missing, at /etc/nixos/configurations/misc/eelco/mandark.nix:216:15 -</screen> - - </para> - </listitem> - - <listitem> - <para>The command <command>nix-setuid-helper</command> is - gone.</para> - </listitem> - - <listitem> - <para>Nix no longer uses Automake, but instead has a - non-recursive, GNU Make-based build system.</para> - </listitem> - - <listitem> - <para>All installed libraries now have the prefix - <literal>libnix</literal>. In particular, this gets rid of - <literal>libutil</literal>, which could clash with libraries with - the same name from other packages.</para> - </listitem> - - <listitem> - <para>Nix now requires a compiler that supports C++11.</para> - </listitem> - -</itemizedlist> - -<para>This release has contributions from Danny Wilson, Domen Kožar, -Eelco Dolstra, Ian-Woo Kim, Ludovic Courtès, Maxim Ivanov, Petr -Rockai, Ricardo M. Correia and Shea Levy.</para> - -</section> diff --git a/doc/manual/release-notes/rl-1.8.xml b/doc/manual/release-notes/rl-1.8.xml deleted file mode 100644 index c854c5c5f..000000000 --- a/doc/manual/release-notes/rl-1.8.xml +++ /dev/null @@ -1,123 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.8"> - -<title>Release 1.8 (2014-12-14)</title> - -<itemizedlist> - - <listitem><para>Breaking change: to address a race condition, the - remote build hook mechanism now uses <command>nix-store - --serve</command> on the remote machine. This requires build slaves - to be updated to Nix 1.8.</para></listitem> - - <listitem><para>Nix now uses HTTPS instead of HTTP to access the - default binary cache, - <literal>cache.nixos.org</literal>.</para></listitem> - - <listitem><para><command>nix-env</command> selectors are now regular - expressions. For instance, you can do - -<screen> -$ nix-env -qa '.*zip.*' -</screen> - - to query all packages with a name containing - <literal>zip</literal>.</para></listitem> - - <listitem><para><command>nix-store --read-log</command> can now - fetch remote build logs. If a build log is not available locally, - then ‘nix-store -l’ will now try to download it from the servers - listed in the ‘log-servers’ option in nix.conf. For instance, if you - have the configuration option - -<programlisting> -log-servers = http://hydra.nixos.org/log -</programlisting> - -then it will try to get logs from -<literal>http://hydra.nixos.org/log/<replaceable>base name of the -store path</replaceable></literal>. This allows you to do things like: - -<screen> -$ nix-store -l $(which xterm) -</screen> - - and get a log even if <command>xterm</command> wasn't built - locally.</para></listitem> - - <listitem><para>New builtin functions: - <function>attrValues</function>, <function>deepSeq</function>, - <function>fromJSON</function>, <function>readDir</function>, - <function>seq</function>.</para></listitem> - - <listitem><para><command>nix-instantiate --eval</command> now has a - <option>--json</option> flag to print the resulting value in JSON - format.</para></listitem> - - <listitem><para><command>nix-copy-closure</command> now uses - <command>nix-store --serve</command> on the remote side to send or - receive closures. This fixes a race condition between - <command>nix-copy-closure</command> and the garbage - collector.</para></listitem> - - <listitem><para>Derivations can specify the new special attribute - <varname>allowedRequisites</varname>, which has a similar meaning to - <varname>allowedReferences</varname>. But instead of only enforcing - to explicitly specify the immediate references, it requires the - derivation to specify all the dependencies recursively (hence the - name, requisites) that are used by the resulting - output.</para></listitem> - - <listitem><para>On Mac OS X, Nix now handles case collisions when - importing closures from case-sensitive file systems. This is mostly - useful for running NixOps on Mac OS X.</para></listitem> - - <listitem><para>The Nix daemon has new configuration options - <option>allowed-users</option> (specifying the users and groups that - are allowed to connect to the daemon) and - <option>trusted-users</option> (specifying the users and groups that - can perform privileged operations like specifying untrusted binary - caches).</para></listitem> - - <listitem><para>The configuration option - <option>build-cores</option> now defaults to the number of available - CPU cores.</para></listitem> - - <listitem><para>Build users are now used by default when Nix is - invoked as root. This prevents builds from accidentally running as - root.</para></listitem> - - <listitem><para>Nix now includes systemd units and Upstart - jobs.</para></listitem> - - <listitem><para>Speed improvements to <command>nix-store - --optimise</command>.</para></listitem> - - <listitem><para>Language change: the <literal>==</literal> operator - now ignores string contexts (the “dependencies” of a - string).</para></listitem> - - <listitem><para>Nix now filters out Nix-specific ANSI escape - sequences on standard error. They are supposed to be invisible, but - some terminals show them anyway.</para></listitem> - - <listitem><para>Various commands now automatically pipe their output - into the pager as specified by the <envar>PAGER</envar> environment - variable.</para></listitem> - - <listitem><para>Several improvements to reduce memory consumption in - the evaluator.</para></listitem> - -</itemizedlist> - -<para>This release has contributions from Adam Szkoda, Aristid -Breitkreuz, Bob van der Linden, Charles Strahan, darealshinji, Eelco -Dolstra, Gergely Risko, Joel Taylor, Ludovic Courtès, Marko Durkovic, -Mikey Ariel, Paul Colomiets, Ricardo M. Correia, Ricky Elrod, Robert -Helgesson, Rob Vermaas, Russell O'Connor, Shea Levy, Shell Turner, -Sönke Hahn, Steve Purcell, Vladimír Čunát and Wout Mertens.</para> - -</section> diff --git a/doc/manual/release-notes/rl-1.9.xml b/doc/manual/release-notes/rl-1.9.xml deleted file mode 100644 index c8406bd20..000000000 --- a/doc/manual/release-notes/rl-1.9.xml +++ /dev/null @@ -1,216 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-1.9"> - -<title>Release 1.9 (2015-06-12)</title> - -<para>In addition to the usual bug fixes, this release has the -following new features:</para> - -<itemizedlist> - - <listitem> - <para>Signed binary cache support. You can enable signature - checking by adding the following to <filename>nix.conf</filename>: - -<programlisting> -signed-binary-caches = * -binary-cache-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= -</programlisting> - - This will prevent Nix from downloading any binary from the cache - that is not signed by one of the keys listed in - <option>binary-cache-public-keys</option>.</para> - - <para>Signature checking is only supported if you built Nix with - the <literal>libsodium</literal> package.</para> - - <para>Note that while Nix has had experimental support for signed - binary caches since version 1.7, this release changes the - signature format in a backwards-incompatible way.</para> - - </listitem> - - <listitem> - - <para>Automatic downloading of Nix expression tarballs. In various - places, you can now specify the URL of a tarball containing Nix - expressions (such as Nixpkgs), which will be downloaded and - unpacked automatically. For example:</para> - - <itemizedlist> - - <listitem><para>In <command>nix-env</command>: - -<screen> -$ nix-env -f https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox -</screen> - - This installs Firefox from the latest tested and built revision - of the NixOS 14.12 channel.</para></listitem> - - <listitem><para>In <command>nix-build</command> and - <command>nix-shell</command>: - -<screen> -$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello -</screen> - - This builds GNU Hello from the latest revision of the Nixpkgs - master branch.</para></listitem> - - <listitem><para>In the Nix search path (as specified via - <envar>NIX_PATH</envar> or <option>-I</option>). For example, to - start a shell containing the Pan package from a specific version - of Nixpkgs: - -<screen> -$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz -</screen> - - </para></listitem> - - <listitem><para>In <command>nixos-rebuild</command> (on NixOS): - -<screen> -$ nixos-rebuild test -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-unstable.tar.gz -</screen> - - </para></listitem> - - <listitem><para>In Nix expressions, via the new builtin function <function>fetchTarball</function>: - -<programlisting> -with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {}; … -</programlisting> - - (This is not allowed in restricted mode.)</para></listitem> - - </itemizedlist> - - </listitem> - - <listitem> - - <para><command>nix-shell</command> improvements:</para> - - <itemizedlist> - - <listitem><para><command>nix-shell</command> now has a flag - <option>--run</option> to execute a command in the - <command>nix-shell</command> environment, - e.g. <literal>nix-shell --run make</literal>. This is like - the existing <option>--command</option> flag, except that it - uses a non-interactive shell (ensuring that hitting Ctrl-C won’t - drop you into the child shell).</para></listitem> - - <listitem><para><command>nix-shell</command> can now be used as - a <literal>#!</literal>-interpreter. This allows you to write - scripts that dynamically fetch their own dependencies. For - example, here is a Haskell script that, when invoked, first - downloads GHC and the Haskell packages on which it depends: - -<programlisting> -#! /usr/bin/env nix-shell -#! nix-shell -i runghc -p haskellPackages.ghc haskellPackages.HTTP - -import Network.HTTP - -main = do - resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/") - body <- getResponseBody resp - print (take 100 body) -</programlisting> - - Of course, the dependencies are cached in the Nix store, so the - second invocation of this script will be much - faster.</para></listitem> - - </itemizedlist> - - </listitem> - - <listitem> - - <para>Chroot improvements:</para> - - <itemizedlist> - - <listitem><para>Chroot builds are now supported on Mac OS X - (using its sandbox mechanism).</para></listitem> - - <listitem><para>If chroots are enabled, they are now used for - all derivations, including fixed-output derivations (such as - <function>fetchurl</function>). The latter do have network - access, but can no longer access the host filesystem. If you - need the old behaviour, you can set the option - <option>build-use-chroot</option> to - <literal>relaxed</literal>.</para></listitem> - - <listitem><para>On Linux, if chroots are enabled, builds are - performed in a private PID namespace once again. (This - functionality was lost in Nix 1.8.)</para></listitem> - - <listitem><para>Store paths listed in - <option>build-chroot-dirs</option> are now automatically - expanded to their closure. For instance, if you want - <filename>/nix/store/…-bash/bin/sh</filename> mounted in your - chroot as <filename>/bin/sh</filename>, you only need to say - <literal>build-chroot-dirs = - /bin/sh=/nix/store/…-bash/bin/sh</literal>; it is no longer - necessary to specify the dependencies of Bash.</para></listitem> - - </itemizedlist> - - </listitem> - - <listitem><para>The new derivation attribute - <varname>passAsFile</varname> allows you to specify that the - contents of derivation attributes should be passed via files rather - than environment variables. This is useful if you need to pass very - long strings that exceed the size limit of the environment. The - Nixpkgs function <function>writeTextFile</function> uses - this.</para></listitem> - - <listitem><para>You can now use <literal>~</literal> in Nix file - names to refer to your home directory, e.g. <literal>import - ~/.nixpkgs/config.nix</literal>.</para></listitem> - - <listitem><para>Nix has a new option <option>restrict-eval</option> - that allows limiting what paths the Nix evaluator has access to. By - passing <literal>--option restrict-eval true</literal> to Nix, the - evaluator will throw an exception if an attempt is made to access - any file outside of the Nix search path. This is primarily intended - for Hydra to ensure that a Hydra jobset only refers to its declared - inputs (and is therefore reproducible).</para></listitem> - - <listitem><para><command>nix-env</command> now only creates a new - “generation” symlink in <filename>/nix/var/nix/profiles</filename> - if something actually changed.</para></listitem> - - <listitem><para>The environment variable <envar>NIX_PAGER</envar> - can now be set to override <envar>PAGER</envar>. You can set it to - <literal>cat</literal> to disable paging for Nix commands - only.</para></listitem> - - <listitem><para>Failing <literal><...></literal> - lookups now show position information.</para></listitem> - - <listitem><para>Improved Boehm GC use: we disabled scanning for - interior pointers, which should reduce the “<literal>Repeated - allocation of very large block</literal>” warnings and associated - retention of memory.</para></listitem> - -</itemizedlist> - -<para>This release has contributions from aszlig, Benjamin Staffin, -Charles Strahan, Christian Theune, Daniel Hahler, Danylo Hlynskyi -Daniel Peebles, Dan Peebles, Domen Kožar, Eelco Dolstra, Harald van -Dijk, Hoang Xuan Phu, Jaka Hudoklin, Jeff Ramnani, j-keck, Linquize, -Luca Bruno, Michael Merickel, Oliver Dunkl, Rob Vermaas, Rok Garbas, -Shea Levy, Tobias Geerinckx-Rice and William A. Kennington III.</para> - -</section> - diff --git a/doc/manual/release-notes/rl-2.0.xml b/doc/manual/release-notes/rl-2.0.xml deleted file mode 100644 index 4c683dd3d..000000000 --- a/doc/manual/release-notes/rl-2.0.xml +++ /dev/null @@ -1,1012 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-2.0"> - -<title>Release 2.0 (2018-02-22)</title> - -<para>The following incompatible changes have been made:</para> - -<itemizedlist> - - <listitem> - <para>The manifest-based substituter mechanism - (<command>download-using-manifests</command>) has been <link - xlink:href="https://github.com/NixOS/nix/commit/867967265b80946dfe1db72d40324b4f9af988ed">removed</link>. It - has been superseded by the binary cache substituter mechanism - since several years. As a result, the following programs have been - removed: - - <itemizedlist> - <listitem><para><command>nix-pull</command></para></listitem> - <listitem><para><command>nix-generate-patches</command></para></listitem> - <listitem><para><command>bsdiff</command></para></listitem> - <listitem><para><command>bspatch</command></para></listitem> - </itemizedlist> - </para> - </listitem> - - <listitem> - <para>The “copy from other stores” substituter mechanism - (<command>copy-from-other-stores</command> and the - <envar>NIX_OTHER_STORES</envar> environment variable) has been - removed. It was primarily used by the NixOS installer to copy - available paths from the installation medium. The replacement is - to use a chroot store as a substituter - (e.g. <literal>--substituters /mnt</literal>), or to build into a - chroot store (e.g. <literal>--store /mnt --substituters /</literal>).</para> - </listitem> - - <listitem> - <para>The command <command>nix-push</command> has been removed as - part of the effort to eliminate Nix's dependency on Perl. You can - use <command>nix copy</command> instead, e.g. <literal>nix copy - --to file:///tmp/my-binary-cache <replaceable>paths…</replaceable></literal></para> - </listitem> - - <listitem> - <para>The “nested” log output feature (<option>--log-type - pretty</option>) has been removed. As a result, - <command>nix-log2xml</command> was also removed.</para> - </listitem> - - <listitem> - <para>OpenSSL-based signing has been <link - xlink:href="https://github.com/NixOS/nix/commit/f435f8247553656774dd1b2c88e9de5d59cab203">removed</link>. This - feature was never well-supported. A better alternative is provided - by the <option>secret-key-files</option> and - <option>trusted-public-keys</option> options.</para> - </listitem> - - <listitem> - <para>Failed build caching has been <link - xlink:href="https://github.com/NixOS/nix/commit/8cffec84859cec8b610a2a22ab0c4d462a9351ff">removed</link>. This - feature was introduced to support the Hydra continuous build - system, but Hydra no longer uses it.</para> - </listitem> - - <listitem> - <para><filename>nix-mode.el</filename> has been removed from - Nix. It is now <link - xlink:href="https://github.com/NixOS/nix-mode">a separate - repository</link> and can be installed through the MELPA package - repository.</para> - </listitem> - -</itemizedlist> - -<para>This release has the following new features:</para> - -<itemizedlist> - - <listitem> - <para>It introduces a new command named <command>nix</command>, - which is intended to eventually replace all - <command>nix-*</command> commands with a more consistent and - better designed user interface. It currently provides replacements - for some (but not all) of the functionality provided by - <command>nix-store</command>, <command>nix-build</command>, - <command>nix-shell -p</command>, <command>nix-env -qa</command>, - <command>nix-instantiate --eval</command>, - <command>nix-push</command> and - <command>nix-copy-closure</command>. It has the following major - features:</para> - - <itemizedlist> - - <listitem> - <para>Unlike the legacy commands, it has a consistent way to - refer to packages and package-like arguments (like store - paths). For example, the following commands all copy the GNU - Hello package to a remote machine: - - <screen>nix copy --to ssh://machine nixpkgs.hello</screen> - <screen>nix copy --to ssh://machine /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10</screen> - <screen>nix copy --to ssh://machine '(with import <nixpkgs> {}; hello)'</screen> - - By contrast, <command>nix-copy-closure</command> only accepted - store paths as arguments.</para> - </listitem> - - <listitem> - <para>It is self-documenting: <option>--help</option> shows - all available command-line arguments. If - <option>--help</option> is given after a subcommand, it shows - examples for that subcommand. <command>nix - --help-config</command> shows all configuration - options.</para> - </listitem> - - <listitem> - <para>It is much less verbose. By default, it displays a - single-line progress indicator that shows how many packages - are left to be built or downloaded, and (if there are running - builds) the most recent line of builder output. If a build - fails, it shows the last few lines of builder output. The full - build log can be retrieved using <command>nix - log</command>.</para> - </listitem> - - <listitem> - <para>It <link - xlink:href="https://github.com/NixOS/nix/commit/b8283773bd64d7da6859ed520ee19867742a03ba">provides</link> - all <filename>nix.conf</filename> configuration options as - command line flags. For example, instead of <literal>--option - http-connections 100</literal> you can write - <literal>--http-connections 100</literal>. Boolean options can - be written as - <literal>--<replaceable>foo</replaceable></literal> or - <literal>--no-<replaceable>foo</replaceable></literal> - (e.g. <option>--no-auto-optimise-store</option>).</para> - </listitem> - - <listitem> - <para>Many subcommands have a <option>--json</option> flag to - write results to stdout in JSON format.</para> - </listitem> - - </itemizedlist> - - <warning><para>Please note that the <command>nix</command> command - is a work in progress and the interface is subject to - change.</para></warning> - - <para>It provides the following high-level (“porcelain”) - subcommands:</para> - - <itemizedlist> - - <listitem> - <para><command>nix build</command> is a replacement for - <command>nix-build</command>.</para> - </listitem> - - <listitem> - <para><command>nix run</command> executes a command in an - environment in which the specified packages are available. It - is (roughly) a replacement for <command>nix-shell - -p</command>. Unlike that command, it does not execute the - command in a shell, and has a flag (<command>-c</command>) - that specifies the unquoted command line to be - executed.</para> - - <para>It is particularly useful in conjunction with chroot - stores, allowing Linux users who do not have permission to - install Nix in <command>/nix/store</command> to still use - binary substitutes that assume - <command>/nix/store</command>. For example, - - <screen>nix run --store ~/my-nix nixpkgs.hello -c hello --greeting 'Hi everybody!'</screen> - - downloads (or if not substitutes are available, builds) the - GNU Hello package into - <filename>~/my-nix/nix/store</filename>, then runs - <command>hello</command> in a mount namespace where - <filename>~/my-nix/nix/store</filename> is mounted onto - <command>/nix/store</command>.</para> - </listitem> - - <listitem> - <para><command>nix search</command> replaces <command>nix-env - -qa</command>. It searches the available packages for - occurrences of a search string in the attribute name, package - name or description. Unlike <command>nix-env -qa</command>, it - has a cache to speed up subsequent searches.</para> - </listitem> - - <listitem> - <para><command>nix copy</command> copies paths between - arbitrary Nix stores, generalising - <command>nix-copy-closure</command> and - <command>nix-push</command>.</para> - </listitem> - - <listitem> - <para><command>nix repl</command> replaces the external - program <command>nix-repl</command>. It provides an - interactive environment for evaluating and building Nix - expressions. Note that it uses <literal>linenoise-ng</literal> - instead of GNU Readline.</para> - </listitem> - - <listitem> - <para><command>nix upgrade-nix</command> upgrades Nix to the - latest stable version. This requires that Nix is installed in - a profile. (Thus it won’t work on NixOS, or if it’s installed - outside of the Nix store.)</para> - </listitem> - - <listitem> - <para><command>nix verify</command> checks whether store paths - are unmodified and/or “trusted” (see below). It replaces - <command>nix-store --verify</command> and <command>nix-store - --verify-path</command>.</para> - </listitem> - - <listitem> - <para><command>nix log</command> shows the build log of a - package or path. If the build log is not available locally, it - will try to obtain it from the configured substituters (such - as <uri>cache.nixos.org</uri>, which now provides build - logs).</para> - </listitem> - - <listitem> - <para><command>nix edit</command> opens the source code of a - package in your editor.</para> - </listitem> - - <listitem> - <para><command>nix eval</command> replaces - <command>nix-instantiate --eval</command>.</para> - </listitem> - - <listitem> - <para><command - xlink:href="https://github.com/NixOS/nix/commit/d41c5eb13f4f3a37d80dbc6d3888644170c3b44a">nix - why-depends</command> shows why one store path has another in - its closure. This is primarily useful to finding the causes of - closure bloat. For example, - - <screen>nix why-depends nixpkgs.vlc nixpkgs.libdrm.dev</screen> - - shows a chain of files and fragments of file contents that - cause the VLC package to have the “dev” output of - <literal>libdrm</literal> in its closure — an undesirable - situation.</para> - </listitem> - - <listitem> - <para><command>nix path-info</command> shows information about - store paths, replacing <command>nix-store -q</command>. A - useful feature is the option <option>--closure-size</option> - (<option>-S</option>). For example, the following command show - the closure sizes of every path in the current NixOS system - closure, sorted by size: - - <screen>nix path-info -rS /run/current-system | sort -nk2</screen> - - </para> - </listitem> - - <listitem> - <para><command>nix optimise-store</command> replaces - <command>nix-store --optimise</command>. The main difference - is that it has a progress indicator.</para> - </listitem> - - </itemizedlist> - - <para>A number of low-level (“plumbing”) commands are also - available:</para> - - <itemizedlist> - - <listitem> - <para><command>nix ls-store</command> and <command>nix - ls-nar</command> list the contents of a store path or NAR - file. The former is primarily useful in conjunction with - remote stores, e.g. - - <screen>nix ls-store --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10</screen> - - lists the contents of path in a binary cache.</para> - </listitem> - - <listitem> - <para><command>nix cat-store</command> and <command>nix - cat-nar</command> allow extracting a file from a store path or - NAR file.</para> - </listitem> - - <listitem> - <para><command>nix dump-path</command> writes the contents of - a store path to stdout in NAR format. This replaces - <command>nix-store --dump</command>.</para> - </listitem> - - <listitem> - <para><command - xlink:href="https://github.com/NixOS/nix/commit/e8d6ee7c1b90a2fe6d824f1a875acc56799ae6e2">nix - show-derivation</command> displays a store derivation in JSON - format. This is an alternative to - <command>pp-aterm</command>.</para> - </listitem> - - <listitem> - <para><command - xlink:href="https://github.com/NixOS/nix/commit/970366266b8df712f5f9cedb45af183ef5a8357f">nix - add-to-store</command> replaces <command>nix-store - --add</command>.</para> - </listitem> - - <listitem> - <para><command>nix sign-paths</command> signs store - paths.</para> - </listitem> - - <listitem> - <para><command>nix copy-sigs</command> copies signatures from - one store to another.</para> - </listitem> - - <listitem> - <para><command>nix show-config</command> shows all - configuration options and their current values.</para> - </listitem> - - </itemizedlist> - - </listitem> - - <listitem> - <para>The store abstraction that Nix has had for a long time to - support store access via the Nix daemon has been extended - significantly. In particular, substituters (which used to be - external programs such as - <command>download-from-binary-cache</command>) are now subclasses - of the abstract <classname>Store</classname> class. This allows - many Nix commands to operate on such store types. For example, - <command>nix path-info</command> shows information about paths in - your local Nix store, while <command>nix path-info --store - https://cache.nixos.org/</command> shows information about paths - in the specified binary cache. Similarly, - <command>nix-copy-closure</command>, <command>nix-push</command> - and substitution are all instances of the general notion of - copying paths between different kinds of Nix stores.</para> - - <para>Stores are specified using an URI-like syntax, - e.g. <uri>https://cache.nixos.org/</uri> or - <uri>ssh://machine</uri>. The following store types are supported: - - <itemizedlist> - - <listitem> - - <para><classname>LocalStore</classname> (stori URI - <literal>local</literal> or an absolute path) and the misnamed - <classname>RemoteStore</classname> (<literal>daemon</literal>) - provide access to a local Nix store, the latter via the Nix - daemon. You can use <literal>auto</literal> or the empty - string to auto-select a local or daemon store depending on - whether you have write permission to the Nix store. It is no - longer necessary to set the <envar>NIX_REMOTE</envar> - environment variable to use the Nix daemon.</para> - - <para>As noted above, <classname>LocalStore</classname> now - supports chroot builds, allowing the “physical” location of - the Nix store - (e.g. <filename>/home/alice/nix/store</filename>) to differ - from its “logical” location (typically - <filename>/nix/store</filename>). This allows non-root users - to use Nix while still getting the benefits from prebuilt - binaries from <uri>cache.nixos.org</uri>.</para> - - </listitem> - - <listitem> - - <para><classname>BinaryCacheStore</classname> is the abstract - superclass of all binary cache stores. It supports writing - build logs and NAR content listings in JSON format.</para> - - </listitem> - - <listitem> - - <para><classname>HttpBinaryCacheStore</classname> - (<literal>http://</literal>, <literal>https://</literal>) - supports binary caches via HTTP or HTTPS. If the server - supports <literal>PUT</literal> requests, it supports - uploading store paths via commands such as <command>nix - copy</command>.</para> - - </listitem> - - <listitem> - - <para><classname>LocalBinaryCacheStore</classname> - (<literal>file://</literal>) supports binary caches in the - local filesystem.</para> - - </listitem> - - <listitem> - - <para><classname>S3BinaryCacheStore</classname> - (<literal>s3://</literal>) supports binary caches stored in - Amazon S3, if enabled at compile time.</para> - - </listitem> - - <listitem> - - <para><classname>LegacySSHStore</classname> (<literal>ssh://</literal>) - is used to implement remote builds and - <command>nix-copy-closure</command>.</para> - - </listitem> - - <listitem> - - <para><classname>SSHStore</classname> - (<literal>ssh-ng://</literal>) supports arbitrary Nix - operations on a remote machine via the same protocol used by - <command>nix-daemon</command>.</para> - - </listitem> - - </itemizedlist> - - </para> - - </listitem> - - <listitem> - - <para>Security has been improved in various ways: - - <itemizedlist> - - <listitem> - <para>Nix now stores signatures for local store - paths. When paths are copied between stores (e.g., copied from - a binary cache to a local store), signatures are - propagated.</para> - - <para>Locally-built paths are signed automatically using the - secret keys specified by the <option>secret-key-files</option> - store option. Secret/public key pairs can be generated using - <command>nix-store - --generate-binary-cache-key</command>.</para> - - <para>In addition, locally-built store paths are marked as - “ultimately trusted”, but this bit is not propagated when - paths are copied between stores.</para> - </listitem> - - <listitem> - <para>Content-addressable store paths no longer require - signatures — they can be imported into a store by unprivileged - users even if they lack signatures.</para> - </listitem> - - <listitem> - <para>The command <command>nix verify</command> checks whether - the specified paths are trusted, i.e., have a certain number - of trusted signatures, are ultimately trusted, or are - content-addressed.</para> - </listitem> - - <listitem> - <para>Substitutions from binary caches <link - xlink:href="https://github.com/NixOS/nix/commit/ecbc3fedd3d5bdc5a0e1a0a51b29062f2874ac8b">now</link> - require signatures by default. This was already the case on - NixOS.</para> - </listitem> - - <listitem> - <para>In Linux sandbox builds, we <link - xlink:href="https://github.com/NixOS/nix/commit/eba840c8a13b465ace90172ff76a0db2899ab11b">now</link> - use <filename>/build</filename> instead of - <filename>/tmp</filename> as the temporary build - directory. This fixes potential security problems when a build - accidentally stores its <envar>TMPDIR</envar> in some - security-sensitive place, such as an RPATH.</para> - </listitem> - - </itemizedlist> - - </para> - - </listitem> - - <listitem> - <para><emphasis>Pure evaluation mode</emphasis>. With the - <literal>--pure-eval</literal> flag, Nix enables a variant of the existing - restricted evaluation mode that forbids access to anything that could cause - different evaluations of the same command line arguments to produce a - different result. This includes builtin functions such as - <function>builtins.getEnv</function>, but more importantly, - <emphasis>all</emphasis> filesystem or network access unless a content hash - or commit hash is specified. For example, calls to - <function>builtins.fetchGit</function> are only allowed if a - <varname>rev</varname> attribute is specified.</para> - - <para>The goal of this feature is to enable true reproducibility - and traceability of builds (including NixOS system configurations) - at the evaluation level. For example, in the future, - <command>nixos-rebuild</command> might build configurations from a - Nix expression in a Git repository in pure mode. That expression - might fetch other repositories such as Nixpkgs via - <function>builtins.fetchGit</function>. The commit hash of the - top-level repository then uniquely identifies a running system, - and, in conjunction with that repository, allows it to be - reproduced or modified.</para> - - </listitem> - - <listitem> - <para>There are several new features to support binary - reproducibility (i.e. to help ensure that multiple builds of the - same derivation produce exactly the same output). When - <option>enforce-determinism</option> is set to - <literal>false</literal>, it’s <link - xlink:href="https://github.com/NixOS/nix/commit/8bdf83f936adae6f2c907a6d2541e80d4120f051">no - longer</link> a fatal error if build rounds produce different - output. Also, a hook named <option>diff-hook</option> is <link - xlink:href="https://github.com/NixOS/nix/commit/9a313469a4bdea2d1e8df24d16289dc2a172a169">provided</link> - to allow you to run tools such as <command>diffoscope</command> - when build rounds produce different output.</para> - </listitem> - - <listitem> - <para>Configuring remote builds is a lot easier now. Provided you - are not using the Nix daemon, you can now just specify a remote - build machine on the command line, e.g. <literal>--option builders - 'ssh://my-mac x86_64-darwin'</literal>. The environment variable - <envar>NIX_BUILD_HOOK</envar> has been removed and is no longer - needed. The environment variable <envar>NIX_REMOTE_SYSTEMS</envar> - is still supported for compatibility, but it is also possible to - specify builders in <command>nix.conf</command> by setting the - option <literal>builders = - @<replaceable>path</replaceable></literal>.</para> - </listitem> - - <listitem> - <para>If a fixed-output derivation produces a result with an - incorrect hash, the output path is moved to the location - corresponding to the actual hash and registered as valid. Thus, a - subsequent build of the fixed-output derivation with the correct - hash is unnecessary.</para> - </listitem> - - <listitem> - <para><command>nix-shell</command> <link - xlink:href="https://github.com/NixOS/nix/commit/ea59f39326c8e9dc42dfed4bcbf597fbce58797c">now</link> - sets the <varname>IN_NIX_SHELL</varname> environment variable - during evaluation and in the shell itself. This can be used to - perform different actions depending on whether you’re in a Nix - shell or in a regular build. Nixpkgs provides - <varname>lib.inNixShell</varname> to check this variable during - evaluation.</para> - </listitem> - - <listitem> - <para><envar>NIX_PATH</envar> is now lazy, so URIs in the path are - only downloaded if they are needed for evaluation.</para> - </listitem> - - <listitem> - <para>You can now use - <uri>channel:<replaceable>channel-name</replaceable></uri> as a - short-hand for - <uri>https://nixos.org/channels/<replaceable>channel-name</replaceable>/nixexprs.tar.xz</uri>. For - example, <literal>nix-build channel:nixos-15.09 -A hello</literal> - will build the GNU Hello package from the - <literal>nixos-15.09</literal> channel. In the future, this may - use Git to fetch updates more efficiently.</para> - </listitem> - - <listitem> - <para>When <option>--no-build-output</option> is given, the last - 10 lines of the build log will be shown if a build - fails.</para> - </listitem> - - <listitem> - <para>Networking has been improved: - - <itemizedlist> - - <listitem> - <para>HTTP/2 is now supported. This makes binary cache lookups - <link - xlink:href="https://github.com/NixOS/nix/commit/90ad02bf626b885a5dd8967894e2eafc953bdf92">much - more efficient</link>.</para> - </listitem> - - <listitem> - <para>We now retry downloads on many HTTP errors, making - binary caches substituters more resilient to temporary - failures.</para> - </listitem> - - <listitem> - <para>HTTP credentials can now be configured via the standard - <filename>netrc</filename> mechanism.</para> - </listitem> - - <listitem> - <para>If S3 support is enabled at compile time, - <uri>s3://</uri> URIs are <link - xlink:href="https://github.com/NixOS/nix/commit/9ff9c3f2f80ba4108e9c945bbfda2c64735f987b">supported</link> - in all places where Nix allows URIs.</para> - </listitem> - - <listitem> - <para>Brotli compression is now supported. In particular, - <uri>cache.nixos.org</uri> build logs are now compressed using - Brotli.</para> - </listitem> - - </itemizedlist> - - </para> - - </listitem> - - <listitem> - <para><command>nix-env</command> <link - xlink:href="https://github.com/NixOS/nix/commit/b0cb11722626e906a73f10dd9a0c9eea29faf43a">now</link> - ignores packages with bad derivation names (in particular those - starting with a digit or containing a dot).</para> - </listitem> - - <listitem> - <para>Many configuration options have been renamed, either because - they were unnecessarily verbose - (e.g. <option>build-use-sandbox</option> is now just - <option>sandbox</option>) or to reflect generalised behaviour - (e.g. <option>binary-caches</option> is now - <option>substituters</option> because it allows arbitrary store - URIs). The old names are still supported for compatibility.</para> - </listitem> - - <listitem> - <para>The <option>max-jobs</option> option can <link - xlink:href="https://github.com/NixOS/nix/commit/7251d048fa812d2551b7003bc9f13a8f5d4c95a5">now</link> - be set to <literal>auto</literal> to use the number of CPUs in the - system.</para> - </listitem> - - <listitem> - <para>Hashes can <link - xlink:href="https://github.com/NixOS/nix/commit/c0015e87af70f539f24d2aa2bc224a9d8b84276b">now</link> - be specified in base-64 format, in addition to base-16 and the - non-standard base-32.</para> - </listitem> - - <listitem> - <para><command>nix-shell</command> now uses - <varname>bashInteractive</varname> from Nixpkgs, rather than the - <command>bash</command> command that happens to be in the caller’s - <envar>PATH</envar>. This is especially important on macOS where - the <command>bash</command> provided by the system is seriously - outdated and cannot execute <literal>stdenv</literal>’s setup - script.</para> - </listitem> - - <listitem> - <para>Nix can now automatically trigger a garbage collection if - free disk space drops below a certain level during a build. This - is configured using the <option>min-free</option> and - <option>max-free</option> options.</para> - </listitem> - - <listitem> - <para><command>nix-store -q --roots</command> and - <command>nix-store --gc --print-roots</command> now show temporary - and in-memory roots.</para> - </listitem> - - <listitem> - <para> - Nix can now be extended with plugins. See the documentation of - the <option>plugin-files</option> option for more details. - </para> - </listitem> - -</itemizedlist> - -<para>The Nix language has the following new features: - -<itemizedlist> - - <listitem> - <para>It supports floating point numbers. They are based on the - C++ <literal>float</literal> type and are supported by the - existing numerical operators. Export and import to and from JSON - and XML works, too.</para> - </listitem> - - <listitem> - <para>Derivation attributes can now reference the outputs of the - derivation using the <function>placeholder</function> builtin - function. For example, the attribute - -<programlisting> -configureFlags = "--prefix=${placeholder "out"} --includedir=${placeholder "dev"}"; -</programlisting> - - will cause the <envar>configureFlags</envar> environment variable - to contain the actual store paths corresponding to the - <literal>out</literal> and <literal>dev</literal> outputs.</para> - </listitem> - -</itemizedlist> - -</para> - -<para>The following builtin functions are new or extended: - -<itemizedlist> - - <listitem> - <para><function - xlink:href="https://github.com/NixOS/nix/commit/38539b943a060d9cdfc24d6e5d997c0885b8aa2f">builtins.fetchGit</function> - allows Git repositories to be fetched at evaluation time. Thus it - differs from the <function>fetchgit</function> function in - Nixpkgs, which fetches at build time and cannot be used to fetch - Nix expressions during evaluation. A typical use case is to import - external NixOS modules from your configuration, e.g. - - <programlisting>imports = [ (builtins.fetchGit https://github.com/edolstra/dwarffs + "/module.nix") ];</programlisting> - - </para> - </listitem> - - <listitem> - <para>Similarly, <function>builtins.fetchMercurial</function> - allows you to fetch Mercurial repositories.</para> - </listitem> - - <listitem> - <para><function>builtins.path</function> generalises - <function>builtins.filterSource</function> and path literals - (e.g. <literal>./foo</literal>). It allows specifying a store path - name that differs from the source path name - (e.g. <literal>builtins.path { path = ./foo; name = "bar"; - }</literal>) and also supports filtering out unwanted - files.</para> - </listitem> - - <listitem> - <para><function>builtins.fetchurl</function> and - <function>builtins.fetchTarball</function> now support - <varname>sha256</varname> and <varname>name</varname> - attributes.</para> - </listitem> - - <listitem> - <para><function - xlink:href="https://github.com/NixOS/nix/commit/b8867a0239b1930a16f9ef3f7f3e864b01416dff">builtins.split</function> - splits a string using a POSIX extended regular expression as the - separator.</para> - </listitem> - - <listitem> - <para><function - xlink:href="https://github.com/NixOS/nix/commit/26d92017d3b36cff940dcb7d1611c42232edb81a">builtins.partition</function> - partitions the elements of a list into two lists, depending on a - Boolean predicate.</para> - </listitem> - - <listitem> - <para><literal><nix/fetchurl.nix></literal> now uses the - content-addressable tarball cache at - <uri>http://tarballs.nixos.org/</uri>, just like - <function>fetchurl</function> in - Nixpkgs. (f2682e6e18a76ecbfb8a12c17e3a0ca15c084197)</para> - </listitem> - - <listitem> - <para>In restricted and pure evaluation mode, builtin functions - that download from the network (such as - <function>fetchGit</function>) are permitted to fetch underneath a - list of URI prefixes specified in the option - <option>allowed-uris</option>.</para> - </listitem> - -</itemizedlist> - -</para> - -<para>The Nix build environment has the following changes: - -<itemizedlist> - - <listitem> - <para>Values such as Booleans, integers, (nested) lists and - attribute sets can <link - xlink:href="https://github.com/NixOS/nix/commit/6de33a9c675b187437a2e1abbcb290981a89ecb1">now</link> - be passed to builders in a non-lossy way. If the special attribute - <varname>__structuredAttrs</varname> is set to - <literal>true</literal>, the other derivation attributes are - serialised in JSON format and made available to the builder via - the file <envar>.attrs.json</envar> in the builder’s temporary - directory. This obviates the need for - <varname>passAsFile</varname> since JSON files have no size - restrictions, unlike process environments.</para> - - <para><link - xlink:href="https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699">As - a convenience to Bash builders</link>, Nix writes a script named - <envar>.attrs.sh</envar> to the builder’s directory that - initialises shell variables corresponding to all attributes that - are representable in Bash. This includes non-nested (associative) - arrays. For example, the attribute <literal>hardening.format = - true</literal> ends up as the Bash associative array element - <literal>${hardening[format]}</literal>.</para> - </listitem> - - <listitem> - <para>Builders can <link - xlink:href="https://github.com/NixOS/nix/commit/88e6bb76de5564b3217be9688677d1c89101b2a3">now</link> - communicate what build phase they are in by writing messages to - the file descriptor specified in <envar>NIX_LOG_FD</envar>. The - current phase is shown by the <command>nix</command> progress - indicator. - </para> - </listitem> - - <listitem> - <para>In Linux sandbox builds, we <link - xlink:href="https://github.com/NixOS/nix/commit/a2d92bb20e82a0957067ede60e91fab256948b41">now</link> - provide a default <filename>/bin/sh</filename> (namely - <filename>ash</filename> from BusyBox).</para> - </listitem> - - <listitem> - <para>In structured attribute mode, - <varname>exportReferencesGraph</varname> <link - xlink:href="https://github.com/NixOS/nix/commit/c2b0d8749f7e77afc1c4b3e8dd36b7ee9720af4a">exports</link> - extended information about closures in JSON format. In particular, - it includes the sizes and hashes of paths. This is primarily - useful for NixOS image builders.</para> - </listitem> - - <listitem> - <para>Builds are <link - xlink:href="https://github.com/NixOS/nix/commit/21948deed99a3295e4d5666e027a6ca42dc00b40">now</link> - killed as soon as Nix receives EOF on the builder’s stdout or - stderr. This fixes a bug that allowed builds to hang Nix - indefinitely, regardless of - timeouts.</para> - </listitem> - - <listitem> - <para>The <option>sandbox-paths</option> configuration - option can now specify optional paths by appending a - <literal>?</literal>, e.g. <literal>/dev/nvidiactl?</literal> will - bind-mount <varname>/dev/nvidiactl</varname> only if it - exists.</para> - </listitem> - - <listitem> - <para>On Linux, builds are now executed in a user - namespace with UID 1000 and GID 100.</para> - </listitem> - -</itemizedlist> - -</para> - -<para>A number of significant internal changes were made: - -<itemizedlist> - - <listitem> - <para>Nix no longer depends on Perl and all Perl components have - been rewritten in C++ or removed. The Perl bindings that used to - be part of Nix have been moved to a separate package, - <literal>nix-perl</literal>.</para> - </listitem> - - <listitem> - <para>All <classname>Store</classname> classes are now - thread-safe. <classname>RemoteStore</classname> supports multiple - concurrent connections to the daemon. This is primarily useful in - multi-threaded programs such as - <command>hydra-queue-runner</command>.</para> - </listitem> - -</itemizedlist> - -</para> - -<para>This release has contributions from - -Adrien Devresse, -Alexander Ried, -Alex Cruice, -Alexey Shmalko, -AmineChikhaoui, -Andy Wingo, -Aneesh Agrawal, -Anthony Cowley, -Armijn Hemel, -aszlig, -Ben Gamari, -Benjamin Hipple, -Benjamin Staffin, -Benno Fünfstück, -Bjørn Forsman, -Brian McKenna, -Charles Strahan, -Chase Adams, -Chris Martin, -Christian Theune, -Chris Warburton, -Daiderd Jordan, -Dan Connolly, -Daniel Peebles, -Dan Peebles, -davidak, -David McFarland, -Dmitry Kalinkin, -Domen Kožar, -Eelco Dolstra, -Emery Hemingway, -Eric Litak, -Eric Wolf, -Fabian Schmitthenner, -Frederik Rietdijk, -Gabriel Gonzalez, -Giorgio Gallo, -Graham Christensen, -Guillaume Maudoux, -Harmen, -Iavael, -James Broadhead, -James Earl Douglas, -Janus Troelsen, -Jeremy Shaw, -Joachim Schiele, -Joe Hermaszewski, -Joel Moberg, -Johannes 'fish' Ziemke, -Jörg Thalheim, -Jude Taylor, -kballou, -Keshav Kini, -Kjetil Orbekk, -Langston Barrett, -Linus Heckemann, -Ludovic Courtès, -Manav Rathi, -Marc Scholten, -Markus Hauck, -Matt Audesse, -Matthew Bauer, -Matthias Beyer, -Matthieu Coudron, -N1X, -Nathan Zadoks, -Neil Mayhew, -Nicolas B. Pierron, -Niklas Hambüchen, -Nikolay Amiantov, -Ole Jørgen Brønner, -Orivej Desh, -Peter Simons, -Peter Stuart, -Pyry Jahkola, -regnat, -Renzo Carbonara, -Rhys, -Robert Vollmert, -Scott Olson, -Scott R. Parish, -Sergei Trofimovich, -Shea Levy, -Sheena Artrip, -Spencer Baugh, -Stefan Junker, -Susan Potter, -Thomas Tuegel, -Timothy Allen, -Tristan Hume, -Tuomas Tynkkynen, -tv, -Tyson Whitehead, -Vladimír Čunát, -Will Dietz, -wmertens, -Wout Mertens, -zimbatm and -Zoran Plesivčak. -</para> - -</section> diff --git a/doc/manual/release-notes/rl-2.1.xml b/doc/manual/release-notes/rl-2.1.xml deleted file mode 100644 index 16c243fc1..000000000 --- a/doc/manual/release-notes/rl-2.1.xml +++ /dev/null @@ -1,133 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-2.1"> - -<title>Release 2.1 (2018-09-02)</title> - -<para>This is primarily a bug fix release. It also reduces memory -consumption in certain situations. In addition, it has the following -new features:</para> - -<itemizedlist> - - <listitem> - <para>The Nix installer will no longer default to the Multi-User - installation for macOS. You can still <link - linkend="sect-multi-user-installation">instruct the installer to - run in multi-user mode</link>. - </para> - </listitem> - - <listitem> - <para>The Nix installer now supports performing a Multi-User - installation for Linux computers which are running systemd. You - can <link - linkend="sect-multi-user-installation">select a Multi-User installation</link> by passing the - <option>--daemon</option> flag to the installer: <command>sh <(curl - https://nixos.org/nix/install) --daemon</command>. - </para> - - <para>The multi-user installer cannot handle systems with SELinux. - If your system has SELinux enabled, you can <link - linkend="sect-single-user-installation">force the installer to run - in single-user mode</link>.</para> - </listitem> - - <listitem> - <para>New builtin functions: - <literal>builtins.bitAnd</literal>, - <literal>builtins.bitOr</literal>, - <literal>builtins.bitXor</literal>, - <literal>builtins.fromTOML</literal>, - <literal>builtins.concatMap</literal>, - <literal>builtins.mapAttrs</literal>. - </para> - </listitem> - - <listitem> - <para>The S3 binary cache store now supports uploading NARs larger - than 5 GiB.</para> - </listitem> - - <listitem> - <para>The S3 binary cache store now supports uploading to - S3-compatible services with the <literal>endpoint</literal> - option.</para> - </listitem> - - <listitem> - <para>The flag <option>--fallback</option> is no longer required - to recover from disappeared NARs in binary caches.</para> - </listitem> - - <listitem> - <para><command>nix-daemon</command> now respects - <option>--store</option>.</para> - </listitem> - - <listitem> - <para><command>nix run</command> now respects - <varname>nix-support/propagated-user-env-packages</varname>.</para> - </listitem> - -</itemizedlist> - -<para>This release has contributions from - -Adrien Devresse, -Aleksandr Pashkov, -Alexandre Esteves, -Amine Chikhaoui, -Andrew Dunham, -Asad Saeeduddin, -aszlig, -Ben Challenor, -Ben Gamari, -Benjamin Hipple, -Bogdan Seniuc, -Corey O'Connor, -Daiderd Jordan, -Daniel Peebles, -Daniel Poelzleithner, -Danylo Hlynskyi, -Dmitry Kalinkin, -Domen Kožar, -Doug Beardsley, -Eelco Dolstra, -Erik Arvstedt, -Félix Baylac-Jacqué, -Gleb Peregud, -Graham Christensen, -Guillaume Maudoux, -Ivan Kozik, -John Arnold, -Justin Humm, -Linus Heckemann, -Lorenzo Manacorda, -Matthew Justin Bauer, -Matthew O'Gorman, -Maximilian Bosch, -Michael Bishop, -Michael Fiano, -Michael Mercier, -Michael Raskin, -Michael Weiss, -Nicolas Dudebout, -Peter Simons, -Ryan Trinkle, -Samuel Dionne-Riel, -Sean Seefried, -Shea Levy, -Symphorien Gibol, -Tim Engler, -Tim Sears, -Tuomas Tynkkynen, -volth, -Will Dietz, -Yorick van Pelt and -zimbatm. -</para> - -</section> diff --git a/doc/manual/release-notes/rl-2.2.xml b/doc/manual/release-notes/rl-2.2.xml deleted file mode 100644 index d29eb87e8..000000000 --- a/doc/manual/release-notes/rl-2.2.xml +++ /dev/null @@ -1,143 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-relnotes-2.2"> - -<title>Release 2.2 (2019-01-11)</title> - -<para>This is primarily a bug fix release. It also has the following -changes:</para> - -<itemizedlist> - - <listitem> - <para>In derivations that use structured attributes (i.e. that - specify set the <varname>__structuredAttrs</varname> attribute to - <literal>true</literal> to cause all attributes to be passed to - the builder in JSON format), you can now specify closure checks - per output, e.g.: - -<programlisting> -outputChecks."out" = { - # The closure of 'out' must not be larger than 256 MiB. - maxClosureSize = 256 * 1024 * 1024; - - # It must not refer to C compiler or to the 'dev' output. - disallowedRequisites = [ stdenv.cc "dev" ]; -}; - -outputChecks."dev" = { - # The 'dev' output must not be larger than 128 KiB. - maxSize = 128 * 1024; -}; -</programlisting> - - </para> - </listitem> - - - <listitem> - <para>The derivation attribute - <varname>requiredSystemFeatures</varname> is now enforced for - local builds, and not just to route builds to remote builders. - The supported features of a machine can be specified through the - configuration setting <varname>system-features</varname>.</para> - - <para>By default, <varname>system-features</varname> includes - <literal>kvm</literal> if <filename>/dev/kvm</filename> - exists. For compatibility, it also includes the pseudo-features - <literal>nixos-test</literal>, <literal>benchmark</literal> and - <literal>big-parallel</literal> which are used by Nixpkgs to route - builds to particular Hydra build machines.</para> - - </listitem> - - <listitem> - <para>Sandbox builds are now enabled by default on Linux.</para> - </listitem> - - <listitem> - <para>The new command <command>nix doctor</command> shows - potential issues with your Nix installation.</para> - </listitem> - - <listitem> - <para>The <literal>fetchGit</literal> builtin function now uses a - caching scheme that puts different remote repositories in distinct - local repositories, rather than a single shared repository. This - may require more disk space but is faster.</para> - </listitem> - - <listitem> - <para>The <literal>dirOf</literal> builtin function now works on - relative paths.</para> - </listitem> - - <listitem> - <para>Nix now supports <link - xlink:href="https://www.w3.org/TR/SRI/">SRI hashes</link>, - allowing the hash algorithm and hash to be specified in a single - string. For example, you can write: - -<programlisting> -import <nix/fetchurl.nix> { - url = https://nixos.org/releases/nix/nix-2.1.3/nix-2.1.3.tar.xz; - hash = "sha256-XSLa0FjVyADWWhFfkZ2iKTjFDda6mMXjoYMXLRSYQKQ="; -}; -</programlisting> - - instead of - -<programlisting> -import <nix/fetchurl.nix> { - url = https://nixos.org/releases/nix/nix-2.1.3/nix-2.1.3.tar.xz; - sha256 = "5d22dad058d5c800d65a115f919da22938c50dd6ba98c5e3a183172d149840a4"; -}; -</programlisting> - - </para> - - <para>In fixed-output derivations, the - <varname>outputHashAlgo</varname> attribute is no longer mandatory - if <varname>outputHash</varname> specifies the hash.</para> - - <para><command>nix hash-file</command> and <command>nix - hash-path</command> now print hashes in SRI format by - default. They also use SHA-256 by default instead of SHA-512 - because that's what we use most of the time in Nixpkgs.</para> - </listitem> - - <listitem> - <para>Integers are now 64 bits on all platforms.</para> - </listitem> - - <listitem> - <para>The evaluator now prints profiling statistics (enabled via - the <envar>NIX_SHOW_STATS</envar> and - <envar>NIX_COUNT_CALLS</envar> environment variables) in JSON - format.</para> - </listitem> - - <listitem> - <para>The option <option>--xml</option> in <command>nix-store - --query</command> has been removed. Instead, there now is an - option <option>--graphml</option> to output the dependency graph - in GraphML format.</para> - </listitem> - - <listitem> - <para>All <filename>nix-*</filename> commands are now symlinks to - <filename>nix</filename>. This saves a bit of disk space.</para> - </listitem> - - <listitem> - <para><command>nix repl</command> now uses - <literal>libeditline</literal> or - <literal>libreadline</literal>.</para> - </listitem> - -</itemizedlist> - -</section> - diff --git a/doc/manual/release-notes/rl-2.3.xml b/doc/manual/release-notes/rl-2.3.xml deleted file mode 100644 index 0ad7d641f..000000000 --- a/doc/manual/release-notes/rl-2.3.xml +++ /dev/null @@ -1,91 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="ssec-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> diff --git a/doc/manual/schemas.xml b/doc/manual/schemas.xml deleted file mode 100644 index 691a517b9..000000000 --- a/doc/manual/schemas.xml +++ /dev/null @@ -1,4 +0,0 @@ -<?xml version="1.0"?> -<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0"> - <uri pattern="*.xml" typeId="DocBook"/> -</locatingRules> diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md new file mode 100644 index 000000000..5f6817674 --- /dev/null +++ b/doc/manual/src/SUMMARY.md @@ -0,0 +1,102 @@ +# Table of Contents + +- [Introduction](introduction.md) +- [Quick Start](quick-start.md) +- [Installation](installation/installation.md) + - [Supported Platforms](installation/supported-platforms.md) + - [Installing a Binary Distribution](installation/installing-binary.md) + - [Installing Nix from Source](installation/installing-source.md) + - [Prerequisites](installation/prerequisites-source.md) + - [Obtaining a Source Distribution](installation/obtaining-source.md) + - [Building Nix from Source](installation/building-source.md) + - [Security](installation/nix-security.md) + - [Single-User Mode](installation/single-user.md) + - [Multi-User Mode](installation/multi-user.md) + - [Environment Variables](installation/env-variables.md) + - [Upgrading Nix](installation/upgrading.md) +- [Package Management](package-management/package-management.md) + - [Basic Package Management](package-management/basic-package-mgmt.md) + - [Profiles](package-management/profiles.md) + - [Garbage Collection](package-management/garbage-collection.md) + - [Garbage Collector Roots](package-management/garbage-collector-roots.md) + - [Channels](package-management/channels.md) + - [Sharing Packages Between Machines](package-management/sharing-packages.md) + - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md) + - [Copying Closures via SSH](package-management/copy-closure.md) + - [Serving a Nix store via SSH](package-management/ssh-substituter.md) + - [Serving a Nix store via S3](package-management/s3-substituter.md) +- [Writing Nix Expressions](expressions/writing-nix-expressions.md) + - [A Simple Nix Expression](expressions/simple-expression.md) + - [Expression Syntax](expressions/expression-syntax.md) + - [Build Script](expressions/build-script.md) + - [Arguments and Variables](expressions/arguments-variables.md) + - [Building and Testing](expressions/simple-building-testing.md) + - [Generic Builder Syntax](expressions/generic-builder.md) + - [Writing Nix Expressions](expressions/expression-language.md) + - [Values](expressions/language-values.md) + - [Language Constructs](expressions/language-constructs.md) + - [Operators](expressions/language-operators.md) + - [Derivations](expressions/derivations.md) + - [Advanced Attributes](expressions/advanced-attributes.md) + - [Built-in Functions](expressions/builtins.md) +- [Advanced Topics](advanced-topics/advanced-topics.md) + - [Remote Builds](advanced-topics/distributed-builds.md) + - [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md) + - [Verifying Build Reproducibility](advanced-topics/diff-hook.md) + - [Using the `post-build-hook`](advanced-topics/post-build-hook.md) +- [Command Reference](command-ref/command-ref.md) + - [Common Options](command-ref/opt-common.md) + - [Common Environment Variables](command-ref/env-common.md) + - [Main Commands](command-ref/main-commands.md) + - [nix-env](command-ref/nix-env.md) + - [nix-build](command-ref/nix-build.md) + - [nix-shell](command-ref/nix-shell.md) + - [nix-store](command-ref/nix-store.md) + - [Utilities](command-ref/utilities.md) + - [nix-channel](command-ref/nix-channel.md) + - [nix-collect-garbage](command-ref/nix-collect-garbage.md) + - [nix-copy-closure](command-ref/nix-copy-closure.md) + - [nix-daemon](command-ref/nix-daemon.md) + - [nix-hash](command-ref/nix-hash.md) + - [nix-instantiate](command-ref/nix-instantiate.md) + - [nix-prefetch-url](command-ref/nix-prefetch-url.md) + - [Files](command-ref/files.md) + - [nix.conf](command-ref/conf-file.md) +- [Glossary](glossary.md) +- [Hacking](hacking.md) +- [Release Notes](release-notes/release-notes.md) + - [Release 2.3 (2019-09-04)](release-notes/rl-2.3.md) + - [Release 2.2 (2019-01-11)](release-notes/rl-2.2.md) + - [Release 2.1 (2018-09-02)](release-notes/rl-2.1.md) + - [Release 2.0 (2018-02-22)](release-notes/rl-2.0.md) + - [Release 1.11.10 (2017-06-12)](release-notes/rl-1.11.10.md) + - [Release 1.11 (2016-01-19)](release-notes/rl-1.11.md) + - [Release 1.10 (2015-09-03)](release-notes/rl-1.10.md) + - [Release 1.9 (2015-06-12)](release-notes/rl-1.9.md) + - [Release 1.8 (2014-12-14)](release-notes/rl-1.8.md) + - [Release 1.7 (2014-04-11)](release-notes/rl-1.7.md) + - [Release 1.6.1 (2013-10-28)](release-notes/rl-1.6.1.md) + - [Release 1.6 (2013-09-10)](release-notes/rl-1.6.md) + - [Release 1.5.2 (2013-05-13)](release-notes/rl-1.5.2.md) + - [Release 1.5 (2013-02-27)](release-notes/rl-1.5.md) + - [Release 1.4 (2013-02-26)](release-notes/rl-1.4.md) + - [Release 1.3 (2013-01-04)](release-notes/rl-1.3.md) + - [Release 1.2 (2012-12-06)](release-notes/rl-1.2.md) + - [Release 1.1 (2012-07-18)](release-notes/rl-1.1.md) + - [Release 1.0 (2012-05-11)](release-notes/rl-1.0.md) + - [Release 0.16 (2010-08-17)](release-notes/rl-0.16.md) + - [Release 0.15 (2010-03-17)](release-notes/rl-0.15.md) + - [Release 0.14 (2010-02-04)](release-notes/rl-0.14.md) + - [Release 0.13 (2009-11-05)](release-notes/rl-0.13.md) + - [Release 0.12 (2008-11-20)](release-notes/rl-0.12.md) + - [Release 0.11 (2007-12-31)](release-notes/rl-0.11.md) + - [Release 0.10.1 (2006-10-11)](release-notes/rl-0.10.1.md) + - [Release 0.10 (2006-10-06)](release-notes/rl-0.10.md) + - [Release 0.9.2 (2005-09-21)](release-notes/rl-0.9.2.md) + - [Release 0.9.1 (2005-09-20)](release-notes/rl-0.9.1.md) + - [Release 0.9 (2005-09-16)](release-notes/rl-0.9.md) + - [Release 0.8.1 (2005-04-13)](release-notes/rl-0.8.1.md) + - [Release 0.8 (2005-04-11)](release-notes/rl-0.8.md) + - [Release 0.7 (2005-01-12)](release-notes/rl-0.7.md) + - [Release 0.6 (2004-11-14)](release-notes/rl-0.6.md) + - [Release 0.5 and earlier](release-notes/rl-0.5.md) diff --git a/doc/manual/src/advanced-topics/advanced-topics.md b/doc/manual/src/advanced-topics/advanced-topics.md new file mode 100644 index 000000000..8b1378917 --- /dev/null +++ b/doc/manual/src/advanced-topics/advanced-topics.md @@ -0,0 +1 @@ + diff --git a/doc/manual/src/advanced-topics/cores-vs-jobs.md b/doc/manual/src/advanced-topics/cores-vs-jobs.md new file mode 100644 index 000000000..4a9058ca1 --- /dev/null +++ b/doc/manual/src/advanced-topics/cores-vs-jobs.md @@ -0,0 +1,39 @@ +# Tuning Cores and Jobs + +Nix has two relevant settings with regards to how your CPU cores will +be utilized: `cores` and `max-jobs`. This chapter will talk about what +they are, how they interact, and their configuration trade-offs. + + - `max-jobs` + 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. + + - `cores` + Suggests how many cores each derivation should use. Similar to + `make -j`. + +The `cores` setting determines the value of +`NIX_BUILD_CORES`. `NIX_BUILD_CORES` is equal to `cores`, unless +`cores` equals `0`, in which case `NIX_BUILD_CORES` will be the total +number of cores in the system. + +The maximum number of consumed cores is a simple multiplication, +`max-jobs` \* `NIX_BUILD_CORES`. + +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: + +| `max-jobs` | `cores` | `NIX_BUILD_CORES` | Maximum Processes | Result | +| --------------------- | ------------------ | ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | 24 | 24 | 24 | One derivation will be built at a time, each one can use 24 cores. Undersold if a job can’t use 24 cores. | +| 4 | 6 | 6 | 24 | Four derivations will be built at once, each given access to six cores. | +| 12 | 6 | 6 | 72 | 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. | +| 24 | 1 | 1 | 24 | 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. | +| 24 | 0 | 24 | 576 | 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. | + +It is up to the derivations' build script to respect host's requested +cores-per-build by following the value of the `NIX_BUILD_CORES` +environment variable. diff --git a/doc/manual/src/advanced-topics/diff-hook.md b/doc/manual/src/advanced-topics/diff-hook.md new file mode 100644 index 000000000..e2234147f --- /dev/null +++ b/doc/manual/src/advanced-topics/diff-hook.md @@ -0,0 +1,139 @@ +# Verifying Build Reproducibility + +You can use Nix's `diff-hook` setting to compare build results. Note +that this hook is only executed if the results differ; it is not used +for determining if the results are the same. + +For purposes of demonstration, we'll use the following Nix file, +`deterministic.nix` for testing: + + let + inherit (import <nixpkgs> {}) runCommand; + in { + stable = runCommand "stable" {} '' + touch $out + ''; + + unstable = runCommand "unstable" {} '' + echo $RANDOM > $out + ''; + } + +Additionally, `nix.conf` contains: + + diff-hook = /etc/nix/my-diff-hook + run-diff-hook = true + +where `/etc/nix/my-diff-hook` is an executable file containing: + + #!/bin/sh + exec >&2 + echo "For derivation $3:" + /run/current-system/sw/bin/diff -r "$1" "$2" + +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. + +# Spot-Checking Build Determinism + +Verify a path which already exists in the Nix store by passing `--check` +to the build command. + +If the build passes and is deterministic, Nix will exit with a status +code of 0: + + $ nix-build ./deterministic.nix -A stable + this derivation 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 + +If the build is not deterministic, Nix will exit with a status code of +1: + + $ nix-build ./deterministic.nix -A unstable + this derivation 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 + +In the Nix daemon's log, we will now see: + + For derivation /nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv: + 1c1 + < 8108 + --- + > 30204 + +Using `--check` with `--keep-failed` will cause Nix to keep the second +build's output in a special, `.check` path: + + $ 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' + +In particular, notice the +`/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check` output. Nix +has copied the build results to that directory where you can examine it. + +> **Note** +> +> Check paths are not protected against garbage collection, and this +> path will be deleted on the next garbage collection. +> +> The path is guaranteed to be alive for the duration of +> the `diff-hook`'s execution, but may be deleted any time after. +> +> 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. + +`--check` 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: + + error: some outputs of '/nix/store/hzi1h60z2qf0nb85iwnpvrai3j2w7rr6-unstable.drv' are not valid, so checking is not possible + +Run the build without `--check`, and then try with `--check` again. + +# Automatic and Optionally Enforced Determinism Verification + +Automatically verify every build at build time by executing the build +multiple times. + +Setting `repeat` and `enforce-determinism` in your `nix.conf` permits +the automated verification of every build Nix performs. + +The following configuration will run each build three times, and will +require the build to be deterministic: + + enforce-determinism = true + repeat = 2 + +Setting `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: + + enforce-determinism = false + repeat = 1 + +An example output of this configuration: + + $ nix-build ./test.nix -A unstable + this derivation 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 diff --git a/doc/manual/src/advanced-topics/distributed-builds.md b/doc/manual/src/advanced-topics/distributed-builds.md new file mode 100644 index 000000000..76a5380bf --- /dev/null +++ b/doc/manual/src/advanced-topics/distributed-builds.md @@ -0,0 +1,140 @@ +# Remote Builds + +Nix supports remote builds, where a local Nix installation can forward +Nix builds to other machines. This allows multiple builds to be +performed in parallel and allows Nix to perform multi-platform builds in +a semi-transparent way. For instance, if you perform a build for a +`x86_64-darwin` on an `i686-linux` machine, Nix can automatically +forward the build to a `x86_64-darwin` machine, if available. + +To forward a build to a remote machine, it’s required that the remote +machine is accessible via SSH and that it has Nix installed. You can +test whether connecting to the remote Nix instance works, e.g. + + $ nix ping-store --store ssh://mac + +will try to connect to the machine named `mac`. It is possible to +specify an SSH identity file as part of the remote store URI, e.g. + + $ nix ping-store --store ssh://mac?ssh-key=/home/alice/my-key + +Since builds should be non-interactive, the key should not have a +passphrase. Alternatively, you can load identities ahead of time into +`ssh-agent` or `gpg-agent`. + +If you get the error + + bash: nix-store: command not found + error: cannot connect to 'mac' + +then you need to ensure that the `PATH` of non-interactive login shells +contains Nix. + +> **Warning** +> +> If you are building via the Nix daemon, it is the Nix daemon user +> account (that is, `root`) that should have SSH access to the remote +> machine. If you can’t or don’t want to configure `root` to be able to +> access to remote machine, you can use a private Nix store instead by +> passing e.g. `--store ~/my-nix`. + +The list of remote machines can be specified on the command line or in +the Nix configuration file. The former is convenient for testing. For +example, the following command allows you to build a derivation for +`x86_64-darwin` on a Linux machine: + + $ uname + Linux + + $ nix build \ + '(with import <nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \ + --builders 'ssh://mac x86_64-darwin' + [1/0/1 built, 0.0 MiB DL] building foo on ssh://mac + + $ cat ./result + Darwin + +It is possible to specify multiple builders separated by a semicolon or +a newline, e.g. + +``` + --builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd' +``` + +Each machine specification consists of the following elements, separated +by spaces. Only the first element is required. To leave a field at its +default, set it to `-`. + +1. The URI of the remote store in the format + `ssh://[username@]hostname`, e.g. `ssh://nix@mac` or `ssh://mac`. + For backward compatibility, `ssh://` may be omitted. The hostname + may be an alias defined in your `~/.ssh/config`. + +2. A comma-separated list of Nix platform type identifiers, such as + `x86_64-darwin`. It is possible for a machine to support multiple + platform types, e.g., `i686-linux,x86_64-linux`. If omitted, this + defaults to the local platform type. + +3. The SSH identity file to be used to log in to the remote machine. If + omitted, SSH will use its regular identities. + +4. The maximum number of builds that Nix will execute in parallel on + the machine. Typically this should be equal to the number of CPU + cores. For instance, the machine `itchy` in the example will execute + up to 8 builds in parallel. + +5. The “speed factor”, indicating the relative speed of the machine. If + there are multiple machines of the right type, Nix will prefer the + fastest, taking load into account. + +6. A comma-separated list of *supported features*. If a derivation has + the `requiredSystemFeatures` attribute, then Nix will only perform + the derivation on a machine that has the specified features. For + instance, the attribute + + requiredSystemFeatures = [ "kvm" ]; + + will cause the build to be performed on a machine that has the `kvm` + feature. + +7. A comma-separated list of *mandatory features*. A machine will only + be used to build a derivation if all of the machine’s mandatory + features appear in the derivation’s `requiredSystemFeatures` + attribute.. + +For example, the machine specification + + nix@scratchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 1 kvm + nix@itchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 2 + nix@poochie.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 1 2 kvm benchmark + +specifies several machines that can perform `i686-linux` builds. +However, `poochie` will only do builds that have the attribute + + requiredSystemFeatures = [ "benchmark" ]; + +or + + requiredSystemFeatures = [ "benchmark" "kvm" ]; + +`itchy` cannot do builds that require `kvm`, but `scratchy` does support +such builds. For regular builds, `itchy` will be preferred over +`scratchy` because it has a higher speed factor. + +Remote builders can also be configured in `nix.conf`, e.g. + + builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd + +Finally, remote builders can be configured in a separate configuration +file included in `builders` via the syntax `@file`. For example, + + builders = @/etc/nix/machines + +causes the list of machines in `/etc/nix/machines` to be included. (This +is the default.) + +If you want the builders to use caches, you likely want to set the +option `builders-use-substitutes` in your local `nix.conf`. + +To build only on remote builders and disable building on the local +machine, you can use the option `--max-jobs 0`. diff --git a/doc/manual/src/advanced-topics/post-build-hook.md b/doc/manual/src/advanced-topics/post-build-hook.md new file mode 100644 index 000000000..7b3ae58fb --- /dev/null +++ b/doc/manual/src/advanced-topics/post-build-hook.md @@ -0,0 +1,111 @@ +# Using the `post-build-hook` + +# Implementation Caveats + +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. + +The post build hook program runs after each executed build, and blocks +the build loop. The build loop exits if the hook program fails. + +Concretely, this implementation will make Nix slow or unusable when the +internet is slow or unreliable. + +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. + +# Prerequisites + +This tutorial assumes you have [configured an S3-compatible binary +cache](../package-management/s3-substituter.md), and that the `root` +user's default AWS profile can upload to the bucket. + +# Set up a Signing Key + +Use `nix-store --generate-binary-cache-key` 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. + + # 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= + +Then, add the public key and the cache URL to your `nix.conf`'s +`trusted-public-keys` and `substituters` options: + + substituters = https://cache.nixos.org/ s3://example-nix-cache + trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM= + +We will restart the Nix daemon in a later step. + +# Implementing the build hook + +Write the following script to `/etc/nix/upload-to-cache.sh`: + + #!/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 + +> **Note** +> +> The `$OUT_PATHS` 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 `nix +> sign-paths`. Nix guarantees the paths will not contain any spaces, +> however a store path might contain glob characters. The `set -f` +> disables globbing in the shell. + +Then make sure the hook program is executable by the `root` user: + + # chmod +x /etc/nix/upload-to-cache.sh + +# Updating Nix Configuration + +Edit `/etc/nix/nix.conf` to run our hook, by adding the following +configuration snippet at the end: + + post-build-hook = /etc/nix/upload-to-cache.sh + +Then, restart the `nix-daemon`. + +# Testing + +Build any derivation, for example: + + $ nix-build -E '(import <nixpkgs> {}).writeText "example" (builtins.toString builtins.currentTime)' + this derivation 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 + +Then delete the path from the store, and try substituting it from the +binary cache: + + $ rm ./result + $ nix-store --delete /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example + +Now, copy the path back from the cache: + + $ nix-store --realise /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 + +# Conclusion + +We now have a Nix installation configured to automatically sign and +upload every local build to a remote binary cache. + +Before deploying this to production, be sure to consider the +[implementation caveats](#implementation-caveats). diff --git a/doc/manual/src/command-ref/command-ref.md b/doc/manual/src/command-ref/command-ref.md new file mode 100644 index 000000000..6a78075db --- /dev/null +++ b/doc/manual/src/command-ref/command-ref.md @@ -0,0 +1,2 @@ +This section lists commands and options that you can use when you work +with Nix. diff --git a/doc/manual/src/command-ref/conf-file.md b/doc/manual/src/command-ref/conf-file.md new file mode 100644 index 000000000..306ad23f5 --- /dev/null +++ b/doc/manual/src/command-ref/conf-file.md @@ -0,0 +1,692 @@ +Title: nix.conf + +# Name + +`nix.conf` - Nix configuration file + +# Description + +By default Nix reads settings from the following places: + + - The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e. + `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if + `NIX_CONF_DIR` is set. Values loaded in this file are not forwarded + to the Nix daemon. The client assumes that the daemon has already + loaded them. + + - If `NIX_USER_CONF_FILES` is set, then each path separated by `:` + will be loaded in reverse order. + + Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` + and `XDG_CONFIG_HOME`. If these are unset, it will look in + `$HOME/.config/nix.conf`. + +The configuration files consist of `name = +value` pairs, one per line. Other files can be included with a line like +`include +path`, where *path* is interpreted relative to the current conf file and +a missing file is an error unless `!include` is used instead. Comments +start with a `#` character. Here is an example configuration file: + + keep-outputs = true # Nice for developers + keep-derivations = true # Idem + +You can override settings on the command line using the `--option` flag, +e.g. `--option keep-outputs +false`. + +The following settings are currently available: + + - `allowed-uris` + A list of URI prefixes to which access is allowed in restricted + evaluation mode. For example, when set to + `https://github.com/NixOS`, builtin functions such as `fetchGit` are + allowed to access `https://github.com/NixOS/patchelf.git`. + + - `allow-import-from-derivation` + By default, Nix allows you to `import` from a derivation, allowing + building at evaluation time. With this option set to false, Nix will + throw an error when evaluating an expression that uses this feature, + allowing users to ensure their evaluation will not require any + builds to take place. + + - `allow-new-privileges` + (Linux-specific.) By default, builders on Linux cannot acquire new + privileges by calling setuid/setgid programs or programs that have + file capabilities. For example, programs such as `sudo` or `ping` + will fail. (Note that in sandbox builds, no such programs are + available unless you bind-mount them into the sandbox via the + `sandbox-paths` option.) You can allow the use of such programs by + enabling this option. This is impure and usually undesirable, but + may be useful in certain scenarios (e.g. to spin up containers or + set up userspace network interfaces in tests). + + - `allowed-users` + A list of names of users (separated by whitespace) that are allowed + to connect to the Nix daemon. As with the `trusted-users` option, + you can specify groups by prefixing them with `@`. Also, you can + allow all users by specifying `*`. The default is `*`. + + Note that trusted users are always allowed to connect. + + - `auto-optimise-store` + If set to `true`, Nix automatically detects files in the store that + have identical contents, and replaces them with hard links to a + single copy. This saves disk space. If set to `false` (the default), + you can still run `nix-store + --optimise` to get rid of duplicate files. + + - `builders` + A list of machines on which to perform builds. + + - `builders-use-substitutes` + If set to `true`, Nix will instruct remote build machines to use + their own binary substitutes if available. In practical terms, this + means that remote hosts will fetch as many build dependencies as + possible from their own substitutes (e.g, from `cache.nixos.org`), + instead of waiting for this host to upload them all. This can + drastically reduce build times if the network connection between + this computer and the remote build host is slow. Defaults to + `false`. + + - `build-users-group` + This options specifies the Unix group containing the Nix build user + accounts. In multi-user Nix installations, builds should not be + performed by the Nix account since that would allow users to + arbitrarily modify the Nix store and database by supplying specially + crafted builders; and they cannot be performed by the calling user + since that would allow him/her to influence the build result. + + Therefore, if this option is non-empty and specifies a valid group, + builds will be performed under the user accounts that are a member + of the group specified here (as listed in `/etc/group`). Those user + accounts should not be used for any other purpose\! + + Nix will never run two builds under the same user account at the + same time. This is to prevent an obvious security hole: a malicious + user writing a Nix expression that modifies the build result of a + legitimate Nix expression being built by another user. Therefore it + is good to have as many Nix build user accounts as you can spare. + (Remember: uids are cheap.) + + The build users should have permission to create files in the Nix + store, but not delete them. Therefore, `/nix/store` should be owned + by the Nix account, its group should be the group specified here, + and its mode should be `1775`. + + If the build users group is empty, builds will be performed under + the uid of the Nix process (that is, the uid of the caller if + `NIX_REMOTE` is empty, the uid under which the Nix daemon runs if + `NIX_REMOTE` is `daemon`). Obviously, this should not be used in + multi-user settings with untrusted users. + + - `compress-build-log` + If set to `true` (the default), build logs written to + `/nix/var/log/nix/drvs` will be compressed on the fly using bzip2. + Otherwise, they will not be compressed. + + - `connect-timeout` + The timeout (in seconds) for establishing connections in the binary + cache substituter. It corresponds to `curl`’s `--connect-timeout` + option. + + - `cores` + Sets the value of the `NIX_BUILD_CORES` environment variable in the + invocation of builders. Builders can use this variable at their + discretion to control the maximum amount of parallelism. For + instance, in Nixpkgs, if the derivation attribute + `enableParallelBuilding` is set to `true`, the builder passes the + `-jN` flag to GNU Make. It can be overridden using the `--cores` + command line switch and defaults to `1`. The value `0` means that + the builder should use all available CPU cores in the system. + + - `diff-hook` + Absolute path to an executable capable of diffing build + results. The hook is executed if `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. + + 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. + + The diff hook program receives three parameters: + + 1. A path to the previous build's results + + 2. A path to the current build's results + + 3. The path to the build's derivation + + 4. The path to the build's scratch directory. This directory will + exist only if the build was run with `--keep-failed`. + + 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. + + When using the Nix daemon, `diff-hook` must be set in the `nix.conf` + configuration file, and cannot be passed at the command line. + + - `enforce-determinism` + See `repeat`. + + - `extra-sandbox-paths` + A list of additional paths appended to `sandbox-paths`. Useful if + you want to extend its default value. + + - `extra-platforms` + Platforms other than the native one which this machine is capable of + building for. This can be useful for supporting additional + architectures on compatible machines: i686-linux can be built on + x86\_64-linux machines (and the default for this setting reflects + this); armv7 is backwards-compatible with armv6 and armv5tel; some + aarch64 machines can also natively run 32-bit ARM code; and + qemu-user may be used to support non-native platforms (though this + may be slow and buggy). Most values for this are not enabled by + default because build systems will often misdetect the target + platform and generate incompatible code, so you may wish to + cross-check the results of using this option against proper + natively-built versions of your derivations. + + - `extra-substituters` + Additional binary caches appended to those specified in + `substituters`. When used by unprivileged users, untrusted + substituters (i.e. those not listed in `trusted-substituters`) are + silently ignored. + + - `fallback` + If set to `true`, Nix will fall back to building from source if a + binary substitute fails. This is equivalent to the `--fallback` + flag. The default is `false`. + + - `fsync-metadata` + If set to `true`, changes to the Nix store metadata (in + `/nix/var/nix/db`) are synchronously flushed to disk. This improves + robustness in case of system crashes, but reduces performance. The + default is `true`. + + - `hashed-mirrors` + A list of web servers used by `builtins.fetchurl` to obtain files by + hash. The default is `http://tarballs.nixos.org/`. Given a hash type + *ht* and a base-16 hash *h*, Nix will try to download the file from + `hashed-mirror/ht/h`. This allows files to be downloaded even if + they have disappeared from their original URI. For example, given + the default mirror `http://tarballs.nixos.org/`, when building the + derivation + + builtins.fetchurl { + url = "https://example.org/foo-1.2.3.tar.xz"; + sha256 = "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"; + } + + Nix will attempt to download this file from + `http://tarballs.nixos.org/sha256/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae` + first. If it is not available there, if will try the original URI. + + - `http-connections` + The maximum number of parallel TCP connections used to fetch files + from binary caches and by other downloads. It defaults to 25. 0 + means no limit. + + - `keep-build-log` + If set to `true` (the default), Nix will write the build log of a + derivation (i.e. the standard output and error of its builder) to + the directory `/nix/var/log/nix/drvs`. The build log can be + retrieved using the command `nix-store -l + path`. + + - `keep-derivations` + If `true` (default), the garbage collector will keep the derivations + from which non-garbage store paths were built. If `false`, they will + be deleted unless explicitly registered as a root (or reachable from + other roots). + + Keeping derivation around is useful for querying and traceability + (e.g., it allows you to ask with what dependencies or options a + store path was built), so by default this option is on. Turn it off + to save a bit of disk space (or a lot if `keep-outputs` is also + turned on). + + - `keep-env-derivations` + If `false` (default), derivations are not stored in Nix user + environments. That is, the derivations of any build-time-only + dependencies may be garbage-collected. + + If `true`, when you add a Nix derivation to a user environment, the + path of the derivation is stored in the user environment. Thus, the + derivation will not be garbage-collected until the user environment + generation is deleted (`nix-env --delete-generations`). To prevent + build-time-only dependencies from being collected, you should also + turn on `keep-outputs`. + + The difference between this option and `keep-derivations` is that + this one is “sticky”: it applies to any user environment created + while this option was enabled, while `keep-derivations` only applies + at the moment the garbage collector is run. + + - `keep-outputs` + If `true`, the garbage collector will keep the outputs of + non-garbage derivations. If `false` (default), outputs will be + deleted unless they are GC roots themselves (or reachable from other + roots). + + In general, outputs must be registered as roots separately. However, + even if the output of a derivation is registered as a root, the + collector will still delete store paths that are used only at build + time (e.g., the C compiler, or source tarballs downloaded from the + network). To prevent it from doing so, set this option to `true`. + + - `max-build-log-size` + This option defines the maximum number of bytes that a builder can + write to its stdout/stderr. If the builder exceeds this limit, it’s + killed. A value of `0` (the default) means that there is no limit. + + - `max-free` + When a garbage collection is triggered by the `min-free` option, it + stops as soon as `max-free` bytes are available. The default is + infinity (i.e. delete all garbage). + + - `max-jobs` + This option defines the maximum number of jobs that Nix will try to + build in parallel. The default is `1`. The special value `auto` + causes Nix to use the number of CPUs in your system. `0` is useful + when using remote builders to prevent any local builds (except for + `preferLocalBuild` derivation attribute which executes locally + regardless). It can be overridden using the `--max-jobs` (`-j`) + command line switch. + + - `max-silent-time` + This option defines the maximum number of seconds that a builder can + go without producing any data on standard output or standard error. + This is useful (for instance in an automated build system) to catch + builds that are stuck in an infinite loop, or to catch remote builds + that are hanging due to network problems. It can be overridden using + the `--max-silent-time` command line switch. + + The value `0` means that there is no timeout. This is also the + default. + + - `min-free` + When free disk space in `/nix/store` drops below `min-free` during a + build, Nix performs a garbage-collection until `max-free` bytes are + available or there is no more garbage. A value of `0` (the default) + disables this feature. + + - `narinfo-cache-negative-ttl` + The TTL in seconds for negative lookups. If a store path is queried + from a substituter but was not found, there will be a negative + lookup cached in the local disk cache database for the specified + duration. + + - `narinfo-cache-positive-ttl` + The TTL in seconds for positive lookups. If a store path is queried + from a substituter, the result of the query will be cached in the + local disk cache database including some of the NAR metadata. The + default TTL is a month, setting a shorter TTL for positive lookups + can be useful for binary caches that have frequent garbage + collection, in which case having a more frequent cache invalidation + would prevent trying to pull the path again and failing with a hash + mismatch if the build isn't reproducible. + + - `netrc-file` + If set to an absolute path to a `netrc` file, Nix will use the HTTP + authentication credentials in this file when trying to download from + a remote host through HTTP or HTTPS. Defaults to + `$NIX_CONF_DIR/netrc`. + + The `netrc` file consists of a list of accounts in the following + format: + + machine my-machine + login my-username + password my-password + + For the exact syntax, see [the `curl` + documentation](https://ec.haxx.se/usingcurl-netrc.html). + + > **Note** + > + > This must be an absolute path, and `~` is not resolved. For + > example, `~/.netrc` won't resolve to your home directory's + > `.netrc`. + + - `plugin-files` + A list of plugin files to be loaded by Nix. Each of these files will + be dlopened by Nix, allowing them to affect execution through static + initialization. In particular, these plugins may construct static + instances of RegisterPrimOp to add new primops or constants to the + expression language, RegisterStoreImplementation to add new store + implementations, RegisterCommand to add new subcommands to the `nix` + command, and RegisterSetting to add new nix config settings. See the + constructors for those types for more details. + + Since these files are loaded into the same address space as Nix + itself, they must be DSOs compatible with the instance of Nix + running at the time (i.e. compiled against the same headers, not + linked to any incompatible libraries). They should not be linked to + any Nix libs directly, as those will be available already at load + time. + + If an entry in the list is a directory, all files in the directory + are loaded as plugins (non-recursively). + + - `pre-build-hook` + If set, the path to a program that can set extra derivation-specific + settings for this system. This is used for settings that can't be + captured by the derivation model itself and are too variable between + different versions of the same system to be hard-coded into nix. + + The hook is passed the derivation path and, if sandboxes are + enabled, the sandbox directory. It can then modify the sandbox and + send a series of commands to modify various settings to stdout. The + currently recognized commands are: + + - `extra-sandbox-paths` + Pass a list of files and directories to be included in the + sandbox for this build. One entry per line, terminated by an + empty line. Entries have the same format as `sandbox-paths`. + + - `post-build-hook` + Optional. The path to a program to execute after each build. + + This option is only settable in the global `nix.conf`, or on the + command line by trusted users. + + When using the nix-daemon, the daemon executes the hook as `root`. + If the nix-daemon is not involved, the hook runs as the user + executing the nix-build. + + - The hook executes after an evaluation-time build. + + - The hook does not execute on substituted paths. + + - The hook's output always goes to the user's terminal. + + - If the hook fails, the build succeeds but no further builds + execute. + + - The hook executes synchronously, and blocks other builds from + progressing while it runs. + + The program executes with no arguments. The program's environment + contains the following environment variables: + + - `DRV_PATH` + The derivation for the built paths. + + Example: + `/nix/store/5nihn1a7pa8b25l9zafqaqibznlvvp3f-bash-4.4-p23.drv` + + - `OUT_PATHS` + Output paths of the built derivation, separated by a space + character. + + Example: + `/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`. + + - `repeat` + 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 and + `enforce-determinism` is true, the build is rejected and the + resulting store paths are not registered as “valid” in Nix’s + database. + + - `require-sigs` + If set to `true` (the default), any non-content-addressed path added + or copied to the Nix store (e.g. when substituting from a binary + cache) must have a valid signature, that is, be signed using one of + the keys listed in `trusted-public-keys` or `secret-key-files`. Set + to `false` to disable signature checking. + + - `restrict-eval` + If set to `true`, the Nix evaluator will not allow access to any + files outside of the Nix search path (as set via the `NIX_PATH` + environment variable or the `-I` option), or to URIs outside of + `allowed-uri`. The default is `false`. + + - `run-diff-hook` + If true, enable the execution of the `diff-hook` program. + + When using the Nix daemon, `run-diff-hook` must be set in the + `nix.conf` configuration file, and cannot be passed at the command + line. + + - `sandbox` + If set to `true`, builds will be performed in a *sandboxed + environment*, i.e., they’re isolated from the normal file system + hierarchy and will only see their dependencies in the Nix store, + the temporary build directory, private versions of `/proc`, + `/dev`, `/dev/shm` and `/dev/pts` (on Linux), and the paths + configured with the `sandbox-paths` option. This is useful to + prevent undeclared dependencies on files in directories such as + `/usr/bin`. In addition, on Linux, builds run in private PID, + mount, network, IPC and UTS namespaces to isolate them from other + processes in the system (except that fixed-output derivations do + not run in private network namespace to ensure they can access the + network). + + Currently, sandboxing only work on Linux and macOS. The use of a + sandbox requires that Nix is run as root (so you should use the + “build users” feature to perform the actual builds under different + users than root). + + If this option is set to `relaxed`, then fixed-output derivations + and derivations that have the `__noChroot` attribute set to `true` + do not run in sandboxes. + + The default is `true` on Linux and `false` on all other platforms. + + - `sandbox-dev-shm-size` + This option determines the maximum size of the `tmpfs` filesystem + mounted on `/dev/shm` in Linux sandboxes. For the format, see the + description of the `size` option of `tmpfs` in mount8. The default + is `50%`. + + - `sandbox-paths` + A list of paths bind-mounted into Nix sandbox environments. You can + use the syntax `target=source` to mount a path in a different + location in the sandbox; for instance, `/bin=/nix-bin` will mount + the path `/nix-bin` as `/bin` inside the sandbox. If *source* is + followed by `?`, then it is not an error if *source* does not exist; + for example, `/dev/nvidiactl?` specifies that `/dev/nvidiactl` will + only be mounted in the sandbox if it exists in the host filesystem. + + Depending on how Nix was built, the default value for this option + may be empty or provide `/bin/sh` as a bind-mount of `bash`. + + - `secret-key-files` + A whitespace-separated list of files containing secret (private) + keys. These are used to sign locally-built paths. They can be + generated using `nix-store + --generate-binary-cache-key`. The corresponding public key can be + distributed to other users, who can add it to `trusted-public-keys` + in their `nix.conf`. + + - `show-trace` + Causes Nix to print out a stack trace in case of Nix expression + evaluation errors. + + - `substitute` + If set to `true` (default), Nix will use binary substitutes if + available. This option can be disabled to force building from + source. + + - `stalled-download-timeout` + The timeout (in seconds) for receiving data from servers during + download. Nix cancels idle downloads after this timeout's duration. + + - `substituters` + A list of URLs of substituters, separated by whitespace. The default + is `https://cache.nixos.org`. + + - `system` + This option specifies the canonical Nix system name of the current + installation, such as `i686-linux` or `x86_64-darwin`. Nix can only + build derivations whose `system` attribute equals the value + specified here. In general, it never makes sense to modify this + value from its default, since you can use it to ‘lie’ about the + platform you are building on (e.g., perform a Mac OS build on a + Linux machine; the result would obviously be wrong). It only makes + sense if the Nix binaries can run on multiple platforms, e.g., + ‘universal binaries’ that run on `x86_64-linux` and `i686-linux`. + + It defaults to the canonical Nix system name detected by `configure` + at build time. + + - `system-features` + A set of system “features” supported by this machine, e.g. `kvm`. + Derivations can express a dependency on such features through the + derivation attribute `requiredSystemFeatures`. For example, the + attribute + + requiredSystemFeatures = [ "kvm" ]; + + ensures that the derivation can only be built on a machine with the + `kvm` feature. + + This setting by default includes `kvm` if `/dev/kvm` is accessible, + and the pseudo-features `nixos-test`, `benchmark` and `big-parallel` + that are used in Nixpkgs to route builds to specific machines. + + - `tarball-ttl` + Default: `3600` seconds. + + 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. + + Setting the TTL to `0` forces Nix to always check if the tarball is + up to date. + + Nix caches tarballs in `$XDG_CACHE_HOME/nix/tarballs`. + + Files fetched via `NIX_PATH`, `fetchGit`, `fetchMercurial`, + `fetchTarball`, and `fetchurl` respect this TTL. + + - `timeout` + This option defines the maximum number of seconds that a builder can + run. This is useful (for instance in an automated build system) to + catch builds that are stuck in an infinite loop but keep writing to + their standard output or standard error. It can be overridden using + the `--timeout` command line switch. + + The value `0` means that there is no timeout. This is also the + default. + + - `trace-function-calls` + Default: `false`. + + If set to `true`, 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. + + 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 + + The `undefined position` means the function call is a builtin. + + Use the `contrib/stack-collapse.py` script distributed with the Nix + source code to convert the trace logs in to a format suitable for + `flamegraph.pl`. + + - `trusted-public-keys` + A whitespace-separated list of public keys. When paths are copied + from another Nix store (such as a binary cache), they must be signed + with one of these keys. For example: + `cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= + hydra.nixos.org-1:CNHJZBh9K4tP3EKF6FkkgeVYsS3ohTl+oS0Qa8bezVs=`. + + - `trusted-substituters` + A list of URLs of substituters, separated by whitespace. These are + not used by default, but can be enabled by users of the Nix daemon + by specifying `--option + substituters urls` on the command line. Unprivileged users are only + allowed to pass a subset of the URLs listed in `substituters` and + `trusted-substituters`. + + - `trusted-users` + A list of names of users (separated by whitespace) that have + additional rights when connecting to the Nix daemon, such as the + ability to specify additional binary caches, or to import unsigned + NARs. You can also specify groups by prefixing them with `@`; for + instance, `@wheel` means all users in the `wheel` group. The default + is `root`. + + > **Warning** + > + > Adding a user to `trusted-users` is essentially equivalent to + > giving that user root access to the system. For example, the user + > can set `sandbox-paths` and thereby obtain read access to + > directories that are otherwise inacessible to them. + +## Deprecated Settings + + - `binary-caches` + *Deprecated:* `binary-caches` is now an alias to `substituters`. + + - `binary-cache-public-keys` + *Deprecated:* `binary-cache-public-keys` is now an alias `trusted-public-keys`. + + - `build-compress-log` + *Deprecated:* `build-compress-log` is now an alias to `compress-build-log`. + + - `build-cores` + *Deprecated:* `build-cores` is now an alias to `cores`. + + - `build-extra-chroot-dirs` + *Deprecated:* `build-extra-chroot-dirs` is now an alias to `extra-sandbox-paths`. + + - `build-extra-sandbox-paths` + *Deprecated:* `build-extra-sandbox-paths` is now an alias to `extra-sandbox-paths`. + + - `build-fallback` + *Deprecated:* `build-fallback` is now an alias to `fallback`. + + - `build-max-jobs` + *Deprecated:* `build-max-jobs` is now an alias to `max-jobs`. + + - `build-max-log-size` + *Deprecated:* `build-max-log-size` is now an alias to `max-build-log-size`. + + - `build-max-silent-time` + *Deprecated:* `build-max-silent-time` is now an alias to `max-silent-time`. + + - `build-repeat` + *Deprecated:* `build-repeat` is now an alias to `repeat`. + + - `build-timeout` + *Deprecated:* `build-timeout` is now an alias to `timeout`. + + - `build-use-chroot` + *Deprecated:* `build-use-chroot` is now an alias to `sandbox`. + + - `build-use-sandbox` + *Deprecated:* `build-use-sandbox` is now an alias to `sandbox`. + + - `build-use-substitutes` + *Deprecated:* `build-use-substitutes` is now an alias to `substitute`. + + - `gc-keep-derivations` + *Deprecated:* `gc-keep-derivations` is now an alias to `keep-derivations`. + + - `gc-keep-outputs` + *Deprecated:* `gc-keep-outputs` is now an alias to `keep-outputs`. + + - `env-keep-derivations` + *Deprecated:* `env-keep-derivations` is now an alias to `keep-env-derivations`. + + - `extra-binary-caches` + *Deprecated:* `extra-binary-caches` is now an alias to `extra-substituters`. + + - `trusted-binary-caches` + *Deprecated:* `trusted-binary-caches` is now an alias to `trusted-substituters`. diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md new file mode 100644 index 000000000..e5fd45a7f --- /dev/null +++ b/doc/manual/src/command-ref/env-common.md @@ -0,0 +1,113 @@ +# Common Environment Variables + +Most Nix commands interpret the following environment variables: + + - `IN_NIX_SHELL` + Indicator that tells if the current environment was set up by + `nix-shell`. Since Nix 2.0 the values are `"pure"` and `"impure"` + + - `NIX_PATH` + A colon-separated list of directories used to look up Nix + expressions enclosed in angle brackets (i.e., `<path>`). For + instance, the value + + /home/eelco/Dev:/etc/nixos + + will cause Nix to look for paths relative to `/home/eelco/Dev` and + `/etc/nixos`, in this order. It is also possible to match paths + against a prefix. For example, the value + + nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos + + will cause Nix to search for `<nixpkgs/path>` in + `/home/eelco/Dev/nixpkgs-branch/path` and `/etc/nixos/nixpkgs/path`. + + If a path in the Nix search path starts with `http://` or + `https://`, it is interpreted as the URL of a tarball that will be + downloaded and unpacked to a temporary location. The tarball must + consist of a single top-level directory. For example, setting + `NIX_PATH` to + + nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz + + tells Nix to download the latest revision in the Nixpkgs/NixOS 15.09 + channel. + + A following shorthand can be used to refer to the official channels: + + nixpkgs=channel:nixos-15.09 + + The search path can be extended using the `-I` option, which takes + precedence over `NIX_PATH`. + + - `NIX_IGNORE_SYMLINK_STORE` + Normally, the Nix store directory (typically `/nix/store`) is not + allowed to contain any symlink components. This is to prevent + “impure” builds. Builders sometimes “canonicalise” paths by + resolving all symlink components. Thus, builds on different machines + (with `/nix/store` resolving to different locations) could yield + different results. This is generally not a problem, except when + builds are deployed to machines where `/nix/store` resolves + differently. If you are sure that you’re not going to do that, you + can set `NIX_IGNORE_SYMLINK_STORE` to `1`. + + Note that if you’re symlinking the Nix store so that you can put it + on another file system than the root file system, on Linux you’re + better off using `bind` mount points, e.g., + + $ mkdir /nix + $ mount -o bind /mnt/otherdisk/nix /nix + + Consult the mount 8 manual page for details. + + - `NIX_STORE_DIR` + Overrides the location of the Nix store (default `prefix/store`). + + - `NIX_DATA_DIR` + Overrides the location of the Nix static data directory (default + `prefix/share`). + + - `NIX_LOG_DIR` + Overrides the location of the Nix log directory (default + `prefix/var/log/nix`). + + - `NIX_STATE_DIR` + Overrides the location of the Nix state directory (default + `prefix/var/nix`). + + - `NIX_CONF_DIR` + Overrides the location of the system Nix configuration directory + (default `prefix/etc/nix`). + + - `NIX_USER_CONF_FILES` + Overrides the location of the user Nix configuration files to load + from (defaults to the XDG spec locations). The variable is treated + as a list separated by the `:` token. + + - `TMPDIR` + Use the specified directory to store temporary files. In particular, + this includes temporary build directories; these can take up + substantial amounts of disk space. The default is `/tmp`. + + - `NIX_REMOTE` + This variable should be set to `daemon` if you want to use the Nix + daemon to execute Nix operations. This is necessary in [multi-user + Nix installations](../installation/multi-user.md). If the Nix + daemon's Unix socket is at some non-standard path, this variable + should be set to `unix://path/to/socket`. Otherwise, it should be + left unset. + + - `NIX_SHOW_STATS` + If set to `1`, Nix will print some evaluation statistics, such as + the number of values allocated. + + - `NIX_COUNT_CALLS` + If set to `1`, Nix will print how often functions were called during + Nix expression evaluation. This is useful for profiling your Nix + expressions. + + - `GC_INITIAL_HEAP_SIZE` + If Nix has been configured to use the Boehm garbage collector, this + variable sets the initial size of the heap in bytes. It defaults to + 384 MiB. Setting it to a low value reduces memory consumption, but + will increase runtime due to the overhead of garbage collection. diff --git a/doc/manual/src/command-ref/files.md b/doc/manual/src/command-ref/files.md new file mode 100644 index 000000000..df5646c05 --- /dev/null +++ b/doc/manual/src/command-ref/files.md @@ -0,0 +1,4 @@ +# Files + +This section lists configuration files that you can use when you work +with Nix. diff --git a/doc/manual/src/command-ref/main-commands.md b/doc/manual/src/command-ref/main-commands.md new file mode 100644 index 000000000..e4f1f1d0e --- /dev/null +++ b/doc/manual/src/command-ref/main-commands.md @@ -0,0 +1,4 @@ +# Main Commands + +This section lists commands and options that you can use when you work +with Nix. diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md new file mode 100644 index 000000000..026495c8d --- /dev/null +++ b/doc/manual/src/command-ref/nix-build.md @@ -0,0 +1,105 @@ +Title: nix-build + +# Name + +`nix-build` - build a Nix expression + +# Synopsis + +`nix-build` [*paths…*] + [`--arg` *name* *value*] + [`--argstr` *name* *value*] + [{`--attr` | `-A`} *attrPath*] + [`--no-out-link`] + [`--dry-run`] + [{`--out-link` | `-o`} *outlink*] + +# Description + +The `nix-build` command builds the derivations described by the Nix +expressions in *paths*. If the build succeeds, it places a symlink to +the result in the current directory. The symlink is called `result`. If +there are multiple Nix expressions, or the Nix expressions evaluate to +multiple derivations, multiple sequentially numbered symlinks are +created (`result`, `result-2`, and so on). + +If no *paths* are specified, then `nix-build` will use `default.nix` in +the current directory, if it exists. + +If an element of *paths* starts with `http://` or `https://`, it is +interpreted as the URL of a tarball that will be downloaded and unpacked +to a temporary location. The tarball must include a single top-level +directory containing at least a file named `default.nix`. + +`nix-build` is essentially a wrapper around +[`nix-instantiate`](nix-instantiate.md) (to translate a high-level Nix +expression to a low-level store derivation) and [`nix-store +--realise`](nix-store.md#operation---realise) (to build the store +derivation). + +> **Warning** +> +> The result of the build is automatically registered as a root of the +> Nix garbage collector. This root disappears automatically when the +> `result` symlink is deleted or renamed. So don’t rename the symlink. + +# Options + +All options not listed here are passed to `nix-store +--realise`, except for `--arg` and `--attr` / `-A` which are passed to +`nix-instantiate`. + + - `--no-out-link` + Do not create a symlink to the output path. Note that as a result + the output does not become a root of the garbage collector, and so + might be deleted by `nix-store + --gc`. + + - `--dry-run` + Show what store paths would be built or downloaded. + + - `--out-link` / `-o` *outlink* + Change the name of the symlink to the output path created from + `result` to *outlink*. + +The following common options are supported: + +# Examples + + $ nix-build '<nixpkgs>' -A firefox + store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv + /nix/store/d18hyl92g30l...-firefox-1.5.0.7 + + $ ls -l result + lrwxrwxrwx ... result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7 + + $ ls ./result/bin/ + firefox firefox-config + +If a derivation has multiple outputs, `nix-build` will build the default +(first) output. You can also build all outputs: + + $ nix-build '<nixpkgs>' -A openssl.all + +This will create a symlink for each output named `result-outputname`. +The suffix is omitted if the output name is `out`. So if `openssl` has +outputs `out`, `bin` and `man`, `nix-build` will create symlinks +`result`, `result-bin` and `result-man`. It’s also possible to build a +specific output: + + $ nix-build '<nixpkgs>' -A openssl.man + +This will create a symlink `result-man`. + +Build a Nix expression given on the command line: + + $ nix-build -E 'with import <nixpkgs> { }; runCommand "foo" { } "echo bar > $out"' + $ cat ./result + bar + +Build the GNU Hello package from the latest revision of the master +branch of Nixpkgs: + + $ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello + +# Environment variables diff --git a/doc/manual/src/command-ref/nix-channel.md b/doc/manual/src/command-ref/nix-channel.md new file mode 100644 index 000000000..ea3a57e69 --- /dev/null +++ b/doc/manual/src/command-ref/nix-channel.md @@ -0,0 +1,94 @@ +Title: nix-channel + +# Name + +`nix-channel` - manage Nix channels + +# Synopsis + +`nix-channel` {`--add` url [*name*] | `--remove` *name* | `--list` | `--update` [*names…*] | `--rollback` [*generation*] } + +# Description + +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. + +To see the list of official NixOS channels, visit +<https://nixos.org/channels>. + +This command has the following operations: + + - `--add` *url* \[*name*\] + Adds a channel named *name* with URL *url* to the list of subscribed + channels. If *name* is omitted, it defaults to the last component of + *url*, with the suffixes `-stable` or `-unstable` removed. + + - `--remove` *name* + Removes the channel named *name* from the list of subscribed + channels. + + - `--list` + Prints the names and URLs of all subscribed channels on standard + output. + + - `--update` \[*names*…\] + Downloads the Nix expressions of all subscribed channels (or only + those included in *names* if specified) and makes them the default + for `nix-env` operations (by symlinking them from the directory + `~/.nix-defexpr`). + + - `--rollback` \[*generation*\] + Reverts the previous call to `nix-channel + --update`. Optionally, you can specify a specific channel generation + number to restore. + +Note that `--add` does not automatically perform an update. + +The list of subscribed channels is stored in `~/.nix-channels`. + +# Examples + +To subscribe to the Nixpkgs channel and install the GNU Hello package: + + $ nix-channel --add https://nixos.org/channels/nixpkgs-unstable + $ nix-channel --update + $ nix-env -iA nixpkgs.hello + +You can revert channel updates using `--rollback`: + + $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' + "14.04.527.0e935f1" + + $ nix-channel --rollback + switching from generation 483 to 482 + + $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' + "14.04.526.dbadfad" + +# Files + + - `/nix/var/nix/profiles/per-user/username/channels` + `nix-channel` uses a `nix-env` profile to keep track of previous + versions of the subscribed channels. Every time you run `nix-channel + --update`, a new channel generation (that is, a symlink to the + channel Nix expressions in the Nix store) is created. This enables + `nix-channel --rollback` to revert to previous versions. + + - `~/.nix-defexpr/channels` + This is a symlink to + `/nix/var/nix/profiles/per-user/username/channels`. It ensures that + `nix-env` can find your channels. In a multi-user installation, you + may also have `~/.nix-defexpr/channels_root`, which links to the + channels of the root user. + +# Channel format + +A channel URL should point to a directory containing the following +files: + + - `nixexprs.tar.xz` + A tarball containing Nix expressions and files referenced by them + (such as build scripts and patches). At the top level, the tarball + should contain a single directory. That directory must contain a + file `default.nix` that serves as the channel’s “entry point”. diff --git a/doc/manual/src/command-ref/nix-collect-garbage.md b/doc/manual/src/command-ref/nix-collect-garbage.md new file mode 100644 index 000000000..37587c7e1 --- /dev/null +++ b/doc/manual/src/command-ref/nix-collect-garbage.md @@ -0,0 +1,30 @@ +Title: nix-collect-garbage + +# Name + +`nix-collect-garbage` - delete unreachable store paths + +# Synopsis + +`nix-collect-garbage` [`--delete-old`] [`-d`] [`--delete-older-than` *period*] [`--max-freed` *bytes*] [`--dry-run`] + +# Description + +The command `nix-collect-garbage` is mostly an alias of [`nix-store +--gc`](nix-store.md#operation---gc), that is, it deletes all +unreachable paths in the Nix store to clean up your system. However, +it provides two additional options: `-d` (`--delete-old`), which +deletes all old generations of all profiles in `/nix/var/nix/profiles` +by invoking `nix-env --delete-generations old` on all profiles (of +course, this makes rollbacks to previous configurations impossible); +and `--delete-older-than` *period*, where period is a value such as +`30d`, which deletes all generations older than the specified number +of days in all profiles in `/nix/var/nix/profiles` (except for the +generations that were active at that point in time). + +# Example + +To delete from the Nix store everything that is not used by the current +generations of each profile, do + + $ nix-collect-garbage -d diff --git a/doc/manual/src/command-ref/nix-copy-closure.md b/doc/manual/src/command-ref/nix-copy-closure.md new file mode 100644 index 000000000..2a4558324 --- /dev/null +++ b/doc/manual/src/command-ref/nix-copy-closure.md @@ -0,0 +1,83 @@ +Title: nix-copy-closure + +# Name + +`nix-copy-closure` - copy a closure to or from a remote machine via SSH + +# Synopsis + +`nix-copy-closure` + [`--to` | `--from`] + [`--gzip`] + [`--include-outputs`] + [`--use-substitutes` | `-s`] + [`-v`] + _user@machine_ _paths_ + +# Description + +`nix-copy-closure` gives you an easy and efficient way to exchange +software between machines. Given one or more Nix store _paths_ on the +local machine, `nix-copy-closure` computes the closure of those paths +(i.e. all their dependencies in the Nix store), and copies all paths +in the closure to the remote machine via the `ssh` (Secure Shell) +command. With the `--from` option, the direction is reversed: the +closure of _paths_ on a remote machine is copied to the Nix store on +the local machine. + +This command is efficient because it only sends the store paths +that are missing on the target machine. + +Since `nix-copy-closure` calls `ssh`, you may be asked to type in the +appropriate password or passphrase. In fact, you may be asked _twice_ +because `nix-copy-closure` currently connects twice to the remote +machine, first to get the set of paths missing on the target machine, +and second to send the dump of those paths. If this bothers you, use +`ssh-agent`. + +# Options + + - `--to` + Copy the closure of _paths_ from the local Nix store to the Nix + store on _machine_. This is the default. + + - `--from` + Copy the closure of _paths_ from the Nix store on _machine_ to the + local Nix store. + + - `--gzip` + Enable compression of the SSH connection. + + - `--include-outputs` + Also copy the outputs of store derivations included in the closure. + + - `--use-substitutes` / `-s` + Attempt to download missing paths on the target machine using Nix’s + substitute mechanism. Any paths that cannot be substituted on the + target are still copied normally from the source. This is useful, + for instance, if the connection between the source and target + machine is slow, but the connection between the target machine and + `nixos.org` (the default binary cache server) is + fast. + + - `-v` + Show verbose output. + +# Environment variables + + - `NIX_SSHOPTS` + Additional options to be passed to `ssh` on the command + line. + +# Examples + +Copy Firefox with all its dependencies to a remote machine: + + $ nix-copy-closure --to alice@itchy.labs $(type -tP firefox) + +Copy Subversion from a remote machine and then install it into a user +environment: + + $ nix-copy-closure --from alice@itchy.labs \ + /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4 + $ nix-env -i /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4 diff --git a/doc/manual/src/command-ref/nix-daemon.md b/doc/manual/src/command-ref/nix-daemon.md new file mode 100644 index 000000000..bd5d25026 --- /dev/null +++ b/doc/manual/src/command-ref/nix-daemon.md @@ -0,0 +1,15 @@ +Title: nix-daemon + +# Name + +`nix-daemon` - Nix multi-user support daemon + +# Synopsis + +`nix-daemon` + +# Description + +The Nix daemon is necessary in multi-user Nix installations. It performs +build actions and other operations on the Nix store on behalf of +unprivileged users. diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md new file mode 100644 index 000000000..c5fcce316 --- /dev/null +++ b/doc/manual/src/command-ref/nix-env.md @@ -0,0 +1,808 @@ +Title: nix-env + +# Name + +`nix-env` - manipulate or query Nix user environments + +# Synopsis + +`nix-env` + [`--option` *name* *value*] + [`--arg` *name* *value*] + [`--argstr` *name* *value*] + [{`--file` | `-f`} *path*] + [{`--profile` | `-p`} *path(] + [`--system-filter` *system*] + [`--dry-run`] + *operation* [*options…*] [*arguments…*] + +# Description + +The command `nix-env` is used to manipulate Nix user environments. User +environments are sets of software packages available to a user at some +point in time. In other words, they are a synthesised view of the +programs available in the Nix store. There may be many user +environments: different users can have different environments, and +individual users can switch between different environments. + +`nix-env` takes exactly one *operation* flag which indicates the +subcommand to be performed. These are documented below. + +# Selectors + +Several commands, such as `nix-env -q` and `nix-env -i`, take a list of +arguments that specify the packages on which to operate. These are +extended regular expressions that must match the entire name of the +package. (For details on regular expressions, see regex7.) The match is +case-sensitive. The regular expression can optionally be followed by a +dash and a version number; if omitted, any version of the package will +match. Here are some examples: + + - `firefox` + Matches the package name `firefox` and any version. + + - `firefox-32.0` + Matches the package name `firefox` and version `32.0`. + + - `gtk\\+` + Matches the package name `gtk+`. The `+` character must be escaped + using a backslash to prevent it from being interpreted as a + quantifier, and the backslash must be escaped in turn with another + backslash to ensure that the shell passes it on. + + - `.\*` + Matches any package name. This is the default for most commands. + + - `'.*zip.*'` + Matches any package name containing the string `zip`. Note the dots: + `'*zip*'` does not work, because in a regular expression, the + character `*` is interpreted as a quantifier. + + - `'.*(firefox|chromium).*'` + Matches any package name containing the strings `firefox` or + `chromium`. + +# Common options + +This section lists the options that are common to all operations. These +options are allowed for every subcommand, though they may not always +have an effect. + + - `--file` / `-f` *path* + Specifies the Nix expression (designated below as the *active Nix + expression*) used by the `--install`, `--upgrade`, and `--query + --available` operations to obtain derivations. The default is + `~/.nix-defexpr`. + + If the argument starts with `http://` or `https://`, it is + interpreted as the URL of a tarball that will be downloaded and + unpacked to a temporary location. The tarball must include a single + top-level directory containing at least a file named `default.nix`. + + - `--profile` / `-p` *path* + Specifies the profile to be used by those operations that operate on + a profile (designated below as the *active profile*). A profile is a + sequence of user environments called *generations*, one of which is + the *current generation*. + + - `--dry-run` + For the `--install`, `--upgrade`, `--uninstall`, + `--switch-generation`, `--delete-generations` and `--rollback` + operations, this flag will cause `nix-env` to print what *would* be + done if this flag had not been specified, without actually doing it. + + `--dry-run` also prints out which paths will be + [substituted](../glossary.md) (i.e., downloaded) and which paths + will be built from source (because no substitute is available). + + - `--system-filter` *system* + By default, operations such as `--query + --available` show derivations matching any platform. This option + allows you to use derivations for the specified platform *system*. + +<!-- end list --> + +# Files + + - `~/.nix-defexpr` + The source for the default Nix expressions used by the + `--install`, `--upgrade`, and `--query --available` operations to + obtain derivations. The `--file` option may be used to override + this default. + + If `~/.nix-defexpr` 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. + + If `~/.nix-defexpr` is a directory containing a `default.nix` file, + that file is loaded as in the above paragraph. + + If `~/.nix-defexpr` is a directory without a `default.nix` 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. + + For example, if `~/.nix-defexpr` contains two files, `foo.nix` and + `bar.nix`, then the default Nix expression will essentially be + + { + foo = import ~/.nix-defexpr/foo.nix; + bar = import ~/.nix-defexpr/bar.nix; + } + + The file `manifest.nix` is always ignored. Subdirectories without a + `default.nix` 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. + + The command `nix-channel` places symlinks to the downloaded Nix + expressions from each subscribed channel in this directory. + + - `~/.nix-profile` + A symbolic link to the user's current profile. By default, this + symlink points to `prefix/var/nix/profiles/default`. The `PATH` + environment variable should include `~/.nix-profile/bin` for the + user environment to be visible to the user. + +# Operation `--install` + +## Synopsis + +`nix-env` {`--install` | `-i`} *args…* + [{`--prebuilt-only` | `-b`}] + [{`--attr` | `-A`}] + [`--from-expression`] [`-E`] + [`--from-profile` *path*] + [`--preserve-installed` | `-P`] + [`--remove-all` | `-r`] + +## Description + +The install operation creates a new user environment, based on the +current generation of the active profile, to which a set of store paths +described by *args* is added. The arguments *args* map to store paths in +a number of possible ways: + + - By default, *args* is a set of derivation names denoting derivations + in the active Nix expression. These are realised, and the resulting + output paths are installed. Currently installed derivations with a + name equal to the name of a derivation being added are removed + unless the option `--preserve-installed` is specified. + + If there are multiple derivations matching a name in *args* that + have the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the + derivation with the highest *priority* is used. A derivation can + define a priority by declaring the `meta.priority` attribute. This + attribute should be a number, with a higher value denoting a lower + priority. The default priority is `0`. + + If there are multiple matching derivations with the same priority, + then the derivation with the highest version will be installed. + + You can force the installation of multiple derivations with the same + name by being specific about the versions. For instance, `nix-env -i + gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will + probably cause a user environment conflict\!). + + - If `--attr` (`-A`) is specified, the arguments are *attribute + paths* that select attributes from the top-level Nix + expression. This is faster than using derivation names and + unambiguous. To find out the attribute paths of available + packages, use `nix-env -qaP`. + + - If `--from-profile` *path* is given, *args* is a set of names + denoting installed store paths in the profile *path*. This is an + easy way to copy user environment elements from one profile to + another. + + - If `--from-expression` is given, *args* are Nix + [functions](../expressions/language-constructs.md#functions) + that are called with the active Nix expression as their single + argument. The derivations returned by those function calls are + installed. This allows derivations to be specified in an + unambiguous way, which is necessary if there are multiple + derivations with the same name. + + - If *args* are store derivations, then these are + [realised](nix-store.md#operation---realise), and the resulting output paths + are installed. + + - If *args* are store paths that are not store derivations, then these + are [realised](nix-store.md#operation---realise) and installed. + + - By default all outputs are installed for each derivation. That can + be reduced by setting `meta.outputsToInstall`. + +## Flags + + - `--prebuilt-only` / `-b` + Use only derivations for which a substitute is registered, i.e., + there is a pre-built binary available that can be downloaded in lieu + of building the derivation. Thus, no packages will be built from + source. + + - `--preserve-installed`; `-P` + Do not remove derivations with a name matching one of the + derivations being installed. Usually, trying to have two versions of + the same package installed in the same generation of a profile will + lead to an error in building the generation, due to file name + clashes between the two versions. However, this is not the case for + all packages. + + - `--remove-all`; `-r` + Remove all previously installed packages first. This is equivalent + to running `nix-env -e '.*'` first, except that everything happens + in a single transaction. + +## Examples + +To install a specific version of `gcc` from the active Nix expression: + + $ nix-env --install gcc-3.3.2 + installing `gcc-3.3.2' + uninstalling `gcc-3.1' + +Note the previously installed version is removed, since +`--preserve-installed` was not specified. + +To install an arbitrary version: + + $ nix-env --install gcc + installing `gcc-3.3.2' + +To install using a specific attribute: + + $ nix-env -i -A gcc40mips + $ nix-env -i -A xorg.xorgserver + +To install all derivations in the Nix expression `foo.nix`: + + $ nix-env -f ~/foo.nix -i '.*' + +To copy the store path with symbolic name `gcc` from another profile: + + $ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc + +To install a specific store derivation (typically created by +`nix-instantiate`): + + $ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv + +To install a specific output path: + + $ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3 + +To install from a Nix expression specified on the command-line: + + $ nix-env -f ./foo.nix -i -E \ + 'f: (f {system = "i686-linux";}).subversionWithJava' + +I.e., this evaluates to `(f: (f {system = +"i686-linux";}).subversionWithJava) (import ./foo.nix)`, thus selecting +the `subversionWithJava` attribute from the set returned by calling the +function defined in `./foo.nix`. + +A dry-run tells you which paths will be downloaded or built from source: + + $ nix-env -f '<nixpkgs>' -iA hello --dry-run + (dry run; not doing anything) + installing ‘hello-2.10’ + this path will be fetched (0.04 MiB download, 0.19 MiB unpacked): + /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10 + ... + +To install Firefox from the latest revision in the Nixpkgs/NixOS 14.12 +channel: + + $ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox + +# Operation `--upgrade` + +## Synopsis + +`nix-env` {`--upgrade` | `-u`} *args* + [`--lt` | `--leq` | `--eq` | `--always`] + [{`--prebuilt-only` | `-b`}] + [{`--attr` | `-A`}] + [`--from-expression`] [`-E`] + [`--from-profile` *path*] + [`--preserve-installed` | `-P`] + +## Description + +The upgrade operation creates a new user environment, based on the +current generation of the active profile, in which all store paths are +replaced for which there are newer versions in the set of paths +described by *args*. Paths for which there are no newer versions are +left untouched; this is not an error. It is also not an error if an +element of *args* matches no installed derivations. + +For a description of how *args* is mapped to a set of store paths, see +[`--install`](#operation---install). If *args* describes multiple +store paths with the same symbolic name, only the one with the highest +version is installed. + +## Flags + + - `--lt` + Only upgrade a derivation to newer versions. This is the default. + + - `--leq` + In addition to upgrading to newer versions, also “upgrade” to + derivations that have the same version. Version are not a unique + identification of a derivation, so there may be many derivations + that have the same version. This flag may be useful to force + “synchronisation” between the installed and available derivations. + + - `--eq` + *Only* “upgrade” to derivations that have the same version. This may + not seem very useful, but it actually is, e.g., when there is a new + release of Nixpkgs and you want to replace installed applications + with the same versions built against newer dependencies (to reduce + the number of dependencies floating around on your system). + + - `--always` + In addition to upgrading to newer versions, also “upgrade” to + derivations that have the same or a lower version. I.e., derivations + may actually be downgraded depending on what is available in the + active Nix expression. + +For the other flags, see `--install`. + +## Examples + + $ nix-env --upgrade gcc + upgrading `gcc-3.3.1' to `gcc-3.4' + + $ nix-env -u gcc-3.3.2 --always (switch to a specific version) + upgrading `gcc-3.4' to `gcc-3.3.2' + + $ nix-env --upgrade pan + (no upgrades available, so nothing happens) + + $ nix-env -u (try to upgrade everything) + upgrading `hello-2.1.2' to `hello-2.1.3' + upgrading `mozilla-1.2' to `mozilla-1.4' + +## Versions + +The upgrade operation determines whether a derivation `y` is an upgrade +of a derivation `x` by looking at their respective `name` attributes. +The names (e.g., `gcc-3.3.1` are split into two parts: the package name +(`gcc`), and the version (`3.3.1`). The version part starts after the +first dash not followed by a letter. `x` is considered an upgrade of `y` +if their package names match, and the version of `y` is higher that that +of `x`. + +The versions are compared by splitting them into contiguous components +of numbers and letters. E.g., `3.3.1pre5` is split into `[3, 3, 1, +"pre", 5]`. These lists are then compared lexicographically (from left +to right). Corresponding components `a` and `b` are compared as follows. +If they are both numbers, integer comparison is used. If `a` is an empty +string and `b` is a number, `a` is considered less than `b`. The special +string component `pre` (for *pre-release*) is considered to be less than +other components. String components are considered less than number +components. Otherwise, they are compared lexicographically (i.e., using +case-sensitive string comparison). + +This is illustrated by the following examples: + + 1.0 < 2.3 + 2.1 < 2.3 + 2.3 = 2.3 + 2.5 > 2.3 + 3.1 > 2.3 + 2.3.1 > 2.3 + 2.3.1 > 2.3a + 2.3pre1 < 2.3 + 2.3pre3 < 2.3pre12 + 2.3a < 2.3c + 2.3pre1 < 2.3c + 2.3pre1 < 2.3q + +# Operation `--uninstall` + +## Synopsis + +`nix-env` {`--uninstall` | `-e`} *drvnames…* + +## Description + +The uninstall operation creates a new user environment, based on the +current generation of the active profile, from which the store paths +designated by the symbolic names *drvnames* are removed. + +## Examples + + $ nix-env --uninstall gcc + $ nix-env -e '.*' (remove everything) + +# Operation `--set` + +## Synopsis + +`nix-env` `--set` *drvname* + +## Description + +The `--set` operation modifies the current generation of a profile so +that it contains exactly the specified derivation, and nothing else. + +## Examples + +The following updates a profile such that its current generation will +contain just Firefox: + + $ nix-env -p /nix/var/nix/profiles/browser --set firefox + +# Operation `--set-flag` + +## Synopsis + +`nix-env` `--set-flag` *name* *value* *drvnames* + +## Description + +The `--set-flag` operation allows meta attributes of installed packages +to be modified. There are several attributes that can be usefully +modified, because they affect the behaviour of `nix-env` or the user +environment build script: + + - `priority` can be changed to resolve filename clashes. The user + environment build script uses the `meta.priority` attribute of + derivations to resolve filename collisions between packages. Lower + priority values denote a higher priority. For instance, the GCC + wrapper package and the Binutils package in Nixpkgs both have a file + `bin/ld`, so previously if you tried to install both you would get a + collision. Now, on the other hand, the GCC wrapper declares a higher + priority than Binutils, so the former’s `bin/ld` is symlinked in the + user environment. + + - `keep` can be set to `true` to prevent the package from being + upgraded or replaced. This is useful if you want to hang on to an + older version of a package. + + - `active` can be set to `false` to “disable” the package. That is, no + symlinks will be generated to the files of the package, but it + remains part of the profile (so it won’t be garbage-collected). It + can be set back to `true` to re-enable the package. + +## Examples + +To prevent the currently installed Firefox from being upgraded: + + $ nix-env --set-flag keep true firefox + +After this, `nix-env -u` will ignore Firefox. + +To disable the currently installed Firefox, then install a new Firefox +while the old remains part of the profile: + + $ nix-env -q + firefox-2.0.0.9 (the current one) + + $ nix-env --preserve-installed -i firefox-2.0.0.11 + installing `firefox-2.0.0.11' + building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment' + collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox' + and `/nix/store/...-firefox-2.0.0.9/bin/firefox'. + (i.e., can’t have two active at the same time) + + $ nix-env --set-flag active false firefox + setting flag on `firefox-2.0.0.9' + + $ nix-env --preserve-installed -i firefox-2.0.0.11 + installing `firefox-2.0.0.11' + + $ nix-env -q + firefox-2.0.0.11 (the enabled one) + firefox-2.0.0.9 (the disabled one) + +To make files from `binutils` take precedence over files from `gcc`: + + $ nix-env --set-flag priority 5 binutils + $ nix-env --set-flag priority 10 gcc + +# Operation `--query` + +## Synopsis + +`nix-env` {`--query` | `-q`} *names…* + [`--installed` | `--available` | `-a`] + [{`--status` | `-s`}] + [{`--attr-path` | `-P`}] + [`--no-name`] + [{`--compare-versions` | `-c`}] + [`--system`] + [`--drv-path`] + [`--out-path`] + [`--description`] + [`--meta`] + [`--xml`] + [`--json`] + [{`--prebuilt-only` | `-b`}] + [{`--attr` | `-A`} *attribute-path*] + +## Description + +The query operation displays information about either the store paths +that are installed in the current generation of the active profile +(`--installed`), or the derivations that are available for installation +in the active Nix expression (`--available`). It only prints information +about derivations whose symbolic name matches one of *names*. + +The derivations are sorted by their `name` attributes. + +## Source selection + +The following flags specify the set of things on which the query +operates. + + - `--installed` + The query operates on the store paths that are installed in the + current generation of the active profile. This is the default. + + - `--available`; `-a` + The query operates on the derivations that are available in the + active Nix expression. + +## Queries + +The following flags specify what information to display about the +selected derivations. Multiple flags may be specified, in which case the +information is shown in the order given here. Note that the name of the +derivation is shown unless `--no-name` is specified. + + - `--xml` + Print the result in an XML representation suitable for automatic + processing by other tools. The root element is called `items`, which + contains a `item` element for each available or installed + derivation. The fields discussed below are all stored in attributes + of the `item` elements. + + - `--json` + Print the result in a JSON representation suitable for automatic + processing by other tools. + + - `--prebuilt-only` / `-b` + Show only derivations for which a substitute is registered, i.e., + there is a pre-built binary available that can be downloaded in lieu + of building the derivation. Thus, this shows all packages that + probably can be installed quickly. + + - `--status`; `-s` + Print the *status* of the derivation. The status consists of three + characters. The first is `I` or `-`, indicating whether the + derivation is currently installed in the current generation of the + active profile. This is by definition the case for `--installed`, + but not for `--available`. The second is `P` or `-`, indicating + whether the derivation is present on the system. This indicates + whether installation of an available derivation will require the + derivation to be built. The third is `S` or `-`, indicating whether + a substitute is available for the derivation. + + - `--attr-path`; `-P` + Print the *attribute path* of the derivation, which can be used to + unambiguously select it using the `--attr` option available in + commands that install derivations like `nix-env --install`. This + option only works together with `--available` + + - `--no-name` + Suppress printing of the `name` attribute of each derivation. + + - `--compare-versions` / `-c` + Compare installed versions to available versions, or vice versa (if + `--available` is given). This is useful for quickly seeing whether + upgrades for installed packages are available in a Nix expression. A + column is added with the following meaning: + + - `<` *version* + A newer version of the package is available or installed. + + - `=` *version* + At most the same version of the package is available or + installed. + + - `>` *version* + Only older versions of the package are available or installed. + + - `- ?` + No version of the package is available or installed. + + - `--system` + Print the `system` attribute of the derivation. + + - `--drv-path` + Print the path of the store derivation. + + - `--out-path` + Print the output path of the derivation. + + - `--description` + Print a short (one-line) description of the derivation, if + available. The description is taken from the `meta.description` + attribute of the derivation. + + - `--meta` + Print all of the meta-attributes of the derivation. This option is + only available with `--xml` or `--json`. + +## Examples + +To show installed packages: + + $ nix-env -q + bison-1.875c + docbook-xml-4.2 + firefox-1.0.4 + MPlayer-1.0pre7 + ORBit2-2.8.3 + … + +To show available packages: + + $ nix-env -qa + firefox-1.0.7 + GConf-2.4.0.1 + MPlayer-1.0pre7 + ORBit2-2.8.3 + … + +To show the status of available packages: + + $ nix-env -qas + -P- firefox-1.0.7 (not installed but present) + --S GConf-2.4.0.1 (not present, but there is a substitute for fast installation) + --S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!) + IP- ORBit2-2.8.3 (installed and by definition present) + … + +To show available packages in the Nix expression `foo.nix`: + + $ nix-env -f ./foo.nix -qa + foo-1.2.3 + +To compare installed versions to what’s available: + + $ nix-env -qc + ... + acrobat-reader-7.0 - ? (package is not available at all) + autoconf-2.59 = 2.59 (same version) + firefox-1.0.4 < 1.0.7 (a more recent version is available) + ... + +To show all packages with “`zip`” in the name: + + $ nix-env -qa '.*zip.*' + bzip2-1.0.6 + gzip-1.6 + zip-3.0 + … + +To show all packages with “`firefox`” or “`chromium`” in the name: + + $ nix-env -qa '.*(firefox|chromium).*' + chromium-37.0.2062.94 + chromium-beta-38.0.2125.24 + firefox-32.0.3 + firefox-with-plugins-13.0.1 + … + +To show all packages in the latest revision of the Nixpkgs repository: + + $ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa + +# Operation `--switch-profile` + +## Synopsis + +`nix-env` {`--switch-profile` | `-S`} *path* + +## Description + +This operation makes *path* the current profile for the user. That is, +the symlink `~/.nix-profile` is made to point to *path*. + +## Examples + + $ nix-env -S ~/my-profile + +# Operation `--list-generations` + +## Synopsis + +`nix-env` `--list-generations` + +## Description + +This operation print a list of all the currently existing generations +for the active profile. These may be switched to using the +`--switch-generation` operation. It also prints the creation date of the +generation, and indicates the current generation. + +## Examples + + $ nix-env --list-generations + 95 2004-02-06 11:48:24 + 96 2004-02-06 11:49:01 + 97 2004-02-06 16:22:45 + 98 2004-02-06 16:24:33 (current) + +# Operation `--delete-generations` + +## Synopsis + +`nix-env` `--delete-generations` *generations* + +## Description + +This operation deletes the specified generations of the current profile. +The generations can be a list of generation numbers, the special value +`old` to delete all non-current generations, a value such as `30d` 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 `+5` to keep the last `5` generations ignoring any newer than +current, e.g., if `30` is the current generation `+5` will delete +generation `25` and all older generations. Periodically deleting old +generations is important to make garbage collection effective. + +## Examples + + $ nix-env --delete-generations 3 4 8 + + $ nix-env --delete-generations +5 + + $ nix-env --delete-generations 30d + + $ nix-env -p other_profile --delete-generations old + +# Operation `--switch-generation` + +## Synopsis + +`nix-env` {`--switch-generation` | `-G`} *generation* + +## Description + +This operation makes generation number *generation* the current +generation of the active profile. That is, if the `profile` is the path +to the active profile, then the symlink `profile` is made to point to +`profile-generation-link`, which is in turn a symlink to the actual user +environment in the Nix store. + +Switching will fail if the specified generation does not exist. + +## Examples + + $ nix-env -G 42 + switching from generation 50 to 42 + +# Operation `--rollback` + +## Synopsis + +`nix-env` `--rollback` + +## Description + +This operation switches to the “previous” generation of the active +profile, that is, the highest numbered generation lower than the current +generation, if it exists. It is just a convenience wrapper around +`--list-generations` and `--switch-generation`. + +## Examples + + $ nix-env --rollback + switching from generation 92 to 91 + + $ nix-env --rollback + error: no generation older than the current (91) exists + +# Environment variables + + - `NIX_PROFILE` + Location of the Nix profile. Defaults to the target of the symlink + `~/.nix-profile`, if it exists, or `/nix/var/nix/profiles/default` + otherwise. diff --git a/doc/manual/src/command-ref/nix-hash.md b/doc/manual/src/command-ref/nix-hash.md new file mode 100644 index 000000000..edb331e1c --- /dev/null +++ b/doc/manual/src/command-ref/nix-hash.md @@ -0,0 +1,98 @@ +Title: nix-hash + +# Name + +`nix-hash` - compute the cryptographic hash of a path + +# Synopsis + +`nix-hash` [`--flat`] [`--base32`] [`--truncate`] [`--type` *hashAlgo*] *path…* + +`nix-hash` `--to-base16` *hash…* + +`nix-hash` `--to-base32` *hash…* + +# Description + +The command `nix-hash` computes the cryptographic hash of the contents +of each *path* and prints it on standard output. By default, it computes +an MD5 hash, but other hash algorithms are available as well. The hash +is printed in hexadecimal. To generate the same hash as +`nix-prefetch-url` you have to specify multiple arguments, see below for +an example. + +The hash is computed over a *serialisation* of each path: a dump of +the file system tree rooted at the path. This allows directories and +symlinks to be hashed as well as regular files. The dump is in the +*NAR format* produced by [`nix-store +--dump`](nix-store.md#operation---dump). Thus, `nix-hash path` +yields the same cryptographic hash as `nix-store --dump path | +md5sum`. + +# Options + + - `--flat` + Print the cryptographic hash of the contents of each regular file + *path*. That is, do not compute the hash over the dump of *path*. + The result is identical to that produced by the GNU commands + `md5sum` and `sha1sum`. + + - `--base32` + Print the hash in a base-32 representation rather than hexadecimal. + This base-32 representation is more compact and can be used in Nix + expressions (such as in calls to `fetchurl`). + + - `--truncate` + Truncate hashes longer than 160 bits (such as SHA-256) to 160 bits. + + - `--type` *hashAlgo* + Use the specified cryptographic hash algorithm, which can be one of + `md5`, `sha1`, and `sha256`. + + - `--to-base16` + Don’t hash anything, but convert the base-32 hash representation + *hash* to hexadecimal. + + - `--to-base32` + Don’t hash anything, but convert the hexadecimal hash representation + *hash* to base-32. + +# Examples + +Computing the same hash as `nix-prefetch-url`: + + $ nix-prefetch-url file://<(echo test) + 1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj + $ nix-hash --type sha256 --flat --base32 <(echo test) + 1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj + +Computing hashes: + + $ mkdir test + $ echo "hello" > test/world + + $ nix-hash test/ (MD5 hash; default) + 8179d3caeff1869b5ba1744e5a245c04 + + $ nix-store --dump test/ | md5sum (for comparison) + 8179d3caeff1869b5ba1744e5a245c04 - + + $ nix-hash --type sha1 test/ + e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 + + $ nix-hash --type sha1 --base32 test/ + nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 + + $ nix-hash --type sha256 --flat test/ + error: reading file `test/': Is a directory + + $ nix-hash --type sha256 --flat test/world + 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03 + +Converting between hexadecimal and base-32: + + $ nix-hash --type sha1 --to-base32 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 + nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 + + $ nix-hash --type sha1 --to-base16 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 + e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md new file mode 100644 index 000000000..2d6525e77 --- /dev/null +++ b/doc/manual/src/command-ref/nix-instantiate.md @@ -0,0 +1,145 @@ +Title: nix-instantiate + +# Name + +`nix-instantiate` - instantiate store derivations from Nix expressions + +# Synopsis + +`nix-instantiate` + [`--parse` | `--eval` [`--strict`] [`--json`] [`--xml`] ] + [`--read-write-mode`] + [`--arg` *name* *value*] + [{`--attr`| `-A`} *attrPath*] + [`--add-root` *path*] + [`--indirect`] + [`--expr` | `-E`] + *files…* + +`nix-instantiate` `--find-file` *files…* + +# Description + +The command `nix-instantiate` generates [store +derivations](../glossary.md) from (high-level) Nix expressions. It +evaluates the Nix expressions in each of *files* (which defaults to +*./default.nix*). Each top-level expression should evaluate to a +derivation, a list of derivations, or a set of derivations. The paths +of the resulting store derivations are printed on standard output. + +If *files* is the character `-`, then a Nix expression will be read from +standard input. + +# Options + + - `--add-root` *path*; `--indirect` + See the [corresponding options](nix-store.md) in `nix-store`. + + - `--parse` + Just parse the input files, and print their abstract syntax trees on + standard output in ATerm format. + + - `--eval` + Just parse and evaluate the input files, and print the resulting + values on standard output. No instantiation of store derivations + takes place. + + - `--find-file` + Look up the given files in Nix’s search path (as specified by the + `NIX_PATH` environment variable). If found, print the corresponding + absolute paths on standard output. For instance, if `NIX_PATH` is + `nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate --find-file + nixpkgs/default.nix` will print `/home/alice/nixpkgs/default.nix`. + + - `--strict` + When used with `--eval`, recursively evaluate list elements and + attributes. Normally, such sub-expressions are left unevaluated + (since the Nix expression language is lazy). + + > **Warning** + > + > This option can cause non-termination, because lazy data + > structures can be infinitely large. + + - `--json` + When used with `--eval`, print the resulting value as an JSON + representation of the abstract syntax tree rather than as an ATerm. + + - `--xml` + When used with `--eval`, print the resulting value as an XML + representation of the abstract syntax tree rather than as an ATerm. + The schema is the same as that used by the [`toXML` + built-in](../expressions/builtins.md). + + - `--read-write-mode` + When used with `--eval`, perform evaluation in read/write mode so + nix language features that require it will still work (at the cost + of needing to do instantiation of every evaluated derivation). If + this option is not enabled, there may be uninstantiated store paths + in the final output. + +<!-- end list --> + +# Examples + +Instantiating store derivations from a Nix expression, and building them +using `nix-store`: + + $ nix-instantiate test.nix (instantiate) + /nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv + + $ nix-store -r $(nix-instantiate test.nix) (build) + ... + /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 (output path) + + $ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 + dr-xr-xr-x 2 eelco users 4096 1970-01-01 01:00 lib + ... + +You can also give a Nix expression on the command line: + + $ nix-instantiate -E 'with import <nixpkgs> { }; hello' + /nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv + +This is equivalent to: + + $ nix-instantiate '<nixpkgs>' -A hello + +Parsing and evaluating Nix expressions: + + $ nix-instantiate --parse -E '1 + 2' + 1 + 2 + + $ nix-instantiate --eval -E '1 + 2' + 3 + + $ nix-instantiate --eval --xml -E '1 + 2' + <?xml version='1.0' encoding='utf-8'?> + <expr> + <int value="3" /> + </expr> + +The difference between non-strict and strict evaluation: + + $ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }' + ... + <attr name="x"> + <string value="foo" /> + </attr> + <attr name="y"> + <unevaluated /> + </attr> + ... + +Note that `y` is left unevaluated (the XML representation doesn’t +attempt to show non-normal forms). + + $ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }' + ... + <attr name="x"> + <string value="foo" /> + </attr> + <attr name="y"> + <string value="foo" /> + </attr> + ... diff --git a/doc/manual/src/command-ref/nix-prefetch-url.md b/doc/manual/src/command-ref/nix-prefetch-url.md new file mode 100644 index 000000000..688496969 --- /dev/null +++ b/doc/manual/src/command-ref/nix-prefetch-url.md @@ -0,0 +1,71 @@ +Title: nix-prefetch-url + +# Name + +`nix-prefetch-url` - copy a file from a URL into the store and print its hash + +# Synopsis + +`nix-prefetch-url` *url* [*hash*] + [`--type` *hashAlgo*] + [`--print-path`] + [`--unpack`] + [`--name` *name*] + +# Description + +The command `nix-prefetch-url` downloads the file referenced by the URL +*url*, prints its cryptographic hash, and copies it into the Nix store. +The file name in the store is `hash-baseName`, where *baseName* is +everything following the final slash in *url*. + +This command is just a convenience for Nix expression writers. Often a +Nix expression fetches some source distribution from the network using +the `fetchurl` expression contained in Nixpkgs. However, `fetchurl` +requires a cryptographic hash. If you don't know the hash, you would +have to download the file first, and then `fetchurl` would download it +again when you build your Nix expression. Since `fetchurl` uses the same +name for the downloaded file as `nix-prefetch-url`, the redundant +download can be avoided. + +If *hash* 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 is signaled if the +actual hash of the file does not match the specified hash. + +This command prints the hash on standard output. Additionally, if the +option `--print-path` is used, the path of the downloaded file in the +Nix store is also printed. + +# Options + + - `--type` *hashAlgo* + Use the specified cryptographic hash algorithm, which can be one of + `md5`, `sha1`, and `sha256`. + + - `--print-path` + Print the store path of the downloaded file on standard output. + + - `--unpack` + Unpack the archive (which must be a tarball or zip file) and add the + result to the Nix store. The resulting hash can be used with + functions such as Nixpkgs’s `fetchzip` or `fetchFromGitHub`. + + - `--name` *name* + Override the name of the file in the Nix store. By default, this is + `hash-basename`, where *basename* is the last component of *url*. + Overriding the name is necessary when *basename* contains characters + that are not allowed in Nix store paths. + +# Examples + + $ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz + 0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i + + $ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz + 0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i + /nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz + + $ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz + 079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7 + /nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md new file mode 100644 index 000000000..492351867 --- /dev/null +++ b/doc/manual/src/command-ref/nix-shell.md @@ -0,0 +1,248 @@ +Title: nix-shell + +# Name + +`nix-shell` - start an interactive shell based on a Nix expression + +# Synopsis + +`nix-shell` + [`--arg` *name* *value*] + [`--argstr` *name* *value*] + [{`--attr` | `-A`} *attrPath*] + [`--command` *cmd*] + [`--run` *cmd*] + [`--exclude` *regexp*] + [--pure] + [--keep *name*] + {{`--packages` | `-p`} {*packages* | *expressions*} … | [*path*]} + +# Description + +The command `nix-shell` will build the dependencies of the specified +derivation, but not the derivation itself. It will then start an +interactive shell in which all environment variables defined by the +derivation *path* have been set to their corresponding values, and the +script `$stdenv/setup` has been sourced. This is useful for reproducing +the environment of a derivation for development. + +If *path* is not given, `nix-shell` defaults to `shell.nix` if it +exists, and `default.nix` otherwise. + +If *path* starts with `http://` or `https://`, it is interpreted as the +URL of a tarball that will be downloaded and unpacked to a temporary +location. The tarball must include a single top-level directory +containing at least a file named `default.nix`. + +If the derivation defines the variable `shellHook`, it will be evaluated +after `$stdenv/setup` has been sourced. Since this hook is not executed +by regular Nix builds, it allows you to perform initialisation specific +to `nix-shell`. For example, the derivation attribute + + shellHook = + '' + echo "Hello shell" + ''; + +will cause `nix-shell` to print `Hello shell`. + +# Options + +All options not listed here are passed to `nix-store +--realise`, except for `--arg` and `--attr` / `-A` which are passed to +`nix-instantiate`. + + - `--command` *cmd* + In the environment of the derivation, run the shell command *cmd*. + This command is executed in an interactive shell. (Use `--run` to + use a non-interactive shell instead.) However, a call to `exit` is + implicitly added to the command, so the shell will exit after + running the command. To prevent this, add `return` at the end; + e.g. `--command "echo Hello; return"` will print `Hello` and then + drop you into the interactive shell. This can be useful for doing + any additional initialisation. + + - `--run` *cmd* + Like `--command`, but executes the command in a non-interactive + shell. This means (among other things) that if you hit Ctrl-C while + the command is running, the shell exits. + + - `--exclude` *regexp* + Do not build any dependencies whose store path matches the regular + expression *regexp*. This option may be specified multiple times. + + - `--pure` + If this flag is specified, the environment is almost entirely + cleared before the interactive shell is started, so you get an + environment that more closely corresponds to the “real” Nix build. A + few variables, in particular `HOME`, `USER` and `DISPLAY`, are + retained. Note that `~/.bashrc` and (depending on your Bash + installation) `/etc/bashrc` are still sourced, so any variables set + there will affect the interactive shell. + + - `--packages` / `-p` *packages*… + Set up an environment in which the specified packages are present. + The command line arguments are interpreted as attribute names inside + the Nix Packages collection. Thus, `nix-shell -p libjpeg openjdk` + will start a shell in which the packages denoted by the attribute + names `libjpeg` and `openjdk` are present. + + - `-i` *interpreter* + The chained script interpreter to be invoked by `nix-shell`. Only + applicable in `#!`-scripts (described below). + + - `--keep` *name* + When a `--pure` shell is started, keep the listed environment + variables. + +The following common options are supported: + +# Environment variables + + - `NIX_BUILD_SHELL` + Shell used to start the interactive environment. Defaults to the + `bash` found in `PATH`. + +# Examples + +To build the dependencies of the package Pan, and start an interactive +shell in which to build it: + + $ nix-shell '<nixpkgs>' -A pan + [nix-shell]$ unpackPhase + [nix-shell]$ cd pan-* + [nix-shell]$ configurePhase + [nix-shell]$ buildPhase + [nix-shell]$ ./pan/gui/pan + +To clear the environment first, and do some additional automatic +initialisation of the interactive shell: + + $ nix-shell '<nixpkgs>' -A pan --pure \ + --command 'export NIX_DEBUG=1; export NIX_CORES=8; return' + +Nix expressions can also be given on the command line using the `-E` and +`-p` flags. For instance, the following starts a shell containing the +packages `sqlite` and `libX11`: + + $ nix-shell -E 'with import <nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""' + +A shorter way to do the same is: + + $ nix-shell -p sqlite xorg.libX11 + [nix-shell]$ echo $NIX_LDFLAGS + … -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib … + +Note that `-p` accepts multiple full nix expressions that are valid in +the `buildInputs = [ ... ]` shown above, not only package names. So the +following is also legal: + + $ nix-shell -p sqlite 'git.override { withManual = false; }' + +The `-p` flag looks up Nixpkgs in the Nix search path. You can override +it by passing `-I` or setting `NIX_PATH`. For example, the following +gives you a shell containing the Pan package from a specific revision of +Nixpkgs: + + $ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz + + [nix-shell:~]$ pan --version + Pan 0.139 + +# Use as a `#!`-interpreter + +You can use `nix-shell` as a script interpreter to allow scripts written +in arbitrary languages to obtain their own dependencies via Nix. This is +done by starting the script with the following lines: + + #! /usr/bin/env nix-shell + #! nix-shell -i real-interpreter -p packages + +where *real-interpreter* is the “real” script interpreter that will be +invoked by `nix-shell` after it has obtained the dependencies and +initialised the environment, and *packages* are the attribute names of +the dependencies in Nixpkgs. + +The lines starting with `#! nix-shell` specify `nix-shell` options (see +above). Note that you cannot write `#! /usr/bin/env nix-shell -i ...` +because many operating systems only allow one argument in `#!` lines. + +For example, here is a Python script that depends on Python and the +`prettytable` package: + + #! /usr/bin/env nix-shell + #! nix-shell -i python -p python pythonPackages.prettytable + + import prettytable + + # Print a simple table. + t = prettytable.PrettyTable(["N", "N^2"]) + for n in range(1, 10): t.add_row([n, n * n]) + print t + +Similarly, the following is a Perl script that specifies that it +requires Perl and the `HTML::TokeParser::Simple` and `LWP` packages: + + #! /usr/bin/env nix-shell + #! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP + + use HTML::TokeParser::Simple; + + # Fetch nixos.org and print all hrefs. + my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/'); + + while (my $token = $p->get_tag("a")) { + my $href = $token->get_attr("href"); + print "$href\n" if $href; + } + +Sometimes you need to pass a simple Nix expression to customize a +package like Terraform: + + #! /usr/bin/env nix-shell + #! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])" + + terraform apply + +> **Note** +> +> You must use double quotes (`"`) when passing a simple Nix expression +> in a nix-shell shebang. + +Finally, using the merging of multiple nix-shell shebangs the following +Haskell script uses a specific branch of Nixpkgs/NixOS (the 18.03 stable +branch): + + #! /usr/bin/env nix-shell + #! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.HTTP ps.tagsoup])" + #! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-18.03.tar.gz + + import Network.HTTP + import Text.HTML.TagSoup + + -- Fetch nixos.org and print all hrefs. + main = do + resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/") + body <- getResponseBody resp + let tags = filter (isTagOpenName "a") $ parseTags body + let tags' = map (fromAttrib "href") tags + mapM_ putStrLn $ filter (/= "") tags' + +If you want to be even more precise, you can specify a specific revision +of Nixpkgs: + + #! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz + +The examples above all used `-p` to get dependencies from Nixpkgs. You +can also use a Nix expression to build your own dependencies. For +example, the Python example could have been written as: + + #! /usr/bin/env nix-shell + #! nix-shell deps.nix -i python + +where the file `deps.nix` in the same directory as the `#!`-script +contains: + + with import <nixpkgs> {}; + + runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } "" diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md new file mode 100644 index 000000000..1842f8858 --- /dev/null +++ b/doc/manual/src/command-ref/nix-store.md @@ -0,0 +1,803 @@ +Title: nix-store + +# Name + +`nix-store` - manipulate or query the Nix store + +# Synopsis + +`nix-store` *operation* [*options…*] [*arguments…*] + [`--option` *name* *value*] + [`--add-root` *path*] + [`--indirect`] + +# Description + +The command `nix-store` performs primitive operations on the Nix store. +You generally do not need to run this command manually. + +`nix-store` takes exactly one *operation* flag which indicates the +subcommand to be performed. These are documented below. + +# Common options + +This section lists the options that are common to all operations. These +options are allowed for every subcommand, though they may not always +have an effect. + + - `--add-root` *path* + Causes the result of a realisation (`--realise` and + `--force-realise`) to be registered as a root of the garbage + collector. The root is stored in *path*, which must be inside a + directory that is scanned for roots by the garbage collector + (i.e., typically in a subdirectory of `/nix/var/nix/gcroots/`) + *unless* the `--indirect` flag is used. + + If there are multiple results, then multiple symlinks will be + created by sequentially numbering symlinks beyond the first one + (e.g., `foo`, `foo-2`, `foo-3`, and so on). + + - `--indirect` + In conjunction with `--add-root`, this option allows roots to be + stored *outside* of the GC roots directory. This is useful for + commands such as `nix-build` that place a symlink to the build + result in the current directory; such a build result should not be + garbage-collected unless the symlink is removed. + + The `--indirect` flag causes a uniquely named symlink to *path* to + be stored in `/nix/var/nix/gcroots/auto/`. For instance, + + $ nix-store --add-root /home/eelco/bla/result --indirect -r ... + + $ ls -l /nix/var/nix/gcroots/auto + lrwxrwxrwx 1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result + + $ ls -l /home/eelco/bla/result + lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10 + + Thus, when `/home/eelco/bla/result` is removed, the GC root in the + `auto` directory becomes a dangling symlink and will be ignored by + the collector. + + > **Warning** + > + > Note that it is not possible to move or rename indirect GC roots, + > since the symlink in the `auto` directory will still point to the + > old location. + +<!-- end list --> + +# Operation `--realise` + +## Synopsis + +`nix-store` {`--realise` | `-r`} *paths…* [`--dry-run`] + +## Description + +The operation `--realise` essentially “builds” the specified store +paths. Realisation is a somewhat overloaded term: + + - If the store path is a *derivation*, realisation ensures that the + output paths of the derivation are [valid](../glossary.md) (i.e., + the output path and its closure exist in the file system). This + can be done in several ways. First, it is possible that the + outputs are already valid, in which case we are done + immediately. Otherwise, there may be [substitutes](../glossary.md) + that produce the outputs (e.g., by downloading them). Finally, the + outputs can be produced by performing the build action described + by the derivation. + + - If the store path is not a derivation, realisation ensures that the + specified path is valid (i.e., it and its closure exist in the file + system). If the path is already valid, we are done immediately. + Otherwise, the path and any missing paths in its closure may be + produced through substitutes. If there are no (successful) + subsitutes, realisation fails. + +The output path of each derivation is printed on standard output. (For +non-derivations argument, the argument itself is printed.) + +The following flags are available: + + - `--dry-run` + Print on standard error a description of what packages would be + built or downloaded, without actually performing the operation. + + - `--ignore-unknown` + If a non-derivation path does not have a substitute, then silently + ignore it. + + - `--check` + This option allows you to check whether a derivation is + deterministic. It rebuilds the specified derivation and checks + whether the result is bitwise-identical with the existing outputs, + printing an error if that’s not the case. The outputs of the + specified derivation must already exist. When used with `-K`, if an + output path is not identical to the corresponding output from the + previous build, the new output path is left in + `/nix/store/name.check.` + + See also the `build-repeat` configuration option, which repeats a + derivation a number of times and prevents its outputs from being + registered as “valid” in the Nix store unless they are identical. + +Special exit codes: + + - `100` + Generic build failure, the builder process returned with a non-zero + exit code. + + - `101` + Build timeout, the build was aborted because it did not complete + within the specified `timeout`. + + - `102` + Hash mismatch, the build output was rejected because it does not + match the [`outputHash` attribute of the + derivation](../expressions/advanced-attributes.md). + + - `104` + Not deterministic, the build succeeded in check mode but the + resulting output is not binary reproducable. + +With the `--keep-going` flag it's possible for multiple failures to +occur, in this case the 1xx status codes are or combined using binary +or. + + 1100100 + ^^^^ + |||`- timeout + ||`-- output hash mismatch + |`--- build failure + `---- not deterministic + +## Examples + +This operation is typically used to build store derivations produced by +[`nix-instantiate`](nix-instantiate.md): + + $ nix-store -r $(nix-instantiate ./test.nix) + /nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1 + +This is essentially what [`nix-build`](nix-build.md) does. + +To test whether a previously-built derivation is deterministic: + + $ nix-build '<nixpkgs>' -A hello --check -K + +# Operation `--serve` + +## Synopsis + +`nix-store` `--serve` [`--write`] + +## Description + +The operation `--serve` provides access to the Nix store over stdin and +stdout, and is intended to be used as a means of providing Nix store +access to a restricted ssh user. + +The following flags are available: + + - `--write` + Allow the connected client to request the realization of + derivations. In effect, this can be used to make the host act as a + remote builder. + +## Examples + +To turn a host into a build server, the `authorized_keys` file can be +used to provide build access to a given SSH public key: + + $ cat <<EOF >>/root/.ssh/authorized_keys + command="nice -n20 nix-store --serve --write" ssh-rsa AAAAB3NzaC1yc2EAAAA... + EOF + +# Operation `--gc` + +## Synopsis + +`nix-store` `--gc` [`--print-roots` | `--print-live` | `--print-dead`] [`--max-freed` *bytes*] + +## Description + +Without additional flags, the operation `--gc` performs a garbage +collection on the Nix store. That is, all paths in the Nix store not +reachable via file system references from a set of “roots”, are deleted. + +The following suboperations may be specified: + + - `--print-roots` + This operation prints on standard output the set of roots used by + the garbage collector. + + - `--print-live` + This operation prints on standard output the set of “live” store + paths, which are all the store paths reachable from the roots. Live + paths should never be deleted, since that would break consistency — + it would become possible that applications are installed that + reference things that are no longer present in the store. + + - `--print-dead` + This operation prints out on standard output the set of “dead” store + paths, which is just the opposite of the set of live paths: any path + in the store that is not live (with respect to the roots) is dead. + +By default, all unreachable paths are deleted. The following options +control what gets deleted and in what order: + + - `--max-freed` *bytes* + Keep deleting paths until at least *bytes* bytes have been deleted, + then stop. The argument *bytes* can be followed by the + multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB + or TiB units. + +The behaviour of the collector is also influenced by the +`keep-outputs` and `keep-derivations` variables in the Nix +configuration file. + +By default, the collector prints the total number of freed bytes when it +finishes (or when it is interrupted). With `--print-dead`, it prints the +number of bytes that would be freed. + +## Examples + +To delete all unreachable paths, just do: + + $ nix-store --gc + deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv' + ... + 8825586 bytes freed (8.42 MiB) + +To delete at least 100 MiBs of unreachable paths: + + $ nix-store --gc --max-freed $((100 * 1024 * 1024)) + +# Operation `--delete` + +## Synopsis + +`nix-store` `--delete` [`--ignore-liveness`] *paths…* + +## Description + +The operation `--delete` deletes the store paths *paths* from the Nix +store, but only if it is safe to do so; that is, when the path is not +reachable from a root of the garbage collector. This means that you can +only delete paths that would also be deleted by `nix-store --gc`. Thus, +`--delete` is a more targeted version of `--gc`. + +With the option `--ignore-liveness`, reachability from the roots is +ignored. However, the path still won’t be deleted if there are other +paths in the store that refer to it (i.e., depend on it). + +## Example + + $ nix-store --delete /nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4 + 0 bytes freed (0.00 MiB) + error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4' since it is still alive + +# Operation `--query` + +## Synopsis + +`nix-store` {`--query` | `-q`} + {`--outputs` | `--requisites` | `-R` | `--references` | + `--referrers` | `--referrers-closure` | `--deriver` | `-d` | + `--graph` | `--tree` | `--binding` *name* | `-b` *name* | `--hash` | + `--size` | `--roots`} + [`--use-output`] [`-u`] [`--force-realise`] [`-f`] + *paths…* + +## Description + +The operation `--query` displays various bits of information about the +store paths . The queries are described below. At most one query can be +specified. The default query is `--outputs`. + +The paths *paths* may also be symlinks from outside of the Nix store, to +the Nix store. In that case, the query is applied to the target of the +symlink. + +## Common query options + + - `--use-output`; `-u` + For each argument to the query that is a store derivation, apply the + query to the output path of the derivation instead. + + - `--force-realise`; `-f` + Realise each argument to the query first (see [`nix-store + --realise`](#operation---realise)). + +## Queries + + - `--outputs` + Prints out the [output paths](../glossary.md) of the store + derivations *paths*. These are the paths that will be produced when + the derivation is built. + + - `--requisites`; `-R` + Prints out the [closure](../glossary.md) of the store path *paths*. + + This query has one option: + + - `--include-outputs` + Also include the output path of store derivations, and their + closures. + + This query can be used to implement various kinds of deployment. A + *source deployment* is obtained by distributing the closure of a + store derivation. A *binary deployment* is obtained by distributing + the closure of an output path. A *cache deployment* (combined + source/binary deployment, including binaries of build-time-only + dependencies) is obtained by distributing the closure of a store + derivation and specifying the option `--include-outputs`. + + - `--references` + Prints the set of [references](../glossary.md) of the store paths + *paths*, that is, their immediate dependencies. (For *all* + dependencies, use `--requisites`.) + + - `--referrers` + Prints the set of *referrers* of the store paths *paths*, that is, + the store paths currently existing in the Nix store that refer to + one of *paths*. Note that contrary to the references, the set of + referrers is not constant; it can change as store paths are added or + removed. + + - `--referrers-closure` + Prints the closure of the set of store paths *paths* under the + referrers relation; that is, all store paths that directly or + indirectly refer to one of *paths*. These are all the path currently + in the Nix store that are dependent on *paths*. + + - `--deriver`; `-d` + Prints the [deriver](../glossary.md) of the store paths *paths*. If + the path has no deriver (e.g., if it is a source file), or if the + deriver is not known (e.g., in the case of a binary-only + deployment), the string `unknown-deriver` is printed. + + - `--graph` + Prints the references graph of the store paths *paths* in the format + of the `dot` tool of AT\&T's [Graphviz + package](http://www.graphviz.org/). This can be used to visualise + dependency graphs. To obtain a build-time dependency graph, apply + this to a store derivation. To obtain a runtime dependency graph, + apply it to an output path. + + - `--tree` + Prints the references graph of the store paths *paths* as a nested + ASCII tree. References are ordered by descending closure size; this + tends to flatten the tree, making it more readable. The query only + recurses into a store path when it is first encountered; this + prevents a blowup of the tree representation of the graph. + + - `--graphml` + Prints the references graph of the store paths *paths* in the + [GraphML](http://graphml.graphdrawing.org/) file format. This can be + used to visualise dependency graphs. To obtain a build-time + dependency graph, apply this to a store derivation. To obtain a + runtime dependency graph, apply it to an output path. + + - `--binding` *name*; `-b` *name* + Prints the value of the attribute *name* (i.e., environment + variable) of the store derivations *paths*. It is an error for a + derivation to not have the specified attribute. + + - `--hash` + Prints the SHA-256 hash of the contents of the store paths *paths* + (that is, the hash of the output of `nix-store --dump` on the given + paths). Since the hash is stored in the Nix database, this is a fast + operation. + + - `--size` + Prints the size in bytes of the contents of the store paths *paths* + — to be precise, the size of the output of `nix-store --dump` on + the given paths. Note that the actual disk space required by the + store paths may be higher, especially on filesystems with large + cluster sizes. + + - `--roots` + Prints the garbage collector roots that point, directly or + indirectly, at the store paths *paths*. + +## Examples + +Print the closure (runtime dependencies) of the `svn` program in the +current user environment: + + $ nix-store -qR $(which svn) + /nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4 + /nix/store/9lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4 + ... + +Print the build-time dependencies of `svn`: + + $ nix-store -qR $(nix-store -qd $(which svn)) + /nix/store/02iizgn86m42q905rddvg4ja975bk2i4-grep-2.5.1.tar.bz2.drv + /nix/store/07a2bzxmzwz5hp58nf03pahrv2ygwgs3-gcc-wrapper.sh + /nix/store/0ma7c9wsbaxahwwl04gbw3fcd806ski4-glibc-2.3.4.drv + ... lots of other paths ... + +The difference with the previous example is that we ask the closure of +the derivation (`-qd`), not the closure of the output path that contains +`svn`. + +Show the build-time dependencies as a tree: + + $ nix-store -q --tree $(nix-store -qd $(which svn)) + /nix/store/7i5082kfb6yjbqdbiwdhhza0am2xvh6c-subversion-1.1.4.drv + +---/nix/store/d8afh10z72n8l1cr5w42366abiblgn54-builder.sh + +---/nix/store/fmzxmpjx2lh849ph0l36snfj9zdibw67-bash-3.0.drv + | +---/nix/store/570hmhmx3v57605cqg9yfvvyh0nnb8k8-bash + | +---/nix/store/p3srsbd8dx44v2pg6nbnszab5mcwx03v-builder.sh + ... + +Show all paths that depend on the same OpenSSL library as `svn`: + + $ nix-store -q --referrers $(nix-store -q --binding openssl $(nix-store -qd $(which svn))) + /nix/store/23ny9l9wixx21632y2wi4p585qhva1q8-sylpheed-1.0.0 + /nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4 + /nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3 + /nix/store/l51240xqsgg8a7yrbqdx1rfzyv6l26fx-lynx-2.8.5 + +Show all paths that directly or indirectly depend on the Glibc (C +library) used by `svn`: + + $ nix-store -q --referrers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}') + /nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2 + /nix/store/15l3yi0d45prm7a82pcrknxdh6nzmxza-gawk-3.1.4 + ... + +Note that `ldd` is a command that prints out the dynamic libraries used +by an ELF executable. + +Make a picture of the runtime dependency graph of the current user +environment: + + $ nix-store -q --graph ~/.nix-profile | dot -Tps > graph.ps + $ gv graph.ps + +Show every garbage collector root that points to a store path that +depends on `svn`: + + $ nix-store -q --roots $(which svn) + /nix/var/nix/profiles/default-81-link + /nix/var/nix/profiles/default-82-link + /nix/var/nix/profiles/per-user/eelco/profile-97-link + +# Operation `--add` + +## Synopsis + +`nix-store` `--add` *paths…* + +## Description + +The operation `--add` adds the specified paths to the Nix store. It +prints the resulting paths in the Nix store on standard output. + +## Example + + $ nix-store --add ./foo.c + /nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c + +# Operation `--add-fixed` + +## Synopsis + +`nix-store` `--add-fixed` [`--recursive`] *algorithm* *paths…* + +## Description + +The operation `--add-fixed` adds the specified paths to the Nix store. +Unlike `--add` 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. + +This operation has the following options: + + - `--recursive` + Use recursive instead of flat hashing mode, used when adding + directories to the store. + +## Example + + $ nix-store --add-fixed sha256 ./hello-2.10.tar.gz + /nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz + +# Operation `--verify` + +## Synopsis + +`nix-store` `--verify` [`--check-contents`] [`--repair`] + +## Description + +The operation `--verify` verifies the internal consistency of the Nix +database, and the consistency between the Nix database and the Nix +store. Any inconsistencies encountered are automatically repaired. +Inconsistencies are generally the result of the Nix store or database +being modified by non-Nix tools, or of bugs in Nix itself. + +This operation has the following options: + + - `--check-contents` + Checks that the contents of every valid store path has not been + altered by computing a SHA-256 hash of the contents and comparing it + with the hash stored in the Nix database at build time. Paths that + have been modified are printed out. For large stores, + `--check-contents` is obviously quite slow. + + - `--repair` + If any valid path is missing from the store, or (if + `--check-contents` is given) the contents of a valid path has been + modified, then try to repair the path by redownloading it. See + `nix-store --repair-path` for details. + +# Operation `--verify-path` + +## Synopsis + +`nix-store` `--verify-path` *paths…* + +## Description + +The operation `--verify-path` compares the contents of the given store +paths to their cryptographic hashes stored in Nix’s database. For every +changed path, it prints a warning message. The exit status is 0 if no +path has changed, and 1 otherwise. + +## Example + +To verify the integrity of the `svn` command and all its dependencies: + + $ nix-store --verify-path $(nix-store -qR $(which svn)) + +# Operation `--repair-path` + +## Synopsis + +`nix-store` `--repair-path` *paths…* + +## Description + +The operation `--repair-path` attempts to “repair” the specified paths +by redownloading them using the available substituters. If no +substitutes are available, then repair is not possible. + +> **Warning** +> +> During repair, there is a very small time window during which the old +> path (if it exists) is moved out of the way and replaced with the new +> path. If repair is interrupted in between, then the system may be left +> in a broken state (e.g., if the path contains a critical system +> component like the GNU C Library). + +## Example + + $ nix-store --verify-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13 + path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified! + expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588', + got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4' + + $ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13 + fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'... + … + +# Operation `--dump` + +## Synopsis + +`nix-store` `--dump` *path* + +## Description + +The operation `--dump` produces a NAR (Nix ARchive) file containing the +contents of the file system tree rooted at *path*. The archive is +written to standard output. + +A NAR archive is like a TAR or Zip archive, but it contains only the +information that Nix considers important. For instance, timestamps are +elided because all files in the Nix store have their timestamp set to 0 +anyway. Likewise, all permissions are left out except for the execute +bit, because all files in the Nix store have 444 or 555 permission. + +Also, a NAR archive is *canonical*, meaning that “equal” paths always +produce the same NAR archive. For instance, directory entries are +always sorted so that the actual on-disk order doesn’t influence the +result. This means that the cryptographic hash of a NAR dump of a +path is usable as a fingerprint of the contents of the path. Indeed, +the hashes of store paths stored in Nix’s database (see `nix-store -q +--hash`) are SHA-256 hashes of the NAR dump of each store path. + +NAR archives support filenames of unlimited length and 64-bit file +sizes. They can contain regular files, directories, and symbolic links, +but not other types of files (such as device nodes). + +A Nix archive can be unpacked using `nix-store +--restore`. + +# Operation `--restore` + +## Synopsis + +`nix-store` `--restore` *path* + +## Description + +The operation `--restore` unpacks a NAR archive to *path*, which must +not already exist. The archive is read from standard input. + +# Operation `--export` + +## Synopsis + +`nix-store` `--export` *paths…* + +## Description + +The operation `--export` writes a serialisation of the specified store +paths to standard output in a format that can be imported into another +Nix store with `nix-store --import`. This is like `nix-store +--dump`, except that the NAR archive produced by that command doesn’t +contain the necessary meta-information to allow it to be imported into +another Nix store (namely, the set of references of the path). + +This command does not produce a *closure* of the specified paths, so if +a store path references other store paths that are missing in the target +Nix store, the import will fail. To copy a whole closure, do something +like: + + $ nix-store --export $(nix-store -qR paths) > out + +To import the whole closure again, run: + + $ nix-store --import < out + +# Operation `--import` + +## Synopsis + +`nix-store` `--import` + +## Description + +The operation `--import` reads a serialisation of a set of store paths +produced by `nix-store --export` from standard input and adds those +store paths to the Nix store. Paths that already exist in the Nix store +are ignored. If a path refers to another path that doesn’t exist in the +Nix store, the import fails. + +# Operation `--optimise` + +## Synopsis + +`nix-store` `--optimise` + +## Description + +The operation `--optimise` reduces Nix store disk space usage by finding +identical files in the store and hard-linking them to each other. It +typically reduces the size of the store by something like 25-35%. Only +regular files and symlinks are hard-linked in this manner. Files are +considered identical when they have the same NAR archive serialisation: +that is, regular files must have the same contents and permission +(executable or non-executable), and symlinks must have the same +contents. + +After completion, or when the command is interrupted, a report on the +achieved savings is printed on standard error. + +Use `-vv` or `-vvv` to get some progress indication. + +## Example + + $ nix-store --optimise + hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1' + ... + 541838819 bytes (516.74 MiB) freed by hard-linking 54143 files; + there are 114486 files with equal contents out of 215894 files in total + +# Operation `--read-log` + +## Synopsis + +`nix-store` {`--read-log` | `-l`} *paths…* + +## Description + +The operation `--read-log` prints the build log of the specified store +paths on standard output. The build log is whatever the builder of a +derivation wrote to standard output and standard error. If a store path +is not a derivation, the deriver of the store path is used. + +Build logs are kept in `/nix/var/log/nix/drvs`. However, there is no +guarantee that a build log is available for any particular store path. +For instance, if the path was downloaded as a pre-built binary through a +substitute, then the log is unavailable. + +## Example + + $ nix-store -l $(which ktorrent) + building /nix/store/dhc73pvzpnzxhdgpimsd9sw39di66ph1-ktorrent-2.2.1 + unpacking sources + unpacking source archive /nix/store/p8n1jpqs27mgkjw07pb5269717nzf5f8-ktorrent-2.2.1.tar.gz + ktorrent-2.2.1/ + ktorrent-2.2.1/NEWS + ... + +# Operation `--dump-db` + +## Synopsis + +`nix-store` `--dump-db` [*paths…*] + +## Description + +The operation `--dump-db` writes a dump of the Nix database to standard +output. It can be loaded into an empty Nix store using `--load-db`. This +is useful for making backups and when migrating to different database +schemas. + +By default, `--dump-db` will dump the entire Nix database. When one or +more store paths is passed, only the subset of the Nix database for +those store paths is dumped. As with `--export`, the user is responsible +for passing all the store paths for a closure. See `--export` for an +example. + +# Operation `--load-db` + +## Synopsis + +`nix-store` `--load-db` + +## Description + +The operation `--load-db` reads a dump of the Nix database created by +`--dump-db` from standard input and loads it into the Nix database. + +# Operation `--print-env` + +## Synopsis + +`nix-store` `--print-env` *drvpath* + +## Description + +The operation `--print-env` prints out the environment of a derivation +in a format that can be evaluated by a shell. The command line arguments +of the builder are placed in the variable `_args`. + +## Example + + $ nix-store --print-env $(nix-instantiate '<nixpkgs>' -A firefox) + … + export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2' + export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv' + export system; system='x86_64-linux' + export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-builder.sh' + +# Operation `--generate-binary-cache-key` + +## Synopsis + +`nix-store` `--generate-binary-cache-key` *key-name* *secret-key-file* *public-key-file* + +## Description + +This command generates an [Ed25519 key pair](http://ed25519.cr.yp.to/) +that can be used to create a signed binary cache. It takes three +mandatory parameters: + +1. A key name, such as `cache.example.org-1`, that is used to look up + keys on the client when it verifies signatures. It can be anything, + but it’s suggested to use the host name of your cache (e.g. + `cache.example.org`) with a suffix denoting the number of the key + (to be incremented every time you need to revoke a key). + +2. The file name where the secret key is to be stored. + +3. The file name where the public key is to be stored. diff --git a/doc/manual/src/command-ref/opt-common-syn.md b/doc/manual/src/command-ref/opt-common-syn.md new file mode 100644 index 000000000..b66d318c2 --- /dev/null +++ b/doc/manual/src/command-ref/opt-common-syn.md @@ -0,0 +1,57 @@ +\--help + +\--version + +\--verbose + +\-v + +\--quiet + +\--log-format + +format + +\--no-build-output + +\-Q + +\--max-jobs + +\-j + +number + +\--cores + +number + +\--max-silent-time + +number + +\--timeout + +number + +\--keep-going + +\-k + +\--keep-failed + +\-K + +\--fallback + +\--readonly-mode + +\-I + +path + +\--option + +name + +value diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md new file mode 100644 index 000000000..ee8419fd2 --- /dev/null +++ b/doc/manual/src/command-ref/opt-common.md @@ -0,0 +1,221 @@ +# Common Options + +Most Nix commands accept the following command-line options: + + - `--help` + Prints out a summary of the command syntax and exits. + + - `--version` + Prints out the Nix version number on standard output and exits. + + - `--verbose` / `-v` + Increases the level of verbosity of diagnostic messages printed on + standard error. For each Nix operation, the information printed on + standard output is well-defined; any diagnostic information is + printed on standard error, never on standard output. + + This option may be specified repeatedly. Currently, the following + verbosity levels exist: + + - 0 + “Errors only”: only print messages explaining why the Nix + invocation failed. + + - 1 + “Informational”: print *useful* messages about what Nix is + doing. This is the default. + + - 2 + “Talkative”: print more informational messages. + + - 3 + “Chatty”: print even more informational messages. + + - 4 + “Debug”: print debug information. + + - 5 + “Vomit”: print vast amounts of debug information. + + - `--quiet` + Decreases the level of verbosity of diagnostic messages printed on + standard error. This is the inverse option to `-v` / `--verbose`. + + This option may be specified repeatedly. See the previous verbosity + levels list. + + - `--log-format` *format* + This option can be used to change the output of the log format, with + *format* being one of: + + - raw + This is the raw format, as outputted by nix-build. + + - internal-json + Outputs the logs in a structured manner. NOTE: the json schema + is not guarantees to be stable between releases. + + - bar + Only display a progress bar during the builds. + + - bar-with-logs + Display the raw logs, with the progress bar at the bottom. + + - `--no-build-output` / `-Q` + By default, output written by builders to standard output and + standard error is echoed to the Nix command's standard error. This + option suppresses this behaviour. Note that the builder's standard + output and error are always written to a log file in + `prefix/nix/var/log/nix`. + + - `--max-jobs` / `-j` *number* + Sets the maximum number of build jobs that Nix will perform in + parallel to the specified number. Specify `auto` to use the number + of CPUs in the system. The default is specified by the `max-jobs` + configuration setting, which itself defaults to `1`. A higher + value is useful on SMP systems or to exploit I/O latency. + + Setting it to `0` disallows building on the local machine, which is + useful when you want builds to happen only on remote builders. + + - `--cores` + Sets the value of the `NIX_BUILD_CORES` environment variable in + the invocation of builders. Builders can use this variable at + their discretion to control the maximum amount of parallelism. For + instance, in Nixpkgs, if the derivation attribute + `enableParallelBuilding` is set to `true`, the builder passes the + `-jN` flag to GNU Make. It defaults to the value of the `cores` + configuration setting, if set, or `1` otherwise. The value `0` + means that the builder should use all available CPU cores in the + system. + + - `--max-silent-time` + Sets the maximum number of seconds that a builder can go without + producing any data on standard output or standard error. The + default is specified by the `max-silent-time` configuration + setting. `0` means no time-out. + + - `--timeout` + Sets the maximum number of seconds that a builder can run. The + default is specified by the `timeout` configuration setting. `0` + means no timeout. + + - `--keep-going` / `-k` + Keep going in case of failed builds, to the greatest extent + possible. That is, if building an input of some derivation fails, + Nix will still build the other inputs, but not the derivation + itself. Without this option, Nix stops if any build fails (except + for builds of substitutes), possibly killing builds in progress (in + case of parallel or distributed builds). + + - `--keep-failed` / `-K` + Specifies that in case of a build failure, the temporary directory + (usually in `/tmp`) in which the build takes place should not be + deleted. The path of the build directory is printed as an + informational message. + + - `--fallback` + Whenever Nix attempts to build a derivation for which substitutes + are known for each output path, but realising the output paths + through the substitutes fails, fall back on building the derivation. + + The most common scenario in which this is useful is when we have + registered substitutes in order to perform binary distribution from, + say, a network repository. If the repository is down, the + realisation of the derivation will fail. When this option is + specified, Nix will build the derivation instead. Thus, installation + from binaries falls back on installation from source. This option is + not the default since it is generally not desirable for a transient + failure in obtaining the substitutes to lead to a full build from + source (with the related consumption of resources). + + - `--no-build-hook` + Disables the build hook mechanism. This allows to ignore remote + builders if they are setup on the machine. + + It's useful in cases where the bandwidth between the client and the + remote builder is too low. In that case it can take more time to + upload the sources to the remote builder and fetch back the result + than to do the computation locally. + + - `--readonly-mode` + When this option is used, no attempt is made to open the Nix + database. Most Nix operations do need database access, so those + operations will fail. + + - `--arg` *name* *value* + This option is accepted by `nix-env`, `nix-instantiate`, + `nix-shell` and `nix-build`. 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 [default + value](../expressions/language-constructs.md#functions) (e.g., + `{ argName ? defaultValue }: ...`). With `--arg`, you can also + call functions that have arguments without a default value (or + override a default value). That is, if the evaluator encounters a + function with an argument named *name*, it will call it with value + *value*. + + For instance, the top-level `default.nix` in Nixpkgs is actually a + function: + + { # The system (e.g., `i686-linux') for which to build the packages. + system ? builtins.currentSystem + ... + }: ... + + So if you call this Nix expression (e.g., when you do `nix-env -i + pkgname`), the function will be called automatically using the + value [`builtins.currentSystem`](../expressions/builtins.md) for + the `system` argument. You can override this using `--arg`, e.g., + `nix-env -i pkgname --arg system \"i686-freebsd\"`. (Note that + since the argument is a Nix string literal, you have to escape the + quotes.) + + - `--argstr` *name* *value* + This option is like `--arg`, only the value is not a Nix + expression but a string. So instead of `--arg system + \"i686-linux\"` (the outer quotes are to keep the shell happy) you + can say `--argstr system i686-linux`. + + - `--attr` / `-A` *attrPath* + Select an attribute from the top-level Nix expression being + evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and + `nix-shell` only.) The *attribute path* *attrPath* is a sequence + of attribute names separated by dots. For instance, given a + top-level Nix expression *e*, the attribute path `xorg.xorgserver` + would cause the expression `e.xorg.xorgserver` to be used. See + [`nix-env --install`](nix-env.md#operation---install) for some + concrete examples. + + In addition to attribute names, you can also specify array indices. + For instance, the attribute path `foo.3.bar` selects the `bar` + attribute of the fourth element of the array in the `foo` attribute + of the top-level expression. + + - `--expr` / `-E` + Interpret the command line arguments as a list of Nix expressions to + be parsed and evaluated, rather than as a list of file names of Nix + expressions. (`nix-instantiate`, `nix-build` and `nix-shell` only.) + + For `nix-shell`, 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 *built* packages ready for + use, give your expression to the `nix-shell -p` convenience flag + instead. + + - `-I` *path* + Add a path to the Nix expression search path. This option may be + given multiple times. See the `NIX_PATH` environment variable for + information on the semantics of the Nix search path. Paths added + through `-I` take precedence over `NIX_PATH`. + + - `--option` *name* *value* + Set the Nix configuration option *name* to *value*. This overrides + settings in the Nix configuration file (see nix.conf5). + + - `--repair` + Fix corrupted or missing store paths by redownloading or rebuilding + them. Note that this is slow because it requires computing a + cryptographic hash of the contents of every path in the closure of + the build. Also note the warning under `nix-store --repair-path`. diff --git a/doc/manual/src/command-ref/opt-inst-syn.md b/doc/manual/src/command-ref/opt-inst-syn.md new file mode 100644 index 000000000..1703c40e3 --- /dev/null +++ b/doc/manual/src/command-ref/opt-inst-syn.md @@ -0,0 +1,15 @@ +\--prebuilt-only + +\-b + +\--attr + +\-A + +\--from-expression + +\-E + +\--from-profile + +path diff --git a/doc/manual/src/command-ref/utilities.md b/doc/manual/src/command-ref/utilities.md new file mode 100644 index 000000000..5ba8a02a3 --- /dev/null +++ b/doc/manual/src/command-ref/utilities.md @@ -0,0 +1,3 @@ +# Utilities + +This section lists utilities that you can use when you work with Nix. diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md new file mode 100644 index 000000000..bfee28acf --- /dev/null +++ b/doc/manual/src/expressions/advanced-attributes.md @@ -0,0 +1,235 @@ +# Advanced Attributes + +Derivations can declare some infrequently used optional attributes. + + - `allowedReferences` + The optional attribute `allowedReferences` specifies a list of legal + references (dependencies) of the output of the builder. For example, + + allowedReferences = []; + + enforces that the output of a derivation cannot have any runtime + dependencies on its inputs. To allow an output to have a runtime + dependency on itself, use `"out"` as a list item. This is used in + NixOS to check that generated files such as initial ramdisks for + booting Linux don’t have accidental dependencies on other paths in + the Nix store. + + - `allowedRequisites` + This attribute is similar to `allowedReferences`, but it specifies + the legal requisites of the whole closure, so all the dependencies + recursively. For example, + + allowedRequisites = [ foobar ]; + + enforces that the output of a derivation cannot have any other + runtime dependency than `foobar`, and in addition it enforces that + `foobar` itself doesn't introduce any other dependency itself. + + - `disallowedReferences` + The optional attribute `disallowedReferences` specifies a list of + illegal references (dependencies) of the output of the builder. For + example, + + disallowedReferences = [ foo ]; + + enforces that the output of a derivation cannot have a direct + runtime dependencies on the derivation `foo`. + + - `disallowedRequisites` + This attribute is similar to `disallowedReferences`, but it + specifies illegal requisites for the whole closure, so all the + dependencies recursively. For example, + + disallowedRequisites = [ foobar ]; + + enforces that the output of a derivation cannot have any runtime + dependency on `foobar` or any other derivation depending recursively + on `foobar`. + + - `exportReferencesGraph` + This attribute allows builders access to the references graph of + their inputs. The attribute is a list of inputs in the Nix store + whose references graph the builder needs to know. The value of this + attribute should be a list of pairs `[ name1 + path1 name2 + path2 ... + ]`. The references graph of each *pathN* will be stored in a text + file *nameN* in the temporary build directory. The text files have + the format used by `nix-store + --register-validity` (with the deriver fields left empty). For + example, when the following derivation is built: + + derivation { + ... + exportReferencesGraph = [ "libfoo-graph" libfoo ]; + }; + + the references graph of `libfoo` is placed in the file + `libfoo-graph` in the temporary build directory. + + `exportReferencesGraph` is useful for builders that want to do + something with the closure of a store path. Examples include the + builders in NixOS that generate the initial ramdisk for booting + Linux (a `cpio` archive containing the closure of the boot script) + and the ISO-9660 image for the installation CD (which is populated + with a Nix store containing the closure of a bootable NixOS + configuration). + + - `impureEnvVars` + This attribute allows you to specify a list of environment variables + that should be passed from the environment of the calling user to + the builder. Usually, the environment is cleared completely when the + builder is executed, but with this attribute you can allow specific + environment variables to be passed unmodified. For example, + `fetchurl` in Nixpkgs has the line + + impureEnvVars = [ "http_proxy" "https_proxy" ... ]; + + to make it use the proxy server configuration specified by the user + in the environment variables `http_proxy` and friends. + + This attribute is only allowed in *fixed-output derivations* (see + below), where impurities such as these are okay since (the hash + of) the output is known in advance. It is ignored for all other + derivations. + + > **Warning** + > + > `impureEnvVars` implementation takes environment variables from + > the current builder process. When a daemon is building its + > environmental variables are used. Without the daemon, the + > environmental variables come from the environment of the + > `nix-build`. + + - `outputHash`; `outputHashAlgo`; `outputHashMode` + These attributes declare that the derivation is a so-called + *fixed-output derivation*, which means that a cryptographic hash of + the output is already known in advance. When the build of a + fixed-output derivation finishes, Nix computes the cryptographic + hash of the output and compares it to the hash declared with these + attributes. If there is a mismatch, the build fails. + + The rationale for fixed-output derivations is derivations such as + those produced by the `fetchurl` function. This function downloads a + file from a given URL. To ensure that the downloaded file has not + been modified, the caller must also specify a cryptographic hash of + the file. For example, + + fetchurl { + url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz"; + sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; + } + + It sometimes happens that the URL of the file changes, e.g., because + servers are reorganised or no longer available. We then must update + the call to `fetchurl`, e.g., + + fetchurl { + url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; + sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; + } + + If a `fetchurl` derivation was treated like a normal derivation, the + output paths of the derivation and *all derivations depending on it* + would change. For instance, if we were to change the URL of the + Glibc source distribution in Nixpkgs (a package on which almost all + other packages depend) massive rebuilds would be needed. This is + unfortunate for a change which we know cannot have a real effect as + it propagates upwards through the dependency graph. + + For fixed-output derivations, on the other hand, the name of the + output path only depends on the `outputHash*` and `name` attributes, + while all other attributes are ignored for the purpose of computing + the output path. (The `name` attribute is included because it is + part of the path.) + + As an example, here is the (simplified) Nix expression for + `fetchurl`: + + { stdenv, curl }: # The curl program is used for downloading. + + { url, sha256 }: + + stdenv.mkDerivation { + name = baseNameOf (toString url); + builder = ./builder.sh; + buildInputs = [ curl ]; + + # This is a fixed-output derivation; the output must be a regular + # file with SHA256 hash sha256. + outputHashMode = "flat"; + outputHashAlgo = "sha256"; + outputHash = sha256; + + inherit url; + } + + The `outputHashAlgo` attribute specifies the hash algorithm used to + compute the hash. It can currently be `"sha1"`, `"sha256"` or + `"sha512"`. + + The `outputHashMode` attribute determines how the hash is computed. + It must be one of the following two values: + + - `"flat"` + The output must be a non-executable regular file. If it isn’t, + the build fails. The hash is simply computed over the contents + of that file (so it’s equal to what Unix commands like + `sha256sum` or `sha1sum` produce). + + This is the default. + + - `"recursive"` + The hash is computed over the NAR archive dump of the output + (i.e., the result of [`nix-store + --dump`](../command-ref/nix-store.md#operation---dump)). In + this case, the output can be anything, including a directory + tree. + + The `outputHash` attribute, finally, must be a string containing + the hash in either hexadecimal or base-32 notation. (See the + [`nix-hash` command](../command-ref/nix-hash.md) for information + about converting to and from base-32 notation.) + + - `passAsFile` + A list of names of attributes that should be passed via files rather + than environment variables. For example, if you have + + ``` + passAsFile = ["big"]; + big = "a very long string"; + + ``` + + then when the builder runs, the environment variable `bigPath` will + contain the absolute path to a temporary file containing `a very + long + string`. That is, for any attribute *x* listed in `passAsFile`, Nix + will pass an environment variable `xPath` holding the path of the + file containing the value of attribute *x*. This is useful when you + need to pass large strings to a builder, since most operating + systems impose a limit on the size of the environment (typically, a + few hundred kilobyte). + + - `preferLocalBuild` + If this attribute is set to `true` and [distributed building is + enabled](../advanced-topics/distributed-builds.md), then, if + possible, the derivaton will be built locally instead of forwarded + to a remote machine. This is appropriate for trivial builders + where the cost of doing a download or remote build would exceed + the cost of building locally. + + - `allowSubstitutes` + If this attribute is set to `false`, then Nix will always build this + derivation; it will not try to substitute its outputs. This is + useful for very trivial derivations (such as `writeText` in Nixpkgs) + that are cheaper to build than to substitute from a binary cache. + + > **Note** + > + > You need to have a builder configured which satisfies the + > derivation’s `system` attribute, since the derivation cannot be + > substituted. Thus it is usually a good idea to align `system` with + > `builtins.currentSystem` when setting `allowSubstitutes` to + > `false`. For most trivial derivations this should be the case. diff --git a/doc/manual/src/expressions/arguments-variables.md b/doc/manual/src/expressions/arguments-variables.md new file mode 100644 index 000000000..2956f98f1 --- /dev/null +++ b/doc/manual/src/expressions/arguments-variables.md @@ -0,0 +1,74 @@ +# Arguments and Variables + +The [Nix expression for GNU Hello](expression-syntax.md) is a +function; it is missing some arguments that have to be filled in +somewhere. In the Nix Packages collection this is done in the file +`pkgs/top-level/all-packages.nix`, where all Nix expressions for +packages are imported and called with the appropriate arguments. Here +are some fragments of `all-packages.nix`, with annotations of what +they mean: + + ... + + rec { ① + + hello = import ../applications/misc/hello/ex-1 ② { ③ + inherit fetchurl stdenv perl; + }; + + perl = import ../development/interpreters/perl { ④ + inherit fetchurl stdenv; + }; + + fetchurl = import ../build-support/fetchurl { + inherit stdenv; ... + }; + + stdenv = ...; + + } + +1. This file defines a set of attributes, all of which are concrete + derivations (i.e., not functions). In fact, we define a *mutually + recursive* set of attributes. That is, the attributes can refer to + each other. This is precisely what we want since we want to “plug” + the various packages into each other. + +2. Here we *import* the Nix expression for GNU Hello. The import + operation just loads and returns the specified Nix expression. In + fact, we could just have put the contents of the Nix expression + for GNU Hello in `all-packages.nix` at this point. That would be + completely equivalent, but it would make `all-packages.nix` rather + bulky. + + Note that we refer to `../applications/misc/hello/ex-1`, not + `../applications/misc/hello/ex-1/default.nix`. When you try to + import a directory, Nix automatically appends `/default.nix` to the + file name. + +3. This is where the actual composition takes place. Here we *call* the + function imported from `../applications/misc/hello/ex-1` with a set + containing the things that the function expects, namely `fetchurl`, + `stdenv`, and `perl`. We use inherit again to use the attributes + defined in the surrounding scope (we could also have written + `fetchurl = fetchurl;`, etc.). + + The result of this function call is an actual derivation that can be + built by Nix (since when we fill in the arguments of the function, + what we get is its body, which is the call to `stdenv.mkDerivation` + in the [Nix expression for GNU Hello](expression-syntax.md)). + + > **Note** + > + > Nixpkgs has a convenience function `callPackage` that imports and + > calls a function, filling in any missing arguments by passing the + > corresponding attribute from the Nixpkgs set, like this: + > + > hello = callPackage ../applications/misc/hello/ex-1 { }; + > + > If necessary, you can set or override arguments: + > + > hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; }; + +4. Likewise, we have to instantiate Perl, `fetchurl`, and the standard + environment. diff --git a/doc/manual/src/expressions/build-script.md b/doc/manual/src/expressions/build-script.md new file mode 100644 index 000000000..e0dda56f8 --- /dev/null +++ b/doc/manual/src/expressions/build-script.md @@ -0,0 +1,68 @@ +# Build Script + +Here is the builder referenced from Hello's Nix expression (stored in +`pkgs/applications/misc/hello/ex-1/builder.sh`): + + source $stdenv/setup ① + + PATH=$perl/bin:$PATH ② + + tar xvfz $src ③ + cd hello-* + ./configure --prefix=$out ④ + make ⑤ + make install + +The builder can actually be made a lot shorter by using the *generic +builder* functions provided by `stdenv`, but here we write out the build +steps to elucidate what a builder does. It performs the following steps: + +1. When Nix runs a builder, it initially completely clears the + environment (except for the attributes declared in the derivation). + This is done to prevent undeclared inputs from being used in the + build process. If for example the `PATH` contained `/usr/bin`, then + you might accidentally use `/usr/bin/gcc`. + + So the first step is to set up the environment. This is done by + calling the `setup` script of the standard environment. The + environment variable `stdenv` points to the location of the + standard environment being used. (It wasn't specified explicitly + as an attribute in Hello's Nix expression, but `mkDerivation` adds + it automatically.) + +2. Since Hello needs Perl, we have to make sure that Perl is in the + `PATH`. The `perl` environment variable points to the location of + the Perl package (since it was passed in as an attribute to the + derivation), so `$perl/bin` is the directory containing the Perl + interpreter. + +3. Now we have to unpack the sources. The `src` attribute was bound to + the result of fetching the Hello source tarball from the network, so + the `src` environment variable points to the location in the Nix + store to which the tarball was downloaded. After unpacking, we `cd` + to the resulting source directory. + + The whole build is performed in a temporary directory created in + `/tmp`, by the way. This directory is removed after the builder + finishes, so there is no need to clean up the sources afterwards. + Also, the temporary directory is always newly created, so you don't + have to worry about files from previous builds interfering with the + current build. + +4. GNU Hello is a typical Autoconf-based package, so we first have to + run its `configure` script. In Nix every package is stored in a + separate location in the Nix store, for instance + `/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix + computes this path by cryptographically hashing all attributes of + the derivation. The path is passed to the builder through the `out` + environment variable. So here we give `configure` the parameter + `--prefix=$out` to cause Hello to be installed in the expected + location. + +5. Finally we build Hello (`make`) and install it into the location + specified by `out` (`make install`). + +If you are wondering about the absence of error checking on the result +of various commands called in the builder: this is because the shell +script is evaluated with Bash's `-e` option, which causes the script to +be aborted if any command fails without an error check. diff --git a/doc/manual/src/expressions/builtins.md b/doc/manual/src/expressions/builtins.md new file mode 100644 index 000000000..22f133c33 --- /dev/null +++ b/doc/manual/src/expressions/builtins.md @@ -0,0 +1,845 @@ +# Built-in Functions + +This section lists the functions and constants built into the Nix +expression evaluator. (The built-in function `derivation` is discussed +above.) Some built-ins, such as `derivation`, 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 `builtins` built-in +value, which is a set that contains all built-in functions and values. +For instance, `derivation` is also available as `builtins.derivation`. + + - `abort` *s*; `builtins.abort` *s* + Abort Nix expression evaluation, print error message *s*. + + - `builtins.add` *e1* *e2* + Return the sum of the numbers *e1* and *e2*. + + - `builtins.all` *pred* *list* + Return `true` if the function *pred* returns `true` for all elements + of *list*, and `false` otherwise. + + - `builtins.any` *pred* *list* + Return `true` if the function *pred* returns `true` for at least one + element of *list*, and `false` otherwise. + + - `builtins.attrNames` *set* + Return the names of the attributes in the set *set* in an + alphabetically sorted list. For instance, `builtins.attrNames { y + = 1; x = "foo"; }` evaluates to `[ "x" "y" ]`. + + - `builtins.attrValues` *set* + Return the values of the attributes in the set *set* in the order + corresponding to the sorted attribute names. + + - `baseNameOf` *s* + Return the *base name* of the string *s*, that is, everything + following the final slash in the string. This is similar to the GNU + `basename` command. + + - `builtins.bitAnd` *e1* *e2* + Return the bitwise AND of the integers *e1* and *e2*. + + - `builtins.bitOr` *e1* *e2* + Return the bitwise OR of the integers *e1* and *e2*. + + - `builtins.bitXor` *e1* *e2* + Return the bitwise XOR of the integers *e1* and *e2*. + + - `builtins` + The set `builtins` contains all the built-in functions and values. + You can use `builtins` to test for the availability of features in + the Nix installation, e.g., + + if builtins ? getEnv then builtins.getEnv "PATH" else "" + + This allows a Nix expression to fall back gracefully on older Nix + installations that don’t have the desired built-in function. + + - `builtins.compareVersions` *s1* *s2* + Compare two strings representing versions and return `-1` if + version *s1* is older than version *s2*, `0` if they are the same, + and `1` if *s1* is newer than *s2*. The version comparison + algorithm is the same as the one used by [`nix-env + -u`](../command-ref/nix-env.md#operation---upgrade). + + - `builtins.concatLists` *lists* + Concatenate a list of lists into a single list. + + - `builtins.concatStringsSep` *separator* *list* + Concatenate a list of strings with a separator between each + element, e.g. `concatStringsSep "/" ["usr" "local" "bin"] == + "usr/local/bin"` + + - `builtins.currentSystem` + The built-in value `currentSystem` evaluates to the Nix platform + identifier for the Nix installation on which the expression is being + evaluated, such as `"i686-linux"` or `"x86_64-darwin"`. + + - `builtins.deepSeq` *e1* *e2* + This is like `seq e1 e2`, except that *e1* is evaluated *deeply*: + if it’s a list or set, its elements or attributes are also + evaluated recursively. + + - `derivation` *attrs*; `builtins.derivation` *attrs* + `derivation` is described in [its own section](derivations.md). + + - `dirOf` *s*; `builtins.dirOf` *s* + Return the directory part of the string *s*, that is, everything + before the final slash in the string. This is similar to the GNU + `dirname` command. + + - `builtins.div` *e1* *e2* + Return the quotient of the numbers *e1* and *e2*. + + - `builtins.elem` *x* *xs* + Return `true` if a value equal to *x* occurs in the list *xs*, and + `false` otherwise. + + - `builtins.elemAt` *xs* *n* + Return element *n* from the list *xs*. Elements are counted starting + from 0. A fatal error occurs if the index is out of bounds. + + - `builtins.fetchurl` *url* + Download the specified URL and return the path of the downloaded + file. This function is not available if [restricted evaluation + mode](../command-ref/conf-file.md) is enabled. + + - `fetchTarball` *url*; `builtins.fetchTarball` *url* + Download the specified URL, unpack it and return the path of the + unpacked tree. The file must be a tape archive (`.tar`) compressed + with `gzip`, `bzip2` or `xz`. 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. + + with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz) {}; + + stdenv.mkDerivation { … } + + The fetched tarball is cached for a certain amount of time (1 hour + by default) in `~/.cache/nix/tarballs/`. You can change the cache + timeout either on the command line with `--option tarball-ttl number + of seconds` or in the Nix configuration file with this option: ` + number of seconds to cache `. + + Note that when obtaining the hash with ` nix-prefetch-url + ` the option `--unpack` is required. + + This function can also verify the contents against a hash. In that + case, the function takes a set instead of a URL. The set requires + the attribute `url` and the attribute `sha256`, e.g. + + with import (fetchTarball { + url = "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz"; + sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2"; + }) {}; + + stdenv.mkDerivation { … } + + This function is not available if [restricted evaluation + mode](../command-ref/conf-file.md) is enabled. + + - `builtins.fetchGit` *args* + Fetch a path from git. *args* 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 `url` optional): + + - url + The URL of the repo. + + - name + The name of the directory the repo should be exported to in the + store. Defaults to the basename of the URL. + + - rev + The git revision to fetch. Defaults to the tip of `ref`. + + - ref + The git ref to look for the requested revision under. This is + often a branch or tag name. Defaults to `HEAD`. + + By default, the `ref` value is prefixed with `refs/heads/`. As + of Nix 2.3.0 Nix will not prefix `refs/heads/` if `ref` starts + with `refs/`. + + - submodules + A Boolean parameter that specifies whether submodules should be + checked out. Defaults to `false`. + + Here are some examples of how to use `fetchGit`. + + - To fetch a private repository over SSH: + + builtins.fetchGit { + url = "git@github.com:my-secret/repository.git"; + ref = "master"; + rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; + } + + - To fetch an arbitrary reference: + + builtins.fetchGit { + url = "https://github.com/NixOS/nix.git"; + ref = "refs/heads/0.5-release"; + } + + - 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 `ref` attribute. + + 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 `ref` attribute as well. + + builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; + ref = "1.11-maintenance"; + } + + > **Note** + > + > 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. + + - If the revision you're looking for is in the default branch of + the git repository you may omit the `ref` attribute. + + builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; + } + + - To fetch a specific tag: + + builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + ref = "refs/tags/1.9"; + } + + - To fetch the latest version of a remote branch: + + builtins.fetchGit { + url = "ssh://git@github.com/nixos/nix.git"; + ref = "master"; + } + + > **Note** + > + > Nix will refetch the branch in accordance with + > the option `tarball-ttl`. + + > **Note** + > + > This behavior is disabled in *Pure evaluation mode*. + + - `builtins.filter` *f* *xs* + Return a list consisting of the elements of *xs* for which the + function *f* returns `true`. + + - `builtins.filterSource` *e1* *e2* + 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 `source-dir` as an input to a Nix expression, e.g. + + stdenv.mkDerivation { + ... + src = ./source-dir; + } + + However, if `source-dir` is a Subversion working copy, then all + those annoying `.svn` subdirectories will also be copied to the + store. Worse, the contents of those directories may change a lot, + causing lots of spurious rebuilds. With `filterSource` you can + filter out the `.svn` directories: + + ``` + src = builtins.filterSource + (path: type: type != "directory" || baseNameOf path != ".svn") + ./source-dir; + ``` + + Thus, the first argument *e1* must be a predicate function that is + called for each regular file, directory or symlink in the source + tree *e2*. If the function returns `true`, 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 + `"regular"`, `"directory"`, `"symlink"` or `"unknown"` (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 + `true` for them, the copy will fail). If you exclude a directory, + the entire corresponding subtree of *e2* will be excluded. + + - `builtins.foldl’` *op* *nul* *list* + Reduce a list by applying a binary operator, from left to right, + e.g. `foldl’ op nul [x0 x1 x2 ...] = op (op + (op nul x0) x1) x2) ...`. The operator is applied strictly, i.e., + its arguments are evaluated first. For example, `foldl’ (x: y: x + + y) 0 [1 2 3]` evaluates to 6. + + - `builtins.functionArgs` *f* + Return a set containing the names of the formal arguments expected + by the function *f*. The value of each attribute is a Boolean + denoting whether the corresponding argument has a default value. For + instance, `functionArgs ({ x, y ? 123}: ...) = { x = false; y = + true; }`. + + "Formal argument" here refers to the attributes pattern-matched by + the function. Plain lambdas are not included, e.g. `functionArgs (x: + ...) = { }`. + + - `builtins.fromJSON` *e* + Convert a JSON string to a Nix value. For example, + + builtins.fromJSON ''{"x": [1, 2, 3], "y": null}'' + + returns the value `{ x = [ 1 2 3 ]; y = null; + }`. + + - `builtins.genList` *generator* *length* + Generate list of size *length*, with each element *i* equal to the + value returned by *generator* `i`. For example, + + builtins.genList (x: x * x) 5 + + returns the list `[ 0 1 4 9 16 ]`. + + - `builtins.getAttr` *s* *set* + `getAttr` returns the attribute named *s* from *set*. Evaluation + aborts if the attribute doesn’t exist. This is a dynamic version of + the `.` operator, since *s* is an expression rather than an + identifier. + + - `builtins.getEnv` *s* + `getEnv` returns the value of the environment variable *s*, 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. + + `getEnv` is used in Nix Packages to locate the file + `~/.nixpkgs/config.nix`, which contains user-local settings for Nix + Packages. (That is, it does a `getEnv "HOME"` to locate the user’s + home directory.) + + - `builtins.hasAttr` *s* *set* + `hasAttr` returns `true` if *set* has an attribute named *s*, and + `false` otherwise. This is a dynamic version of the `?` operator, + since *s* is an expression rather than an identifier. + + - `builtins.hashString` *type* *s* + Return a base-16 representation of the cryptographic hash of string + *s*. The hash algorithm specified by *type* must be one of `"md5"`, + `"sha1"`, `"sha256"` or `"sha512"`. + + - `builtins.hashFile` *type* *p* + Return a base-16 representation of the cryptographic hash of the + file at path *p*. The hash algorithm specified by *type* must be one + of `"md5"`, `"sha1"`, `"sha256"` or `"sha512"`. + + - `builtins.head` *list* + 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 `[]`. + + - `import` *path*; `builtins.import` *path* + Load, parse and return the Nix expression in the file *path*. If + *path* is a directory, the file ` default.nix ` in that directory + is loaded. Evaluation aborts if the file doesn’t exist or contains + an incorrect Nix expression. `import` 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. + + > **Note** + > + > Unlike some languages, `import` is a regular function in Nix. + > Paths using the angle bracket syntax (e.g., `import` *\<foo\>*) + > are [normal path values](language-values.md). + + A Nix expression loaded by `import` must not contain any *free + variables* (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 + + rec { + x = 123; + y = import ./foo.nix; + } + + then the following `foo.nix` will give an error: + + x + 456 + + since `x` is not in scope in `foo.nix`. If you want `x` to be + available in `foo.nix`, you should pass it as a function argument: + + rec { + x = 123; + y = import ./foo.nix x; + } + + and + + x: x + 456 + + (The function argument doesn’t have to be called `x` in `foo.nix`; + any name would work.) + + - `builtins.intersectAttrs` *e1* *e2* + Return a set consisting of the attributes in the set *e2* that also + exist in the set *e1*. + + - `builtins.isAttrs` *e* + Return `true` if *e* evaluates to a set, and `false` otherwise. + + - `builtins.isList` *e* + Return `true` if *e* evaluates to a list, and `false` otherwise. + + - `builtins.isFunction` *e* + Return `true` if *e* evaluates to a function, and `false` otherwise. + + - `builtins.isString` *e* + Return `true` if *e* evaluates to a string, and `false` otherwise. + + - `builtins.isInt` *e* + Return `true` if *e* evaluates to an int, and `false` otherwise. + + - `builtins.isFloat` *e* + Return `true` if *e* evaluates to a float, and `false` otherwise. + + - `builtins.isBool` *e* + Return `true` if *e* evaluates to a bool, and `false` otherwise. + + - `builtins.isPath` *e* + Return `true` if *e* evaluates to a path, and `false` otherwise. + + - `isNull` *e*; `builtins.isNull` *e* + Return `true` if *e* evaluates to `null`, and `false` otherwise. + + > **Warning** + > + > This function is *deprecated*; just write `e == null` instead. + + - `builtins.length` *e* + Return the length of the list *e*. + + - `builtins.lessThan` *e1* *e2* + Return `true` if the number *e1* is less than the number *e2*, and + `false` otherwise. Evaluation aborts if either *e1* or *e2* does not + evaluate to a number. + + - `builtins.listToAttrs` *e* + 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 `name` specifying the name of the attribute, + and an attribute `value` specifying its value. Example: + + builtins.listToAttrs + [ { name = "foo"; value = 123; } + { name = "bar"; value = 456; } + ] + + evaluates to + + { foo = 123; bar = 456; } + + - `map` *f* *list*; `builtins.map` *f* *list* + Apply the function *f* to each element in the list *list*. For + example, + + map (x: "foo" + x) [ "bar" "bla" "abc" ] + + evaluates to `[ "foobar" "foobla" "fooabc" + ]`. + + - `builtins.match` *regex* *str* + Returns a list if the [extended POSIX regular + expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04) + *regex* matches *str* precisely, otherwise returns `null`. Each item + in the list is a regex group. + + builtins.match "ab" "abc" + + Evaluates to `null`. + + builtins.match "abc" "abc" + + Evaluates to `[ ]`. + + builtins.match "a(b)(c)" "abc" + + Evaluates to `[ "b" "c" ]`. + + builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO " + + Evaluates to `[ "foo" ]`. + + - `builtins.mul` *e1* *e2* + Return the product of the numbers *e1* and *e2*. + + - `builtins.parseDrvName` *s* + Split the string *s* into a package name and version. The package + name is everything up to but not including the first dash followed + by a digit, and the version is everything following that dash. The + result is returned in a set `{ name, version }`. Thus, + `builtins.parseDrvName "nix-0.12pre12876"` returns `{ name = + "nix"; version = "0.12pre12876"; }`. + + - `builtins.path` *args* + An enrichment of the built-in path type, based on the attributes + present in *args*. All are optional except `path`: + + - path + The underlying path. + + - name + 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 `@`. + + - filter + A function of the type expected by `builtins.filterSource`, + with the same semantics. + + - recursive + When `false`, when `path` is added to the store it is with a + flat hash, rather than a hash of the NAR serialization of the + file. Thus, `path` must refer to a regular file, not a + directory. This allows similar behavior to `fetchurl`. Defaults + to `true`. + + - sha256 + 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 `builtins.path` to be used even when the + `pure-eval` nix config option is on. + + - `builtins.pathExists` *path* + Return `true` if the path *path* exists at evaluation time, and + `false` otherwise. + + - `builtins.placeholder` *output* + Return a placeholder string for the specified *output* that will be + substituted by the corresponding output path at build time. Typical + outputs would be `"out"`, `"bin"` or `"dev"`. + + - `builtins.readDir` *path* + Return the contents of the directory *path* as a set mapping + directory entries to the corresponding file type. For instance, if + directory `A` contains a regular file `B` and another directory `C`, + then `builtins.readDir + ./A` will return the set + + { B = "regular"; C = "directory"; } + + The possible values for the file type are `"regular"`, + `"directory"`, `"symlink"` and `"unknown"`. + + - `builtins.readFile` *path* + Return the contents of the file *path* as a string. + + - `removeAttrs` *set* *list*; `builtins.removeAttrs` *set* *list* + Remove the attributes listed in *list* from *set*. The attributes + don’t have to exist in *set*. For instance, + + removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ] + + evaluates to `{ y = 2; }`. + + - `builtins.replaceStrings` *from* *to* *s* + Given string *s*, replace every occurrence of the strings in *from* + with the corresponding string in *to*. For example, + + builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar" + + evaluates to `"fabir"`. + + - `builtins.seq` *e1* *e2* + Evaluate *e1*, then evaluate and return *e2*. This ensures that a + computation is strict in the value of *e1*. + + - `builtins.sort` *comparator* *list* + Return *list* in sorted order. It repeatedly calls the function + *comparator* with two elements. The comparator should return `true` + if the first element is less than the second, and `false` otherwise. + For example, + + builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ] + + produces the list `[ 42 77 147 249 483 526 + ]`. + + This is a stable sort: it preserves the relative order of elements + deemed equal by the comparator. + + - `builtins.split` *regex* *str* + Returns a list composed of non matched strings interleaved with the + lists of the [extended POSIX regular + expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04) + *regex* matches of *str*. Each item in the lists of matched + sequences is a regex group. + + builtins.split "(a)b" "abc" + + Evaluates to `[ "" [ "a" ] "c" ]`. + + builtins.split "([ac])" "abc" + + Evaluates to `[ "" [ "a" ] "b" [ "c" ] "" ]`. + + builtins.split "(a)|(c)" "abc" + + Evaluates to `[ "" [ "a" null ] "b" [ null "c" ] "" ]`. + + builtins.split "([[:upper:]]+)" " FOO " + + Evaluates to `[ " " [ "FOO" ] " " ]`. + + - `builtins.splitVersion` *s* + Split a string representing a version into its components, by the + same version splitting logic underlying the version comparison in + [`nix-env -u`](../command-ref/nix-env.md#operation---upgrade). + + - `builtins.stringLength` *e* + Return the length of the string *e*. If *e* is not a string, + evaluation is aborted. + + - `builtins.sub` *e1* *e2* + Return the difference between the numbers *e1* and *e2*. + + - `builtins.substring` *start* *len* *s* + Return the substring of *s* from character position *start* + (zero-based) up to but not including *start + len*. If *start* is + greater than the length of the string, an empty string is returned, + and if *start + len* lies beyond the end of the string, only the + substring up to the end of the string is returned. *start* must be + non-negative. For example, + + builtins.substring 0 3 "nixos" + + evaluates to `"nix"`. + + - `builtins.tail` *list* + Return the second to last elements of a list; abort evaluation if + the argument isn’t a list or is an empty list. + + - `throw` *s*; `builtins.throw` *s* + Throw an error message *s*. This usually aborts Nix expression + evaluation, but in `nix-env -qa` 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 `abort`). + + - `builtins.toFile` *name* *s* + Store the string *s* in a file in the Nix store and return its + path. The file has suffix *name*. This file can be used as an + input to derivations. One application is to write builders + “inline”. For instance, the following Nix expression combines the + [Nix expression for GNU Hello](expression-syntax.md) and its + [build script](build-script.md) into one file: + + { stdenv, fetchurl, perl }: + + stdenv.mkDerivation { + name = "hello-2.1.1"; + + builder = builtins.toFile "builder.sh" " + source $stdenv/setup + + PATH=$perl/bin:$PATH + + tar xvfz $src + cd hello-* + ./configure --prefix=$out + make + make install + "; + + src = fetchurl { + url = "http://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; + sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; + }; + inherit perl; + } + + It is even possible for one file to refer to another, e.g., + + ``` + builder = let + configFile = builtins.toFile "foo.conf" " + # This is some dummy configuration file. + ... + "; + in builtins.toFile "builder.sh" " + source $stdenv/setup + ... + cp ${configFile} $out/etc/foo.conf + "; + ``` + + Note that `${configFile}` is an + [antiquotation](language-values.md), so the result of the + expression `configFile` + (i.e., a path like `/nix/store/m7p7jfny445k...-foo.conf`) will be + spliced into the resulting string. + + It is however *not* allowed to have files mutually referring to each + other, like so: + + let + foo = builtins.toFile "foo" "...${bar}..."; + bar = builtins.toFile "bar" "...${foo}..."; + in foo + + This is not allowed because it would cause a cyclic dependency in + the computation of the cryptographic hashes for `foo` and `bar`. + + It is also not possible to reference the result of a derivation. If + you are using Nixpkgs, the `writeTextFile` function is able to do + that. + + - `builtins.toJSON` *e* + Return a string containing a JSON representation of *e*. Strings, + integers, floats, booleans, nulls and lists are mapped to their JSON + equivalents. Sets (except derivations) are represented as objects. + Derivations are translated to a JSON string containing the + derivation’s output path. Paths are copied to the store and + represented as a JSON string of the resulting store path. + + - `builtins.toPath` *s* + DEPRECATED. Use `/. + "/path"` to convert a string into an absolute + path. For relative paths, use `./. + "/path"`. + + - `toString` *e*; `builtins.toString` *e* + Convert the expression *e* to a string. *e* can be: + + - A string (in which case the string is returned unmodified). + + - A path (e.g., `toString /foo/bar` yields `"/foo/bar"`. + + - A set containing `{ __toString = self: ...; }`. + + - An integer. + + - A list, in which case the string representations of its elements + are joined with spaces. + + - A Boolean (`false` yields `""`, `true` yields `"1"`). + + - `null`, which yields the empty string. + + - `builtins.toXML` *e* + Return a string containing an XML representation of *e*. The main + application for `toXML` is to communicate information with the + builder in a more structured format than plain environment + variables. + + Here is an example where this is the case: + + { stdenv, fetchurl, libxslt, jira, uberwiki }: + + stdenv.mkDerivation (rec { + name = "web-server"; + + buildInputs = [ libxslt ]; + + builder = builtins.toFile "builder.sh" " + source $stdenv/setup + mkdir $out + echo "$servlets" | xsltproc ${stylesheet} - > $out/server-conf.xml ① + "; + + stylesheet = builtins.toFile "stylesheet.xsl" ② + "<?xml version='1.0' encoding='UTF-8'?> + <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'> + <xsl:template match='/'> + <Configure> + <xsl:for-each select='/expr/list/attrs'> + <Call name='addWebApplication'> + <Arg><xsl:value-of select=\"attr[@name = 'path']/string/@value\" /></Arg> + <Arg><xsl:value-of select=\"attr[@name = 'war']/path/@value\" /></Arg> + </Call> + </xsl:for-each> + </Configure> + </xsl:template> + </xsl:stylesheet> + "; + + servlets = builtins.toXML [ ③ + { path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; } + { path = "/wiki"; war = uberwiki + "/uberwiki.war"; } + ]; + }) + + The builder is supposed to generate the configuration file for a + [Jetty servlet container](http://jetty.mortbay.org/). A servlet + container contains a number of servlets (`*.war` files) each + exported under a specific URI prefix. So the servlet configuration + is a list of sets containing the `path` and `war` of the servlet + (①). This kind of information is difficult to communicate with the + normal method of passing information through an environment + variable, which just concatenates everything together into a + string (which might just work in this case, but wouldn’t work if + fields are optional or contain lists themselves). Instead the Nix + expression is converted to an XML representation with `toXML`, + which is unambiguous and can easily be processed with the + appropriate tools. For instance, in the example an XSLT stylesheet + (at point ②) is applied to it (at point ①) to generate the XML + configuration file for the Jetty server. The XML representation + produced at point ③ by `toXML` is as follows: + + <?xml version='1.0' encoding='utf-8'?> + <expr> + <list> + <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> + + Note that we used the `toFile` built-in to write the builder and + the stylesheet “inline” in the Nix expression. The path of the + stylesheet is spliced into the builder using the syntax `xsltproc + ${stylesheet}`. + + - `builtins.trace` *e1* *e2* + Evaluate *e1* and print its abstract syntax representation on + standard error. Then return *e2*. This function is useful for + debugging. + + - `builtins.tryEval` *e* + Try to shallowly evaluate *e*. Return a set containing the + attributes `success` (`true` if *e* evaluated successfully, `false` + if an error was thrown) and `value`, equalling *e* if successful and + `false` otherwise. Note that this doesn't evaluate *e* deeply, so + ` let e = { x = throw ""; }; in (builtins.tryEval e).success + ` will be `true`. Using ` builtins.deepSeq + ` one can get the expected result: `let e = { x = throw ""; + }; in (builtins.tryEval (builtins.deepSeq e e)).success` will be + `false`. + + - `builtins.typeOf` *e* + Return a string representing the type of the value *e*, namely + `"int"`, `"bool"`, `"string"`, `"path"`, `"null"`, `"set"`, + `"list"`, `"lambda"` or `"float"`. diff --git a/doc/manual/src/expressions/derivations.md b/doc/manual/src/expressions/derivations.md new file mode 100644 index 000000000..0e5656b5b --- /dev/null +++ b/doc/manual/src/expressions/derivations.md @@ -0,0 +1,150 @@ +# Derivations + +The most important built-in function is `derivation`, which is used to +describe a single derivation (a build action). It takes as input a set, +the attributes of which specify the inputs of the build. + + - There must be an attribute named `system` whose value must be a + string specifying a Nix system type, such as `"i686-linux"` or + `"x86_64-darwin"`. (To figure out your system type, run `nix -vv + --version`.) The build can only be performed on a machine and + operating system matching the system type. (Nix can automatically + [forward builds for other + platforms](../advanced-topics/distributed-builds.md) by forwarding + them to other machines.) + + - There must be an attribute named `name` whose value must be a + string. This is used as a symbolic name for the package by + `nix-env`, and it is appended to the output paths of the derivation. + + - There must be an attribute named `builder` that identifies the + program that is executed to perform the build. It can be either a + derivation or a source (a local file reference, e.g., + `./builder.sh`). + + - Every attribute is passed as an environment variable to the builder. + Attribute values are translated to environment variables as follows: + + - Strings and numbers are just passed verbatim. + + - A *path* (e.g., `../foo/sources.tar`) causes the referenced file + to be copied to the store; its location in the store is put in + the environment variable. The idea is that all sources should + reside in the Nix store, since all inputs to a derivation should + reside in the Nix store. + + - A *derivation* causes that derivation to be built prior to the + present derivation; its default output path is put in the + environment variable. + + - Lists of the previous types are also allowed. They are simply + concatenated, separated by spaces. + + - `true` is passed as the string `1`, `false` and `null` are + passed as an empty string. + + - The optional attribute `args` specifies command-line arguments to be + passed to the builder. It should be a list. + + - The optional attribute `outputs` specifies a list of symbolic + outputs of the derivation. By default, a derivation produces a + single output path, denoted as `out`. However, derivations can + produce multiple output paths. This is useful because it allows + outputs to be downloaded or garbage-collected separately. For + instance, imagine a library package that provides a dynamic library, + header files, and documentation. A program that links against the + library doesn’t need the header files and documentation at runtime, + and it doesn’t need the documentation at build time. Thus, the + library package could specify: + + outputs = [ "lib" "headers" "doc" ]; + + This will cause Nix to pass environment variables `lib`, `headers` + and `doc` to the builder containing the intended store paths of each + output. The builder would typically do something like + + ./configure --libdir=$lib/lib --includedir=$headers/include --docdir=$doc/share/doc + + for an Autoconf-style package. You can refer to each output of a + derivation by selecting it as an attribute, e.g. + + buildInputs = [ pkg.lib pkg.headers ]; + + The first element of `outputs` determines the *default output*. + Thus, you could also write + + buildInputs = [ pkg pkg.headers ]; + + since `pkg` is equivalent to `pkg.lib`. + +The function `mkDerivation` in the Nixpkgs standard environment is a +wrapper around `derivation` that adds a default value for `system` and +always uses Bash as the builder, to which the supplied builder is passed +as a command-line argument. See the Nixpkgs manual for details. + +The builder is executed as follows: + + - A temporary directory is created under the directory specified by + `TMPDIR` (default `/tmp`) where the build will take place. The + current directory is changed to this directory. + + - The environment is cleared and set to the derivation attributes, as + specified above. + + - In addition, the following variables are set: + + - `NIX_BUILD_TOP` contains the path of the temporary directory for + this build. + + - Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the + temporary directory. This is to prevent the builder from + accidentally writing temporary files anywhere else. Doing so + might cause interference by other processes. + + - `PATH` is set to `/path-not-set` to prevent shells from + initialising it to their built-in default value. + + - `HOME` is set to `/homeless-shelter` to prevent programs from + using `/etc/passwd` or the like to find the user's home + directory, which could cause impurity. Usually, when `HOME` is + set, it is used as the location of the home directory, even if + it points to a non-existent path. + + - `NIX_STORE` is set to the path of the top-level Nix store + directory (typically, `/nix/store`). + + - For each output declared in `outputs`, the corresponding + environment variable is set to point to the intended path in the + Nix store for that output. Each output path is a concatenation + of the cryptographic hash of all build inputs, the `name` + attribute and the output name. (The output name is omitted if + it’s `out`.) + + - If an output path already exists, it is removed. Also, locks are + acquired to prevent multiple Nix instances from performing the same + build at the same time. + + - A log of the combined standard output and error is written to + `/nix/var/log/nix`. + + - The builder is executed with the arguments specified by the + attribute `args`. If it exits with exit code 0, it is considered to + have succeeded. + + - The temporary directory is removed (unless the `-K` option was + specified). + + - If the build was successful, Nix scans each output path for + references to input paths by looking for the hash parts of the input + paths. Since these are potential runtime dependencies, Nix registers + them as dependencies of the output paths. + + - After the build, Nix sets the last-modified timestamp on all files + in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to + the default group, and sets the mode of the file to 0444 or 0555 + (i.e., read-only, with execute permission enabled if the file was + originally executable). Note that possible `setuid` and `setgid` + bits are cleared. Setuid and setgid programs are not currently + supported by Nix. This is because the Nix archives used in + deployment have no concept of ownership information, and because it + makes the build result dependent on the user performing the build. diff --git a/doc/manual/src/expressions/expression-language.md b/doc/manual/src/expressions/expression-language.md new file mode 100644 index 000000000..267fcb983 --- /dev/null +++ b/doc/manual/src/expressions/expression-language.md @@ -0,0 +1,12 @@ +# Nix Expression Language + +The Nix expression language is a pure, lazy, functional language. Purity +means that operations in the language don't have side-effects (for +instance, there is no variable assignment). Laziness means that +arguments to functions are evaluated only when they are needed. +Functional means that functions are “normal” values that can be passed +around and manipulated in interesting ways. The language is not a +full-featured, general purpose language. Its main job is to describe +packages, compositions of packages, and the variability within packages. + +This section presents the various features of the language. diff --git a/doc/manual/src/expressions/expression-syntax.md b/doc/manual/src/expressions/expression-syntax.md new file mode 100644 index 000000000..e3432b577 --- /dev/null +++ b/doc/manual/src/expressions/expression-syntax.md @@ -0,0 +1,93 @@ +# Expression Syntax + +Here is a Nix expression for GNU Hello: + + { stdenv, fetchurl, perl }: ① + + stdenv.mkDerivation { ② + name = "hello-2.1.1"; ③ + builder = ./builder.sh; ④ + src = fetchurl { ⑤ + url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; + sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; + }; + inherit perl; ⑥ + } + +This file is actually already in the Nix Packages collection in +`pkgs/applications/misc/hello/ex-1/default.nix`. It is customary to +place each package in a separate directory and call the single Nix +expression in that directory `default.nix`. The file has the following +elements (referenced from the figure by number): + +1. This states that the expression is a *function* that expects to be + called with three arguments: `stdenv`, `fetchurl`, and `perl`. They + are needed to build Hello, but we don't know how to build them here; + that's why they are function arguments. `stdenv` is a package that + is used by almost all Nix Packages packages; it provides a + “standard” environment consisting of the things you would expect + in a basic Unix environment: a C/C++ compiler (GCC, to be precise), + the Bash shell, fundamental Unix tools such as `cp`, `grep`, `tar`, + etc. `fetchurl` is a function that downloads files. `perl` is the + Perl interpreter. + + Nix functions generally have the form `{ x, y, ..., + z }: e` where `x`, `y`, etc. are the names of the expected + arguments, and where *e* is the body of the function. So here, the + entire remainder of the file is the body of the function; when given + the required arguments, the body should describe how to build an + instance of the Hello package. + +2. So we have to build a package. Building something from other stuff + is called a *derivation* in Nix (as opposed to sources, which are + built by humans instead of computers). We perform a derivation by + calling `stdenv.mkDerivation`. `mkDerivation` is a function provided + by `stdenv` that builds a package from a set of *attributes*. A set + is just a list of key/value pairs where each key is a string and + each value is an arbitrary Nix expression. They take the general + form `{ + name1 = + expr1; ... + nameN = + exprN; }`. + +3. The attribute `name` specifies the symbolic name and version of the + package. Nix doesn't really care about these things, but they are + used by for instance `nix-env + -q` to show a “human-readable” name for packages. This attribute is + required by `mkDerivation`. + +4. The attribute `builder` specifies the builder. This attribute can + sometimes be omitted, in which case `mkDerivation` will fill in a + default builder (which does a `configure; make; make install`, in + essence). Hello is sufficiently simple that the default builder + would suffice, but in this case, we will show an actual builder + for educational purposes. The value `./builder.sh` refers to the + shell script shown in the [next section](build-script.md), + discussed below. + +5. The builder has to know what the sources of the package are. Here, + the attribute `src` is bound to the result of a call to the + `fetchurl` function. Given a URL and a SHA-256 hash of the expected + contents of the file at that URL, this function builds a derivation + that downloads the file and checks its hash. So the sources are a + dependency that like all other dependencies is built before Hello + itself is built. + + Instead of `src` any other name could have been used, and in fact + there can be any number of sources (bound to different attributes). + However, `src` is customary, and it's also expected by the default + builder (which we don't use in this example). + +6. Since the derivation requires Perl, we have to pass the value of the + `perl` function argument to the builder. All attributes in the set + are actually passed as environment variables to the builder, so + declaring an attribute + + perl = perl; + + will do the trick: it binds an attribute `perl` to the function + argument which also happens to be called `perl`. However, it looks a + bit silly, so there is a shorter syntax. The `inherit` keyword + causes the specified attributes to be bound to whatever variables + with the same name happen to be in scope. diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md new file mode 100644 index 000000000..43275dbf7 --- /dev/null +++ b/doc/manual/src/expressions/generic-builder.md @@ -0,0 +1,60 @@ +# Generic Builder Syntax + +Recall that the [build script for GNU Hello](build-script.md) looked +something like this: + + PATH=$perl/bin:$PATH + tar xvfz $src + cd hello-* + ./configure --prefix=$out + make + make install + +The builders for almost all Unix packages look like this — set up some +environment variables, unpack the sources, configure, build, and +install. For this reason the standard environment provides some Bash +functions that automate the build process. Here is what a builder using +the generic build facilities looks like: + + buildInputs="$perl" ① + + source $stdenv/setup ② + + genericBuild ③ + +Here is what each line means: + +1. The `buildInputs` variable tells `setup` to use the indicated + packages as “inputs”. This means that if a package provides a `bin` + subdirectory, it's added to `PATH`; if it has a `include` + subdirectory, it's added to GCC's header search path; and so on. + (This is implemented in a modular way: `setup` tries to source the + file `pkg/nix-support/setup-hook` of all dependencies. These “setup + hooks” can then set up whatever environment variables they want; for + instance, the setup hook for Perl sets the `PERL5LIB` environment + variable to contain the `lib/site_perl` directories of all inputs.) + +2. The function `genericBuild` is defined in the file `$stdenv/setup`. + +3. The final step calls the shell function `genericBuild`, which + performs the steps that were done explicitly in the previous build + script. The generic builder is smart enough to figure out whether + to unpack the sources using `gzip`, `bzip2`, etc. It can be + customised in many ways; see the Nixpkgs manual for details. + +Discerning readers will note that the `buildInputs` could just as well +have been set in the Nix expression, like this: + +``` + buildInputs = [ perl ]; +``` + +The `perl` attribute can then be removed, and the builder becomes even +shorter: + + source $stdenv/setup + genericBuild + +In fact, `mkDerivation` provides a default builder that looks exactly +like that, so it is actually possible to omit the builder for Hello +entirely. diff --git a/doc/manual/src/expressions/language-constructs.md b/doc/manual/src/expressions/language-constructs.md new file mode 100644 index 000000000..8e267a799 --- /dev/null +++ b/doc/manual/src/expressions/language-constructs.md @@ -0,0 +1,306 @@ +# Language Constructs + +## Recursive sets + +Recursive sets are just normal sets, but the attributes can refer to +each other. For example, + + rec { + x = y; + y = 123; + }.x + +evaluates to `123`. Note that without `rec` the binding `x = y;` would +refer to the variable `y` in the surrounding scope, if one exists, and +would be invalid if no such variable exists. That is, in a normal +(non-recursive) set, attributes are not added to the lexical scope; in a +recursive set, they are. + +Recursive sets of course introduce the danger of infinite recursion. For +example, the expression + + rec { + x = y; + y = x; + }.x + +will crash with an `infinite recursion encountered` error message. + +## Let-expressions + +A let-expression allows you to define local variables for an expression. +For instance, + + let + x = "foo"; + y = "bar"; + in x + y + +evaluates to `"foobar"`. + +## Inheriting attributes + +When defining a set or in a let-expression it is often convenient to +copy variables from the surrounding lexical scope (e.g., when you want +to propagate attributes). This can be shortened using the `inherit` +keyword. For instance, + + let x = 123; in + { inherit x; + y = 456; + } + +is equivalent to + + let x = 123; in + { x = x; + y = 456; + } + +and both evaluate to `{ x = 123; y = 456; }`. (Note that this works +because `x` is added to the lexical scope by the `let` construct.) It is +also possible to inherit attributes from another set. For instance, in +this fragment from `all-packages.nix`, + +``` + graphviz = (import ../tools/graphics/graphviz) { + inherit fetchurl stdenv libpng libjpeg expat x11 yacc; + inherit (xlibs) libXaw; + }; + + xlibs = { + libX11 = ...; + libXaw = ...; + ... + } + + libpng = ...; + libjpg = ...; + ... +``` + +the set used in the function call to the function defined in +`../tools/graphics/graphviz` inherits a number of variables from the +surrounding scope (`fetchurl` ... `yacc`), but also inherits `libXaw` +(the X Athena Widgets) from the `xlibs` (X11 client-side libraries) set. + +Summarizing the fragment + + ... + inherit x y z; + inherit (src-set) a b c; + ... + +is equivalent to + + ... + x = x; y = y; z = z; + a = src-set.a; b = src-set.b; c = src-set.c; + ... + +when used while defining local variables in a let-expression or while +defining a set. + +## Functions + +Functions have the following form: + + pattern: body + +The pattern specifies what the argument of the function must look like, +and binds variables in the body to (parts of) the argument. There are +three kinds of patterns: + + - If a pattern is a single identifier, then the function matches any + argument. Example: + + let negate = x: !x; + concat = x: y: x + y; + in if negate true then concat "foo" "bar" else "" + + Note that `concat` is a function that takes one argument and returns + a function that takes another argument. This allows partial + parameterisation (i.e., only filling some of the arguments of a + function); e.g., + + map (concat "foo") [ "bar" "bla" "abc" ] + + evaluates to `[ "foobar" "foobla" + "fooabc" ]`. + + - A *set pattern* of the form `{ name1, name2, …, nameN }` matches a + set containing the listed attributes, and binds the values of those + attributes to variables in the function body. For example, the + function + + { x, y, z }: z + y + x + + can only be called with a set containing exactly the attributes `x`, + `y` and `z`. No other attributes are allowed. If you want to allow + additional arguments, you can use an ellipsis (`...`): + + { x, y, z, ... }: z + y + x + + This works on any set that contains at least the three named + attributes. + + It is possible to provide *default values* for attributes, in which + case they are allowed to be missing. A default value is specified by + writing `name ? + e`, where *e* is an arbitrary expression. For example, + + { x, y ? "foo", z ? "bar" }: z + y + x + + specifies a function that only requires an attribute named `x`, but + optionally accepts `y` and `z`. + + - An `@`-pattern provides a means of referring to the whole value + being matched: + + ``` + args@{ x, y, z, ... }: z + y + x + args.a + ``` + + but can also be written as: + + ``` + { x, y, z, ... } @ args: z + y + x + args.a + ``` + + Here `args` is bound to the entire argument, which is further + matched against the pattern `{ x, y, z, + ... }`. `@`-pattern makes mainly sense with an ellipsis(`...`) as + you can access attribute names as `a`, using `args.a`, which was + given as an additional attribute to the function. + + > **Warning** + > + > The `args@` 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 `args`. + > + > For instance + > + > let + > function = args@{ a ? 23, ... }: args; + > in + > function {} + > + > will evaluate to an empty attribute set. + +Note that functions do not have names. If you want to give them a name, +you can bind them to an attribute, e.g., + + let concat = { x, y }: x + y; + in concat { x = "foo"; y = "bar"; } + +## Conditionals + +Conditionals look like this: + + if e1 then e2 else e3 + +where *e1* is an expression that should evaluate to a Boolean value +(`true` or `false`). + +## Assertions + +Assertions are generally used to check that certain requirements on or +between features and dependencies hold. They look like this: + + assert e1; e2 + +where *e1* is an expression that should evaluate to a Boolean value. If +it evaluates to `true`, *e2* is returned; otherwise expression +evaluation is aborted and a backtrace is printed. + +Here is a Nix expression for the Subversion package that shows how +assertions can be used:. + + { localServer ? false + , httpServer ? false + , sslSupport ? false + , pythonBindings ? false + , javaSwigBindings ? false + , javahlBindings ? false + , stdenv, fetchurl + , openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null + }: + + assert localServer -> db4 != null; ① + assert httpServer -> httpd != null && httpd.expat == expat; ② + assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); ③ + assert pythonBindings -> swig != null && swig.pythonSupport; + assert javaSwigBindings -> swig != null && swig.javaSupport; + assert javahlBindings -> j2sdk != null; + + stdenv.mkDerivation { + name = "subversion-1.1.1"; + ... + openssl = if sslSupport then openssl else null; ④ + ... + } + +The points of interest are: + +1. This assertion states that if Subversion is to have support for + local repositories, then Berkeley DB is needed. So if the Subversion + function is called with the `localServer` argument set to `true` but + the `db4` argument set to `null`, then the evaluation fails. + +2. This is a more subtle condition: if Subversion is built with Apache + (`httpServer`) support, then the Expat library (an XML library) used + by Subversion should be same as the one used by Apache. This is + because in this configuration Subversion code ends up being linked + with Apache code, and if the Expat libraries do not match, a build- + or runtime link error or incompatibility might occur. + +3. This assertion says that in order for Subversion to have SSL support + (so that it can access `https` URLs), an OpenSSL library must be + passed. Additionally, it says that *if* Apache support is enabled, + then Apache's OpenSSL should match Subversion's. (Note that if + Apache support is not enabled, we don't care about Apache's + OpenSSL.) + +4. The conditional here is not really related to assertions, but is + worth pointing out: it ensures that if SSL support is disabled, then + the Subversion derivation is not dependent on OpenSSL, even if a + non-`null` value was passed. This prevents an unnecessary rebuild of + Subversion if OpenSSL changes. + +## With-expressions + +A *with-expression*, + + with e1; e2 + +introduces the set *e1* into the lexical scope of the expression *e2*. +For instance, + + let as = { x = "foo"; y = "bar"; }; + in with as; x + y + +evaluates to `"foobar"` since the `with` adds the `x` and `y` attributes +of `as` to the lexical scope in the expression `x + y`. The most common +use of `with` is in conjunction with the `import` function. E.g., + + with (import ./definitions.nix); ... + +makes all attributes defined in the file `definitions.nix` available as +if they were defined locally in a `let`-expression. + +The bindings introduced by `with` do not shadow bindings introduced by +other means, e.g. + + let a = 3; in with { a = 1; }; let a = 4; in with { a = 2; }; ... + +establishes the same scope as + + let a = 1; in let a = 2; in let a = 3; in let a = 4; in ... + +## Comments + +Comments can be single-line, started with a `#` character, or +inline/multi-line, enclosed within `/* +... */`. diff --git a/doc/manual/src/expressions/language-operators.md b/doc/manual/src/expressions/language-operators.md new file mode 100644 index 000000000..1d787ffe3 --- /dev/null +++ b/doc/manual/src/expressions/language-operators.md @@ -0,0 +1,29 @@ +# Operators + +The table below lists the operators in the Nix expression language, in +order of precedence (from strongest to weakest binding). + +| Name | Syntax | Associativity | Description | Precedence | +| ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | +| Select | *e* `.` *attrpath* \[ `or` *def* \] | none | Select attribute denoted by the attribute path *attrpath* from set *e*. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation. | 1 | +| Application | *e1* *e2* | left | Call function *e1* with argument *e2*. | 2 | +| Arithmetic Negation | `-` *e* | none | Arithmetic negation. | 3 | +| Has Attribute | *e* `?` *attrpath* | none | Test whether set *e* contains the attribute denoted by *attrpath*; return `true` or `false`. | 4 | +| List Concatenation | *e1* `++` *e2* | right | List concatenation. | 5 | +| Multiplication | *e1* `*` *e2*, | left | Arithmetic multiplication. | 6 | +| Division | *e1* `/` *e2* | left | Arithmetic division. | 6 | +| Addition | *e1* `+` *e2* | left | Arithmetic addition. | 7 | +| Subtraction | *e1* `-` *e2* | left | Arithmetic subtraction. | 7 | +| String Concatenation | *string1* `+` *string2* | left | String concatenation. | 7 | +| Not | `!` *e* | none | Boolean negation. | 8 | +| Update | *e1* `//` *e2* | right | Return a set consisting of the attributes in *e1* and *e2* (with the latter taking precedence over the former in case of equally named attributes). | 9 | +| Less Than | *e1* `<` *e2*, | none | Arithmetic comparison. | 10 | +| Less Than or Equal To | *e1* `<=` *e2* | none | Arithmetic comparison. | 10 | +| Greater Than | *e1* `>` *e2* | none | Arithmetic comparison. | 10 | +| Greater Than or Equal To | *e1* `>=` *e2* | none | Arithmetic comparison. | 10 | +| Equality | *e1* `==` *e2* | none | Equality. | 11 | +| Inequality | *e1* `!=` *e2* | none | Inequality. | 11 | +| Logical AND | *e1* `&&` *e2* | left | Logical AND. | 12 | +| Logical OR | *e1* `\|\|` *e2* | left | Logical OR. | 13 | +| Logical Implication | *e1* `->` *e2* | none | Logical implication (equivalent to `!e1 \|\| + e2`). | 14 | diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md new file mode 100644 index 000000000..eca2cab51 --- /dev/null +++ b/doc/manual/src/expressions/language-values.md @@ -0,0 +1,214 @@ +# Values + +## Simple Values + +Nix has the following basic data types: + + - *Strings* can be written in three ways. + + The most common way is to enclose the string between double quotes, + e.g., `"foo bar"`. Strings can span multiple lines. The special + characters `"` and `\` and the character sequence `${` must be + escaped by prefixing them with a backslash (`\`). Newlines, carriage + returns and tabs can be written as `\n`, `\r` and `\t`, + respectively. + + You can include the result of an expression into a string by + enclosing it in `${...}`, a feature known as *antiquotation*. The + enclosed expression must evaluate to something that can be coerced + into a string (meaning that it must be a string, a path, or a + derivation). For instance, rather than writing + + "--with-freetype2-library=" + freetype + "/lib" + + (where `freetype` is a derivation), you can instead write the more + natural + + "--with-freetype2-library=${freetype}/lib" + + The latter is automatically translated to the former. A more + complicated example (from the Nix expression for + [Qt](http://www.trolltech.com/products/qt)): + + configureFlags = " + -system-zlib -system-libpng -system-libjpeg + ${if openglSupport then "-dlopen-opengl + -L${mesa}/lib -I${mesa}/include + -L${libXmu}/lib -I${libXmu}/include" else ""} + ${if threadSupport then "-thread" else "-no-thread"} + "; + + Note that Nix expressions and strings can be arbitrarily nested; in + this case the outer string contains various antiquotations that + themselves contain strings (e.g., `"-thread"`), some of which in + turn contain expressions (e.g., `${mesa}`). + + The second way to write string literals is as an *indented string*, + which is enclosed between pairs of *double single-quotes*, like so: + + '' + This is the first line. + This is the second line. + This is the third line. + '' + + This kind of string literal intelligently strips indentation from + the start of each line. To be precise, it strips from each line a + number of spaces equal to the minimal indentation of the string as a + whole (disregarding the indentation of empty lines). For instance, + the first and second line are indented two space, while the third + line is indented four spaces. Thus, two spaces are stripped from + each line, so the resulting string is + + "This is the first line.\nThis is the second line.\n This is the third line.\n" + + Note that the whitespace and newline following the opening `''` is + ignored if there is no non-whitespace text on the initial line. + + Antiquotation (`${expr}`) is supported in indented strings. + + Since `${` and `''` have special meaning in indented strings, you + need a way to quote them. `$` can be escaped by prefixing it with + `''` (that is, two single quotes), i.e., `''$`. `''` can be escaped + by prefixing it with `'`, i.e., `'''`. `$` removes any special + meaning from the following `$`. Linefeed, carriage-return and tab + characters can be written as `''\n`, `''\r`, `''\t`, and `''\` + escapes any other character. + + Indented strings are primarily useful in that they allow multi-line + string literals to follow the indentation of the enclosing Nix + expression, and that less escaping is typically necessary for + strings representing languages such as shell scripts and + configuration files because `''` is much less common than `"`. + Example: + + stdenv.mkDerivation { + ... + postInstall = + '' + mkdir $out/bin $out/etc + cp foo $out/bin + echo "Hello World" > $out/etc/foo.conf + ${if enableBar then "cp bar $out/bin" else ""} + ''; + ... + } + + Finally, as a convenience, *URIs* as defined in appendix B of + [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as + is*, without quotes. For instance, the string + `"http://example.org/foo.tar.bz2"` can also be written as + `http://example.org/foo.tar.bz2`. + + - Numbers, which can be *integers* (like `123`) or *floating point* + (like `123.43` or `.27e13`). + + Numbers are type-compatible: pure integer operations will always + return integers, whereas any operation involving at least one + floating point number will have a floating point number as a result. + + - *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at + least one slash to be recognised as such. For instance, `builder.sh` + is not a path: it's parsed as an expression that selects the + attribute `sh` from the variable `builder`. If the file name is + relative, i.e., if it does not begin with a slash, it is made + absolute at parse time relative to the directory of the Nix + expression that contained it. For instance, if a Nix expression in + `/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path + is `/foo/xyzzy/fnord.nix`. + + If the first component of a path is a `~`, it is interpreted as if + the rest of the path were relative to the user's home directory. + e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user + whose home directory is `/home/edolstra`. + + Paths can also be specified between angle brackets, e.g. + `<nixpkgs>`. This means that the directories listed in the + environment variable `NIX_PATH` will be searched for the given file + or directory name. + + - *Booleans* with values `true` and `false`. + + - The null value, denoted as `null`. + +## Lists + +Lists are formed by enclosing a whitespace-separated list of values +between square brackets. For example, + + [ 123 ./foo.nix "abc" (f { x = y; }) ] + +defines a list of four elements, the last being the result of a call to +the function `f`. Note that function calls have to be enclosed in +parentheses. If they had been omitted, e.g., + + [ 123 ./foo.nix "abc" f { x = y; } ] + +the result would be a list of five elements, the fourth one being a +function and the fifth being a set. + +Note that lists are only lazy in values, and they are strict in length. + +## Sets + +Sets are really the core of the language, since ultimately the Nix +language is all about creating derivations, which are really just sets +of attributes to be passed to build scripts. + +Sets are just a list of name/value pairs (called *attributes*) enclosed +in curly brackets, where each value is an arbitrary expression +terminated by a semicolon. For example: + + { x = 123; + text = "Hello"; + y = f { bla = 456; }; + } + +This defines a set with attributes named `x`, `text`, `y`. The order of +the attributes is irrelevant. An attribute name may only occur once. + +Attributes can be selected from a set using the `.` operator. For +instance, + + { a = "Foo"; b = "Bar"; }.a + +evaluates to `"Foo"`. It is possible to provide a default value in an +attribute selection using the `or` keyword. For example, + + { a = "Foo"; b = "Bar"; }.c or "Xyzzy" + +will evaluate to `"Xyzzy"` because there is no `c` attribute in the set. + +You can use arbitrary double-quoted strings as attribute names: + + { "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}" + +This will evaluate to `123` (Assuming `bar` is antiquotable). In the +case where an attribute name is just a single antiquotation, the quotes +can be dropped: + + { foo = 123; }.${bar} or 456 + +This will evaluate to `123` if `bar` evaluates to `"foo"` when coerced +to a string and `456` otherwise (again assuming `bar` is antiquotable). + +In the special case where an attribute name inside of a set declaration +evaluates to `null` (which is normally an error, as `null` is not +antiquotable), that attribute is simply not added to the set: + + { ${if foo then "bar" else null} = true; } + +This will evaluate to `{}` if `foo` evaluates to `false`. + +A set that has a `__functor` attribute whose value is callable (i.e. is +itself a function or a set with a `__functor` attribute whose value is +callable) can be applied as if it were a function, with the set itself +passed in first , e.g., + + let add = { __functor = self: x: x + self.x; }; + inc = add // { x = 1; }; + in inc 1 + +evaluates to `2`. This can be used to attach metadata to a function +without the caller needing to treat it specially, or to implement a form +of object-oriented programming, for example. diff --git a/doc/manual/src/expressions/simple-building-testing.md b/doc/manual/src/expressions/simple-building-testing.md new file mode 100644 index 000000000..ca422acea --- /dev/null +++ b/doc/manual/src/expressions/simple-building-testing.md @@ -0,0 +1,57 @@ +# Building and Testing + +You can now try to build Hello. Of course, you could do `nix-env -i +hello`, but you may not want to install a possibly broken package just +yet. The best way to test the package is by using the command +`nix-build`, which builds a Nix expression and creates a symlink named +`result` in the current directory: + + $ nix-build -A hello + building path `/nix/store/632d2b22514d...-hello-2.1.1' + hello-2.1.1/ + hello-2.1.1/intl/ + hello-2.1.1/intl/ChangeLog + ... + + $ ls -l result + lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1 + + $ ./result/bin/hello + Hello, world! + +The `-A` option selects the `hello` attribute. This is faster than +using the symbolic package name specified by the `name` attribute +(which also happens to be `hello`) and is unambiguous (there can be +multiple packages with the symbolic name `hello`, but there can be +only one attribute in a set named `hello`). + +`nix-build` registers the `./result` symlink as a garbage collection +root, so unless and until you delete the `./result` symlink, the output +of the build will be safely kept on your system. You can use +`nix-build`’s `-o` switch to give the symlink another name. + +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 `out` is now “valid”. If you try to build the derivation again, Nix +will see that the path is already valid and finish immediately. If a +build fails, either because it returns a non-zero exit code, because Nix +or the builder are killed, or because the machine crashes, then the +output paths will not be registered as valid. If you try to build the +derivation again, Nix will remove the output paths if they exist (e.g., +because the builder died half-way through `make +install`) and try again. Note that there is no “negative caching”: Nix +doesn't remember that a build failed, and so a failed build can always +be repeated. This is because Nix cannot distinguish between permanent +failures (e.g., a compiler error due to a syntax error in the source) +and transient failures (e.g., a disk full condition). + +Nix also performs locking. If you run multiple Nix builds +simultaneously, and they try to build the same derivation, the first Nix +instance that gets there will perform the build, while the others block +(or perform other derivations if available) until the build finishes: + + $ nix-build -A hello + waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x' + +So it is always safe to run multiple instances of Nix in parallel (which +isn’t the case with, say, `make`). diff --git a/doc/manual/src/expressions/simple-expression.md b/doc/manual/src/expressions/simple-expression.md new file mode 100644 index 000000000..857f71b9b --- /dev/null +++ b/doc/manual/src/expressions/simple-expression.md @@ -0,0 +1,23 @@ +# A Simple Nix Expression + +This section shows how to add and test the [GNU Hello +package](http://www.gnu.org/software/hello/hello.html) to the Nix +Packages collection. Hello is a program that prints out the text “Hello, +world\!”. + +To add a package to the Nix Packages collection, you generally need to +do three things: + +1. Write a Nix expression for the package. This is a file that + describes all the inputs involved in building the package, such as + dependencies, sources, and so on. + +2. Write a *builder*. This is a shell script that builds the package + from the inputs. (In fact, it can be written in any language, but + typically it's a `bash` shell script.) + +3. Add the package to the file `pkgs/top-level/all-packages.nix`. The + Nix expression written in the first step is a *function*; it + requires other packages in order to build it. In this step you put + it all together, i.e., you call the function with the right + arguments to build the actual package. diff --git a/doc/manual/src/expressions/writing-nix-expressions.md b/doc/manual/src/expressions/writing-nix-expressions.md new file mode 100644 index 000000000..5664108e7 --- /dev/null +++ b/doc/manual/src/expressions/writing-nix-expressions.md @@ -0,0 +1,12 @@ +This chapter shows you how to write Nix expressions, which instruct Nix +how to build packages. It starts with a simple example (a Nix expression +for GNU Hello), and then moves on to a more in-depth look at the Nix +expression language. + +> **Note** +> +> This chapter is mostly about the Nix expression language. For more +> extensive information on adding packages to the Nix Packages +> collection (such as functions in the standard environment and coding +> conventions), please consult [its +> manual](http://nixos.org/nixpkgs/manual/). diff --git a/doc/manual/figures/user-environments.png b/doc/manual/src/figures/user-environments.png Binary files differindex 1f781cf23..1f781cf23 100644 --- a/doc/manual/figures/user-environments.png +++ b/doc/manual/src/figures/user-environments.png diff --git a/doc/manual/figures/user-environments.sxd b/doc/manual/src/figures/user-environments.sxd Binary files differindex bc661b640..bc661b640 100644 --- a/doc/manual/figures/user-environments.sxd +++ b/doc/manual/src/figures/user-environments.sxd diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md new file mode 100644 index 000000000..56af9cd85 --- /dev/null +++ b/doc/manual/src/glossary.md @@ -0,0 +1,100 @@ +# Glossary + + - derivation + A description of a build action. The result of a derivation is a + store object. Derivations are typically specified in Nix expressions + using the [`derivation` primitive](expressions/derivations.md). These are + translated into low-level *store derivations* (implicitly by + `nix-env` and `nix-build`, or explicitly by `nix-instantiate`). + + - store + The location in the file system where store objects live. Typically + `/nix/store`. + + - store path + The location in the file system of a store object, i.e., an + immediate child of the Nix store directory. + + - store object + A file that is an immediate child of the Nix store directory. These + can be regular files, but also entire directory trees. Store objects + can be sources (objects copied from outside of the store), + derivation outputs (objects produced by running a build action), or + derivations (files describing a build action). + + - substitute + A substitute is a command invocation stored in the Nix database that + describes how to build a store object, bypassing the normal build + mechanism (i.e., derivations). Typically, the substitute builds the + store object by downloading a pre-built version of the store object + from some server. + + - purity + The assumption that equal Nix derivations when run always produce + the same output. This cannot be guaranteed in general (e.g., a + builder can rely on external inputs such as the network or the + system time) but the Nix model assumes it. + + - Nix expression + A high-level description of software packages and compositions + thereof. Deploying software using Nix entails writing Nix + expressions for your packages. Nix expressions are translated to + derivations that are stored in the Nix store. These derivations can + then be built. + + - reference + A store path `P` is said to have a reference to a store path `Q` if + the store object at `P` contains the path `Q` somewhere. The + *references* of a store path are the set of store paths to which it + has a reference. + + A derivation can reference other derivations and sources (but not + output paths), whereas an output path only references other output + paths. + + - reachable + A store path `Q` is reachable from another store path `P` if `Q` + is in the *closure* of the *references* relation. + + - closure + The closure of a store path is the set of store paths that are + directly or indirectly “reachable” from that store path; that is, + it’s the closure of the path under the *references* relation. For + a package, the closure of its derivation is equivalent to the + build-time dependencies, while the closure of its output path is + equivalent to its runtime dependencies. For correct deployment it + is necessary to deploy whole closures, since otherwise at runtime + files could be missing. The command `nix-store -qR` prints out + closures of store paths. + + As an example, if the store object at path `P` contains a reference + to path `Q`, then `Q` is in the closure of `P`. Further, if `Q` + references `R` then `R` is also in the closure of `P`. + + - output path + A store path produced by a derivation. + + - deriver + The deriver of an *output path* is the store + derivation that built it. + + - validity + A store path is considered *valid* if it exists in the file system, + is listed in the Nix database as being valid, and if all paths in + its closure are also valid. + + - user environment + An automatically generated store object that consists of a set of + symlinks to “active” applications, i.e., other store paths. These + are generated automatically by + [`nix-env`](command-ref/nix-env.md). See *profiles*. + + - profile + A symlink to the current *user environment* of a user, e.g., + `/nix/var/nix/profiles/default`. + + - NAR + A *N*ix *AR*chive. This is a serialisation of a path in the Nix + store. It can contain regular files, directories and symbolic + links. NARs are generated and unpacked using `nix-store --dump` + and `nix-store --restore`. diff --git a/doc/manual/src/hacking.md b/doc/manual/src/hacking.md new file mode 100644 index 000000000..f8375822d --- /dev/null +++ b/doc/manual/src/hacking.md @@ -0,0 +1,47 @@ +# Hacking + +This section provides some notes on how to hack on Nix. To get the +latest version of Nix from GitHub: + + $ git clone https://github.com/NixOS/nix.git + $ cd nix + +To build Nix for the current operating system/architecture use + + $ nix-build + +or if you have a flakes-enabled nix: + + $ nix build + +This will build `defaultPackage` attribute defined in the `flake.nix` +file. To build for other platforms add one of the following suffixes to +it: aarch64-linux, i686-linux, x86\_64-darwin, x86\_64-linux. i.e. + + $ nix-build -A defaultPackage.x86_64-linux + +To build all dependencies and start a shell in which all environment +variables are set up so that those dependencies can be found: + + $ nix-shell + +To build Nix itself in this shell: + + [nix-shell]$ ./bootstrap.sh + [nix-shell]$ ./configure $configureFlags + [nix-shell]$ make -j $NIX_BUILD_CORES + +To install it in `$(pwd)/inst` and test it: + + [nix-shell]$ make install + [nix-shell]$ make installcheck + [nix-shell]$ ./inst/bin/nix --version + nix (Nix) 2.4 + +If you have a flakes-enabled nix you can replace: + + $ nix-shell + +by: + + $ nix develop diff --git a/doc/manual/src/installation/building-source.md b/doc/manual/src/installation/building-source.md new file mode 100644 index 000000000..35dbd5541 --- /dev/null +++ b/doc/manual/src/installation/building-source.md @@ -0,0 +1,34 @@ +# Building Nix from Source + +After unpacking or checking out the Nix sources, issue the following +commands: + + $ ./configure options... + $ make + $ make install + +Nix requires GNU Make so you may need to invoke `gmake` instead. + +When building from the Git repository, these should be preceded by the +command: + + $ ./bootstrap.sh + +The installation path can be specified by passing the `--prefix=prefix` +to `configure`. The default installation directory is `/usr/local`. You +can change this to any location you like. You must have write permission +to the *prefix* path. + +Nix keeps its *store* (the place where packages are stored) in +`/nix/store` by default. This can be changed using +`--with-store-dir=path`. + +> **Warning** +> +> It is best *not* to change the Nix store from its default, since doing +> so makes it impossible to use pre-built binaries from the standard +> Nixpkgs channels — that is, all packages will need to be built from +> source. + +Nix keeps state (such as its database and log files) in `/nix/var` by +default. This can be changed using `--localstatedir=path`. diff --git a/doc/manual/src/installation/env-variables.md b/doc/manual/src/installation/env-variables.md new file mode 100644 index 000000000..6e78245c9 --- /dev/null +++ b/doc/manual/src/installation/env-variables.md @@ -0,0 +1,56 @@ +# Environment Variables + +To use Nix, some environment variables should be set. In particular, +`PATH` should contain the directories `prefix/bin` and +`~/.nix-profile/bin`. The first directory contains the Nix tools +themselves, while `~/.nix-profile` is a symbolic link to the current +*user environment* (an automatically generated package consisting of +symlinks to installed packages). The simplest way to set the required +environment variables is to include the file +`prefix/etc/profile.d/nix.sh` in your `~/.profile` (or similar), like +this: + + source prefix/etc/profile.d/nix.sh + +# `NIX_SSL_CERT_FILE` + +If you need to specify a custom certificate bundle to account for an +HTTPS-intercepting man in the middle proxy, you must specify the path to +the certificate bundle in the environment variable `NIX_SSL_CERT_FILE`. + +If you don't specify a `NIX_SSL_CERT_FILE` manually, Nix will install +and use its own certificate bundle. + +Set the environment variable and install Nix + + $ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt + $ sh <(curl -L https://nixos.org/nix/install) + +In the shell profile and rc files (for example, `/etc/bashrc`, +`/etc/zshrc`), add the following line: + + export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt + +> **Note** +> +> You must not add the export and then do the install, as the Nix +> installer will detect the presense of Nix configuration, and abort. + +## `NIX_SSL_CERT_FILE` with macOS and the Nix daemon + +On macOS you must specify the environment variable for the Nix daemon +service, then restart it: + + $ sudo launchctl setenv NIX_SSL_CERT_FILE /etc/ssl/my-certificate-bundle.crt + $ sudo launchctl kickstart -k system/org.nixos.nix-daemon + +## Proxy Environment Variables + +The Nix installer has special handling for these proxy-related +environment variables: `http_proxy`, `https_proxy`, `ftp_proxy`, +`no_proxy`, `HTTP_PROXY`, `HTTPS_PROXY`, `FTP_PROXY`, `NO_PROXY`. + +If any of these variables are set when running the Nix installer, then +the installer will create an override file at +`/etc/systemd/system/nix-daemon.service.d/override.conf` so `nix-daemon` +will use them. diff --git a/doc/manual/src/installation/installation.md b/doc/manual/src/installation/installation.md new file mode 100644 index 000000000..b40c5b95f --- /dev/null +++ b/doc/manual/src/installation/installation.md @@ -0,0 +1,2 @@ +This section describes how to install and configure Nix for first-time +use. diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md new file mode 100644 index 000000000..a1dd993c4 --- /dev/null +++ b/doc/manual/src/installation/installing-binary.md @@ -0,0 +1,273 @@ +# Installing a Binary Distribution + +If you are using Linux or macOS versions up to 10.14 (Mojave), the +easiest way to install Nix is to run the following command: + +``` + $ sh <(curl -L https://nixos.org/nix/install) +``` + +If you're using macOS 10.15 (Catalina) or newer, consult [the macOS +installation instructions](#macos-installation) before installing. + +As of Nix 2.1.0, the Nix installer will always default to creating a +single-user installation, however opting in to the multi-user +installation is highly recommended. + +# Single User Installation + +To explicitly select a single-user installation on your system: + +``` + sh <(curl -L https://nixos.org/nix/install) --no-daemon +``` + +This will perform a single-user installation of Nix, meaning that `/nix` +is owned by the invoking user. You should run this under your usual user +account, *not* as root. The script will invoke `sudo` to create `/nix` +if it doesn’t already exist. If you don’t have `sudo`, you should +manually create `/nix` first as root, e.g.: + + $ mkdir /nix + $ chown alice /nix + +The install script will modify the first writable file from amongst +`.bash_profile`, `.bash_login` and `.profile` to source +`~/.nix-profile/etc/profile.d/nix.sh`. You can set the +`NIX_INSTALLER_NO_MODIFY_PROFILE` environment variable before executing +the install script to disable this behaviour. + +You can uninstall Nix simply by running: + + $ rm -rf /nix + +# Multi User Installation + +The multi-user Nix installation creates system users, and a system +service for the Nix daemon. + + - Linux running systemd, with SELinux disabled + + - macOS + +You can instruct the installer to perform a multi-user installation on +your system: + + sh <(curl -L https://nixos.org/nix/install) --daemon + +The multi-user installation of Nix will create build users between the +user IDs 30001 and 30032, and a group with the group ID 30000. You +should run this under your usual user account, *not* as root. The script +will invoke `sudo` as needed. + +> **Note** +> +> If you need Nix to use a different group ID or user ID set, you will +> have to download the tarball manually and [edit the install +> script](#installing-from-a-binary-tarball). + +The installer will modify `/etc/bashrc`, and `/etc/zshrc` if they exist. +The installer will first back up these files with a `.backup-before-nix` +extension. The installer will also create `/etc/profile.d/nix.sh`. + +You can uninstall Nix with the following commands: + + sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels + + # If you are on Linux with systemd, you will need to run: + sudo systemctl stop nix-daemon.socket + sudo systemctl stop nix-daemon.service + sudo systemctl disable nix-daemon.socket + sudo systemctl disable nix-daemon.service + sudo systemctl daemon-reload + + # If you are on macOS, you will need to run: + sudo launchctl unload /Library/LaunchDaemons/org.nixos.nix-daemon.plist + sudo rm /Library/LaunchDaemons/org.nixos.nix-daemon.plist + +There may also be references to Nix in `/etc/profile`, `/etc/bashrc`, +and `/etc/zshrc` which you may remove. + +# macOS Installation + +Starting with macOS 10.15 (Catalina), the root filesystem is read-only. +This means `/nix` can no longer live on your system volume, and that +you'll need a workaround to install Nix. + +The recommended approach, which creates an unencrypted APFS volume for +your Nix store and a "synthetic" empty directory to mount it over at +`/nix`, is least likely to impair Nix or your system. + +> **Note** +> +> With all separate-volume approaches, it's possible something on your +> system (particularly daemons/services and restored apps) may need +> access to your Nix store before the volume is mounted. Adding +> additional encryption makes this more likely. + +If you're using a recent Mac with a [T2 +chip](https://www.apple.com/euro/mac/shared/docs/Apple_T2_Security_Chip_Overview.pdf), +your drive will still be encrypted at rest (in which case "unencrypted" +is a bit of a misnomer). To use this approach, just install Nix with: + + $ sh <(curl -L https://nixos.org/nix/install) --darwin-use-unencrypted-nix-store-volume + +If you don't like the sound of this, you'll want to weigh the other +approaches and tradeoffs detailed in this section. + +> **Note** +> +> All of the known workarounds have drawbacks, but we hope better +> solutions will be available in the future. Some that we have our eye +> on are: +> +> 1. A true firmlink would enable the Nix store to live on the primary +> data volume without the build problems caused by the symlink +> approach. End users cannot currently create true firmlinks. +> +> 2. If the Nix store volume shared FileVault encryption with the +> primary data volume (probably by using the same volume group and +> role), FileVault encryption could be easily supported by the +> installer without requiring manual setup by each user. + +## Change the Nix store path prefix + +Changing the default prefix for the Nix store is a simple approach which +enables you to leave it on your root volume, where it can take full +advantage of FileVault encryption if enabled. Unfortunately, this +approach also opts your device out of some benefits that are enabled by +using the same prefix across systems: + + - Your system won't be able to take advantage of the binary cache + (unless someone is able to stand up and support duplicate caching + infrastructure), which means you'll spend more time waiting for + builds. + + - It's harder to build and deploy packages to Linux systems. + +It would also possible (and often requested) to just apply this change +ecosystem-wide, but it's an intrusive process that has side effects we +want to avoid for now. + +## Use a separate encrypted volume + +If you like, you can also add encryption to the recommended approach +taken by the installer. You can do this by pre-creating an encrypted +volume before you run the installer--or you can run the installer and +encrypt the volume it creates later. + +In either case, adding encryption to a second volume isn't quite as +simple as enabling FileVault for your boot volume. Before you dive in, +there are a few things to weigh: + +1. The additional volume won't be encrypted with your existing + FileVault key, so you'll need another mechanism to decrypt the + volume. + +2. You can store the password in Keychain to automatically decrypt the + volume on boot--but it'll have to wait on Keychain and may not mount + before your GUI apps restore. If any of your launchd agents or apps + depend on Nix-installed software (for example, if you use a + Nix-installed login shell), the restore may fail or break. + + On a case-by-case basis, you may be able to work around this problem + by using `wait4path` to block execution until your executable is + available. + + It's also possible to decrypt and mount the volume earlier with a + login hook--but this mechanism appears to be deprecated and its + future is unclear. + +3. You can hard-code the password in the clear, so that your store + volume can be decrypted before Keychain is available. + +If you are comfortable navigating these tradeoffs, you can encrypt the +volume with something along the lines of: + + alice$ diskutil apfs enableFileVault /nix -user disk + +## Symlink the Nix store to a custom location + +Another simple approach is using `/etc/synthetic.conf` to symlink the +Nix store to the data volume. This option also enables your store to +share any configured FileVault encryption. Unfortunately, builds that +resolve the symlink may leak the canonical path or even fail. + +Because of these downsides, we can't recommend this approach. + +## Notes on the recommended approach + +This section goes into a little more detail on the recommended approach. +You don't need to understand it to run the installer, but it can serve +as a helpful reference if you run into trouble. + +1. In order to compose user-writable locations into the new read-only + system root, Apple introduced a new concept called `firmlinks`, + which it describes as a "bi-directional wormhole" between two + filesystems. You can see the current firmlinks in + `/usr/share/firmlinks`. Unfortunately, firmlinks aren't (currently?) + user-configurable. + + For special cases like NFS mount points or package manager roots, + [synthetic.conf(5)](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man5/synthetic.conf.5.html) + supports limited user-controlled file-creation (of symlinks, and + synthetic empty directories) at `/`. To create a synthetic empty + directory for mounting at `/nix`, add the following line to + `/etc/synthetic.conf` (create it if necessary): + + nix + +2. This configuration is applied at boot time, but you can use + `apfs.util` to trigger creation (not deletion) of new entries + without a reboot: + + alice$ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B + +3. Create the new APFS volume with diskutil: + + alice$ sudo diskutil apfs addVolume diskX APFS 'Nix Store' -mountpoint /nix + +4. Using `vifs`, add the new mount to `/etc/fstab`. If it doesn't + already have other entries, it should look something like: + + # + # Warning - this file should only be modified with vifs(8) + # + # Failure to do so is unsupported and may be destructive. + # + LABEL=Nix\040Store /nix apfs rw,nobrowse + + The nobrowse setting will keep Spotlight from indexing this volume, + and keep it from showing up on your desktop. + +# Installing a pinned Nix version from a URL + +NixOS.org hosts version-specific installation URLs for all Nix versions +since 1.11.16, at `https://releases.nixos.org/nix/nix-version/install`. + +These install scripts can be used the same as the main NixOS.org +installation script: + +``` + sh <(curl -L https://nixos.org/nix/install) +``` + +In the same directory of the install script are sha256 sums, and gpg +signature files. + +# Installing from a binary tarball + +You can also download a binary tarball that contains Nix and all its +dependencies. (This is what the install script at +<https://nixos.org/nix/install> does automatically.) You should unpack +it somewhere (e.g. in `/tmp`), and then run the script named `install` +inside the binary tarball: + + alice$ cd /tmp + alice$ tar xfj nix-1.8-x86_64-darwin.tar.bz2 + alice$ cd nix-1.8-x86_64-darwin + alice$ ./install + +If you need to edit the multi-user installation script to use different +group ID or a different user ID range, modify the variables set in the +file named `install-multi-user`. diff --git a/doc/manual/src/installation/installing-source.md b/doc/manual/src/installation/installing-source.md new file mode 100644 index 000000000..e52d38a03 --- /dev/null +++ b/doc/manual/src/installation/installing-source.md @@ -0,0 +1,4 @@ +# Installing Nix from Source + +If no binary package is available, you can download and compile a source +distribution. diff --git a/doc/manual/src/installation/multi-user.md b/doc/manual/src/installation/multi-user.md new file mode 100644 index 000000000..de159b603 --- /dev/null +++ b/doc/manual/src/installation/multi-user.md @@ -0,0 +1,69 @@ +# Multi-User Mode + +To allow a Nix store to be shared safely among multiple users, it is +important that users are not able to run builders that modify the Nix +store or database in arbitrary ways, or that interfere with builds +started by other users. If they could do so, they could install a Trojan +horse in some package and compromise the accounts of other users. + +To prevent this, the Nix store and database are owned by some privileged +user (usually `root`) and builders are executed under special user +accounts (usually named `nixbld1`, `nixbld2`, etc.). When a unprivileged +user runs a Nix command, actions that operate on the Nix store (such as +builds) are forwarded to a *Nix daemon* running under the owner of the +Nix store/database that performs the operation. + +> **Note** +> +> Multi-user mode has one important limitation: only root and a set of +> trusted users specified in `nix.conf` can specify arbitrary binary +> caches. So while unprivileged users may install packages from +> arbitrary Nix expressions, they may not get pre-built binaries. + +## Setting up the build users + +The *build users* are the special UIDs under which builds are performed. +They should all be members of the *build users group* `nixbld`. This +group should have no other members. The build users should not be +members of any other group. On Linux, you can create the group and users +as follows: + + $ groupadd -r nixbld + $ for n in $(seq 1 10); do useradd -c "Nix build user $n" \ + -d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \ + nixbld$n; done + +This creates 10 build users. There can never be more concurrent builds +than the number of build users, so you may want to increase this if you +expect to do many builds at the same time. + +## Running the daemon + +The [Nix daemon](../command-ref/nix-daemon.md) should be started as +follows (as `root`): + + $ nix-daemon + +You’ll want to put that line somewhere in your system’s boot scripts. + +To let unprivileged users use the daemon, they should set the +[`NIX_REMOTE` environment variable](../command-ref/env-common.md) to +`daemon`. So you should put a line like + + export NIX_REMOTE=daemon + +into the users’ login scripts. + +## Restricting access + +To limit which users can perform Nix operations, you can use the +permissions on the directory `/nix/var/nix/daemon-socket`. For instance, +if you want to restrict the use of Nix to the members of a group called +`nix-users`, do + + $ chgrp nix-users /nix/var/nix/daemon-socket + $ chmod ug=rwx,o= /nix/var/nix/daemon-socket + +This way, users who are not in the `nix-users` group cannot connect to +the Unix domain socket `/nix/var/nix/daemon-socket/socket`, so they +cannot perform Nix operations. diff --git a/doc/manual/src/installation/nix-security.md b/doc/manual/src/installation/nix-security.md new file mode 100644 index 000000000..1e9036b68 --- /dev/null +++ b/doc/manual/src/installation/nix-security.md @@ -0,0 +1,15 @@ +# Security + +Nix has two basic security models. First, it can be used in “single-user +mode”, which is similar to what most other package management tools do: +there is a single user (typically root) who performs all package +management operations. All other users can then use the installed +packages, but they cannot perform package management operations +themselves. + +Alternatively, you can configure Nix in “multi-user mode”. In this +model, all users can perform package management operations — for +instance, every user can install software without requiring root +privileges. Nix ensures that this is secure. For instance, it’s not +possible for one user to overwrite a package used by another user with a +Trojan horse. diff --git a/doc/manual/src/installation/obtaining-source.md b/doc/manual/src/installation/obtaining-source.md new file mode 100644 index 000000000..2937130cf --- /dev/null +++ b/doc/manual/src/installation/obtaining-source.md @@ -0,0 +1,16 @@ +# Obtaining a Source Distribution + +The source tarball of the most recent stable release can be downloaded +from the [Nix homepage](http://nixos.org/nix/download.html). You can +also grab the [most recent development +release](http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents). + +Alternatively, the most recent sources of Nix can be obtained from its +[Git repository](https://github.com/NixOS/nix). For example, the +following command will check out the latest revision into a directory +called `nix`: + + $ git clone https://github.com/NixOS/nix + +Likewise, specific releases can be obtained from the +[tags](https://github.com/NixOS/nix/tags) of the repository. diff --git a/doc/manual/src/installation/prerequisites-source.md b/doc/manual/src/installation/prerequisites-source.md new file mode 100644 index 000000000..69b7c5a5e --- /dev/null +++ b/doc/manual/src/installation/prerequisites-source.md @@ -0,0 +1,71 @@ +# Prerequisites + + - GNU Autoconf (<https://www.gnu.org/software/autoconf/>) and the + autoconf-archive macro collection + (<https://www.gnu.org/software/autoconf-archive/>). These are only + needed to run the bootstrap script, and are not necessary if your + source distribution came with a pre-built `./configure` script. + + - GNU Make. + + - Bash Shell. The `./configure` script relies on bashisms, so Bash is + required. + + - A version of GCC or Clang that supports C++17. + + - `pkg-config` to locate dependencies. If your distribution does not + provide it, you can get it from + <http://www.freedesktop.org/wiki/Software/pkg-config>. + + - The OpenSSL library to calculate cryptographic hashes. If your + distribution does not provide it, you can get it from + <https://www.openssl.org>. + + - The `libbrotlienc` and `libbrotlidec` libraries to provide + implementation of the Brotli compression algorithm. They are + available for download from the official repository + <https://github.com/google/brotli>. + + - The bzip2 compressor program and the `libbz2` library. Thus you must + have bzip2 installed, including development headers and libraries. + If your distribution does not provide these, you can obtain bzip2 + from + <https://web.archive.org/web/20180624184756/http://www.bzip.org/>. + + - `liblzma`, which is provided by XZ Utils. If your distribution does + not provide this, you can get it from <https://tukaani.org/xz/>. + + - cURL and its library. If your distribution does not provide it, you + can get it from <https://curl.haxx.se/>. + + - The SQLite embedded database library, version 3.6.19 or higher. If + your distribution does not provide it, please install it from + <http://www.sqlite.org/>. + + - The [Boehm garbage collector](http://www.hboehm.info/gc/) to reduce + the evaluator’s memory consumption (optional). To enable it, install + `pkgconfig` and the Boehm garbage collector, and pass the flag + `--enable-gc` to `configure`. + + - The `boost` library of version 1.66.0 or higher. It can be obtained + from the official web site <https://www.boost.org/>. + + - The `editline` library of version 1.14.0 or higher. It can be + obtained from the its repository + <https://github.com/troglobit/editline>. + + - Recent versions of Bison and Flex to build the parser. (This is + because Nix needs GLR support in Bison and reentrancy support in + Flex.) For Bison, you need version 2.6, which can be obtained from + the [GNU FTP server](ftp://alpha.gnu.org/pub/gnu/bison). For Flex, + you need version 2.5.35, which is available on + [SourceForge](http://lex.sourceforge.net/). Slightly older versions + may also work, but ancient versions like the ubiquitous 2.5.4a + won't. Note that these are only required if you modify the parser or + when you are building from the Git repository. + + - The `libseccomp` is used to provide syscall filtering on Linux. This + is an optional dependency and can be disabled passing a + `--disable-seccomp-sandboxing` option to the `configure` script (Not + recommended unless your system doesn't support `libseccomp`). To get + the library, visit <https://github.com/seccomp/libseccomp>. diff --git a/doc/manual/src/installation/single-user.md b/doc/manual/src/installation/single-user.md new file mode 100644 index 000000000..f9a3b26ed --- /dev/null +++ b/doc/manual/src/installation/single-user.md @@ -0,0 +1,9 @@ +# Single-User Mode + +In single-user mode, all Nix operations that access the database in +`prefix/var/nix/db` or modify the Nix store in `prefix/store` must be +performed under the user ID that owns those directories. This is +typically root. (If you install from RPM packages, that’s in fact the +default ownership.) However, on single-user machines, it is often +convenient to `chown` those directories to your normal user account so +that you don’t have to `su` to root all the time. diff --git a/doc/manual/src/installation/supported-platforms.md b/doc/manual/src/installation/supported-platforms.md new file mode 100644 index 000000000..8ef1f0e78 --- /dev/null +++ b/doc/manual/src/installation/supported-platforms.md @@ -0,0 +1,7 @@ +# Supported Platforms + +Nix is currently supported on the following platforms: + + - Linux (i686, x86\_64, aarch64). + + - macOS (x86\_64). diff --git a/doc/manual/src/installation/upgrading.md b/doc/manual/src/installation/upgrading.md new file mode 100644 index 000000000..24efc4681 --- /dev/null +++ b/doc/manual/src/installation/upgrading.md @@ -0,0 +1,14 @@ +# Upgrading Nix + +Multi-user Nix users on macOS can upgrade Nix by running: `sudo -i sh -c +'nix-channel --update && +nix-env -iA nixpkgs.nix && +launchctl remove org.nixos.nix-daemon && +launchctl load /Library/LaunchDaemons/org.nixos.nix-daemon.plist'` + +Single-user installations of Nix should run this: `nix-channel --update; +nix-env -iA nixpkgs.nix nixpkgs.cacert` + +Multi-user Nix users on Linux should run this with sudo: `nix-channel +--update; nix-env -iA nixpkgs.nix nixpkgs.cacert; systemctl +daemon-reload; systemctl restart nix-daemon` diff --git a/doc/manual/src/introduction.md b/doc/manual/src/introduction.md new file mode 100644 index 000000000..b54b0d02d --- /dev/null +++ b/doc/manual/src/introduction.md @@ -0,0 +1,181 @@ +# Introduction + +Nix is a _purely functional package manager_. This means that it +treats packages like values in purely functional programming languages +such as Haskell — they are built by functions that don’t have +side-effects, and they never change after they have been built. Nix +stores packages in the _Nix store_, usually the directory +`/nix/store`, where each package has its own unique subdirectory such +as + + /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/ + +where `b6gvzjyb2pg0…` is a unique identifier for the package that +captures all its dependencies (it’s a cryptographic hash of the +package’s build dependency graph). This enables many powerful +features. + +## Multiple versions + +You can have multiple versions or variants of a package +installed at the same time. This is especially important when +different applications have dependencies on different versions of the +same package — it prevents the “DLL hell”. Because of the hashing +scheme, different versions of a package end up in different paths in +the Nix store, so they don’t interfere with each other. + +An important consequence is that operations like upgrading or +uninstalling an application cannot break other applications, since +these operations never “destructively” update or delete files that are +used by other packages. + +## Complete dependencies + +Nix helps you make sure that package dependency specifications are +complete. In general, when you’re making a package for a package +management system like RPM, you have to specify for each package what +its dependencies are, but there are no guarantees that this +specification is complete. If you forget a dependency, then the +package will build and work correctly on _your_ machine if you have +the dependency installed, but not on the end user's machine if it's +not there. + +Since Nix on the other hand doesn’t install packages in “global” +locations like `/usr/bin` but in package-specific directories, the +risk of incomplete dependencies is greatly reduced. This is because +tools such as compilers don’t search in per-packages directories such +as `/nix/store/5lbfaxb722zp…-openssl-0.9.8d/include`, so if a package +builds correctly on your system, this is because you specified the +dependency explicitly. This takes care of the build-time dependencies. + +Once a package is built, runtime dependencies are found by scanning +binaries for the hash parts of Nix store paths (such as `r8vvq9kq…`). +This sounds risky, but it works extremely well. + +## Multi-user support + +Nix has multi-user support. This means that non-privileged users can +securely install software. Each user can have a different _profile_, +a set of packages in the Nix store that appear in the user’s `PATH`. +If a user installs a package that another user has already installed +previously, the package won’t be built or downloaded a second time. +At the same time, it is not possible for one user to inject a Trojan +horse into a package that might be used by another user. + +## Atomic upgrades and rollbacks + +Since package management operations never overwrite packages in the +Nix store but just add new versions in different paths, they are +_atomic_. So during a package upgrade, there is no time window in +which the package has some files from the old version and some files +from the new version — which would be bad because a program might well +crash if it’s started during that period. + +And since packages aren’t overwritten, the old versions are still +there after an upgrade. This means that you can _roll back_ to the +old version: + + $ nix-env --upgrade some-packages + $ nix-env --rollback + +## Garbage collection + +When you uninstall a package like this… + + $ nix-env --uninstall firefox + +the package isn’t deleted from the system right away (after all, you +might want to do a rollback, or it might be in the profiles of other +users). Instead, unused packages can be deleted safely by running the +_garbage collector_: + + $ nix-collect-garbage + +This deletes all packages that aren’t in use by any user profile or by +a currently running program. + +## Functional package language + +Packages are built from _Nix expressions_, which is a simple +functional language. A Nix expression describes everything that goes +into a package build action (a “derivation”): other packages, sources, +the build script, environment variables for the build script, etc. +Nix tries very hard to ensure that Nix expressions are +_deterministic_: building a Nix expression twice should yield the same +result. + +Because it’s a functional language, it’s easy to support +building variants of a package: turn the Nix expression into a +function and call it any number of times with the appropriate +arguments. Due to the hashing scheme, variants don’t conflict with +each other in the Nix store. + +## Transparent source/binary deployment + +Nix expressions generally describe how to build a package from +source, so an installation action like + + $ nix-env --install firefox + +_could_ cause quite a bit of build activity, as not only Firefox but +also all its dependencies (all the way up to the C library and the +compiler) would have to built, at least if they are not already in the +Nix store. This is a _source deployment model_. For most users, +building from source is not very pleasant as it takes far too long. +However, Nix can automatically skip building from source and instead +use a _binary cache_, a web server that provides pre-built +binaries. For instance, when asked to build +`/nix/store/b6gvzjyb2pg0…-firefox-33.1` from source, Nix would first +check if the file `https://cache.nixos.org/b6gvzjyb2pg0….narinfo` +exists, and if so, fetch the pre-built binary referenced from there; +otherwise, it would fall back to building from source. + +## Nix Packages collection + +We provide a large set of Nix expressions containing hundreds of +existing Unix packages, the _Nix Packages collection_ (Nixpkgs). + +## Managing build environments + +Nix is extremely useful for developers as it makes it easy to +automatically set up the build environment for a package. Given a Nix +expression that describes the dependencies of your package, the +command `nix-shell` will build or download those dependencies if +they’re not already in your Nix store, and then start a Bash shell in +which all necessary environment variables (such as compiler search +paths) are set. + +For example, the following command gets all dependencies of the +Pan newsreader, as described by [its +Nix expression](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix): + + $ nix-shell '<nixpkgs>' -A pan + +You’re then dropped into a shell where you can edit, build and test +the package: + + [nix-shell]$ tar xf $src + [nix-shell]$ cd pan-* + [nix-shell]$ ./configure + [nix-shell]$ make + [nix-shell]$ ./pan/gui/pan + +## Portability + +Nix runs on Linux and macOS. + +## NixOS + +NixOS is a Linux distribution based on Nix. It uses Nix not just for +package management but also to manage the system configuration (e.g., +to build configuration files in `/etc`). This means, among other +things, that it is easy to roll back the entire configuration of the +system to an earlier state. Also, users can install software without +root privileges. For more information and downloads, see the [NixOS +homepage](https://nixos.org/). + +## License + +Nix is released under the terms of the [GNU LGPLv2.1 or (at your +option) any later +version](http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html). diff --git a/doc/manual/src/package-management/basic-package-mgmt.md b/doc/manual/src/package-management/basic-package-mgmt.md new file mode 100644 index 000000000..17b5cc9c2 --- /dev/null +++ b/doc/manual/src/package-management/basic-package-mgmt.md @@ -0,0 +1,150 @@ +# Basic Package Management + +The main command for package management is +[`nix-env`](../command-ref/nix-env.md). You can use it to install, +upgrade, and erase packages, and to query what packages are installed +or are available for installation. + +In Nix, different users can have different “views” on the set of +installed applications. That is, there might be lots of applications +present on the system (possibly in many different versions), but users +can have a specific selection of those active — where “active” just +means that it appears in a directory in the user’s `PATH`. Such a view +on the set of installed applications is called a *user environment*, +which is just a directory tree consisting of symlinks to the files of +the active applications. + +Components are installed from a set of *Nix expressions* that tell Nix +how to build those packages, including, if necessary, their +dependencies. There is a collection of 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 Nixpkgs package +collection; you could write your own Nix expressions based on Nixpkgs, +or completely new ones.) + +You can manually download the latest version of Nixpkgs from +<http://nixos.org/nixpkgs/download.html>. However, it’s much more +convenient to use the Nixpkgs [*channel*](channels.md), since it makes +it easy to stay up to date with new versions of Nixpkgs. Nixpkgs is +automatically added to your list of “subscribed” channels when you +install Nix. If this is not the case for some reason, you can add it +as follows: + + $ nix-channel --add https://nixos.org/channels/nixpkgs-unstable + $ nix-channel --update + +> **Note** +> +> On NixOS, you’re automatically subscribed to a NixOS channel +> corresponding to your NixOS major release (e.g. +> <http://nixos.org/channels/nixos-14.12>). A NixOS channel is identical +> to the Nixpkgs channel, except that it contains only Linux binaries +> and is updated only if a set of regression tests succeed. + +You can view the set of available packages in Nixpkgs: + + $ nix-env -qa + aterm-2.2 + bash-3.0 + binutils-2.15 + bison-1.875d + blackdown-1.4.2 + bzip2-1.0.2 + … + +The flag `-q` specifies a query operation, and `-a` means that you want +to show the “available” (i.e., installable) packages, as opposed to the +installed packages. If you downloaded Nixpkgs yourself, or if you +checked it out from GitHub, then you need to pass the path to your +Nixpkgs tree using the `-f` flag: + + $ nix-env -qaf /path/to/nixpkgs + +where */path/to/nixpkgs* is where you’ve unpacked or checked out +Nixpkgs. + +You can select specific packages by name: + + $ nix-env -qa firefox + firefox-34.0.5 + firefox-with-plugins-34.0.5 + +and using regular expressions: + + $ nix-env -qa 'firefox.*' + +It is also possible to see the *status* of available packages, i.e., +whether they are installed into the user environment and/or present in +the system: + + $ nix-env -qas + … + -PS bash-3.0 + --S binutils-2.15 + IPS bison-1.875d + … + +The first character (`I`) indicates whether the package is installed in +your current user environment. The second (`P`) indicates whether it is +present on your system (in which case installing it into your user +environment would be a very quick operation). The last one (`S`) +indicates whether there is a so-called *substitute* for the package, +which is Nix’s mechanism for doing binary deployment. It just means that +Nix knows that it can fetch a pre-built package from somewhere +(typically a network server) instead of building it locally. + +You can install a package using `nix-env -i`. For instance, + + $ nix-env -i subversion + +will install the package called `subversion` (which is, of course, the +[Subversion version management system](http://subversion.tigris.org/)). + +> **Note** +> +> When you ask Nix to install a package, it will first try to get it in +> pre-compiled form from a *binary cache*. By default, Nix will use the +> binary cache <https://cache.nixos.org>; it contains binaries for most +> packages in Nixpkgs. Only if no binary is available in the binary +> cache, Nix will build the package from source. So if `nix-env +> -i subversion` results in Nix building stuff from source, then either +> the package is not built for your platform by the Nixpkgs build +> servers, or your version of Nixpkgs is too old or too new. For +> instance, if you have a very recent checkout of Nixpkgs, then the +> Nixpkgs build servers may not have had a chance to build everything +> and upload the resulting binaries to <https://cache.nixos.org>. The +> Nixpkgs channel is only updated after all binaries have been uploaded +> to the cache, so if you stick to the Nixpkgs channel (rather than +> using a Git checkout of the Nixpkgs tree), you will get binaries for +> most packages. + +Naturally, packages can also be uninstalled: + + $ nix-env -e subversion + +Upgrading to a new version is just as easy. If you have a new release of +Nix Packages, you can do: + + $ nix-env -u subversion + +This will *only* upgrade Subversion if there is a “newer” version in the +new set of Nix expressions, as defined by some pretty arbitrary rules +regarding ordering of version numbers (which generally do what you’d +expect of them). To just unconditionally replace Subversion with +whatever version is in the Nix expressions, use `-i` instead of `-u`; +`-i` will remove whatever version is already installed. + +You can also upgrade all packages for which there are newer versions: + + $ nix-env -u + +Sometimes it’s useful to be able to ask what `nix-env` would do, without +actually doing it. For instance, to find out what packages would be +upgraded by `nix-env -u`, you can do + + $ nix-env -u --dry-run + (dry run; not doing anything) + upgrading `libxslt-1.1.0' to `libxslt-1.1.10' + upgrading `graphviz-1.10' to `graphviz-1.12' + upgrading `coreutils-5.0' to `coreutils-5.2.1' diff --git a/doc/manual/src/package-management/binary-cache-substituter.md b/doc/manual/src/package-management/binary-cache-substituter.md new file mode 100644 index 000000000..44f0da238 --- /dev/null +++ b/doc/manual/src/package-management/binary-cache-substituter.md @@ -0,0 +1,42 @@ +# Serving a Nix store via HTTP + +You can easily share the Nix store of a machine via HTTP. This allows +other machines to fetch store paths from that machine to speed up +installations. It uses the same *binary cache* mechanism that Nix +usually uses to fetch pre-built binaries from <https://cache.nixos.org>. + +The daemon that handles binary cache requests via HTTP, `nix-serve`, is +not part of the Nix distribution, but you can install it from Nixpkgs: + + $ nix-env -i nix-serve + +You can then start the server, listening for HTTP connections on +whatever port you like: + + $ nix-serve -p 8080 + +To check whether it works, try the following on the client: + + $ curl http://avalon:8080/nix-cache-info + +which should print something like: + + StoreDir: /nix/store + WantMassQuery: 1 + Priority: 30 + +On the client side, you can tell Nix to use your binary cache using +`--option extra-binary-caches`, e.g.: + + $ nix-env -i firefox --option extra-binary-caches http://avalon:8080/ + +The option `extra-binary-caches` tells Nix to use this binary cache in +addition to your default caches, such as <https://cache.nixos.org>. +Thus, for any path in the closure of Firefox, Nix will first check if +the path is available on the server `avalon` or another binary caches. +If not, it will fall back to building from source. + +You can also tell Nix to always use your binary cache by adding a line +to the `nix.conf` configuration file like this: + + binary-caches = http://avalon:8080/ https://cache.nixos.org/ diff --git a/doc/manual/src/package-management/channels.md b/doc/manual/src/package-management/channels.md new file mode 100644 index 000000000..c239998d9 --- /dev/null +++ b/doc/manual/src/package-management/channels.md @@ -0,0 +1,42 @@ +# Channels + +If you want to stay up to date with a set of packages, it’s not very +convenient to manually download the latest set of Nix expressions for +those packages and upgrade using `nix-env`. Fortunately, there’s a +better way: *Nix channels*. + +A Nix channel is just a URL that points to a place that contains a set +of Nix expressions and a manifest. Using the command +[`nix-channel`](../command-ref/nix-channel.md) you can automatically +stay up to date with whatever is available at that URL. + +To see the list of official NixOS channels, visit +<https://nixos.org/channels>. + +You can “subscribe” to a channel using `nix-channel --add`, e.g., + + $ nix-channel --add https://nixos.org/channels/nixpkgs-unstable + +subscribes you to a channel that always contains that latest version of +the Nix Packages collection. (Subscribing really just means that the URL +is added to the file `~/.nix-channels`, where it is read by subsequent +calls to `nix-channel +--update`.) You can “unsubscribe” using `nix-channel +--remove`: + + $ nix-channel --remove nixpkgs + +To obtain the latest Nix expressions available in a channel, do + + $ nix-channel --update + +This downloads and unpacks the Nix expressions in every channel +(downloaded from `url/nixexprs.tar.bz2`). It also makes the union of +each channel’s Nix expressions available by default to `nix-env` +operations (via the symlink `~/.nix-defexpr/channels`). Consequently, +you can then say + + $ nix-env -u + +to upgrade all packages in your profile to the latest versions available +in the subscribed channels. diff --git a/doc/manual/src/package-management/copy-closure.md b/doc/manual/src/package-management/copy-closure.md new file mode 100644 index 000000000..d3fac4d76 --- /dev/null +++ b/doc/manual/src/package-management/copy-closure.md @@ -0,0 +1,34 @@ +# Copying Closures via SSH + +The command `nix-copy-closure` copies a Nix store path along with all +its dependencies to or from another machine via the SSH protocol. It +doesn’t copy store paths that are already present on the target machine. +For example, the following command copies Firefox with all its +dependencies: + + $ nix-copy-closure --to alice@itchy.example.org $(type -p firefox) + +See the [manpage for `nix-copy-closure`](../command-ref/nix-copy-closure.md) for details. + +With `nix-store +--export` and `nix-store --import` you can write the closure of a store +path (that is, the path and all its dependencies) to a file, and then +unpack that file into another Nix store. For example, + + $ nix-store --export $(nix-store -qR $(type -p firefox)) > firefox.closure + +writes the closure of Firefox to a file. You can then copy this file to +another machine and install the closure: + + $ nix-store --import < firefox.closure + +Any store paths in the closure that are already present in the target +store are ignored. It is also possible to pipe the export into another +command, e.g. to copy and install a closure directly to/on another +machine: + + $ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \ + ssh alice@itchy.example.org "bunzip2 | nix-store --import" + +However, `nix-copy-closure` is generally more efficient because it only +copies paths that are not already present in the target Nix store. diff --git a/doc/manual/src/package-management/garbage-collection.md b/doc/manual/src/package-management/garbage-collection.md new file mode 100644 index 000000000..4c8799dfe --- /dev/null +++ b/doc/manual/src/package-management/garbage-collection.md @@ -0,0 +1,61 @@ +# Garbage Collection + +`nix-env` operations such as upgrades (`-u`) and uninstall (`-e`) never +actually delete packages from the system. All they do (as shown above) +is to create a new user environment that no longer contains symlinks to +the “deleted” packages. + +Of course, since disk space is not infinite, unused packages should be +removed at some point. You can do this by running the Nix garbage +collector. It will remove from the Nix store any package not used +(directly or indirectly) by any generation of any profile. + +Note however that as long as old generations reference a package, it +will not be deleted. After all, we wouldn’t be able to do a rollback +otherwise. So in order for garbage collection to be effective, you +should also delete (some) old generations. Of course, this should only +be done if you are certain that you will not need to roll back. + +To delete all old (non-current) generations of your current profile: + + $ nix-env --delete-generations old + +Instead of `old` you can also specify a list of generations, e.g., + + $ nix-env --delete-generations 10 11 14 + +To delete all generations older than a specified number of days (except +the current generation), use the `d` suffix. For example, + + $ nix-env --delete-generations 14d + +deletes all generations older than two weeks. + +After removing appropriate old generations you can run the garbage +collector as follows: + + $ nix-store --gc + +The behaviour of the gargage collector is affected by the +`keep-derivations` (default: true) and `keep-outputs` (default: false) +options in the Nix configuration file. The defaults will ensure 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 be +deleted: + + $ nix-store --gc --print-dead + +Likewise, the option `--print-live` will show the paths that *won’t* be +deleted. + +There is also a convenient little utility `nix-collect-garbage`, which +when invoked with the `-d` (`--delete-old`) switch deletes all old +generations of all profiles in `/nix/var/nix/profiles`. So + + $ nix-collect-garbage -d + +is a quick and easy way to clean up your system. diff --git a/doc/manual/src/package-management/garbage-collector-roots.md b/doc/manual/src/package-management/garbage-collector-roots.md new file mode 100644 index 000000000..6f4d48e80 --- /dev/null +++ b/doc/manual/src/package-management/garbage-collector-roots.md @@ -0,0 +1,16 @@ +# Garbage Collector Roots + +The roots of the garbage collector are all store paths to which there +are symlinks in the directory `prefix/nix/var/nix/gcroots`. For +instance, the following command makes the path +`/nix/store/d718ef...-foo` a root of the collector: + + $ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar + +That is, after this command, the garbage collector will not remove +`/nix/store/d718ef...-foo` or any of its dependencies. + +Subdirectories of `prefix/nix/var/nix/gcroots` are also searched for +symlinks. Symlinks to non-store paths are followed and searched for +roots, but symlinks to non-store paths *inside* the paths reached in +that way are not followed to prevent infinite recursion. diff --git a/doc/manual/src/package-management/package-management.md b/doc/manual/src/package-management/package-management.md new file mode 100644 index 000000000..bd26a09ab --- /dev/null +++ b/doc/manual/src/package-management/package-management.md @@ -0,0 +1,5 @@ +This chapter discusses how to do package management with Nix, i.e., +how to obtain, install, upgrade, and erase packages. This is the +“user’s” perspective of the Nix system — people who want to *create* +packages should consult the [chapter on writing Nix +expressions](../expressions/writing-nix-expressions.md). diff --git a/doc/manual/src/package-management/profiles.md b/doc/manual/src/package-management/profiles.md new file mode 100644 index 000000000..f3786072d --- /dev/null +++ b/doc/manual/src/package-management/profiles.md @@ -0,0 +1,115 @@ +# Profiles + +Profiles and user environments are Nix’s mechanism for implementing the +ability to allow different users to have different configurations, and +to do atomic upgrades and rollbacks. To understand how they work, it’s +useful to know a bit about how Nix works. In Nix, packages are stored in +unique locations in the *Nix store* (typically, `/nix/store`). For +instance, a particular version of the Subversion package might be stored +in a directory +`/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/`, while +another version might be stored in +`/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2`. The long +strings prefixed to the directory names are cryptographic hashes (to be +precise, 160-bit truncations of SHA-256 hashes encoded in a base-32 +notation) of *all* inputs involved in building the package — sources, +dependencies, compiler flags, and so on. So if two packages differ in +any way, they end up in different locations in the file system, so they +don’t interfere with each other. Here is what a part of a typical Nix +store looks like: + + + +Of course, you wouldn’t want to type + + $ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn + +every time you want to run Subversion. Of course we could set up the +`PATH` environment variable to include the `bin` directory of every +package we want to use, but this is not very convenient since changing +`PATH` doesn’t take effect for already existing processes. The solution +Nix uses is to create directory trees of symlinks to *activated* +packages. These are called *user environments* and they are packages +themselves (though automatically generated by `nix-env`), so they too +reside in the Nix store. For instance, in the figure above, the user +environment `/nix/store/0c1p5z4kda11...-user-env` contains a symlink to +just Subversion 1.1.2 (arrows in the figure indicate symlinks). This +would be what we would obtain if we had done + + $ nix-env -i subversion + +on a set of Nix expressions that contained Subversion 1.1.2. + +This doesn’t in itself solve the problem, of course; you wouldn’t want +to type `/nix/store/0c1p5z4kda11...-user-env/bin/svn` either. That’s why +there are symlinks outside of the store that point to the user +environments in the store; for instance, the symlinks `default-42-link` +and `default-43-link` in the example. These are called *generations* +since every time you perform a `nix-env` operation, a new user +environment is generated based on the current one. For instance, +generation 43 was created from generation 42 when we did + + $ nix-env -i subversion firefox + +on a set of Nix expressions that contained Firefox and a new version of +Subversion. + +Generations are grouped together into *profiles* so that different users +don’t interfere with each other if they don’t want to. For example: + + $ ls -l /nix/var/nix/profiles/ + ... + lrwxrwxrwx 1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env + lrwxrwxrwx 1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env + lrwxrwxrwx 1 eelco ... default -> default-43-link + +This shows a profile called `default`. The file `default` itself is +actually a symlink that points to the current generation. When we do a +`nix-env` operation, a new user environment and generation link are +created based on the current one, and finally the `default` symlink is +made to point at the new generation. This last step is atomic on Unix, +which explains how we can do atomic upgrades. (Note that the +building/installing of new packages doesn’t interfere in any way with +old packages, since they are stored in different locations in the Nix +store.) + +If you find that you want to undo a `nix-env` operation, you can just do + + $ nix-env --rollback + +which will just make the current generation link point at the previous +link. E.g., `default` would be made to point at `default-42-link`. You +can also switch to a specific generation: + + $ nix-env --switch-generation 43 + +which in this example would roll forward to generation 43 again. You can +also see all available generations: + + $ nix-env --list-generations + +You generally wouldn’t have `/nix/var/nix/profiles/some-profile/bin` in +your `PATH`. Rather, there is a symlink `~/.nix-profile` that points to +your current profile. This means that you should put +`~/.nix-profile/bin` in your `PATH` (and indeed, that’s what the +initialisation script `/nix/etc/profile.d/nix.sh` does). This makes it +easier to switch to a different profile. You can do that using the +command `nix-env --switch-profile`: + + $ nix-env --switch-profile /nix/var/nix/profiles/my-profile + + $ nix-env --switch-profile /nix/var/nix/profiles/default + +These commands switch to the `my-profile` and default profile, +respectively. If the profile doesn’t exist, it will be created +automatically. You should be careful about storing a profile in another +location than the `profiles` directory, since otherwise it might not be +used as a root of the [garbage collector](garbage-collection.md). + +All `nix-env` operations work on the profile pointed to by +`~/.nix-profile`, but you can override this using the `--profile` option +(abbreviation `-p`): + + $ nix-env -p /nix/var/nix/profiles/other-profile -i subversion + +This will *not* change the `~/.nix-profile` symlink. diff --git a/doc/manual/src/package-management/s3-substituter.md b/doc/manual/src/package-management/s3-substituter.md new file mode 100644 index 000000000..2824c1a9b --- /dev/null +++ b/doc/manual/src/package-management/s3-substituter.md @@ -0,0 +1,135 @@ +# Serving a Nix store via S3 + +Nix has built-in support for storing and fetching store paths from +Amazon S3 and S3-compatible services. This uses the same *binary* +cache mechanism that Nix usually uses to fetch prebuilt binaries from +[cache.nixos.org](https://cache.nixos.org/). + +The following options can be specified as URL parameters to the S3 URL: + + - `profile` + The name of the AWS configuration profile to use. By default Nix + will use the `default` profile. + + - `region` + The region of the S3 bucket. `us–east-1` by default. + + If your bucket is not in `us–east-1`, you should always explicitly + specify the region parameter. + + - `endpoint` + The URL to your S3-compatible service, for when not using Amazon S3. + Do not specify this value if you're using Amazon S3. + + > **Note** + > + > This endpoint must support HTTPS and will use path-based + > addressing instead of virtual host based addressing. + + - `scheme` + The scheme used for S3 requests, `https` (default) or `http`. This + option allows you to disable HTTPS for binary caches which don't + support it. + + > **Note** + > + > HTTPS should be used if the cache might contain sensitive + > information. + +In this example we will use the bucket named `example-nix-cache`. + +## Anonymous Reads to your S3-compatible binary cache + +If your binary cache is publicly accessible and does not require +authentication, the simplest and easiest way to use Nix with your S3 +compatible binary cache is to use the HTTP URL for that cache. + +For AWS S3 the binary cache URL for example bucket will be exactly +<https://example-nix-cache.s3.amazonaws.com> or +<s3://example-nix-cache>. For S3 compatible binary caches, consult that +cache's documentation. + +Your bucket will need the following bucket policy: + + { + "Id": "DirectReads", + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "AllowDirectReads", + "Action": [ + "s3:GetObject", + "s3:GetBucketLocation" + ], + "Effect": "Allow", + "Resource": [ + "arn:aws:s3:::example-nix-cache", + "arn:aws:s3:::example-nix-cache/*" + ], + "Principal": "*" + } + ] + } + +## Authenticated Reads to your S3 binary cache + +For AWS S3 the binary cache URL for example bucket will be exactly +<s3://example-nix-cache>. + +Nix will use the [default credential provider +chain](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html) +for authenticating requests to Amazon S3. + +Nix supports authenticated reads from Amazon S3 and S3 compatible binary +caches. + +Your bucket will need a bucket policy allowing the desired users to +perform the `s3:GetObject` and `s3:GetBucketLocation` action on all +objects in the bucket. The [anonymous policy given +above](#anonymous-reads-to-your-s3-compatible-binary-cache) can be +updated to have a restricted `Principal` to support this. + +## Authenticated Writes to your S3-compatible binary cache + +Nix support fully supports writing to Amazon S3 and S3 compatible +buckets. The binary cache URL for our example bucket will be +<s3://example-nix-cache>. + +Nix will use the [default credential provider +chain](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html) +for authenticating requests to Amazon S3. + +Your account will need the following IAM policy to upload to the cache: + + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "UploadToCache", + "Effect": "Allow", + "Action": [ + "s3:AbortMultipartUpload", + "s3:GetBucketLocation", + "s3:GetObject", + "s3:ListBucket", + "s3:ListBucketMultipartUploads", + "s3:ListMultipartUploadParts", + "s3:PutObject" + ], + "Resource": [ + "arn:aws:s3:::example-nix-cache", + "arn:aws:s3:::example-nix-cache/*" + ] + } + ] + } + +## Examples + +To upload with a specific credential profile for Amazon S3: + + nix copy --to 's3://example-nix-cache?profile=cache-upload®ion=eu-west-2' nixpkgs.hello + +To upload to an S3-compatible binary cache: + + nix copy --to 's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' nixpkgs.hello diff --git a/doc/manual/src/package-management/sharing-packages.md b/doc/manual/src/package-management/sharing-packages.md new file mode 100644 index 000000000..846ca6934 --- /dev/null +++ b/doc/manual/src/package-management/sharing-packages.md @@ -0,0 +1,6 @@ +# Sharing Packages Between Machines + +Sometimes you want to copy a package from one machine to another. Or, +you want to install some packages and you know that another machine +already has some or all of those packages or their dependencies. In that +case there are mechanisms to quickly copy packages between machines. diff --git a/doc/manual/src/package-management/ssh-substituter.md b/doc/manual/src/package-management/ssh-substituter.md new file mode 100644 index 000000000..482844c7c --- /dev/null +++ b/doc/manual/src/package-management/ssh-substituter.md @@ -0,0 +1,52 @@ +# Serving a Nix store via SSH + +You can tell Nix to automatically fetch needed binaries from a remote +Nix store via SSH. For example, the following installs Firefox, +automatically fetching any store paths in Firefox’s closure if they are +available on the server `avalon`: + + $ nix-env -i firefox --substituters ssh://alice@avalon + +This works similar to the binary cache substituter that Nix usually +uses, only using SSH instead of HTTP: if a store path `P` is needed, Nix +will first check if it’s available in the Nix store on `avalon`. If not, +it will fall back to using the binary cache substituter, and then to +building from source. + +> **Note** +> +> The SSH substituter currently does not allow you to enter an SSH +> passphrase interactively. Therefore, you should use `ssh-add` to load +> the decrypted private key into `ssh-agent`. + +You can also copy the closure of some store path, without installing it +into your profile, e.g. + + $ nix-store -r /nix/store/m85bxg…-firefox-34.0.5 --substituters ssh://alice@avalon + +This is essentially equivalent to doing + + $ nix-copy-closure --from alice@avalon /nix/store/m85bxg…-firefox-34.0.5 + +You can use SSH’s *forced command* feature to set up a restricted user +account for SSH substituter access, allowing read-only access to the +local Nix store, but nothing more. For example, add the following lines +to `sshd_config` to restrict the user `nix-ssh`: + + Match User nix-ssh + AllowAgentForwarding no + AllowTcpForwarding no + PermitTTY no + PermitTunnel no + X11Forwarding no + ForceCommand nix-store --serve + Match All + +On NixOS, you can accomplish the same by adding the following to your +`configuration.nix`: + + nix.sshServe.enable = true; + nix.sshServe.keys = [ "ssh-dss AAAAB3NzaC1k... bob@example.org" ]; + +where the latter line lists the public keys of users that are allowed to +connect. diff --git a/doc/manual/src/quick-start.md b/doc/manual/src/quick-start.md new file mode 100644 index 000000000..3c519217b --- /dev/null +++ b/doc/manual/src/quick-start.md @@ -0,0 +1,79 @@ +# Quick Start + +This chapter is for impatient people who don't like reading +documentation. For more in-depth information you are kindly referred +to subsequent chapters. + +1. Install single-user Nix by running the following: + + $ bash <(curl -L https://nixos.org/nix/install) + + This will install Nix in `/nix`. The install script will create + `/nix` using `sudo`, so make sure you have sufficient rights. (For + other installation methods, see + [here](installation/installation.md).) + +1. See what installable packages are currently available in the + channel: + + $ nix-env -qa + docbook-xml-4.3 + docbook-xml-4.5 + firefox-33.0.2 + hello-2.9 + libxslt-1.1.28 + … + +1. Install some packages from the channel: + + $ nix-env -i hello + + This should download pre-built packages; it should not build them + locally (if it does, something went wrong). + +1. Test that they work: + + $ which hello + /home/eelco/.nix-profile/bin/hello + $ hello + Hello, world! + +1. Uninstall a package: + + $ nix-env -e hello + +1. You can also test a package without installing it: + + $ nix-shell -p hello + + This builds or downloads GNU Hello and its dependencies, then drops + you into a Bash shell where the `hello` command is present, all + without affecting your normal environment: + + [nix-shell:~]$ hello + Hello, world! + + [nix-shell:~]$ exit + + $ hello + hello: command not found + +1. To keep up-to-date with the channel, do: + + $ nix-channel --update nixpkgs + $ nix-env -u '*' + + The latter command will upgrade each installed package for which + there is a “newer” version (as determined by comparing the version + numbers). + +1. If you're unhappy with the result of a `nix-env` action (e.g., an + upgraded package turned out not to work properly), you can go back: + + $ nix-env --rollback + +1. You should periodically run the Nix garbage collector to get rid of + unused packages, since uninstalls or upgrades don't actually delete + them: + + $ nix-collect-garbage -d diff --git a/doc/manual/src/release-notes/release-notes.md b/doc/manual/src/release-notes/release-notes.md new file mode 100644 index 000000000..b05d5ee0a --- /dev/null +++ b/doc/manual/src/release-notes/release-notes.md @@ -0,0 +1 @@ +# Nix Release Notes diff --git a/doc/manual/src/release-notes/rl-0.10.1.md b/doc/manual/src/release-notes/rl-0.10.1.md new file mode 100644 index 000000000..e1ed6558a --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.10.1.md @@ -0,0 +1,5 @@ +# Release 0.10.1 (2006-10-11) + +This release fixes two somewhat obscure bugs that occur when evaluating +Nix expressions that are stored inside the Nix store (`NIX-67`). These +do not affect most users. diff --git a/doc/manual/src/release-notes/rl-0.10.md b/doc/manual/src/release-notes/rl-0.10.md new file mode 100644 index 000000000..1301add26 --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.10.md @@ -0,0 +1,212 @@ +# Release 0.10 (2006-10-06) + +> **Note** +> +> This version of Nix uses Berkeley DB 4.4 instead of 4.3. The database +> is upgraded automatically, but you should be careful not to use old +> versions of Nix that still use Berkeley DB 4.3. In particular, if you +> use a Nix installed through Nix, you should run +> +> $ nix-store --clear-substitutes +> +> first. + +> **Warning** +> +> Also, the database schema has changed slighted to fix a performance +> issue (see below). When you run any Nix 0.10 command for the first +> time, the database will be upgraded automatically. This is +> irreversible. + + - `nix-env` usability improvements: + + - An option `--compare-versions` (or `-c`) has been added to + `nix-env + --query` to allow you to compare installed versions of packages + to available versions, or vice versa. An easy way to see if you + are up to date with what’s in your subscribed channels is + `nix-env -qc \*`. + + - `nix-env --query` now takes as arguments a list of package names + about which to show information, just like `--install`, etc.: + for example, `nix-env -q gcc`. Note that to show all + derivations, you need to specify `\*`. + + - `nix-env -i + pkgname` will now install the highest available version of + *pkgname*, rather than installing all available versions (which + would probably give collisions) (`NIX-31`). + + - `nix-env (-i|-u) --dry-run` now shows exactly which missing + paths will be built or substituted. + + - `nix-env -qa --description` shows human-readable descriptions of + packages, provided that they have a `meta.description` attribute + (which most packages in Nixpkgs don’t have yet). + + - New language features: + + - Reference scanning (which happens after each build) is much + faster and takes a constant amount of memory. + + - String interpolation. Expressions like + + "--with-freetype2-library=" + freetype + "/lib" + + can now be written as + + "--with-freetype2-library=${freetype}/lib" + + You can write arbitrary expressions within `${...}`, not just + identifiers. + + - Multi-line string literals. + + - String concatenations can now involve derivations, as in the + example `"--with-freetype2-library=" + + freetype + "/lib"`. This was not previously possible because + we need to register that a derivation that uses such a string is + dependent on `freetype`. The evaluator now properly propagates + this information. Consequently, the subpath operator (`~`) has + been deprecated. + + - Default values of function arguments can now refer to other + function arguments; that is, all arguments are in scope in the + default values (`NIX-45`). + + - Lots of new built-in primitives, such as functions for list + manipulation and integer arithmetic. See the manual for a + complete list. All primops are now available in the set + `builtins`, allowing one to test for the availability of primop + in a backwards-compatible way. + + - Real let-expressions: `let x = ...; + ... z = ...; in ...`. + + - New commands `nix-pack-closure` and `nix-unpack-closure` than can be + used to easily transfer a store path with all its dependencies to + another machine. Very convenient whenever you have some package on + your machine and you want to copy it somewhere else. + + - XML support: + + - `nix-env -q --xml` prints the installed or available packages in + an XML representation for easy processing by other tools. + + - `nix-instantiate --eval-only + --xml` prints an XML representation of the resulting term. (The + new flag `--strict` forces ‘deep’ evaluation of the result, + i.e., list elements and attributes are evaluated recursively.) + + - In Nix expressions, the primop `builtins.toXML` converts a term + to an XML representation. This is primarily useful for passing + structured information to builders. + + - You can now unambiguously specify which derivation to build or + install in `nix-env`, `nix-instantiate` and `nix-build` using the + `--attr` / `-A` flags, which takes an attribute name as argument. + (Unlike symbolic package names such as `subversion-1.4.0`, attribute + names in an attribute set are unique.) For instance, a quick way to + perform a test build of a package in Nixpkgs is `nix-build + pkgs/top-level/all-packages.nix -A + foo`. `nix-env -q + --attr` shows the attribute names corresponding to each derivation. + + - If the top-level Nix expression used by `nix-env`, `nix-instantiate` + or `nix-build` evaluates to a function whose arguments all have + default values, the function will be called automatically. Also, the + new command-line switch `--arg + name + value` can be used to specify function arguments on the command + line. + + - `nix-install-package --url + URL` allows a package to be installed directly from the given URL. + + - Nix now works behind an HTTP proxy server; just set the standard + environment variables `http_proxy`, `https_proxy`, `ftp_proxy` or + `all_proxy` appropriately. Functions such as `fetchurl` in Nixpkgs + also respect these variables. + + - `nix-build -o + symlink` allows the symlink to the build result to be named + something other than `result`. + + - Platform support: + + - Support for 64-bit platforms, provided a [suitably patched ATerm + library](http://bugzilla.sen.cwi.nl:8080/show_bug.cgi?id=606) is + used. Also, files larger than 2 GiB are now supported. + + - Added support for Cygwin (Windows, `i686-cygwin`), Mac OS X on + Intel (`i686-darwin`) and Linux on PowerPC (`powerpc-linux`). + + - Users of SMP and multicore machines will appreciate that the + number of builds to be performed in parallel can now be + specified in the configuration file in the `build-max-jobs` + setting. + + - Garbage collector improvements: + + - Open files (such as running programs) are now used as roots of + the garbage collector. This prevents programs that have been + uninstalled from being garbage collected while they are still + running. The script that detects these additional runtime roots + (`find-runtime-roots.pl`) is inherently system-specific, but it + should work on Linux and on all platforms that have the `lsof` + utility. + + - `nix-store --gc` (a.k.a. `nix-collect-garbage`) prints out the + number of bytes freed on standard output. `nix-store + --gc --print-dead` shows how many bytes would be freed by an + actual garbage collection. + + - `nix-collect-garbage -d` removes all old generations of *all* + profiles before calling the actual garbage collector (`nix-store + --gc`). This is an easy way to get rid of all old packages in + the Nix store. + + - `nix-store` now has an operation `--delete` to delete specific + paths from the Nix store. It won’t delete reachable + (non-garbage) paths unless `--ignore-liveness` is specified. + + - Berkeley DB 4.4’s process registry feature is used to recover from + crashed Nix processes. + + - A performance issue has been fixed with the `referer` table, which + stores the inverse of the `references` table (i.e., it tells you + what store paths refer to a given path). Maintaining this table + could take a quadratic amount of time, as well as a quadratic amount + of Berkeley DB log file space (in particular when running the + garbage collector) (`NIX-23`). + + - Nix now catches the `TERM` and `HUP` signals in addition to the + `INT` signal. So you can now do a `killall + nix-store` without triggering a database recovery. + + - `bsdiff` updated to version 4.3. + + - Substantial performance improvements in expression evaluation and + `nix-env -qa`, all thanks to [Valgrind](http://valgrind.org/). + Memory use has been reduced by a factor 8 or so. Big speedup by + memoisation of path hashing. + + - Lots of bug fixes, notably: + + - Make sure that the garbage collector can run successfully when + the disk is full (`NIX-18`). + + - `nix-env` now locks the profile to prevent races between + concurrent `nix-env` operations on the same profile (`NIX-7`). + + - Removed misleading messages from `nix-env -i` (e.g., + ``installing + `foo'`` followed by ``uninstalling + `foo'``) (`NIX-17`). + + - Nix source distributions are a lot smaller now since we no longer + include a full copy of the Berkeley DB source distribution (but only + the bits we need). + + - Header files are now installed so that external programs can use the + Nix libraries. diff --git a/doc/manual/src/release-notes/rl-0.11.md b/doc/manual/src/release-notes/rl-0.11.md new file mode 100644 index 000000000..d2f4d73aa --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.11.md @@ -0,0 +1,167 @@ +# Release 0.11 (2007-12-31) + +Nix 0.11 has many improvements over the previous stable release. The +most important improvement is secure multi-user support. It also +features many usability enhancements and language extensions, many of +them prompted by NixOS, the purely functional Linux distribution based +on Nix. Here is an (incomplete) list: + + - Secure multi-user support. A single Nix store can now be shared + between multiple (possible untrusted) users. This is an important + feature for NixOS, where it allows non-root users to install + software. The old setuid method for sharing a store between multiple + users has been removed. Details for setting up a multi-user store + can be found in the manual. + + - The new command `nix-copy-closure` gives you an easy and efficient + way to exchange software between machines. It copies the missing + parts of the closure of a set of store path to or from a remote + machine via `ssh`. + + - A new kind of string literal: strings between double single-quotes + (`''`) have indentation “intelligently” removed. This allows large + strings (such as shell scripts or configuration file fragments in + NixOS) to cleanly follow the indentation of the surrounding + expression. It also requires much less escaping, since `''` is less + common in most languages than `"`. + + - `nix-env` `--set` modifies the current generation of a profile so + that it contains exactly the specified derivation, and nothing else. + For example, `nix-env -p /nix/var/nix/profiles/browser --set + firefox` lets the profile named `browser` contain just Firefox. + + - `nix-env` now maintains meta-information about installed packages in + profiles. The meta-information is the contents of the `meta` + attribute of derivations, such as `description` or `homepage`. The + command `nix-env -q --xml + --meta` shows all meta-information. + + - `nix-env` now uses the `meta.priority` attribute of derivations to + resolve filename collisions between packages. Lower priority values + denote a higher priority. For instance, the GCC wrapper package and + the Binutils package in Nixpkgs both have a file `bin/ld`, so + previously if you tried to install both you would get a collision. + Now, on the other hand, the GCC wrapper declares a higher priority + than Binutils, so the former’s `bin/ld` is symlinked in the user + environment. + + - `nix-env -i / -u`: instead of breaking package ties by version, + break them by priority and version number. That is, if there are + multiple packages with the same name, then pick the package with the + highest priority, and only use the version if there are multiple + packages with the same priority. + + This makes it possible to mark specific versions/variant in Nixpkgs + more or less desirable than others. A typical example would be a + beta version of some package (e.g., `gcc-4.2.0rc1`) which should not + be installed even though it is the highest version, except when it + is explicitly selected (e.g., `nix-env -i + gcc-4.2.0rc1`). + + - `nix-env --set-flag` allows meta attributes of installed packages to + be modified. There are several attributes that can be usefully + modified, because they affect the behaviour of `nix-env` or the user + environment build script: + + - `meta.priority` can be changed to resolve filename clashes (see + above). + + - `meta.keep` can be set to `true` to prevent the package from + being upgraded or replaced. Useful if you want to hang on to an + older version of a package. + + - `meta.active` can be set to `false` to “disable” the package. + That is, no symlinks will be generated to the files of the + package, but it remains part of the profile (so it won’t be + garbage-collected). Set it back to `true` to re-enable the + package. + + - `nix-env -q` now has a flag `--prebuilt-only` (`-b`) that causes + `nix-env` to show only those derivations whose output is already in + the Nix store or that can be substituted (i.e., downloaded from + somewhere). In other words, it shows the packages that can be + installed “quickly”, i.e., don’t need to be built from source. The + `-b` flag is also available in `nix-env -i` and `nix-env -u` to + filter out derivations for which no pre-built binary is available. + + - The new option `--argstr` (in `nix-env`, `nix-instantiate` and + `nix-build`) is like `--arg`, except that the value is a string. For + example, `--argstr system + i686-linux` is equivalent to `--arg system + \"i686-linux\"` (note that `--argstr` prevents annoying quoting + around shell arguments). + + - `nix-store` has a new operation `--read-log` (`-l`) `paths` that + shows the build log of the given paths. + + - Nix now uses Berkeley DB 4.5. The database is upgraded + automatically, but you should be careful not to use old versions of + Nix that still use Berkeley DB 4.4. + + - The option `--max-silent-time` (corresponding to the configuration + setting `build-max-silent-time`) allows you to set a timeout on + builds — if a build produces no output on `stdout` or `stderr` for + the given number of seconds, it is terminated. This is useful for + recovering automatically from builds that are stuck in an infinite + loop. + + - `nix-channel`: each subscribed channel is its own attribute in the + top-level expression generated for the channel. This allows + disambiguation (e.g. `nix-env + -i -A nixpkgs_unstable.firefox`). + + - The substitutes table has been removed from the database. This makes + operations such as `nix-pull` and `nix-channel --update` much, much + faster. + + - `nix-pull` now supports bzip2-compressed manifests. This speeds up + channels. + + - `nix-prefetch-url` now has a limited form of caching. This is used + by `nix-channel` to prevent unnecessary downloads when the channel + hasn’t changed. + + - `nix-prefetch-url` now by default computes the SHA-256 hash of the + file instead of the MD5 hash. In calls to `fetchurl` you should pass + the `sha256` attribute instead of `md5`. You can pass either a + hexadecimal or a base-32 encoding of the hash. + + - Nix can now perform builds in an automatically generated “chroot”. + This prevents a builder from accessing stuff outside of the Nix + store, and thus helps ensure purity. This is an experimental + feature. + + - The new command `nix-store + --optimise` reduces Nix store disk space usage by finding identical + files in the store and hard-linking them to each other. It typically + reduces the size of the store by something like 25-35%. + + - `~/.nix-defexpr` can now be a directory, in which case the Nix + expressions in that directory are combined into an attribute set, + with the file names used as the names of the attributes. The command + `nix-env + --import` (which set the `~/.nix-defexpr` symlink) is removed. + + - Derivations can specify the new special attribute + `allowedReferences` to enforce that the references in the output of + a derivation are a subset of a declared set of paths. For example, + if `allowedReferences` is an empty list, then the output must not + have any references. This is used in NixOS to check that generated + files such as initial ramdisks for booting Linux don’t have any + dependencies. + + - The new attribute `exportReferencesGraph` allows builders access to + the references graph of their inputs. This is used in NixOS for + tasks such as generating ISO-9660 images that contain a Nix store + populated with the closure of certain paths. + + - Fixed-output derivations (like `fetchurl`) can define the attribute + `impureEnvVars` to allow external environment variables to be passed + to builders. This is used in Nixpkgs to support proxy configuration, + among other things. + + - Several new built-in functions: `builtins.attrNames`, + `builtins.filterSource`, `builtins.isAttrs`, `builtins.isFunction`, + `builtins.listToAttrs`, `builtins.stringLength`, `builtins.sub`, + `builtins.substring`, `throw`, `builtins.trace`, + `builtins.readFile`. diff --git a/doc/manual/src/release-notes/rl-0.12.md b/doc/manual/src/release-notes/rl-0.12.md new file mode 100644 index 000000000..3a4aba07d --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.12.md @@ -0,0 +1,123 @@ +# Release 0.12 (2008-11-20) + + - Nix no longer uses Berkeley DB to store Nix store metadata. The + principal advantages of the new storage scheme are: it works + properly over decent implementations of NFS (allowing Nix stores to + be shared between multiple machines); no recovery is needed when a + Nix process crashes; no write access is needed for read-only + operations; no more running out of Berkeley DB locks on certain + operations. + + You still need to compile Nix with Berkeley DB support if you want + Nix to automatically convert your old Nix store to the new schema. + If you don’t need this, you can build Nix with the `configure` + option `--disable-old-db-compat`. + + After the automatic conversion to the new schema, you can delete the + old Berkeley DB files: + + $ cd /nix/var/nix/db + $ rm __db* log.* derivers references referrers reserved validpaths DB_CONFIG + + The new metadata is stored in the directories `/nix/var/nix/db/info` + and `/nix/var/nix/db/referrer`. Though the metadata is stored in + human-readable plain-text files, they are not intended to be + human-editable, as Nix is rather strict about the format. + + The new storage schema may or may not require less disk space than + the Berkeley DB environment, mostly depending on the cluster size of + your file system. With 1 KiB clusters (which seems to be the `ext3` + default nowadays) it usually takes up much less space. + + - There is a new substituter that copies paths directly from other + (remote) Nix stores mounted somewhere in the filesystem. For + instance, you can speed up an installation by mounting some remote + Nix store that already has the packages in question via NFS or + `sshfs`. The environment variable `NIX_OTHER_STORES` specifies the + locations of the remote Nix directories, e.g. `/mnt/remote-fs/nix`. + + - New `nix-store` operations `--dump-db` and `--load-db` to dump and + reload the Nix database. + + - The garbage collector has a number of new options to allow only some + of the garbage to be deleted. The option `--max-freed N` tells the + collector to stop after at least *N* bytes have been deleted. The + option `--max-links + N` tells it to stop after the link count on `/nix/store` has dropped + below *N*. This is useful for very large Nix stores on filesystems + with a 32000 subdirectories limit (like `ext3`). The option + `--use-atime` causes store paths to be deleted in order of ascending + last access time. This allows non-recently used stuff to be deleted. + The option `--max-atime time` specifies an upper limit to the last + accessed time of paths that may be deleted. For instance, + + ``` + $ nix-store --gc -v --max-atime $(date +%s -d "2 months ago") + ``` + + deletes everything that hasn’t been accessed in two months. + + - `nix-env` now uses optimistic profile locking when performing an + operation like installing or upgrading, instead of setting an + exclusive lock on the profile. This allows multiple `nix-env -i / -u + / -e` operations on the same profile in parallel. If a `nix-env` + operation sees at the end that the profile was changed in the + meantime by another process, it will just restart. This is generally + cheap because the build results are still in the Nix store. + + - The option `--dry-run` is now supported by `nix-store -r` and + `nix-build`. + + - The information previously shown by `--dry-run` (i.e., which + derivations will be built and which paths will be substituted) is + now always shown by `nix-env`, `nix-store -r` and `nix-build`. The + total download size of substitutable paths is now also shown. For + instance, a build will show something like + + the following derivations will be built: + /nix/store/129sbxnk5n466zg6r1qmq1xjv9zymyy7-activate-configuration.sh.drv + /nix/store/7mzy971rdm8l566ch8hgxaf89x7lr7ik-upstart-jobs.drv + ... + the following paths will be downloaded/copied (30.02 MiB): + /nix/store/4m8pvgy2dcjgppf5b4cj5l6wyshjhalj-samba-3.2.4 + /nix/store/7h1kwcj29ip8vk26rhmx6bfjraxp0g4l-libunwind-0.98.6 + ... + + - Language features: + + - @-patterns as in Haskell. For instance, in a function definition + + f = args @ {x, y, z}: ...; + + `args` refers to the argument as a whole, which is further + pattern-matched against the attribute set pattern `{x, y, z}`. + + - “`...`” (ellipsis) patterns. An attribute set pattern can now + say `...` at the end of the attribute name list to specify that + the function takes *at least* the listed attributes, while + ignoring additional attributes. For instance, + + {stdenv, fetchurl, fuse, ...}: ... + + defines a function that accepts any attribute set that includes + at least the three listed attributes. + + - New primops: `builtins.parseDrvName` (split a package name + string like `"nix-0.12pre12876"` into its name and version + components, e.g. `"nix"` and `"0.12pre12876"`), + `builtins.compareVersions` (compare two version strings using + the same algorithm that `nix-env` uses), `builtins.length` + (efficiently compute the length of a list), `builtins.mul` + (integer multiplication), `builtins.div` (integer division). + + - `nix-prefetch-url` now supports `mirror://` URLs, provided that the + environment variable `NIXPKGS_ALL` points at a Nixpkgs tree. + + - Removed the commands `nix-pack-closure` and `nix-unpack-closure`. + You can do almost the same thing but much more efficiently by doing + `nix-store --export + $(nix-store -qR paths) > closure` and `nix-store --import < + closure`. + + - Lots of bug fixes, including a big performance bug in the handling + of `with`-expressions. diff --git a/doc/manual/src/release-notes/rl-0.13.md b/doc/manual/src/release-notes/rl-0.13.md new file mode 100644 index 000000000..13a60e01c --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.13.md @@ -0,0 +1,55 @@ +# Release 0.13 (2009-11-05) + +This is primarily a bug fix release. It has some new features: + + - Syntactic sugar for writing nested attribute sets. Instead of + + { + foo = { + bar = 123; + xyzzy = true; + }; + a = { b = { c = "d"; }; }; + } + + you can write + + { + foo.bar = 123; + foo.xyzzy = true; + a.b.c = "d"; + } + + This is useful, for instance, in NixOS configuration files. + + - Support for Nix channels generated by Hydra, the Nix-based + continuous build system. (Hydra generates NAR archives on the fly, + so the size and hash of these archives isn’t known in advance.) + + - Support `i686-linux` builds directly on `x86_64-linux` Nix + installations. This is implemented using the `personality()` + syscall, which causes `uname` to return `i686` in child processes. + + - Various improvements to the `chroot` support. Building in a `chroot` + works quite well now. + + - Nix no longer blocks if it tries to build a path and another process + is already building the same path. Instead it tries to build another + buildable path first. This improves parallelism. + + - Support for large (\> 4 GiB) files in NAR archives. + + - Various (performance) improvements to the remote build mechanism. + + - New primops: `builtins.addErrorContext` (to add a string to stack + traces — useful for debugging), `builtins.isBool`, + `builtins.isString`, `builtins.isInt`, `builtins.intersectAttrs`. + + - OpenSolaris support (Sander van der Burg). + + - Stack traces are no longer displayed unless the `--show-trace` + option is used. + + - The scoping rules for `inherit + (e) ...` in recursive attribute sets have changed. The expression + *e* can now refer to the attributes defined in the containing set. diff --git a/doc/manual/src/release-notes/rl-0.14.md b/doc/manual/src/release-notes/rl-0.14.md new file mode 100644 index 000000000..9d58f2072 --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.14.md @@ -0,0 +1,21 @@ +# Release 0.14 (2010-02-04) + +This release has the following improvements: + + - The garbage collector now starts deleting garbage much faster than + before. It no longer determines liveness of all paths in the store, + but does so on demand. + + - Added a new operation, `nix-store --query + --roots`, that shows the garbage collector roots that directly or + indirectly point to the given store paths. + + - Removed support for converting Berkeley DB-based Nix databases to + the new schema. + + - Removed the `--use-atime` and `--max-atime` garbage collector + options. They were not very useful in practice. + + - On Windows, Nix now requires Cygwin 1.7.x. + + - A few bug fixes. diff --git a/doc/manual/src/release-notes/rl-0.15.md b/doc/manual/src/release-notes/rl-0.15.md new file mode 100644 index 000000000..48e2a6f1b --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.15.md @@ -0,0 +1,5 @@ +# Release 0.15 (2010-03-17) + +This is a bug-fix release. Among other things, it fixes building on Mac +OS X (Snow Leopard), and improves the contents of `/etc/passwd` and +`/etc/group` in `chroot` builds. diff --git a/doc/manual/src/release-notes/rl-0.16.md b/doc/manual/src/release-notes/rl-0.16.md new file mode 100644 index 000000000..23ac53786 --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.16.md @@ -0,0 +1,25 @@ +# Release 0.16 (2010-08-17) + +This release has the following improvements: + + - The Nix expression evaluator is now much faster in most cases: + typically, [3 to 8 times compared to the old + implementation](http://www.mail-archive.com/nix-dev@cs.uu.nl/msg04113.html). + It also uses less memory. It no longer depends on the ATerm library. + + - Support for configurable parallelism inside builders. Build scripts + have always had the ability to perform multiple build actions in + parallel (for instance, by running `make -j + 2`), but this was not desirable because the number of actions to be + performed in parallel was not configurable. Nix now has an option + `--cores + N` as well as a configuration setting `build-cores = + N` that causes the environment variable `NIX_BUILD_CORES` to be set + to *N* when the builder is invoked. The builder can use this at its + discretion to perform a parallel build, e.g., by calling `make -j + N`. In Nixpkgs, this can be enabled on a per-package basis by + setting the derivation attribute `enableParallelBuilding` to `true`. + + - `nix-store -q` now supports XML output through the `--xml` flag. + + - Several bug fixes. diff --git a/doc/manual/src/release-notes/rl-0.5.md b/doc/manual/src/release-notes/rl-0.5.md new file mode 100644 index 000000000..5cff2da0b --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.5.md @@ -0,0 +1,3 @@ +# Release 0.5 and earlier + +Please refer to the Subversion commit log messages. diff --git a/doc/manual/src/release-notes/rl-0.6.md b/doc/manual/src/release-notes/rl-0.6.md new file mode 100644 index 000000000..ed2d21583 --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.6.md @@ -0,0 +1,64 @@ +# Release 0.6 (2004-11-14) + + - Rewrite of the normalisation engine. + + - Multiple builds can now be performed in parallel (option `-j`). + + - Distributed builds. Nix can now call a shell script to forward + builds to Nix installations on remote machines, which may or may + not be of the same platform type. + + - Option `--fallback` allows recovery from broken substitutes. + + - Option `--keep-going` causes building of other (unaffected) + derivations to continue if one failed. + + - Improvements to the garbage collector (i.e., it should actually work + now). + + - Setuid Nix installations allow a Nix store to be shared among + multiple users. + + - Substitute registration is much faster now. + + - A utility `nix-build` to build a Nix expression and create a symlink + to the result int the current directory; useful for testing Nix + derivations. + + - Manual updates. + + - `nix-env` changes: + + - Derivations for other platforms are filtered out (which can be + overridden using `--system-filter`). + + - `--install` by default now uninstall previous derivations with + the same name. + + - `--upgrade` allows upgrading to a specific version. + + - New operation `--delete-generations` to remove profile + generations (necessary for effective garbage collection). + + - Nicer output (sorted, columnised). + + - More sensible verbosity levels all around (builder output is now + shown always, unless `-Q` is given). + + - Nix expression language changes: + + - New language construct: `with + E1; + E2` brings all attributes defined in the attribute set *E1* in + scope in *E2*. + + - Added a `map` function. + + - Various new operators (e.g., string concatenation). + + - Expression evaluation is much faster. + + - An Emacs mode for editing Nix expressions (with syntax highlighting + and indentation) has been added. + + - Many bug fixes. diff --git a/doc/manual/src/release-notes/rl-0.7.md b/doc/manual/src/release-notes/rl-0.7.md new file mode 100644 index 000000000..d873fe890 --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.7.md @@ -0,0 +1,21 @@ +# Release 0.7 (2005-01-12) + + - Binary patching. When upgrading components using pre-built binaries + (through nix-pull / nix-channel), Nix can automatically download and + apply binary patches to already installed components instead of full + downloads. Patching is “smart”: if there is a *sequence* of patches + to an installed component, Nix will use it. Patches are currently + generated automatically between Nixpkgs (pre-)releases. + + - Simplifications to the substitute mechanism. + + - Nix-pull now stores downloaded manifests in + `/nix/var/nix/manifests`. + + - Metadata on files in the Nix store is canonicalised after builds: + the last-modified timestamp is set to 0 (00:00:00 1/1/1970), the + mode is set to 0444 or 0555 (readable and possibly executable by + all; setuid/setgid bits are dropped), and the group is set to the + default. This ensures that the result of a build and an installation + through a substitute is the same; and that timestamp dependencies + are revealed. diff --git a/doc/manual/src/release-notes/rl-0.8.1.md b/doc/manual/src/release-notes/rl-0.8.1.md new file mode 100644 index 000000000..7629f81cb --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.8.1.md @@ -0,0 +1,8 @@ +# Release 0.8.1 (2005-04-13) + +This is a bug fix release. + + - Patch downloading was broken. + + - The garbage collector would not delete paths that had references + from invalid (but substitutable) paths. diff --git a/doc/manual/src/release-notes/rl-0.8.md b/doc/manual/src/release-notes/rl-0.8.md new file mode 100644 index 000000000..626c0c92b --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.8.md @@ -0,0 +1,166 @@ +# Release 0.8 (2005-04-11) + +NOTE: the hashing scheme in Nix 0.8 changed (as detailed below). As a +result, `nix-pull` manifests and channels built for Nix 0.7 and below +will not work anymore. However, the Nix expression language has not +changed, so you can still build from source. Also, existing user +environments continue to work. Nix 0.8 will automatically upgrade the +database schema of previous installations when it is first run. + +If you get the error message + + you have an old-style manifest `/nix/var/nix/manifests/[...]'; please + delete it + +you should delete previously downloaded manifests: + + $ rm /nix/var/nix/manifests/* + +If `nix-channel` gives the error message + + manifest `http://catamaran.labs.cs.uu.nl/dist/nix/channels/[channel]/MANIFEST' + is too old (i.e., for Nix <= 0.7) + +then you should unsubscribe from the offending channel (`nix-channel +--remove +URL`; leave out `/MANIFEST`), and subscribe to the same URL, with +`channels` replaced by `channels-v3` (e.g., +<http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable>). + +Nix 0.8 has the following improvements: + + - The cryptographic hashes used in store paths are now 160 bits long, + but encoded in base-32 so that they are still only 32 characters + long (e.g., + `/nix/store/csw87wag8bqlqk7ipllbwypb14xainap-atk-1.9.0`). (This is + actually a 160 bit truncation of a SHA-256 hash.) + + - Big cleanups and simplifications of the basic store semantics. The + notion of “closure store expressions” is gone (and so is the notion + of “successors”); the file system references of a store path are now + just stored in the database. + + For instance, given any store path, you can query its closure: + + $ nix-store -qR $(which firefox) + ... lots of paths ... + + Also, Nix now remembers for each store path the derivation that + built it (the “deriver”): + + $ nix-store -qR $(which firefox) + /nix/store/4b0jx7vq80l9aqcnkszxhymsf1ffa5jd-firefox-1.0.1.drv + + So to see the build-time dependencies, you can do + + $ nix-store -qR $(nix-store -qd $(which firefox)) + + or, in a nicer format: + + $ nix-store -q --tree $(nix-store -qd $(which firefox)) + + File system references are also stored in reverse. For instance, you + can query all paths that directly or indirectly use a certain Glibc: + + $ nix-store -q --referrers-closure \ + /nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4 + + - The concept of fixed-output derivations has been formalised. + Previously, functions such as `fetchurl` in Nixpkgs used a hack + (namely, explicitly specifying a store path hash) to prevent changes + to, say, the URL of the file from propagating upwards through the + dependency graph, causing rebuilds of everything. This can now be + done cleanly by specifying the `outputHash` and `outputHashAlgo` + attributes. Nix itself checks that the content of the output has the + specified hash. (This is important for maintaining certain + invariants necessary for future work on secure shared stores.) + + - One-click installation :-) It is now possible to install any + top-level component in Nixpkgs directly, through the web — see, + e.g., <http://catamaran.labs.cs.uu.nl/dist/nixpkgs-0.8/>. All you + have to do is associate `/nix/bin/nix-install-package` with the MIME + type `application/nix-package` (or the extension `.nixpkg`), and + clicking on a package link will cause it to be installed, with all + appropriate dependencies. If you just want to install some specific + application, this is easier than subscribing to a channel. + + - `nix-store -r + PATHS` now builds all the derivations PATHS in parallel. Previously + it did them sequentially (though exploiting possible parallelism + between subderivations). This is nice for build farms. + + - `nix-channel` has new operations `--list` and `--remove`. + + - New ways of installing components into user environments: + + - Copy from another user environment: + + $ nix-env -i --from-profile .../other-profile firefox + + - Install a store derivation directly (bypassing the Nix + expression language entirely): + + $ nix-env -i /nix/store/z58v41v21xd3...-aterm-2.3.1.drv + + (This is used to implement `nix-install-package`, which is + therefore immune to evolution in the Nix expression language.) + + - Install an already built store path directly: + + $ nix-env -i /nix/store/hsyj5pbn0d9i...-aterm-2.3.1 + + - Install the result of a Nix expression specified as a + command-line argument: + + $ nix-env -f .../i686-linux.nix -i -E 'x: x.firefoxWrapper' + + The difference with the normal installation mode is that `-E` + does not use the `name` attributes of derivations. Therefore, + this can be used to disambiguate multiple derivations with the + same name. + + - A hash of the contents of a store path is now stored in the database + after a successful build. This allows you to check whether store + paths have been tampered with: `nix-store + --verify --check-contents`. + + - Implemented a concurrent garbage collector. It is now always safe to + run the garbage collector, even if other Nix operations are + happening simultaneously. + + However, there can still be GC races if you use `nix-instantiate` + and `nix-store + --realise` directly to build things. To prevent races, use the + `--add-root` flag of those commands. + + - The garbage collector now finally deletes paths in the right order + (i.e., topologically sorted under the “references” relation), thus + making it safe to interrupt the collector without risking a store + that violates the closure invariant. + + - Likewise, the substitute mechanism now downloads files in the right + order, thus preserving the closure invariant at all times. + + - The result of `nix-build` is now registered as a root of the garbage + collector. If the `./result` link is deleted, the GC root disappears + automatically. + + - The behaviour of the garbage collector can be changed globally by + setting options in `/nix/etc/nix/nix.conf`. + + - `gc-keep-derivations` specifies whether deriver links should be + followed when searching for live paths. + + - `gc-keep-outputs` specifies whether outputs of derivations + should be followed when searching for live paths. + + - `env-keep-derivations` specifies whether user environments + should store the paths of derivations when they are added (thus + keeping the derivations alive). + + - New `nix-env` query flags `--drv-path` and `--out-path`. + + - `fetchurl` allows SHA-1 and SHA-256 in addition to MD5. Just specify + the attribute `sha1` or `sha256` instead of `md5`. + + - Manual updates. diff --git a/doc/manual/src/release-notes/rl-0.9.1.md b/doc/manual/src/release-notes/rl-0.9.1.md new file mode 100644 index 000000000..9c20eed1b --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.9.1.md @@ -0,0 +1,4 @@ +# Release 0.9.1 (2005-09-20) + +This bug fix release addresses a problem with the ATerm library when the +`--with-aterm` flag in `configure` was *not* used. diff --git a/doc/manual/src/release-notes/rl-0.9.2.md b/doc/manual/src/release-notes/rl-0.9.2.md new file mode 100644 index 000000000..0caaf28de --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.9.2.md @@ -0,0 +1,11 @@ +# Release 0.9.2 (2005-09-21) + +This bug fix release fixes two problems on Mac OS X: + + - If Nix was linked against statically linked versions of the ATerm or + Berkeley DB library, there would be dynamic link errors at runtime. + + - `nix-pull` and `nix-push` intermittently failed due to race + conditions involving pipes and child processes with error messages + such as `open2: open(GLOB(0x180b2e4), >&=9) failed: Bad + file descriptor at /nix/bin/nix-pull line 77` (issue `NIX-14`). diff --git a/doc/manual/src/release-notes/rl-0.9.md b/doc/manual/src/release-notes/rl-0.9.md new file mode 100644 index 000000000..8c3e1b28e --- /dev/null +++ b/doc/manual/src/release-notes/rl-0.9.md @@ -0,0 +1,72 @@ +# Release 0.9 (2005-09-16) + +NOTE: this version of Nix uses Berkeley DB 4.3 instead of 4.2. The +database is upgraded automatically, but you should be careful not to use +old versions of Nix that still use Berkeley DB 4.2. In particular, if +you use a Nix installed through Nix, you should run + + $ nix-store --clear-substitutes + +first. + + - Unpacking of patch sequences is much faster now since we no longer + do redundant unpacking and repacking of intermediate paths. + + - Nix now uses Berkeley DB 4.3. + + - The `derivation` primitive is lazier. Attributes of dependent + derivations can mutually refer to each other (as long as there are + no data dependencies on the `outPath` and `drvPath` attributes + computed by `derivation`). + + For example, the expression `derivation + attrs` now evaluates to (essentially) + + attrs // { + type = "derivation"; + outPath = derivation! attrs; + drvPath = derivation! attrs; + } + + where `derivation!` is a primop that does the actual derivation + instantiation (i.e., it does what `derivation` used to do). The + advantage is that it allows commands such as `nix-env -qa` and + `nix-env -i` to be much faster since they no longer need to + instantiate all derivations, just the `name` attribute. + + Also, it allows derivations to cyclically reference each other, for + example, + + webServer = derivation { + ... + hostName = "svn.cs.uu.nl"; + services = [svnService]; + }; + + svnService = derivation { + ... + hostName = webServer.hostName; + }; + + Previously, this would yield a black hole (infinite recursion). + + - `nix-build` now defaults to using `./default.nix` if no Nix + expression is specified. + + - `nix-instantiate`, when applied to a Nix expression that evaluates + to a function, will call the function automatically if all its + arguments have defaults. + + - Nix now uses libtool to build dynamic libraries. This reduces the + size of executables. + + - A new list concatenation operator `++`. For example, `[1 2 3] ++ + [4 5 + 6]` evaluates to `[1 2 3 4 5 + 6]`. + + - Some currently undocumented primops to support low-level build + management using Nix (i.e., using Nix as a Make replacement). See + the commit messages for `r3578` and `r3580`. + + - Various bug fixes and performance improvements. diff --git a/doc/manual/src/release-notes/rl-1.0.md b/doc/manual/src/release-notes/rl-1.0.md new file mode 100644 index 000000000..cdb257787 --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.0.md @@ -0,0 +1,68 @@ +# Release 1.0 (2012-05-11) + +There have been numerous improvements and bug fixes since the previous +release. Here are the most significant: + + - Nix can now optionally use the Boehm garbage collector. This + significantly reduces the Nix evaluator’s memory footprint, + especially when evaluating large NixOS system configurations. It can + be enabled using the `--enable-gc` configure option. + + - Nix now uses SQLite for its database. This is faster and more + flexible than the old *ad hoc* format. SQLite is also used to cache + the manifests in `/nix/var/nix/manifests`, resulting in a + significant speedup. + + - Nix now has an search path for expressions. The search path is set + using the environment variable `NIX_PATH` and the `-I` command line + option. In Nix expressions, paths between angle brackets are used to + specify files that must be looked up in the search path. For + instance, the expression `<nixpkgs/default.nix>` looks for a file + `nixpkgs/default.nix` relative to every element in the search path. + + - The new command `nix-build --run-env` builds all dependencies of a + derivation, then starts a shell in an environment containing all + variables from the derivation. This is useful for reproducing the + environment of a derivation for development. + + - The new command `nix-store --verify-path` verifies that the contents + of a store path have not changed. + + - The new command `nix-store --print-env` prints out the environment + of a derivation in a format that can be evaluated by a shell. + + - Attribute names can now be arbitrary strings. For instance, you can + write `{ "foo-1.2" = …; "bla bla" = …; }."bla + bla"`. + + - Attribute selection can now provide a default value using the `or` + operator. For instance, the expression `x.y.z or e` evaluates to the + attribute `x.y.z` if it exists, and `e` otherwise. + + - The right-hand side of the `?` operator can now be an attribute + path, e.g., `attrs ? + a.b.c`. + + - On Linux, Nix will now make files in the Nix store immutable on + filesystems that support it. This prevents accidental modification + of files in the store by the root user. + + - Nix has preliminary support for derivations with multiple outputs. + This is useful because it allows parts of a package to be deployed + and garbage-collected separately. For instance, development parts of + a package such as header files or static libraries would typically + not be part of the closure of an application, resulting in reduced + disk usage and installation time. + + - The Nix store garbage collector is faster and holds the global lock + for a shorter amount of time. + + - The option `--timeout` (corresponding to the configuration setting + `build-timeout`) allows you to set an absolute timeout on builds — + if a build runs for more than the given number of seconds, it is + terminated. This is useful for recovering automatically from builds + that are stuck in an infinite loop but keep producing output, and + for which `--max-silent-time` is ineffective. + + - Nix development has moved to GitHub + (<https://github.com/NixOS/nix>). diff --git a/doc/manual/src/release-notes/rl-1.1.md b/doc/manual/src/release-notes/rl-1.1.md new file mode 100644 index 000000000..1e658fe15 --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.1.md @@ -0,0 +1,61 @@ +# Release 1.1 (2012-07-18) + +This release has the following improvements: + + - On Linux, when doing a chroot build, Nix now uses various namespace + features provided by the Linux kernel to improve build isolation. + Namely: + + - The private network namespace ensures that builders cannot talk + to the outside world (or vice versa): each build only sees a + private loopback interface. This also means that two concurrent + builds can listen on the same port (e.g. as part of a test) + without conflicting with each other. + + - The PID namespace causes each build to start as PID 1. Processes + outside of the chroot are not visible to those on the inside. On + the other hand, processes inside the chroot *are* visible from + the outside (though with different PIDs). + + - The IPC namespace prevents the builder from communicating with + outside processes using SysV IPC mechanisms (shared memory, + message queues, semaphores). It also ensures that all IPC + objects are destroyed when the builder exits. + + - The UTS namespace ensures that builders see a hostname of + `localhost` rather than the actual hostname. + + - The private mount namespace was already used by Nix to ensure + that the bind-mounts used to set up the chroot are cleaned up + automatically. + + - Build logs are now compressed using `bzip2`. The command `nix-store + -l` decompresses them on the fly. This can be disabled by setting + the option `build-compress-log` to `false`. + + - The creation of build logs in `/nix/var/log/nix/drvs` can be + disabled by setting the new option `build-keep-log` to `false`. This + is useful, for instance, for Hydra build machines. + + - Nix now reserves some space in `/nix/var/nix/db/reserved` to ensure + that the garbage collector can run successfully if the disk is full. + This is necessary because SQLite transactions fail if the disk is + full. + + - Added a basic `fetchurl` function. This is not intended to replace + the `fetchurl` in Nixpkgs, but is useful for bootstrapping; e.g., it + will allow us to get rid of the bootstrap binaries in the Nixpkgs + source tree and download them instead. You can use it by doing + `import <nix/fetchurl.nix> { url = + url; sha256 = + "hash"; }`. (Shea Levy) + + - Improved RPM spec file. (Michel Alexandre Salim) + + - Support for on-demand socket-based activation in the Nix daemon with + `systemd`. + + - Added a manpage for nix.conf5. + + - When using the Nix daemon, the `-s` flag in `nix-env -qa` is now + much faster. diff --git a/doc/manual/src/release-notes/rl-1.10.md b/doc/manual/src/release-notes/rl-1.10.md new file mode 100644 index 000000000..2bb859536 --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.10.md @@ -0,0 +1,31 @@ +# Release 1.10 (2015-09-03) + +This is primarily a bug fix release. It also has a number of new +features: + + - A number of builtin functions have been added to reduce + Nixpkgs/NixOS evaluation time and memory consumption: `all`, `any`, + `concatStringsSep`, `foldl’`, `genList`, `replaceStrings`, `sort`. + + - The garbage collector is more robust when the disk is full. + + - Nix supports a new API for building derivations that doesn’t require + a `.drv` file to be present on disk; it only requires an in-memory + representation of the derivation. This is used by the Hydra + continuous build system to make remote builds more efficient. + + - The function `<nix/fetchurl.nix>` now uses a *builtin* builder (i.e. + it doesn’t require starting an external process; the download is + performed by Nix itself). This ensures that derivation paths don’t + change when Nix is upgraded, and obviates the need for ugly hacks to + support chroot execution. + + - `--version -v` now prints some configuration information, in + particular what compile-time optional features are enabled, and the + paths of various directories. + + - Build users have their supplementary groups set correctly. + +This release has contributions from Eelco Dolstra, Guillaume Maudoux, +Iwan Aucamp, Jaka Hudoklin, Kirill Elagin, Ludovic Courtès, Manolis +Ragkousis, Nicolas B. Pierron and Shea Levy. diff --git a/doc/manual/src/release-notes/rl-1.11.10.md b/doc/manual/src/release-notes/rl-1.11.10.md new file mode 100644 index 000000000..d1efe1d0b --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.11.10.md @@ -0,0 +1,21 @@ +# Release 1.11.10 (2017-06-12) + +This release fixes a security bug in Nix’s “build user” build isolation +mechanism. Previously, Nix builders had the ability to create setuid +binaries owned by a `nixbld` user. Such a binary could then be used by +an attacker to assume a `nixbld` identity and interfere with subsequent +builds running under the same UID. + +To prevent this issue, Nix now disallows builders to create setuid and +setgid binaries. On Linux, this is done using a seccomp BPF filter. Note +that this imposes a small performance penalty (e.g. 1% when building GNU +Hello). Using seccomp, we now also prevent the creation of extended +attributes and POSIX ACLs since these cannot be represented in the NAR +format and (in the case of POSIX ACLs) allow bypassing regular Nix store +permissions. On macOS, the restriction is implemented using the existing +sandbox mechanism, which now uses a minimal “allow all except the +creation of setuid/setgid binaries” profile when regular sandboxing is +disabled. On other platforms, the “build user” mechanism is now +disabled. + +Thanks go to Linus Heckemann for discovering and reporting this bug. diff --git a/doc/manual/src/release-notes/rl-1.11.md b/doc/manual/src/release-notes/rl-1.11.md new file mode 100644 index 000000000..fbabdaa2f --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.11.md @@ -0,0 +1,87 @@ +# Release 1.11 (2016-01-19) + +This is primarily a bug fix release. It also has a number of new +features: + + - `nix-prefetch-url` can now download URLs specified in a Nix + expression. For example, + + $ nix-prefetch-url -A hello.src + + will prefetch the file specified by the `fetchurl` call in the + attribute `hello.src` from the Nix expression in the current + directory, and print the cryptographic hash of the resulting file on + stdout. This differs from `nix-build -A + hello.src` in that it doesn't verify the hash, and is thus useful + when you’re updating a Nix expression. + + You can also prefetch the result of functions that unpack a tarball, + such as `fetchFromGitHub`. For example: + + $ nix-prefetch-url --unpack https://github.com/NixOS/patchelf/archive/0.8.tar.gz + + or from a Nix expression: + + $ nix-prefetch-url -A nix-repl.src + + - The builtin function `<nix/fetchurl.nix>` now supports downloading + and unpacking NARs. This removes the need to have multiple downloads + in the Nixpkgs stdenv bootstrap process (like a separate busybox + binary for Linux, or curl/mkdir/sh/bzip2 for Darwin). Now all those + files can be combined into a single NAR, optionally compressed using + `xz`. + + - Nix now supports SHA-512 hashes for verifying fixed-output + derivations, and in `builtins.hashString`. + + - The new flag `--option build-repeat + N` will cause every build to be executed *N*+1 times. If the build + output differs between any round, the build is rejected, and the + output paths are not registered as valid. This is primarily useful + to verify build determinism. (We already had a `--check` option to + repeat a previously succeeded build. However, with `--check`, + non-deterministic builds are registered in the DB. Preventing that + is useful for Hydra to ensure that non-deterministic builds don't + end up getting published to the binary cache.) + + - The options `--check` and `--option + build-repeat N`, if they detect a difference between two runs of the + same derivation and `-K` is given, will make the output of the other + run available under `store-path-check`. This makes it easier to + investigate the non-determinism using tools like `diffoscope`, e.g., + + $ nix-build pkgs/stdenv/linux -A stage1.pkgs.zlib --check -K + error: derivation ‘/nix/store/l54i8wlw2265…-zlib-1.2.8.drv’ may not + be deterministic: output ‘/nix/store/11a27shh6n2i…-zlib-1.2.8’ + differs from ‘/nix/store/11a27shh6n2i…-zlib-1.2.8-check’ + + $ diffoscope /nix/store/11a27shh6n2i…-zlib-1.2.8 /nix/store/11a27shh6n2i…-zlib-1.2.8-check + … + ├── lib/libz.a + │ ├── metadata + │ │ @@ -1,15 +1,15 @@ + │ │ -rw-r--r-- 30001/30000 3096 Jan 12 15:20 2016 adler32.o + … + │ │ +rw-r--r-- 30001/30000 3096 Jan 12 15:28 2016 adler32.o + … + + - Improved FreeBSD support. + + - `nix-env -qa --xml --meta` now prints license information. + + - The maximum number of parallel TCP connections that the binary cache + substituter will use has been decreased from 150 to 25. This should + prevent upsetting some broken NAT routers, and also improves + performance. + + - All "chroot"-containing strings got renamed to "sandbox". In + particular, some Nix options got renamed, but the old names are + still accepted as lower-priority aliases. + +This release has contributions from Anders Claesson, Anthony Cowley, +Bjørn Forsman, Brian McKenna, Danny Wilson, davidak, Eelco Dolstra, +Fabian Schmitthenner, FrankHB, Ilya Novoselov, janus, Jim Garrison, John +Ericson, Jude Taylor, Ludovic Courtès, Manuel Jacob, Mathnerd314, Pascal +Wittmann, Peter Simons, Philip Potter, Preston Bennes, Rommel M. +Martinez, Sander van der Burg, Shea Levy, Tim Cuthbertson, Tuomas +Tynkkynen, Utku Demir and Vladimír Čunát. diff --git a/doc/manual/src/release-notes/rl-1.2.md b/doc/manual/src/release-notes/rl-1.2.md new file mode 100644 index 000000000..25b830955 --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.2.md @@ -0,0 +1,97 @@ +# Release 1.2 (2012-12-06) + +This release has the following improvements and changes: + + - Nix has a new binary substituter mechanism: the *binary cache*. A + binary cache contains pre-built binaries of Nix packages. Whenever + Nix wants to build a missing Nix store path, it will check a set of + binary caches to see if any of them has a pre-built binary of that + path. The configuration setting `binary-caches` contains a list of + URLs of binary caches. For instance, doing + + $ nix-env -i thunderbird --option binary-caches http://cache.nixos.org + + will install Thunderbird and its dependencies, using the available + pre-built binaries in <http://cache.nixos.org>. The main advantage + over the old “manifest”-based method of getting pre-built binaries + is that you don’t have to worry about your manifest being in sync + with the Nix expressions you’re installing from; i.e., you don’t + need to run `nix-pull` to update your manifest. It’s also more + scalable because you don’t need to redownload a giant manifest file + every time. + + A Nix channel can provide a binary cache URL that will be used + automatically if you subscribe to that channel. If you use the + Nixpkgs or NixOS channels (<http://nixos.org/channels>) you + automatically get the cache <http://cache.nixos.org>. + + Binary caches are created using `nix-push`. For details on the + operation and format of binary caches, see the `nix-push` manpage. + More details are provided in [this nix-dev + posting](https://nixos.org/nix-dev/2012-September/009826.html). + + - Multiple output support should now be usable. A derivation can + declare that it wants to produce multiple store paths by saying + something like + + outputs = [ "lib" "headers" "doc" ]; + + This will cause Nix to pass the intended store path of each output + to the builder through the environment variables `lib`, `headers` + and `doc`. Other packages can refer to a specific output by + referring to `pkg.output`, e.g. + + buildInputs = [ pkg.lib pkg.headers ]; + + If you install a package with multiple outputs using `nix-env`, each + output path will be symlinked into the user environment. + + - Dashes are now valid as part of identifiers and attribute names. + + - The new operation `nix-store --repair-path` allows corrupted or + missing store paths to be repaired by redownloading them. `nix-store + --verify --check-contents + --repair` will scan and repair all paths in the Nix store. + Similarly, `nix-env`, `nix-build`, `nix-instantiate` and `nix-store + --realise` have a `--repair` flag to detect and fix bad paths by + rebuilding or redownloading them. + + - Nix no longer sets the immutable bit on files in the Nix store. + Instead, the recommended way to guard the Nix store against + accidental modification on Linux is to make it a read-only bind + mount, like this: + + $ mount --bind /nix/store /nix/store + $ mount -o remount,ro,bind /nix/store + + Nix will automatically make `/nix/store` writable as needed (using a + private mount namespace) to allow modifications. + + - Store optimisation (replacing identical files in the store with hard + links) can now be done automatically every time a path is added to + the store. This is enabled by setting the configuration option + `auto-optimise-store` to `true` (disabled by default). + + - Nix now supports `xz` compression for NARs in addition to `bzip2`. + It compresses about 30% better on typical archives and decompresses + about twice as fast. + + - Basic Nix expression evaluation profiling: setting the environment + variable `NIX_COUNT_CALLS` to `1` will cause Nix to print how many + times each primop or function was executed. + + - New primops: `concatLists`, `elem`, `elemAt` and `filter`. + + - The command `nix-copy-closure` has a new flag `--use-substitutes` + (`-s`) to download missing paths on the target machine using the + substitute mechanism. + + - The command `nix-worker` has been renamed to `nix-daemon`. Support + for running the Nix worker in “slave” mode has been removed. + + - The `--help` flag of every Nix command now invokes `man`. + + - Chroot builds are now supported on systemd machines. + +This release has contributions from Eelco Dolstra, Florian Friesdorf, +Mats Erik Andersson and Shea Levy. diff --git a/doc/manual/src/release-notes/rl-1.3.md b/doc/manual/src/release-notes/rl-1.3.md new file mode 100644 index 000000000..0c7b48380 --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.3.md @@ -0,0 +1,10 @@ +# Release 1.3 (2013-01-04) + +This is primarily a bug fix release. When this version is first run on +Linux, it removes any immutable bits from the Nix store and increases +the schema version of the Nix store. (The previous release removed +support for setting the immutable bit; this release clears any remaining +immutable bits to make certain operations more efficient.) + +This release has contributions from Eelco Dolstra and Stuart +Pernsteiner. diff --git a/doc/manual/src/release-notes/rl-1.4.md b/doc/manual/src/release-notes/rl-1.4.md new file mode 100644 index 000000000..d23de71ad --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.4.md @@ -0,0 +1,22 @@ +# Release 1.4 (2013-02-26) + +This release fixes a security bug in multi-user operation. It was +possible for derivations to cause the mode of files outside of the Nix +store to be changed to 444 (read-only but world-readable) by creating +hard links to those files +([details](https://github.com/NixOS/nix/commit/5526a282b5b44e9296e61e07d7d2626a79141ac4)). + +There are also the following improvements: + + - New built-in function: `builtins.hashString`. + + - Build logs are now stored in `/nix/var/log/nix/drvs/XX/`, where *XX* + is the first two characters of the derivation. This is useful on + machines that keep a lot of build logs (such as Hydra servers). + + - The function `corepkgs/fetchurl` can now make the downloaded file + executable. This will allow getting rid of all bootstrap binaries in + the Nixpkgs source tree. + + - Language change: The expression `"${./path} + ..."` now evaluates to a string instead of a path. diff --git a/doc/manual/src/release-notes/rl-1.5.1.md b/doc/manual/src/release-notes/rl-1.5.1.md new file mode 100644 index 000000000..72b29518e --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.5.1.md @@ -0,0 +1,4 @@ +# Release 1.5.1 (2013-02-28) + +The bug fix to the bug fix had a bug itself, of course. But this time it +will work for sure\! diff --git a/doc/manual/src/release-notes/rl-1.5.2.md b/doc/manual/src/release-notes/rl-1.5.2.md new file mode 100644 index 000000000..508580554 --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.5.2.md @@ -0,0 +1,4 @@ +# Release 1.5.2 (2013-05-13) + +This is primarily a bug fix release. It has contributions from Eelco +Dolstra, Lluís Batlle i Rossell and Shea Levy. diff --git a/doc/manual/src/release-notes/rl-1.5.md b/doc/manual/src/release-notes/rl-1.5.md new file mode 100644 index 000000000..d2ccf8a5d --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.5.md @@ -0,0 +1,4 @@ +# Release 1.5 (2013-02-27) + +This is a brown paper bag release to fix a regression introduced by the +hard link security fix in 1.4. diff --git a/doc/manual/src/release-notes/rl-1.6.1.md b/doc/manual/src/release-notes/rl-1.6.1.md new file mode 100644 index 000000000..9bb9bb1f8 --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.6.1.md @@ -0,0 +1,32 @@ +# Release 1.6.1 (2013-10-28) + +This is primarily a bug fix release. Changes of interest are: + + - Nix 1.6 accidentally changed the semantics of antiquoted paths in + strings, such as `"${/foo}/bar"`. This release reverts to the Nix + 1.5.3 behaviour. + + - Previously, Nix optimised expressions such as `"${expr}"` to *expr*. + Thus it neither checked whether *expr* could be coerced to a string, + nor applied such coercions. This meant that `"${123}"` evaluatued to + `123`, and `"${./foo}"` evaluated to `./foo` (even though `"${./foo} + "` evaluates to `"/nix/store/hash-foo "`). Nix now checks the type + of antiquoted expressions and applies coercions. + + - Nix now shows the exact position of undefined variables. In + particular, undefined variable errors in a `with` previously didn't + show *any* position information, so this makes it a lot easier to + fix such errors. + + - Undefined variables are now treated consistently. Previously, the + `tryEval` function would catch undefined variables inside a `with` + but not outside. Now `tryEval` never catches undefined variables. + + - Bash completion in `nix-shell` now works correctly. + + - Stack traces are less verbose: they no longer show calls to builtin + functions and only show a single line for each derivation on the + call stack. + + - New built-in function: `builtins.typeOf`, which returns the type of + its argument as a string. diff --git a/doc/manual/src/release-notes/rl-1.6.md b/doc/manual/src/release-notes/rl-1.6.md new file mode 100644 index 000000000..9b83d9274 --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.6.md @@ -0,0 +1,72 @@ +# Release 1.6 (2013-09-10) + +In addition to the usual bug fixes, this release has several new +features: + + - The command `nix-build --run-env` has been renamed to `nix-shell`. + + - `nix-shell` now sources `$stdenv/setup` *inside* the interactive + shell, rather than in a parent shell. This ensures that shell + functions defined by `stdenv` can be used in the interactive shell. + + - `nix-shell` has a new flag `--pure` to clear the environment, so you + get an environment that more closely corresponds to the “real” Nix + build. + + - `nix-shell` now sets the shell prompt (`PS1`) to ensure that Nix + shells are distinguishable from your regular shells. + + - `nix-env` no longer requires a `*` argument to match all packages, + so `nix-env -qa` is equivalent to `nix-env + -qa '*'`. + + - `nix-env -i` has a new flag `--remove-all` (`-r`) to remove all + previous packages from the profile. This makes it easier to do + declarative package management similar to NixOS’s + `environment.systemPackages`. For instance, if you have a + specification `my-packages.nix` like this: + + with import <nixpkgs> {}; + [ thunderbird + geeqie + ... + ] + + then after any change to this file, you can run: + + $ nix-env -f my-packages.nix -ir + + to update your profile to match the specification. + + - The ‘`with`’ language construct is now more lazy. It only evaluates + its argument if a variable might actually refer to an attribute in + the argument. For instance, this now works: + + let + pkgs = with pkgs; { foo = "old"; bar = foo; } // overrides; + overrides = { foo = "new"; }; + in pkgs.bar + + This evaluates to `"new"`, while previously it gave an “infinite + recursion” error. + + - Nix now has proper integer arithmetic operators. For instance, you + can write `x + y` instead of `builtins.add x y`, or `x < + y` instead of `builtins.lessThan x y`. The comparison operators also + work on strings. + + - On 64-bit systems, Nix integers are now 64 bits rather than 32 bits. + + - When using the Nix daemon, the `nix-daemon` worker process now runs + on the same CPU as the client, on systems that support setting CPU + affinity. This gives a significant speedup on some systems. + + - If a stack overflow occurs in the Nix evaluator, you now get a + proper error message (rather than “Segmentation fault”) on some + systems. + + - In addition to directories, you can now bind-mount regular files in + chroots through the (now misnamed) option `build-chroot-dirs`. + +This release has contributions from Domen Kožar, Eelco Dolstra, Florian +Friesdorf, Gergely Risko, Ivan Kozik, Ludovic Courtès and Shea Levy. diff --git a/doc/manual/src/release-notes/rl-1.7.md b/doc/manual/src/release-notes/rl-1.7.md new file mode 100644 index 000000000..8d49ae54e --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.7.md @@ -0,0 +1,140 @@ +# Release 1.7 (2014-04-11) + +In addition to the usual bug fixes, this release has the following new +features: + + - Antiquotation is now allowed inside of quoted attribute names (e.g. + `set."${foo}"`). In the case where the attribute name is just a + single antiquotation, the quotes can be dropped (e.g. the above + example can be written `set.${foo}`). If an attribute name inside of + a set declaration evaluates to `null` (e.g. `{ ${null} = false; }`), + then that attribute is not added to the set. + + - Experimental support for cryptographically signed binary caches. See + [the commit for + details](https://github.com/NixOS/nix/commit/0fdf4da0e979f992db75cc17376e455ddc5a96d8). + + - An experimental new substituter, `download-via-ssh`, that fetches + binaries from remote machines via SSH. Specifying the flags + `--option + use-ssh-substituter true --option ssh-substituter-hosts + user@hostname` will cause Nix to download binaries from the + specified machine, if it has them. + + - `nix-store -r` and `nix-build` have a new flag, `--check`, that + builds a previously built derivation again, and prints an error + message if the output is not exactly the same. This helps to verify + whether a derivation is truly deterministic. For example: + + $ nix-build '<nixpkgs>' -A patchelf + … + $ nix-build '<nixpkgs>' -A patchelf --check + … + error: derivation `/nix/store/1ipvxs…-patchelf-0.6' may not be deterministic: + hash mismatch in output `/nix/store/4pc1dm…-patchelf-0.6.drv' + + - The `nix-instantiate` flags `--eval-only` and `--parse-only` have + been renamed to `--eval` and `--parse`, respectively. + + - `nix-instantiate`, `nix-build` and `nix-shell` now have a flag + `--expr` (or `-E`) that allows you to specify the expression to be + evaluated as a command line argument. For instance, `nix-instantiate + --eval -E + '1 + 2'` will print `3`. + + - `nix-shell` improvements: + + - It has a new flag, `--packages` (or `-p`), that sets up a build + environment containing the specified packages from Nixpkgs. For + example, the command + + $ nix-shell -p sqlite xorg.libX11 hello + + will start a shell in which the given packages are present. + + - It now uses `shell.nix` as the default expression, falling back + to `default.nix` if the former doesn’t exist. This makes it + convenient to have a `shell.nix` in your project to set up a + nice development environment. + + - It evaluates the derivation attribute `shellHook`, if set. Since + `stdenv` does not normally execute this hook, it allows you to + do `nix-shell`-specific setup. + + - It preserves the user’s timezone setting. + + - In chroots, Nix now sets up a `/dev` containing only a minimal set + of devices (such as `/dev/null`). Note that it only does this if you + *don’t* have `/dev` listed in your `build-chroot-dirs` setting; + otherwise, it will bind-mount the `/dev` from outside the chroot. + + Similarly, if you don’t have `/dev/pts` listed in + `build-chroot-dirs`, Nix will mount a private `devpts` filesystem on + the chroot’s `/dev/pts`. + + - New built-in function: `builtins.toJSON`, which returns a JSON + representation of a value. + + - `nix-env -q` has a new flag `--json` to print a JSON representation + of the installed or available packages. + + - `nix-env` now supports meta attributes with more complex values, + such as attribute sets. + + - The `-A` flag now allows attribute names with dots in them, e.g. + + $ nix-instantiate --eval '<nixos>' -A 'config.systemd.units."nscd.service".text' + + - The `--max-freed` option to `nix-store --gc` now accepts a unit + specifier. For example, `nix-store --gc --max-freed + 1G` will free up to 1 gigabyte of disk space. + + - `nix-collect-garbage` has a new flag `--delete-older-than` *N*`d`, + which deletes all user environment generations older than *N* days. + Likewise, `nix-env + --delete-generations` accepts a *N*`d` age limit. + + - Nix now heuristically detects whether a build failure was due to a + disk-full condition. In that case, the build is not flagged as + “permanently failed”. This is mostly useful for Hydra, which needs + to distinguish between permanent and transient build failures. + + - There is a new symbol `__curPos` that expands to an attribute set + containing its file name and line and column numbers, e.g. `{ file = + "foo.nix"; line = 10; + column = 5; }`. There also is a new builtin function, + `unsafeGetAttrPos`, that returns the position of an attribute. This + is used by Nixpkgs to provide location information in error + messages, e.g. + + $ nix-build '<nixpkgs>' -A libreoffice --argstr system x86_64-darwin + error: the package ‘libreoffice-4.0.5.2’ in ‘.../applications/office/libreoffice/default.nix:263’ + is not supported on ‘x86_64-darwin’ + + - The garbage collector is now more concurrent with other Nix + processes because it releases certain locks earlier. + + - The binary tarball installer has been improved. You can now install + Nix by running: + + $ bash <(curl https://nixos.org/nix/install) + + - More evaluation errors include position information. For instance, + selecting a missing attribute will print something like + + error: attribute `nixUnstabl' missing, at /etc/nixos/configurations/misc/eelco/mandark.nix:216:15 + + - The command `nix-setuid-helper` is gone. + + - Nix no longer uses Automake, but instead has a non-recursive, GNU + Make-based build system. + + - All installed libraries now have the prefix `libnix`. In particular, + this gets rid of `libutil`, which could clash with libraries with + the same name from other packages. + + - Nix now requires a compiler that supports C++11. + +This release has contributions from Danny Wilson, Domen Kožar, Eelco +Dolstra, Ian-Woo Kim, Ludovic Courtès, Maxim Ivanov, Petr Rockai, +Ricardo M. Correia and Shea Levy. diff --git a/doc/manual/src/release-notes/rl-1.8.md b/doc/manual/src/release-notes/rl-1.8.md new file mode 100644 index 000000000..59af363e8 --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.8.md @@ -0,0 +1,88 @@ +# Release 1.8 (2014-12-14) + + - Breaking change: to address a race condition, the remote build hook + mechanism now uses `nix-store + --serve` on the remote machine. This requires build slaves to be + updated to Nix 1.8. + + - Nix now uses HTTPS instead of HTTP to access the default binary + cache, `cache.nixos.org`. + + - `nix-env` selectors are now regular expressions. For instance, you + can do + + $ nix-env -qa '.*zip.*' + + to query all packages with a name containing `zip`. + + - `nix-store --read-log` can now fetch remote build logs. If a build + log is not available locally, then ‘nix-store -l’ will now try to + download it from the servers listed in the ‘log-servers’ option in + nix.conf. For instance, if you have the configuration option + + log-servers = http://hydra.nixos.org/log + + then it will try to get logs from `http://hydra.nixos.org/log/base + name of the + store path`. This allows you to do things like: + + $ nix-store -l $(which xterm) + + and get a log even if `xterm` wasn't built locally. + + - New builtin functions: `attrValues`, `deepSeq`, `fromJSON`, + `readDir`, `seq`. + + - `nix-instantiate --eval` now has a `--json` flag to print the + resulting value in JSON format. + + - `nix-copy-closure` now uses `nix-store --serve` on the remote side + to send or receive closures. This fixes a race condition between + `nix-copy-closure` and the garbage collector. + + - Derivations can specify the new special attribute + `allowedRequisites`, which has a similar meaning to + `allowedReferences`. But instead of only enforcing to explicitly + specify the immediate references, it requires the derivation to + specify all the dependencies recursively (hence the name, + requisites) that are used by the resulting output. + + - On Mac OS X, Nix now handles case collisions when importing closures + from case-sensitive file systems. This is mostly useful for running + NixOps on Mac OS X. + + - The Nix daemon has new configuration options `allowed-users` + (specifying the users and groups that are allowed to connect to the + daemon) and `trusted-users` (specifying the users and groups that + can perform privileged operations like specifying untrusted binary + caches). + + - The configuration option `build-cores` now defaults to the number of + available CPU cores. + + - Build users are now used by default when Nix is invoked as root. + This prevents builds from accidentally running as root. + + - Nix now includes systemd units and Upstart jobs. + + - Speed improvements to `nix-store + --optimise`. + + - Language change: the `==` operator now ignores string contexts (the + “dependencies” of a string). + + - Nix now filters out Nix-specific ANSI escape sequences on standard + error. They are supposed to be invisible, but some terminals show + them anyway. + + - Various commands now automatically pipe their output into the pager + as specified by the `PAGER` environment variable. + + - Several improvements to reduce memory consumption in the evaluator. + +This release has contributions from Adam Szkoda, Aristid Breitkreuz, Bob +van der Linden, Charles Strahan, darealshinji, Eelco Dolstra, Gergely +Risko, Joel Taylor, Ludovic Courtès, Marko Durkovic, Mikey Ariel, Paul +Colomiets, Ricardo M. Correia, Ricky Elrod, Robert Helgesson, Rob +Vermaas, Russell O'Connor, Shea Levy, Shell Turner, Sönke Hahn, Steve +Purcell, Vladimír Čunát and Wout Mertens. diff --git a/doc/manual/src/release-notes/rl-1.9.md b/doc/manual/src/release-notes/rl-1.9.md new file mode 100644 index 000000000..92c6af90b --- /dev/null +++ b/doc/manual/src/release-notes/rl-1.9.md @@ -0,0 +1,143 @@ +# Release 1.9 (2015-06-12) + +In addition to the usual bug fixes, this release has the following new +features: + + - Signed binary cache support. You can enable signature checking by + adding the following to `nix.conf`: + + signed-binary-caches = * + binary-cache-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= + + This will prevent Nix from downloading any binary from the cache + that is not signed by one of the keys listed in + `binary-cache-public-keys`. + + Signature checking is only supported if you built Nix with the + `libsodium` package. + + Note that while Nix has had experimental support for signed binary + caches since version 1.7, this release changes the signature format + in a backwards-incompatible way. + + - Automatic downloading of Nix expression tarballs. In various places, + you can now specify the URL of a tarball containing Nix expressions + (such as Nixpkgs), which will be downloaded and unpacked + automatically. For example: + + - In `nix-env`: + + $ nix-env -f https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox + + This installs Firefox from the latest tested and built revision + of the NixOS 14.12 channel. + + - In `nix-build` and `nix-shell`: + + $ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello + + This builds GNU Hello from the latest revision of the Nixpkgs + master branch. + + - In the Nix search path (as specified via `NIX_PATH` or `-I`). + For example, to start a shell containing the Pan package from a + specific version of Nixpkgs: + + $ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz + + - In `nixos-rebuild` (on NixOS): + + $ nixos-rebuild test -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-unstable.tar.gz + + - In Nix expressions, via the new builtin function `fetchTarball`: + + with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {}; … + + (This is not allowed in restricted mode.) + + - `nix-shell` improvements: + + - `nix-shell` now has a flag `--run` to execute a command in the + `nix-shell` environment, e.g. `nix-shell --run make`. This is + like the existing `--command` flag, except that it uses a + non-interactive shell (ensuring that hitting Ctrl-C won’t drop + you into the child shell). + + - `nix-shell` can now be used as a `#!`-interpreter. This allows + you to write scripts that dynamically fetch their own + dependencies. For example, here is a Haskell script that, when + invoked, first downloads GHC and the Haskell packages on which + it depends: + + #! /usr/bin/env nix-shell + #! nix-shell -i runghc -p haskellPackages.ghc haskellPackages.HTTP + + import Network.HTTP + + main = do + resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/") + body <- getResponseBody resp + print (take 100 body) + + Of course, the dependencies are cached in the Nix store, so the + second invocation of this script will be much faster. + + - Chroot improvements: + + - Chroot builds are now supported on Mac OS X (using its sandbox + mechanism). + + - If chroots are enabled, they are now used for all derivations, + including fixed-output derivations (such as `fetchurl`). The + latter do have network access, but can no longer access the host + filesystem. If you need the old behaviour, you can set the + option `build-use-chroot` to `relaxed`. + + - On Linux, if chroots are enabled, builds are performed in a + private PID namespace once again. (This functionality was lost + in Nix 1.8.) + + - Store paths listed in `build-chroot-dirs` are now automatically + expanded to their closure. For instance, if you want + `/nix/store/…-bash/bin/sh` mounted in your chroot as `/bin/sh`, + you only need to say `build-chroot-dirs = + /bin/sh=/nix/store/…-bash/bin/sh`; it is no longer necessary to + specify the dependencies of Bash. + + - The new derivation attribute `passAsFile` allows you to specify that + the contents of derivation attributes should be passed via files + rather than environment variables. This is useful if you need to + pass very long strings that exceed the size limit of the + environment. The Nixpkgs function `writeTextFile` uses this. + + - You can now use `~` in Nix file names to refer to your home + directory, e.g. `import + ~/.nixpkgs/config.nix`. + + - Nix has a new option `restrict-eval` that allows limiting what paths + the Nix evaluator has access to. By passing `--option restrict-eval + true` to Nix, the evaluator will throw an exception if an attempt is + made to access any file outside of the Nix search path. This is + primarily intended for Hydra to ensure that a Hydra jobset only + refers to its declared inputs (and is therefore reproducible). + + - `nix-env` now only creates a new “generation” symlink in + `/nix/var/nix/profiles` if something actually changed. + + - The environment variable `NIX_PAGER` can now be set to override + `PAGER`. You can set it to `cat` to disable paging for Nix commands + only. + + - Failing `<...>` lookups now show position information. + + - Improved Boehm GC use: we disabled scanning for interior pointers, + which should reduce the “`Repeated + allocation of very large block`” warnings and associated retention + of memory. + +This release has contributions from aszlig, Benjamin Staffin, Charles +Strahan, Christian Theune, Daniel Hahler, Danylo Hlynskyi Daniel +Peebles, Dan Peebles, Domen Kožar, Eelco Dolstra, Harald van Dijk, Hoang +Xuan Phu, Jaka Hudoklin, Jeff Ramnani, j-keck, Linquize, Luca Bruno, +Michael Merickel, Oliver Dunkl, Rob Vermaas, Rok Garbas, Shea Levy, +Tobias Geerinckx-Rice and William A. Kennington III. diff --git a/doc/manual/src/release-notes/rl-2.0.md b/doc/manual/src/release-notes/rl-2.0.md new file mode 100644 index 000000000..9f6d4aa83 --- /dev/null +++ b/doc/manual/src/release-notes/rl-2.0.md @@ -0,0 +1,558 @@ +# Release 2.0 (2018-02-22) + +The following incompatible changes have been made: + + - The manifest-based substituter mechanism + (`download-using-manifests`) has been + [removed](https://github.com/NixOS/nix/commit/867967265b80946dfe1db72d40324b4f9af988ed). + It has been superseded by the binary cache substituter mechanism + since several years. As a result, the following programs have been + removed: + + - `nix-pull` + + - `nix-generate-patches` + + - `bsdiff` + + - `bspatch` + + - The “copy from other stores” substituter mechanism + (`copy-from-other-stores` and the `NIX_OTHER_STORES` environment + variable) has been removed. It was primarily used by the NixOS + installer to copy available paths from the installation medium. The + replacement is to use a chroot store as a substituter (e.g. + `--substituters /mnt`), or to build into a chroot store (e.g. + `--store /mnt --substituters /`). + + - The command `nix-push` has been removed as part of the effort to + eliminate Nix's dependency on Perl. You can use `nix copy` instead, + e.g. `nix copy + --to file:///tmp/my-binary-cache paths…` + + - The “nested” log output feature (`--log-type + pretty`) has been removed. As a result, `nix-log2xml` was also + removed. + + - OpenSSL-based signing has been + [removed](https://github.com/NixOS/nix/commit/f435f8247553656774dd1b2c88e9de5d59cab203). + This feature was never well-supported. A better alternative is + provided by the `secret-key-files` and `trusted-public-keys` + options. + + - Failed build caching has been + [removed](https://github.com/NixOS/nix/commit/8cffec84859cec8b610a2a22ab0c4d462a9351ff). + This feature was introduced to support the Hydra continuous build + system, but Hydra no longer uses it. + + - `nix-mode.el` has been removed from Nix. It is now [a separate + repository](https://github.com/NixOS/nix-mode) and can be installed + through the MELPA package repository. + +This release has the following new features: + + - It introduces a new command named `nix`, which is intended to + eventually replace all `nix-*` commands with a more consistent and + better designed user interface. It currently provides replacements + for some (but not all) of the functionality provided by `nix-store`, + `nix-build`, `nix-shell -p`, `nix-env -qa`, `nix-instantiate + --eval`, `nix-push` and `nix-copy-closure`. It has the following + major features: + + - Unlike the legacy commands, it has a consistent way to refer to + packages and package-like arguments (like store paths). For + example, the following commands all copy the GNU Hello package + to a remote machine: + + nix copy --to ssh://machine nixpkgs.hello + + nix copy --to ssh://machine /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10 + + nix copy --to ssh://machine '(with import <nixpkgs> {}; hello)' + + By contrast, `nix-copy-closure` only accepted store paths as + arguments. + + - It is self-documenting: `--help` shows all available + command-line arguments. If `--help` is given after a subcommand, + it shows examples for that subcommand. `nix + --help-config` shows all configuration options. + + - It is much less verbose. By default, it displays a single-line + progress indicator that shows how many packages are left to be + built or downloaded, and (if there are running builds) the most + recent line of builder output. If a build fails, it shows the + last few lines of builder output. The full build log can be + retrieved using `nix + log`. + + - It + [provides](https://github.com/NixOS/nix/commit/b8283773bd64d7da6859ed520ee19867742a03ba) + all `nix.conf` configuration options as command line flags. For + example, instead of `--option + http-connections 100` you can write `--http-connections 100`. + Boolean options can be written as `--foo` or `--no-foo` (e.g. + `--no-auto-optimise-store`). + + - Many subcommands have a `--json` flag to write results to stdout + in JSON format. + + > **Warning** + > + > Please note that the `nix` command is a work in progress and the + > interface is subject to change. + + It provides the following high-level (“porcelain”) subcommands: + + - `nix build` is a replacement for `nix-build`. + + - `nix run` executes a command in an environment in which the + specified packages are available. It is (roughly) a replacement + for `nix-shell + -p`. Unlike that command, it does not execute the command in a + shell, and has a flag (`-c`) that specifies the unquoted command + line to be executed. + + It is particularly useful in conjunction with chroot stores, + allowing Linux users who do not have permission to install Nix + in `/nix/store` to still use binary substitutes that assume + `/nix/store`. For example, + + nix run --store ~/my-nix nixpkgs.hello -c hello --greeting 'Hi everybody!' + + downloads (or if not substitutes are available, builds) the GNU + Hello package into `~/my-nix/nix/store`, then runs `hello` in a + mount namespace where `~/my-nix/nix/store` is mounted onto + `/nix/store`. + + - `nix search` replaces `nix-env + -qa`. It searches the available packages for occurrences of a + search string in the attribute name, package name or + description. Unlike `nix-env -qa`, it has a cache to speed up + subsequent searches. + + - `nix copy` copies paths between arbitrary Nix stores, + generalising `nix-copy-closure` and `nix-push`. + + - `nix repl` replaces the external program `nix-repl`. It provides + an interactive environment for evaluating and building Nix + expressions. Note that it uses `linenoise-ng` instead of GNU + Readline. + + - `nix upgrade-nix` upgrades Nix to the latest stable version. + This requires that Nix is installed in a profile. (Thus it won’t + work on NixOS, or if it’s installed outside of the Nix store.) + + - `nix verify` checks whether store paths are unmodified and/or + “trusted” (see below). It replaces `nix-store --verify` and + `nix-store + --verify-path`. + + - `nix log` shows the build log of a package or path. If the + build log is not available locally, it will try to obtain it + from the configured substituters (such as + [cache.nixos.org](https://cache.nixos.org/), which now + provides build logs). + + - `nix edit` opens the source code of a package in your editor. + + - `nix eval` replaces `nix-instantiate --eval`. + + - `nix + why-depends` shows why one store path has another in its + closure. This is primarily useful to finding the causes of + closure bloat. For example, + + nix why-depends nixpkgs.vlc nixpkgs.libdrm.dev + + shows a chain of files and fragments of file contents that cause + the VLC package to have the “dev” output of `libdrm` in its + closure — an undesirable situation. + + - `nix path-info` shows information about store paths, replacing + `nix-store -q`. A useful feature is the option `--closure-size` + (`-S`). For example, the following command show the closure + sizes of every path in the current NixOS system closure, sorted + by size: + + nix path-info -rS /run/current-system | sort -nk2 + + - `nix optimise-store` replaces `nix-store --optimise`. The main + difference is that it has a progress indicator. + + A number of low-level (“plumbing”) commands are also available: + + - `nix ls-store` and `nix + ls-nar` list the contents of a store path or NAR file. The + former is primarily useful in conjunction with remote stores, + e.g. + + nix ls-store --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10 + + lists the contents of path in a binary cache. + + - `nix cat-store` and `nix + cat-nar` allow extracting a file from a store path or NAR file. + + - `nix dump-path` writes the contents of a store path to stdout in + NAR format. This replaces `nix-store --dump`. + + - `nix + show-derivation` displays a store derivation in JSON format. + This is an alternative to `pp-aterm`. + + - `nix + add-to-store` replaces `nix-store + --add`. + + - `nix sign-paths` signs store paths. + + - `nix copy-sigs` copies signatures from one store to another. + + - `nix show-config` shows all configuration options and their + current values. + + - The store abstraction that Nix has had for a long time to support + store access via the Nix daemon has been extended + significantly. In particular, substituters (which used to be + external programs such as `download-from-binary-cache`) are now + subclasses of the abstract `Store` class. This allows many Nix + commands to operate on such store types. For example, `nix + path-info` shows information about paths in your local Nix store, + while `nix path-info --store https://cache.nixos.org/` shows + information about paths in the specified binary cache. Similarly, + `nix-copy-closure`, `nix-push` and substitution are all instances + of the general notion of copying paths between different kinds of + Nix stores. + + Stores are specified using an URI-like syntax, e.g. + <https://cache.nixos.org/> or <ssh://machine>. The following store + types are supported: + + - `LocalStore` (stori URI `local` or an absolute path) and the + misnamed `RemoteStore` (`daemon`) provide access to a local Nix + store, the latter via the Nix daemon. You can use `auto` or the + empty string to auto-select a local or daemon store depending on + whether you have write permission to the Nix store. It is no + longer necessary to set the `NIX_REMOTE` environment variable to + use the Nix daemon. + + As noted above, `LocalStore` now supports chroot builds, + allowing the “physical” location of the Nix store (e.g. + `/home/alice/nix/store`) to differ from its “logical” location + (typically `/nix/store`). This allows non-root users to use Nix + while still getting the benefits from prebuilt binaries from + [cache.nixos.org](https://cache.nixos.org/). + + - `BinaryCacheStore` is the abstract superclass of all binary + cache stores. It supports writing build logs and NAR content + listings in JSON format. + + - `HttpBinaryCacheStore` (`http://`, `https://`) supports binary + caches via HTTP or HTTPS. If the server supports `PUT` requests, + it supports uploading store paths via commands such as `nix + copy`. + + - `LocalBinaryCacheStore` (`file://`) supports binary caches in + the local filesystem. + + - `S3BinaryCacheStore` (`s3://`) supports binary caches stored in + Amazon S3, if enabled at compile time. + + - `LegacySSHStore` (`ssh://`) is used to implement remote builds + and `nix-copy-closure`. + + - `SSHStore` (`ssh-ng://`) supports arbitrary Nix operations on a + remote machine via the same protocol used by `nix-daemon`. + + - Security has been improved in various ways: + + - Nix now stores signatures for local store paths. When paths are + copied between stores (e.g., copied from a binary cache to a + local store), signatures are propagated. + + Locally-built paths are signed automatically using the secret + keys specified by the `secret-key-files` store option. + Secret/public key pairs can be generated using `nix-store + --generate-binary-cache-key`. + + In addition, locally-built store paths are marked as “ultimately + trusted”, but this bit is not propagated when paths are copied + between stores. + + - Content-addressable store paths no longer require signatures — + they can be imported into a store by unprivileged users even if + they lack signatures. + + - The command `nix verify` checks whether the specified paths are + trusted, i.e., have a certain number of trusted signatures, are + ultimately trusted, or are content-addressed. + + - Substitutions from binary caches + [now](https://github.com/NixOS/nix/commit/ecbc3fedd3d5bdc5a0e1a0a51b29062f2874ac8b) + require signatures by default. This was already the case on + NixOS. + + - In Linux sandbox builds, we + [now](https://github.com/NixOS/nix/commit/eba840c8a13b465ace90172ff76a0db2899ab11b) + use `/build` instead of `/tmp` as the temporary build directory. + This fixes potential security problems when a build accidentally + stores its `TMPDIR` in some security-sensitive place, such as an + RPATH. + + - *Pure evaluation mode*. With the `--pure-eval` flag, Nix enables a + variant of the existing restricted evaluation mode that forbids + access to anything that could cause different evaluations of the + same command line arguments to produce a different result. This + includes builtin functions such as `builtins.getEnv`, but more + importantly, *all* filesystem or network access unless a content + hash or commit hash is specified. For example, calls to + `builtins.fetchGit` are only allowed if a `rev` attribute is + specified. + + The goal of this feature is to enable true reproducibility and + traceability of builds (including NixOS system configurations) at + the evaluation level. For example, in the future, `nixos-rebuild` + might build configurations from a Nix expression in a Git repository + in pure mode. That expression might fetch other repositories such as + Nixpkgs via `builtins.fetchGit`. The commit hash of the top-level + repository then uniquely identifies a running system, and, in + conjunction with that repository, allows it to be reproduced or + modified. + + - There are several new features to support binary reproducibility + (i.e. to help ensure that multiple builds of the same derivation + produce exactly the same output). When `enforce-determinism` is set + to `false`, it’s [no + longer](https://github.com/NixOS/nix/commit/8bdf83f936adae6f2c907a6d2541e80d4120f051) + a fatal error if build rounds produce different output. Also, a hook + named `diff-hook` is + [provided](https://github.com/NixOS/nix/commit/9a313469a4bdea2d1e8df24d16289dc2a172a169) + to allow you to run tools such as `diffoscope` when build rounds + produce different output. + + - Configuring remote builds is a lot easier now. Provided you are not + using the Nix daemon, you can now just specify a remote build + machine on the command line, e.g. `--option builders + 'ssh://my-mac x86_64-darwin'`. The environment variable + `NIX_BUILD_HOOK` has been removed and is no longer needed. The + environment variable `NIX_REMOTE_SYSTEMS` is still supported for + compatibility, but it is also possible to specify builders in + `nix.conf` by setting the option `builders = + @path`. + + - If a fixed-output derivation produces a result with an incorrect + hash, the output path is moved to the location corresponding to the + actual hash and registered as valid. Thus, a subsequent build of the + fixed-output derivation with the correct hash is unnecessary. + + - `nix-shell` + [now](https://github.com/NixOS/nix/commit/ea59f39326c8e9dc42dfed4bcbf597fbce58797c) + sets the `IN_NIX_SHELL` environment variable during evaluation and + in the shell itself. This can be used to perform different actions + depending on whether you’re in a Nix shell or in a regular build. + Nixpkgs provides `lib.inNixShell` to check this variable during + evaluation. + + - `NIX_PATH` is now lazy, so URIs in the path are only downloaded if + they are needed for evaluation. + + - You can now use `channel:` as a short-hand for + <https://nixos.org/channels//nixexprs.tar.xz>. For example, + `nix-build channel:nixos-15.09 -A hello` will build the GNU Hello + package from the `nixos-15.09` channel. In the future, this may + use Git to fetch updates more efficiently. + + - When `--no-build-output` is given, the last 10 lines of the build + log will be shown if a build fails. + + - Networking has been improved: + + - HTTP/2 is now supported. This makes binary cache lookups [much + more + efficient](https://github.com/NixOS/nix/commit/90ad02bf626b885a5dd8967894e2eafc953bdf92). + + - We now retry downloads on many HTTP errors, making binary caches + substituters more resilient to temporary failures. + + - HTTP credentials can now be configured via the standard `netrc` + mechanism. + + - If S3 support is enabled at compile time, <s3://> URIs are + [supported](https://github.com/NixOS/nix/commit/9ff9c3f2f80ba4108e9c945bbfda2c64735f987b) + in all places where Nix allows URIs. + + - Brotli compression is now supported. In particular, + [cache.nixos.org](https://cache.nixos.org/) build logs are now compressed + using Brotli. + + - `nix-env` + [now](https://github.com/NixOS/nix/commit/b0cb11722626e906a73f10dd9a0c9eea29faf43a) + ignores packages with bad derivation names (in particular those + starting with a digit or containing a dot). + + - Many configuration options have been renamed, either because they + were unnecessarily verbose (e.g. `build-use-sandbox` is now just + `sandbox`) or to reflect generalised behaviour (e.g. `binary-caches` + is now `substituters` because it allows arbitrary store URIs). The + old names are still supported for compatibility. + + - The `max-jobs` option can + [now](https://github.com/NixOS/nix/commit/7251d048fa812d2551b7003bc9f13a8f5d4c95a5) + be set to `auto` to use the number of CPUs in the system. + + - Hashes can + [now](https://github.com/NixOS/nix/commit/c0015e87af70f539f24d2aa2bc224a9d8b84276b) + be specified in base-64 format, in addition to base-16 and the + non-standard base-32. + + - `nix-shell` now uses `bashInteractive` from Nixpkgs, rather than the + `bash` command that happens to be in the caller’s `PATH`. This is + especially important on macOS where the `bash` provided by the + system is seriously outdated and cannot execute `stdenv`’s setup + script. + + - Nix can now automatically trigger a garbage collection if free disk + space drops below a certain level during a build. This is configured + using the `min-free` and `max-free` options. + + - `nix-store -q --roots` and `nix-store --gc --print-roots` now show + temporary and in-memory roots. + + - Nix can now be extended with plugins. See the documentation of the + `plugin-files` option for more details. + +The Nix language has the following new features: + + - It supports floating point numbers. They are based on the C++ + `float` type and are supported by the existing numerical operators. + Export and import to and from JSON and XML works, too. + + - Derivation attributes can now reference the outputs of the + derivation using the `placeholder` builtin function. For example, + the attribute + + configureFlags = "--prefix=${placeholder "out"} --includedir=${placeholder "dev"}"; + + will cause the `configureFlags` environment variable to contain the + actual store paths corresponding to the `out` and `dev` outputs. + +The following builtin functions are new or extended: + + - `builtins.fetchGit` allows Git repositories to be fetched at + evaluation time. Thus it differs from the `fetchgit` function in + Nixpkgs, which fetches at build time and cannot be used to fetch Nix + expressions during evaluation. A typical use case is to import + external NixOS modules from your configuration, e.g. + + imports = [ (builtins.fetchGit https://github.com/edolstra/dwarffs + "/module.nix") ]; + + - Similarly, `builtins.fetchMercurial` allows you to fetch Mercurial + repositories. + + - `builtins.path` generalises `builtins.filterSource` and path + literals (e.g. `./foo`). It allows specifying a store path name that + differs from the source path name (e.g. `builtins.path { path = + ./foo; name = "bar"; + }`) and also supports filtering out unwanted files. + + - `builtins.fetchurl` and `builtins.fetchTarball` now support `sha256` + and `name` attributes. + + - `builtins.split` splits a string using a POSIX extended regular + expression as the separator. + + - `builtins.partition` partitions the elements of a list into two + lists, depending on a Boolean predicate. + + - `<nix/fetchurl.nix>` now uses the content-addressable tarball cache + at <http://tarballs.nixos.org/>, just like `fetchurl` in Nixpkgs. + (f2682e6e18a76ecbfb8a12c17e3a0ca15c084197) + + - In restricted and pure evaluation mode, builtin functions that + download from the network (such as `fetchGit`) are permitted to + fetch underneath a list of URI prefixes specified in the option + `allowed-uris`. + +The Nix build environment has the following changes: + + - Values such as Booleans, integers, (nested) lists and attribute sets + can + [now](https://github.com/NixOS/nix/commit/6de33a9c675b187437a2e1abbcb290981a89ecb1) + be passed to builders in a non-lossy way. If the special attribute + `__structuredAttrs` is set to `true`, the other derivation + attributes are serialised in JSON format and made available to the + builder via the file `.attrs.json` in the builder’s temporary + directory. This obviates the need for `passAsFile` since JSON files + have no size restrictions, unlike process environments. + + [As a convenience to Bash + builders](https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699), + Nix writes a script named `.attrs.sh` to the builder’s directory + that initialises shell variables corresponding to all attributes + that are representable in Bash. This includes non-nested + (associative) arrays. For example, the attribute `hardening.format = + true` ends up as the Bash associative array element + `${hardening[format]}`. + + - Builders can + [now](https://github.com/NixOS/nix/commit/88e6bb76de5564b3217be9688677d1c89101b2a3) + communicate what build phase they are in by writing messages to the + file descriptor specified in `NIX_LOG_FD`. The current phase is + shown by the `nix` progress indicator. + + - In Linux sandbox builds, we + [now](https://github.com/NixOS/nix/commit/a2d92bb20e82a0957067ede60e91fab256948b41) + provide a default `/bin/sh` (namely `ash` from BusyBox). + + - In structured attribute mode, `exportReferencesGraph` + [exports](https://github.com/NixOS/nix/commit/c2b0d8749f7e77afc1c4b3e8dd36b7ee9720af4a) + extended information about closures in JSON format. In particular, + it includes the sizes and hashes of paths. This is primarily useful + for NixOS image builders. + + - Builds are + [now](https://github.com/NixOS/nix/commit/21948deed99a3295e4d5666e027a6ca42dc00b40) + killed as soon as Nix receives EOF on the builder’s stdout or + stderr. This fixes a bug that allowed builds to hang Nix + indefinitely, regardless of timeouts. + + - The `sandbox-paths` configuration option can now specify optional + paths by appending a `?`, e.g. `/dev/nvidiactl?` will bind-mount + `/dev/nvidiactl` only if it exists. + + - On Linux, builds are now executed in a user namespace with UID 1000 + and GID 100. + +A number of significant internal changes were made: + + - Nix no longer depends on Perl and all Perl components have been + rewritten in C++ or removed. The Perl bindings that used to be part + of Nix have been moved to a separate package, `nix-perl`. + + - All `Store` classes are now thread-safe. `RemoteStore` supports + multiple concurrent connections to the daemon. This is primarily + useful in multi-threaded programs such as `hydra-queue-runner`. + +This release has contributions from Adrien Devresse, Alexander Ried, +Alex Cruice, Alexey Shmalko, AmineChikhaoui, Andy Wingo, Aneesh Agrawal, +Anthony Cowley, Armijn Hemel, aszlig, Ben Gamari, Benjamin Hipple, +Benjamin Staffin, Benno Fünfstück, Bjørn Forsman, Brian McKenna, Charles +Strahan, Chase Adams, Chris Martin, Christian Theune, Chris Warburton, +Daiderd Jordan, Dan Connolly, Daniel Peebles, Dan Peebles, davidak, +David McFarland, Dmitry Kalinkin, Domen Kožar, Eelco Dolstra, Emery +Hemingway, Eric Litak, Eric Wolf, Fabian Schmitthenner, Frederik +Rietdijk, Gabriel Gonzalez, Giorgio Gallo, Graham Christensen, Guillaume +Maudoux, Harmen, Iavael, James Broadhead, James Earl Douglas, Janus +Troelsen, Jeremy Shaw, Joachim Schiele, Joe Hermaszewski, Joel Moberg, +Johannes 'fish' Ziemke, Jörg Thalheim, Jude Taylor, kballou, Keshav +Kini, Kjetil Orbekk, Langston Barrett, Linus Heckemann, Ludovic Courtès, +Manav Rathi, Marc Scholten, Markus Hauck, Matt Audesse, Matthew Bauer, +Matthias Beyer, Matthieu Coudron, N1X, Nathan Zadoks, Neil Mayhew, +Nicolas B. Pierron, Niklas Hambüchen, Nikolay Amiantov, Ole Jørgen +Brønner, Orivej Desh, Peter Simons, Peter Stuart, Pyry Jahkola, regnat, +Renzo Carbonara, Rhys, Robert Vollmert, Scott Olson, Scott R. Parish, +Sergei Trofimovich, Shea Levy, Sheena Artrip, Spencer Baugh, Stefan +Junker, Susan Potter, Thomas Tuegel, Timothy Allen, Tristan Hume, Tuomas +Tynkkynen, tv, Tyson Whitehead, Vladimír Čunát, Will Dietz, wmertens, +Wout Mertens, zimbatm and Zoran Plesivčak. diff --git a/doc/manual/src/release-notes/rl-2.1.md b/doc/manual/src/release-notes/rl-2.1.md new file mode 100644 index 000000000..b88834c83 --- /dev/null +++ b/doc/manual/src/release-notes/rl-2.1.md @@ -0,0 +1,49 @@ +# Release 2.1 (2018-09-02) + +This is primarily a bug fix release. It also reduces memory consumption +in certain situations. In addition, it has the following new features: + + - The Nix installer will no longer default to the Multi-User + installation for macOS. You can still instruct the installer to + run in multi-user mode. + + - The Nix installer now supports performing a Multi-User + installation for Linux computers which are running systemd. You + can select a Multi-User installation by passing the `--daemon` + flag to the installer: `sh <(curl https://nixos.org/nix/install) + --daemon`. + + The multi-user installer cannot handle systems with SELinux. If + your system has SELinux enabled, you can force the installer to + run in single-user mode. + + - New builtin functions: `builtins.bitAnd`, `builtins.bitOr`, + `builtins.bitXor`, `builtins.fromTOML`, `builtins.concatMap`, + `builtins.mapAttrs`. + + - The S3 binary cache store now supports uploading NARs larger than 5 + GiB. + + - The S3 binary cache store now supports uploading to S3-compatible + services with the `endpoint` option. + + - The flag `--fallback` is no longer required to recover from + disappeared NARs in binary caches. + + - `nix-daemon` now respects `--store`. + + - `nix run` now respects `nix-support/propagated-user-env-packages`. + +This release has contributions from Adrien Devresse, Aleksandr Pashkov, +Alexandre Esteves, Amine Chikhaoui, Andrew Dunham, Asad Saeeduddin, +aszlig, Ben Challenor, Ben Gamari, Benjamin Hipple, Bogdan Seniuc, Corey +O'Connor, Daiderd Jordan, Daniel Peebles, Daniel Poelzleithner, Danylo +Hlynskyi, Dmitry Kalinkin, Domen Kožar, Doug Beardsley, Eelco Dolstra, +Erik Arvstedt, Félix Baylac-Jacqué, Gleb Peregud, Graham Christensen, +Guillaume Maudoux, Ivan Kozik, John Arnold, Justin Humm, Linus +Heckemann, Lorenzo Manacorda, Matthew Justin Bauer, Matthew O'Gorman, +Maximilian Bosch, Michael Bishop, Michael Fiano, Michael Mercier, +Michael Raskin, Michael Weiss, Nicolas Dudebout, Peter Simons, Ryan +Trinkle, Samuel Dionne-Riel, Sean Seefried, Shea Levy, Symphorien Gibol, +Tim Engler, Tim Sears, Tuomas Tynkkynen, volth, Will Dietz, Yorick van +Pelt and zimbatm. diff --git a/doc/manual/src/release-notes/rl-2.2.md b/doc/manual/src/release-notes/rl-2.2.md new file mode 100644 index 000000000..b67d65db7 --- /dev/null +++ b/doc/manual/src/release-notes/rl-2.2.md @@ -0,0 +1,82 @@ +# Release 2.2 (2019-01-11) + +This is primarily a bug fix release. It also has the following changes: + + - In derivations that use structured attributes (i.e. that specify set + the `__structuredAttrs` attribute to `true` to cause all attributes + to be passed to the builder in JSON format), you can now specify + closure checks per output, e.g.: + + outputChecks."out" = { + # The closure of 'out' must not be larger than 256 MiB. + maxClosureSize = 256 * 1024 * 1024; + + # It must not refer to C compiler or to the 'dev' output. + disallowedRequisites = [ stdenv.cc "dev" ]; + }; + + outputChecks."dev" = { + # The 'dev' output must not be larger than 128 KiB. + maxSize = 128 * 1024; + }; + + - The derivation attribute `requiredSystemFeatures` is now enforced + for local builds, and not just to route builds to remote builders. + The supported features of a machine can be specified through the + configuration setting `system-features`. + + By default, `system-features` includes `kvm` if `/dev/kvm` exists. + For compatibility, it also includes the pseudo-features + `nixos-test`, `benchmark` and `big-parallel` which are used by + Nixpkgs to route builds to particular Hydra build machines. + + - Sandbox builds are now enabled by default on Linux. + + - The new command `nix doctor` shows potential issues with your Nix + installation. + + - The `fetchGit` builtin function now uses a caching scheme that puts + different remote repositories in distinct local repositories, rather + than a single shared repository. This may require more disk space + but is faster. + + - The `dirOf` builtin function now works on relative paths. + + - Nix now supports [SRI hashes](https://www.w3.org/TR/SRI/), allowing + the hash algorithm and hash to be specified in a single string. For + example, you can write: + + import <nix/fetchurl.nix> { + url = https://nixos.org/releases/nix/nix-2.1.3/nix-2.1.3.tar.xz; + hash = "sha256-XSLa0FjVyADWWhFfkZ2iKTjFDda6mMXjoYMXLRSYQKQ="; + }; + + instead of + + import <nix/fetchurl.nix> { + url = https://nixos.org/releases/nix/nix-2.1.3/nix-2.1.3.tar.xz; + sha256 = "5d22dad058d5c800d65a115f919da22938c50dd6ba98c5e3a183172d149840a4"; + }; + + In fixed-output derivations, the `outputHashAlgo` attribute is no + longer mandatory if `outputHash` specifies the hash. + + `nix hash-file` and `nix + hash-path` now print hashes in SRI format by default. They also use + SHA-256 by default instead of SHA-512 because that's what we use + most of the time in Nixpkgs. + + - Integers are now 64 bits on all platforms. + + - The evaluator now prints profiling statistics (enabled via the + `NIX_SHOW_STATS` and `NIX_COUNT_CALLS` environment variables) in + JSON format. + + - The option `--xml` in `nix-store + --query` has been removed. Instead, there now is an option + `--graphml` to output the dependency graph in GraphML format. + + - All `nix-*` commands are now symlinks to `nix`. This saves a bit of + disk space. + + - `nix repl` now uses `libeditline` or `libreadline`. diff --git a/doc/manual/src/release-notes/rl-2.3.md b/doc/manual/src/release-notes/rl-2.3.md new file mode 100644 index 000000000..d1f4e3734 --- /dev/null +++ b/doc/manual/src/release-notes/rl-2.3.md @@ -0,0 +1,44 @@ +# Release 2.3 (2019-09-04) + +This is primarily a bug fix release. However, it makes some incompatible +changes: + + - 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. + +It also has the following changes: + + - `builtins.fetchGit`'s `ref` argument now allows specifying an + absolute remote ref. Nix will automatically prefix `ref` with + `refs/heads` only if `ref` doesn't already begin with `refs/`. + + - The installer now enables sandboxing by default on Linux when the + system has the necessary kernel support. + + - The `max-jobs` setting now defaults to 1. + + - New builtin functions: `builtins.isPath`, `builtins.hashFile`. + + - The `nix` command has a new `--print-build-logs` (`-L`) 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. + + - Builds are now executed in a pseudo-terminal, and the `TERM` + environment variable is set to `xterm-256color`. This allows many + programs (e.g. `gcc`, `clang`, `cmake`) to print colorized log + output. + + - Add `--no-net` convenience flag. This flag disables substituters; + sets the `tarball-ttl` 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. + + - Add a `post-build-hook` setting to run a program after a build has + succeeded. + + - Add a `trace-function-calls` setting to log the duration of Nix + function calls to stderr. |
