aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorBen Burdette <bburdette@gmail.com>2021-09-13 11:57:25 -0600
committerBen Burdette <bburdette@gmail.com>2021-09-13 11:57:25 -0600
commit176911102ce2c0be06bbfed9099f364d71c3c679 (patch)
treee8b0c12410c5126d57313601ba73c0afdc5e8851 /doc
parent310c689d317d1eb4bcf50cd11d84165fe2ffd512 (diff)
printEnvPosChain
Diffstat (limited to 'doc')
-rw-r--r--doc/manual/manual.html8926
-rw-r--r--doc/manual/manual.is-valid0
-rw-r--r--doc/manual/manual.xmli20139
-rw-r--r--doc/manual/src/command-ref/conf-file.md.tmp52
-rw-r--r--doc/manual/src/command-ref/nix.md3021
-rw-r--r--doc/manual/src/expressions/builtins.md.tmp16
-rw-r--r--doc/manual/version.txt1
7 files changed, 32155 insertions, 0 deletions
diff --git a/doc/manual/manual.html b/doc/manual/manual.html
new file mode 100644
index 000000000..2396756ef
--- /dev/null
+++ b/doc/manual/manual.html
@@ -0,0 +1,8926 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Nix Package Manager Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.79.2" /></head><body><div class="book"><div class="titlepage"><div><div><h1 class="title"><a id="idm139733328760992"></a>Nix Package Manager Guide</h1></div><div><h2 class="subtitle">Version 3.0</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Eelco</span> <span class="surname">Dolstra</span></h3></div></div><div><p class="copyright">Copyright © 2004-2018 Eelco Dolstra</p></div></div><hr /></div><div class="toc"><dl class="toc"><dt><span class="part"><a href="#chap-introduction">I. Introduction</a></span></dt><dd><dl><dt><span class="chapter"><a href="#ch-about-nix">1. About Nix</a></span></dt><dt><span class="chapter"><a href="#chap-quick-start">2. Quick Start</a></span></dt></dl></dd><dt><span class="part"><a href="#chap-installation">II. Installation</a></span></dt><dd><dl><dt><span class="chapter"><a href="#ch-supported-platforms">3. Supported Platforms</a></span></dt><dt><span class="chapter"><a href="#ch-installing-binary">4. Installing a Binary Distribution</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-single-user-installation">4.1. Single User Installation</a></span></dt><dt><span class="section"><a href="#sect-multi-user-installation">4.2. Multi User Installation</a></span></dt><dt><span class="section"><a href="#sect-macos-installation">4.3. macOS Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-macos-installation-change-store-prefix">4.3.1. Change the Nix store path prefix</a></span></dt><dt><span class="section"><a href="#sect-macos-installation-encrypted-volume">4.3.2. Use a separate encrypted volume</a></span></dt><dt><span class="section"><a href="#sect-macos-installation-symlink">4.3.3. Symlink the Nix store to a custom location</a></span></dt><dt><span class="section"><a href="#sect-macos-installation-recommended-notes">4.3.4. Notes on the recommended approach</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-nix-install-pinned-version-url">4.4. Installing a pinned Nix version from a URL</a></span></dt><dt><span class="section"><a href="#sect-nix-install-binary-tarball">4.5. Installing from a binary tarball</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ch-installing-source">5. Installing Nix from Source</a></span></dt><dd><dl><dt><span class="section"><a href="#sec-prerequisites-source">5.1. Prerequisites</a></span></dt><dt><span class="section"><a href="#sec-obtaining-source">5.2. Obtaining a Source Distribution</a></span></dt><dt><span class="section"><a href="#sec-building-source">5.3. Building Nix from Source</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ch-nix-security">6. Security</a></span></dt><dd><dl><dt><span class="section"><a href="#sec-single-user">6.1. Single-User Mode</a></span></dt><dt><span class="section"><a href="#ssec-multi-user">6.2. Multi-User Mode</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ch-env-variables">7. Environment Variables</a></span></dt><dd><dl><dt><span class="section"><a href="#sec-nix-ssl-cert-file">7.1. <code class="envar">NIX_SSL_CERT_FILE</code></a></span></dt><dd><dl><dt><span class="section"><a href="#sec-nix-ssl-cert-file-with-nix-daemon-and-macos">7.1.1. <code class="envar">NIX_SSL_CERT_FILE</code> with macOS and the Nix daemon</a></span></dt><dt><span class="section"><a href="#sec-installer-proxy-settings">7.1.2. Proxy Environment Variables</a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="chapter"><a href="#ch-upgrading-nix">8. Upgrading Nix</a></span></dt><dt><span class="part"><a href="#chap-package-management">III. Package Management</a></span></dt><dd><dl><dt><span class="chapter"><a href="#ch-basic-package-mgmt">9. Basic Package Management</a></span></dt><dt><span class="chapter"><a href="#sec-profiles">10. Profiles</a></span></dt><dt><span class="chapter"><a href="#sec-garbage-collection">11. Garbage Collection</a></span></dt><dd><dl><dt><span class="section"><a href="#ssec-gc-roots">11.1. Garbage Collector Roots</a></span></dt></dl></dd><dt><span class="chapter"><a href="#sec-channels">12. Channels</a></span></dt><dt><span class="chapter"><a href="#sec-sharing-packages">13. Sharing Packages Between Machines</a></span></dt><dd><dl><dt><span class="section"><a href="#ssec-binary-cache-substituter">13.1. Serving a Nix store via HTTP</a></span></dt><dt><span class="section"><a href="#ssec-copy-closure">13.2. Copying Closures Via SSH</a></span></dt><dt><span class="section"><a href="#ssec-ssh-substituter">13.3. Serving a Nix store via SSH</a></span></dt><dt><span class="section"><a href="#ssec-s3-substituter">13.4. Serving a Nix store via AWS S3 or S3-compatible Service</a></span></dt><dd><dl><dt><span class="section"><a href="#ssec-s3-substituter-anonymous-reads">13.4.1. Anonymous Reads to your S3-compatible binary cache</a></span></dt><dt><span class="section"><a href="#ssec-s3-substituter-authenticated-reads">13.4.2. Authenticated Reads to your S3 binary cache</a></span></dt><dt><span class="section"><a href="#ssec-s3-substituter-authenticated-writes">13.4.3. Authenticated Writes to your S3-compatible binary cache</a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="part"><a href="#chap-writing-nix-expressions">IV. Writing Nix Expressions</a></span></dt><dd><dl><dt><span class="chapter"><a href="#ch-simple-expression">14. A Simple Nix Expression</a></span></dt><dd><dl><dt><span class="section"><a href="#sec-expression-syntax">14.1. Expression Syntax</a></span></dt><dt><span class="section"><a href="#sec-build-script">14.2. Build Script</a></span></dt><dt><span class="section"><a href="#sec-arguments">14.3. Arguments and Variables</a></span></dt><dt><span class="section"><a href="#sec-building-simple">14.4. Building and Testing</a></span></dt><dt><span class="section"><a href="#sec-generic-builder">14.5. Generic Builder Syntax</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ch-expression-language">15. Nix Expression Language</a></span></dt><dd><dl><dt><span class="section"><a href="#ssec-values">15.1. Values</a></span></dt><dt><span class="section"><a href="#sec-constructs">15.2. Language Constructs</a></span></dt><dt><span class="section"><a href="#sec-language-operators">15.3. Operators</a></span></dt><dt><span class="section"><a href="#ssec-derivation">15.4. Derivations</a></span></dt><dd><dl><dt><span class="section"><a href="#sec-advanced-attributes">15.4.1. Advanced Attributes</a></span></dt></dl></dd><dt><span class="section"><a href="#ssec-builtins">15.5. Built-in Functions</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#part-advanced-topics">V. Advanced Topics</a></span></dt><dd><dl><dt><span class="chapter"><a href="#chap-distributed-builds">16. Remote Builds</a></span></dt><dt><span class="chapter"><a href="#chap-tuning-cores-and-jobs">17. Tuning Cores and Jobs</a></span></dt><dt><span class="chapter"><a href="#chap-diff-hook">18. Verifying Build Reproducibility with <code class="option"><a class="option" href="#conf-diff-hook">diff-hook</a></code></a></span></dt><dd><dl><dt><span class="section"><a href="#idm139733300510624">18.1.
+ Spot-Checking Build Determinism
+ </a></span></dt><dt><span class="section"><a href="#idm139733300495744">18.2.
+ Automatic and Optionally Enforced Determinism Verification
+ </a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-post-build-hook">19. Using the <code class="option"><a class="option" href="#conf-post-build-hook">post-build-hook</a></code></a></span></dt><dd><dl><dt><span class="section"><a href="#chap-post-build-hook-caveats">19.1. Implementation Caveats</a></span></dt><dt><span class="section"><a href="#idm139733300481840">19.2. Prerequisites</a></span></dt><dt><span class="section"><a href="#idm139733300479440">19.3. Set up a Signing Key</a></span></dt><dt><span class="section"><a href="#idm139733300473952">19.4. Implementing the build hook</a></span></dt><dt><span class="section"><a href="#idm139733300467040">19.5. Updating Nix Configuration</a></span></dt><dt><span class="section"><a href="#idm139733300464016">19.6. Testing</a></span></dt><dt><span class="section"><a href="#idm139733300459088">19.7. Conclusion</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#part-command-ref">VI. Command Reference</a></span></dt><dd><dl><dt><span class="chapter"><a href="#sec-common-options">20. Common Options</a></span></dt><dt><span class="chapter"><a href="#sec-common-env">21. Common Environment Variables</a></span></dt><dt><span class="chapter"><a href="#ch-main-commands">22. Main Commands</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="#sec-nix-env">nix-env</a></span><span class="refpurpose"> — manipulate or query Nix user environments</span></dt><dt><span class="refentrytitle"><a href="#sec-nix-build">nix-build</a></span><span class="refpurpose"> — build a Nix expression</span></dt><dt><span class="refentrytitle"><a href="#sec-nix-shell">nix-shell</a></span><span class="refpurpose"> — start an interactive shell based on a Nix expression</span></dt><dt><span class="refentrytitle"><a href="#sec-nix-store">nix-store</a></span><span class="refpurpose"> — manipulate or query the Nix store</span></dt></dl></dd><dt><span class="chapter"><a href="#ch-utilities">23. Utilities</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="#sec-nix-channel">nix-channel</a></span><span class="refpurpose"> — manage Nix channels</span></dt><dt><span class="refentrytitle"><a href="#sec-nix-collect-garbage">nix-collect-garbage</a></span><span class="refpurpose"> — delete unreachable store paths</span></dt><dt><span class="refentrytitle"><a href="#sec-nix-copy-closure">nix-copy-closure</a></span><span class="refpurpose"> — copy a closure to or from a remote machine via SSH</span></dt><dt><span class="refentrytitle"><a href="#sec-nix-daemon">nix-daemon</a></span><span class="refpurpose"> — Nix multi-user support daemon</span></dt><dt><span class="refentrytitle"><a href="#sec-nix-hash">nix-hash</a></span><span class="refpurpose"> — compute the cryptographic hash of a path</span></dt><dt><span class="refentrytitle"><a href="#sec-nix-instantiate">nix-instantiate</a></span><span class="refpurpose"> — instantiate store derivations from Nix expressions</span></dt><dt><span class="refentrytitle"><a href="#sec-nix-prefetch-url">nix-prefetch-url</a></span><span class="refpurpose"> — copy a file from a URL into the store and print its hash</span></dt></dl></dd><dt><span class="chapter"><a href="#ch-files">24. Files</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="#sec-conf-file">nix.conf</a></span><span class="refpurpose"> — Nix configuration file</span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="#part-glossary">A. Glossary</a></span></dt><dt><span class="appendix"><a href="#chap-hacking">B. Hacking</a></span></dt><dt><span class="appendix"><a href="#sec-relnotes">C. Nix Release Notes</a></span></dt><dd><dl><dt><span class="section"><a href="#ssec-relnotes-2.3">C.1. Release 2.3 (2019-09-04)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-2.2">C.2. Release 2.2 (2019-01-11)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-2.1">C.3. Release 2.1 (2018-09-02)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-2.0">C.4. Release 2.0 (2018-02-22)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.11.10">C.5. Release 1.11.10 (2017-06-12)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.11">C.6. Release 1.11 (2016-01-19)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.10">C.7. Release 1.10 (2015-09-03)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.9">C.8. Release 1.9 (2015-06-12)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.8">C.9. Release 1.8 (2014-12-14)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.7">C.10. Release 1.7 (2014-04-11)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.6.1">C.11. Release 1.6.1 (2013-10-28)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.6.0">C.12. Release 1.6 (2013-09-10)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.5.2">C.13. Release 1.5.2 (2013-05-13)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.5">C.14. Release 1.5 (2013-02-27)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.4">C.15. Release 1.4 (2013-02-26)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.3">C.16. Release 1.3 (2013-01-04)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.2">C.17. Release 1.2 (2012-12-06)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.1">C.18. Release 1.1 (2012-07-18)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-1.0">C.19. Release 1.0 (2012-05-11)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-0.16">C.20. Release 0.16 (2010-08-17)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-0.15">C.21. Release 0.15 (2010-03-17)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-0.14">C.22. Release 0.14 (2010-02-04)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-0.13">C.23. Release 0.13 (2009-11-05)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-0.12">C.24. Release 0.12 (2008-11-20)</a></span></dt><dt><span class="section"><a href="#ssec-relnotes-0.11">C.25. Release 0.11 (2007-12-31)</a></span></dt><dt><span class="section"><a href="#ch-relnotes-0.10.1">C.26. Release 0.10.1 (2006-10-11)</a></span></dt><dt><span class="section"><a href="#ch-relnotes-0.10">C.27. Release 0.10 (2006-10-06)</a></span></dt><dt><span class="section"><a href="#ch-relnotes-0.9.2">C.28. Release 0.9.2 (2005-09-21)</a></span></dt><dt><span class="section"><a href="#ch-relnotes-0.9.1">C.29. Release 0.9.1 (2005-09-20)</a></span></dt><dt><span class="section"><a href="#ch-relnotes-0.9">C.30. Release 0.9 (2005-09-16)</a></span></dt><dt><span class="section"><a href="#ch-relnotes-0.8.1">C.31. Release 0.8.1 (2005-04-13)</a></span></dt><dt><span class="section"><a href="#ch-relnotes-0.8">C.32. Release 0.8 (2005-04-11)</a></span></dt><dt><span class="section"><a href="#ch-relnotes-0.7">C.33. Release 0.7 (2005-01-12)</a></span></dt><dt><span class="section"><a href="#ch-relnotes-0.6">C.34. Release 0.6 (2004-11-14)</a></span></dt><dt><span class="section"><a href="#ch-relnotes-0.5">C.35. Release 0.5 and earlier</a></span></dt></dl></dd></dl></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="chap-introduction"></a>Part I. Introduction</h1></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-about-nix"></a>Chapter 1. About Nix</h2></div></div></div><p>Nix is a <span class="emphasis"><em>purely functional package manager</em></span>.
+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 <span class="emphasis"><em>Nix
+store</em></span>, usually the directory
+<code class="filename">/nix/store</code>, where each package has its own unique
+subdirectory such as
+
+</p><pre class="programlisting">
+/nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/
+</pre><p>
+
+where <code class="literal">b6gvzjyb2pg0…</code> 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.</p><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733302010000"></a>Multiple versions</h2></div></div></div><p>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.</p><p>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.</p></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733302007296"></a>Complete dependencies</h2></div></div></div><p>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 <span class="emphasis"><em>your</em></span>
+machine if you have the dependency installed, but not on the end
+user's machine if it's not there.</p><p>Since Nix on the other hand doesn’t install packages in “global”
+locations like <code class="filename">/usr/bin</code> 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
+<code class="filename">/nix/store/5lbfaxb722zp…-openssl-0.9.8d/include</code>,
+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.</p><p>Once a package is built, runtime dependencies are found by
+scanning binaries for the hash parts of Nix store paths (such as
+<code class="literal">r8vvq9kq…</code>). This sounds risky, but it works
+extremely well.</p></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733302002080"></a>Multi-user support</h2></div></div></div><p>Nix has multi-user support. This means that non-privileged
+users can securely install software. Each user can have a different
+<span class="emphasis"><em>profile</em></span>, a set of packages in the Nix store that
+appear in the user’s <code class="envar">PATH</code>. 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.</p></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733301999344"></a>Atomic upgrades and rollbacks</h2></div></div></div><p>Since package management operations never overwrite packages in
+the Nix store but just add new versions in different paths, they are
+<span class="emphasis"><em>atomic</em></span>. 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.</p><p>And since packages aren’t overwritten, the old versions are still
+there after an upgrade. This means that you can <span class="emphasis"><em>roll
+back</em></span> to the old version:</p><pre class="screen">
+$ nix-env --upgrade <em class="replaceable"><code>some-packages</code></em>
+$ nix-env --rollback
+</pre></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733301995248"></a>Garbage collection</h2></div></div></div><p>When you uninstall a package like this…
+
+</p><pre class="screen">
+$ nix-env --uninstall firefox
+</pre><p>
+
+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
+<span class="emphasis"><em>garbage collector</em></span>:
+
+</p><pre class="screen">
+$ nix-collect-garbage
+</pre><p>
+
+This deletes all packages that aren’t in use by any user profile or by
+a currently running program.</p></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733301992112"></a>Functional package language</h2></div></div></div><p>Packages are built from <span class="emphasis"><em>Nix expressions</em></span>,
+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 <span class="emphasis"><em>deterministic</em></span>: building a Nix
+expression twice should yield the same result.</p><p>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.</p></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733301988512"></a>Transparent source/binary deployment</h2></div></div></div><p>Nix expressions generally describe how to build a package from
+source, so an installation action like
+
+</p><pre class="screen">
+$ nix-env --install firefox
+</pre><p>
+
+<span class="emphasis"><em>could</em></span> 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 <span class="emphasis"><em>source deployment
+model</em></span>. 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 <span class="emphasis"><em>binary
+cache</em></span>, a web server that provides pre-built binaries. For
+instance, when asked to build
+<code class="literal">/nix/store/b6gvzjyb2pg0…-firefox-33.1</code> from source,
+Nix would first check if the file
+<code class="uri">https://cache.nixos.org/b6gvzjyb2pg0….narinfo</code> exists, and
+if so, fetch the pre-built binary referenced from there; otherwise, it
+would fall back to building from source.</p></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733301983504"></a>Nix Packages collection</h2></div></div></div><p>We provide a large set of Nix expressions containing hundreds of
+existing Unix packages, the <span class="emphasis"><em>Nix Packages
+collection</em></span> (Nixpkgs).</p></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733301981888"></a>Managing build environments</h2></div></div></div><p>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 <span class="command"><strong>nix-shell</strong></span> 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.</p><p>For example, the following command gets all dependencies of the
+Pan newsreader, as described by <a class="link" href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix" target="_top">its
+Nix expression</a>:</p><pre class="screen">
+$ nix-shell '&lt;nixpkgs&gt;' -A pan
+</pre><p>You’re then dropped into a shell where you can edit, build and test
+the package:</p><pre class="screen">
+[nix-shell]$ tar xf $src
+[nix-shell]$ cd pan-*
+[nix-shell]$ ./configure
+[nix-shell]$ make
+[nix-shell]$ ./pan/gui/pan
+</pre></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733301976352"></a>Portability</h2></div></div></div><p>Nix runs on Linux and macOS.</p></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733301975296"></a>NixOS</h2></div></div></div><p>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
+<code class="filename">/etc</code>). 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 <a class="link" href="http://nixos.org/" target="_top">NixOS homepage</a>.</p></div><div class="simplesect"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733301972848"></a>License</h2></div></div></div><p>Nix is released under the terms of the <a class="link" href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html" target="_top">GNU
+LGPLv2.1 or (at your option) any later version</a>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="chap-quick-start"></a>Chapter 2. Quick Start</h2></div></div></div><p>This chapter is for impatient people who don't like reading
+documentation. For more in-depth information you are kindly referred
+to subsequent chapters.</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Install single-user Nix by running the following:
+
+</p><pre class="screen">
+$ bash &lt;(curl -L https://nixos.org/nix/install)
+</pre><p>
+
+This will install Nix in <code class="filename">/nix</code>. The install script
+will create <code class="filename">/nix</code> using <span class="command"><strong>sudo</strong></span>,
+so make sure you have sufficient rights. (For other installation
+methods, see <a class="xref" href="#chap-installation" title="Part II. Installation">Part II, “Installation”</a>.)</p></li><li class="step"><p>See what installable packages are currently available
+in the channel:
+
+</p><pre class="screen">
+$ nix-env -qa
+docbook-xml-4.3
+docbook-xml-4.5
+firefox-33.0.2
+hello-2.9
+libxslt-1.1.28
+<em class="replaceable"><code>...</code></em></pre><p>
+
+</p></li><li class="step"><p>Install some packages from the channel:
+
+</p><pre class="screen">
+$ nix-env -i hello</pre><p>
+
+This should download pre-built packages; it should not build them
+locally (if it does, something went wrong).</p></li><li class="step"><p>Test that they work:
+
+</p><pre class="screen">
+$ which hello
+/home/eelco/.nix-profile/bin/hello
+$ hello
+Hello, world!
+</pre><p>
+
+</p></li><li class="step"><p>Uninstall a package:
+
+</p><pre class="screen">
+$ nix-env -e hello</pre><p>
+
+</p></li><li class="step"><p>You can also test a package without installing it:
+
+</p><pre class="screen">
+$ nix-shell -p hello
+</pre><p>
+
+This builds or downloads GNU Hello and its dependencies, then drops
+you into a Bash shell where the <span class="command"><strong>hello</strong></span> command is
+present, all without affecting your normal environment:
+
+</p><pre class="screen">
+[nix-shell:~]$ hello
+Hello, world!
+
+[nix-shell:~]$ exit
+
+$ hello
+hello: command not found
+</pre><p>
+
+</p></li><li class="step"><p>To keep up-to-date with the channel, do:
+
+</p><pre class="screen">
+$ nix-channel --update nixpkgs
+$ nix-env -u '*'</pre><p>
+
+The latter command will upgrade each installed package for which there
+is a “newer” version (as determined by comparing the version
+numbers).</p></li><li class="step"><p>If you're unhappy with the result of a
+<span class="command"><strong>nix-env</strong></span> action (e.g., an upgraded package turned
+out not to work properly), you can go back:
+
+</p><pre class="screen">
+$ nix-env --rollback</pre><p>
+
+</p></li><li class="step"><p>You should periodically run the Nix garbage collector
+to get rid of unused packages, since uninstalls or upgrades don't
+actually delete them:
+
+</p><pre class="screen">
+$ nix-collect-garbage -d</pre><p>
+
+
+
+</p></li></ol></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="chap-installation"></a>Part II. Installation</h1></div></div></div><div class="partintro"><div></div><p>This section describes how to install and configure Nix for first-time use.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-supported-platforms"></a>Chapter 3. Supported Platforms</h2></div></div></div><p>Nix is currently supported on the following platforms:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Linux (i686, x86_64, aarch64).</p></li><li class="listitem"><p>macOS (x86_64).</p></li></ul></div><p>
+
+</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-installing-binary"></a>Chapter 4. Installing a Binary Distribution</h2></div></div></div><p>
+ 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:
+</p><pre class="screen">
+ $ sh &lt;(curl -L https://nixos.org/nix/install)
+</pre><p>
+ If you're using macOS 10.15 (Catalina) or newer, consult
+ <a class="link" href="#sect-macos-installation" title="4.3. macOS Installation">the macOS installation instructions</a>
+ before installing.
+</p><p>
+ 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.
+
+</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sect-single-user-installation"></a>4.1. Single User Installation</h2></div></div></div><p>
+ To explicitly select a single-user installation on your system:
+
+ </p><pre class="screen">
+ sh &lt;(curl -L https://nixos.org/nix/install) --no-daemon
+</pre><p>
+ </p><p>
+This will perform a single-user installation of Nix, meaning that
+<code class="filename">/nix</code> is owned by the invoking user. You should
+run this under your usual user account, <span class="emphasis"><em>not</em></span> as
+root. The script will invoke <span class="command"><strong>sudo</strong></span> to create
+<code class="filename">/nix</code> if it doesn’t already exist. If you don’t
+have <span class="command"><strong>sudo</strong></span>, you should manually create
+<code class="filename">/nix</code> first as root, e.g.:
+
+</p><pre class="screen">
+$ mkdir /nix
+$ chown alice /nix
+</pre><p>
+
+The install script will modify the first writable file from amongst
+<code class="filename">.bash_profile</code>, <code class="filename">.bash_login</code>
+and <code class="filename">.profile</code> to source
+<code class="filename">~/.nix-profile/etc/profile.d/nix.sh</code>. You can set
+the <code class="envar">NIX_INSTALLER_NO_MODIFY_PROFILE</code> environment
+variable before executing the install script to disable this
+behaviour.
+</p><p>You can uninstall Nix simply by running:
+
+</p><pre class="screen">
+$ rm -rf /nix
+</pre><p>
+
+</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sect-multi-user-installation"></a>4.2. Multi User Installation</h2></div></div></div><p>
+ The multi-user Nix installation creates system users, and a system
+ service for the Nix daemon.
+ </p><div class="itemizedlist"><p class="title"><strong>Supported Systems</strong></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Linux running systemd, with SELinux disabled</p></li><li class="listitem"><p>macOS</p></li></ul></div><p>
+ You can instruct the installer to perform a multi-user
+ installation on your system:
+ </p><pre class="screen">sh &lt;(curl -L https://nixos.org/nix/install) --daemon</pre><p>
+ 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,
+ <span class="emphasis"><em>not</em></span> as root. The script will invoke
+ <span class="command"><strong>sudo</strong></span> as needed.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ If you need Nix to use a different group ID or user ID set, you
+ will have to download the tarball manually and <a class="link" href="#sect-nix-install-binary-tarball" title="4.5. Installing from a binary tarball">edit the install
+ script</a>.
+ </p></div><p>
+ The installer will modify <code class="filename">/etc/bashrc</code>, and
+ <code class="filename">/etc/zshrc</code> if they exist. The installer will
+ first back up these files with a
+ <code class="literal">.backup-before-nix</code> extension. The installer
+ will also create <code class="filename">/etc/profile.d/nix.sh</code>.
+ </p><p>You can uninstall Nix with the following commands:
+
+</p><pre class="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
+</pre><p>
+
+ There may also be references to Nix in
+ <code class="filename">/etc/profile</code>,
+ <code class="filename">/etc/bashrc</code>, and
+ <code class="filename">/etc/zshrc</code> which you may remove.
+ </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sect-macos-installation"></a>4.3. macOS Installation</h2></div></div></div><p>
+ Starting with macOS 10.15 (Catalina), the root filesystem is read-only.
+ This means <code class="filename">/nix</code> can no longer live on your system
+ volume, and that you'll need a workaround to install Nix.
+ </p><p>
+ The recommended approach, which creates an unencrypted APFS volume
+ for your Nix store and a "synthetic" empty directory to mount it
+ over at <code class="filename">/nix</code>, is least likely to impair Nix
+ or your system.
+ </p><div class="note"><h3 class="title">Note</h3><p>
+ 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.
+ </p></div><p>
+ If you're using a recent Mac with a
+ <a class="link" href="https://www.apple.com/euro/mac/shared/docs/Apple_T2_Security_Chip_Overview.pdf" target="_top">T2 chip</a>,
+ 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:
+ </p><pre class="screen">$ sh &lt;(curl -L https://nixos.org/nix/install) --darwin-use-unencrypted-nix-store-volume</pre><p>
+ If you don't like the sound of this, you'll want to weigh the
+ other approaches and tradeoffs detailed in this section.
+ </p><div class="note"><h3 class="title">Eventual solutions?</h3><p>
+ 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:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ 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.
+ </p></li><li class="listitem"><p>
+ 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.
+ </p></li></ol></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sect-macos-installation-change-store-prefix"></a>4.3.1. Change the Nix store path prefix</h3></div></div></div><p>
+ 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:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
+ 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.
+ </p></li><li class="listitem"><p>
+ It's harder to build and deploy packages to Linux systems.
+ </p></li></ul></div><p>
+
+
+
+ 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.
+
+ </p><p>
+ </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sect-macos-installation-encrypted-volume"></a>4.3.2. Use a separate encrypted volume</h3></div></div></div><p>
+ 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.
+
+ </p><p>
+ 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:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ The additional volume won't be encrypted with your existing
+ FileVault key, so you'll need another mechanism to decrypt
+ the volume.
+ </p></li><li class="listitem"><p>
+ 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.
+ </p><p>
+ On a case-by-case basis, you may be able to work around this
+ problem by using <span class="command"><strong>wait4path</strong></span> to block
+ execution until your executable is available.
+ </p><p>
+ 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.
+ </p></li><li class="listitem"><p>
+ You can hard-code the password in the clear, so that your
+ store volume can be decrypted before Keychain is available.
+ </p></li></ol></div><p>
+ If you are comfortable navigating these tradeoffs, you can encrypt the volume with
+ something along the lines of:
+
+ </p><pre class="screen">alice$ diskutil apfs enableFileVault /nix -user disk</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sect-macos-installation-symlink"></a>4.3.3. Symlink the Nix store to a custom location</h3></div></div></div><p>
+ Another simple approach is using <code class="filename">/etc/synthetic.conf</code>
+ 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.
+ </p><p>
+ Because of these downsides, we can't recommend this approach.
+ </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sect-macos-installation-recommended-notes"></a>4.3.4. Notes on the recommended approach</h3></div></div></div><p>
+ 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.
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ In order to compose user-writable locations into the new
+ read-only system root, Apple introduced a new concept called
+ <code class="literal">firmlinks</code>, which it describes as a
+ "bi-directional wormhole" between two filesystems. You can
+ see the current firmlinks in <code class="filename">/usr/share/firmlinks</code>.
+ Unfortunately, firmlinks aren't (currently?) user-configurable.
+ </p><p>
+ For special cases like NFS mount points or package manager roots,
+ <a class="link" href="https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man5/synthetic.conf.5.html" target="_top">synthetic.conf(5)</a>
+ supports limited user-controlled file-creation (of symlinks,
+ and synthetic empty directories) at <code class="filename">/</code>.
+ To create a synthetic empty directory for mounting at <code class="filename">/nix</code>,
+ add the following line to <code class="filename">/etc/synthetic.conf</code>
+ (create it if necessary):
+ </p><pre class="screen">nix</pre></li><li class="listitem"><p>
+ This configuration is applied at boot time, but you can use
+ <span class="command"><strong>apfs.util</strong></span> to trigger creation (not deletion)
+ of new entries without a reboot:
+ </p><pre class="screen">alice$ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B</pre></li><li class="listitem"><p>
+ Create the new APFS volume with diskutil:
+ </p><pre class="screen">alice$ sudo diskutil apfs addVolume diskX APFS 'Nix Store' -mountpoint /nix</pre></li><li class="listitem"><p>
+ Using <span class="command"><strong>vifs</strong></span>, add the new mount to
+ <code class="filename">/etc/fstab</code>. If it doesn't already have
+ other entries, it should look something like:
+ </p><pre class="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
+</pre><p>
+ The nobrowse setting will keep Spotlight from indexing this
+ volume, and keep it from showing up on your desktop.
+ </p></li></ol></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sect-nix-install-pinned-version-url"></a>4.4. Installing a pinned Nix version from a URL</h2></div></div></div><p>
+ NixOS.org hosts version-specific installation URLs for all Nix
+ versions since 1.11.16, at
+ <code class="literal">https://releases.nixos.org/nix/nix-<em class="replaceable"><code>version</code></em>/install</code>.
+ </p><p>
+ These install scripts can be used the same as the main
+ NixOS.org installation script:
+
+ </p><pre class="screen">
+ sh &lt;(curl -L https://nixos.org/nix/install)
+</pre><p>
+ </p><p>
+ In the same directory of the install script are sha256 sums, and
+ gpg signature files.
+ </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sect-nix-install-binary-tarball"></a>4.5. Installing from a binary tarball</h2></div></div></div><p>
+ You can also download a binary tarball that contains Nix and all
+ its dependencies. (This is what the install script at
+ <code class="uri">https://nixos.org/nix/install</code> does automatically.) You
+ should unpack it somewhere (e.g. in <code class="filename">/tmp</code>),
+ and then run the script named <span class="command"><strong>install</strong></span> inside
+ the binary tarball:
+
+
+</p><pre class="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
+</pre><p>
+ </p><p>
+ 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
+ <code class="filename">install-multi-user</code>.
+ </p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-installing-source"></a>Chapter 5. Installing Nix from Source</h2></div></div></div><p>If no binary package is available, you can download and compile
+a source distribution.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-prerequisites-source"></a>5.1. Prerequisites</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GNU Autoconf
+ (<a class="link" href="https://www.gnu.org/software/autoconf/" target="_top">https://www.gnu.org/software/autoconf/</a>)
+ and the autoconf-archive macro collection
+ (<a class="link" href="https://www.gnu.org/software/autoconf-archive/" target="_top">https://www.gnu.org/software/autoconf-archive/</a>).
+ These are only needed to run the bootstrap script, and are not necessary
+ if your source distribution came with a pre-built
+ <code class="literal">./configure</code> script.</p></li><li class="listitem"><p>GNU Make.</p></li><li class="listitem"><p>Bash Shell. The <code class="literal">./configure</code> script
+ relies on bashisms, so Bash is required.</p></li><li class="listitem"><p>A version of GCC or Clang that supports C++17.</p></li><li class="listitem"><p><span class="command"><strong>pkg-config</strong></span> to locate
+ dependencies. If your distribution does not provide it, you can get
+ it from <a class="link" href="http://www.freedesktop.org/wiki/Software/pkg-config" target="_top">http://www.freedesktop.org/wiki/Software/pkg-config</a>.</p></li><li class="listitem"><p>The OpenSSL library to calculate cryptographic hashes.
+ If your distribution does not provide it, you can get it from <a class="link" href="https://www.openssl.org" target="_top">https://www.openssl.org</a>.</p></li><li class="listitem"><p>The <code class="literal">libbrotlienc</code> and
+ <code class="literal">libbrotlidec</code> libraries to provide implementation
+ of the Brotli compression algorithm. They are available for download
+ from the official repository <a class="link" href="https://github.com/google/brotli" target="_top">https://github.com/google/brotli</a>.</p></li><li class="listitem"><p>The bzip2 compressor program and the
+ <code class="literal">libbz2</code> library. Thus you must have bzip2
+ installed, including development headers and libraries. If your
+ distribution does not provide these, you can obtain bzip2 from <a class="link" href="https://web.archive.org/web/20180624184756/http://www.bzip.org/" target="_top">https://web.archive.org/web/20180624184756/http://www.bzip.org/</a>.</p></li><li class="listitem"><p><code class="literal">liblzma</code>, which is provided by
+ XZ Utils. If your distribution does not provide this, you can
+ get it from <a class="link" href="https://tukaani.org/xz/" target="_top">https://tukaani.org/xz/</a>.</p></li><li class="listitem"><p>cURL and its library. If your distribution does not
+ provide it, you can get it from <a class="link" href="https://curl.haxx.se/" target="_top">https://curl.haxx.se/</a>.</p></li><li class="listitem"><p>The SQLite embedded database library, version 3.6.19
+ or higher. If your distribution does not provide it, please install
+ it from <a class="link" href="http://www.sqlite.org/" target="_top">http://www.sqlite.org/</a>.</p></li><li class="listitem"><p>The <a class="link" href="http://www.hboehm.info/gc/" target="_top">Boehm
+ garbage collector</a> to reduce the evaluator’s memory
+ consumption (optional). To enable it, install
+ <code class="literal">pkgconfig</code> and the Boehm garbage collector, and
+ pass the flag <code class="option">--enable-gc</code> to
+ <span class="command"><strong>configure</strong></span>.</p></li><li class="listitem"><p>The <code class="literal">boost</code> library of version
+ 1.66.0 or higher. It can be obtained from the official web site
+ <a class="link" href="https://www.boost.org/" target="_top">https://www.boost.org/</a>.</p></li><li class="listitem"><p>The <code class="literal">editline</code> library of version
+ 1.14.0 or higher. It can be obtained from the its repository
+ <a class="link" href="https://github.com/troglobit/editline" target="_top">https://github.com/troglobit/editline</a>.</p></li><li class="listitem"><p>The <span class="command"><strong>xmllint</strong></span> and
+ <span class="command"><strong>xsltproc</strong></span> programs to build this manual and the
+ man-pages. These are part of the <code class="literal">libxml2</code> and
+ <code class="literal">libxslt</code> packages, respectively. You also need
+ the <a class="link" href="http://docbook.sourceforge.net/projects/xsl/" target="_top">DocBook
+ XSL stylesheets</a> and optionally the <a class="link" href="http://www.docbook.org/schemas/5x" target="_top"> DocBook 5.0 RELAX NG
+ schemas</a>. Note that these are only required if you modify the
+ manual sources or when you are building from the Git
+ repository.</p></li><li class="listitem"><p>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 <a class="link" href="ftp://alpha.gnu.org/pub/gnu/bison" target="_top">GNU FTP
+ server</a>. For Flex, you need version 2.5.35, which is
+ available on <a class="link" href="http://lex.sourceforge.net/" target="_top">SourceForge</a>.
+ 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.</p></li><li class="listitem"><p>The <code class="literal">libseccomp</code> is used to provide
+ syscall filtering on Linux. This is an optional dependency and can
+ be disabled passing a <code class="option">--disable-seccomp-sandboxing</code>
+ option to the <span class="command"><strong>configure</strong></span> script (Not recommended
+ unless your system doesn't support
+ <code class="literal">libseccomp</code>). To get the library, visit <a class="link" href="https://github.com/seccomp/libseccomp" target="_top">https://github.com/seccomp/libseccomp</a>.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-obtaining-source"></a>5.2. Obtaining a Source Distribution</h2></div></div></div><p>The source tarball of the most recent stable release can be
+downloaded from the <a class="link" href="http://nixos.org/nix/download.html" target="_top">Nix homepage</a>.
+You can also grab the <a class="link" href="http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents" target="_top">most
+recent development release</a>.</p><p>Alternatively, the most recent sources of Nix can be obtained
+from its <a class="link" href="https://github.com/NixOS/nix" target="_top">Git
+repository</a>. For example, the following command will check out
+the latest revision into a directory called
+<code class="filename">nix</code>:</p><pre class="screen">
+$ git clone https://github.com/NixOS/nix</pre><p>Likewise, specific releases can be obtained from the <a class="link" href="https://github.com/NixOS/nix/tags" target="_top">tags</a> of the
+repository.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-building-source"></a>5.3. Building Nix from Source</h2></div></div></div><p>After unpacking or checking out the Nix sources, issue the
+following commands:
+
+</p><pre class="screen">
+$ ./configure <em class="replaceable"><code>options...</code></em>
+$ make
+$ make install</pre><p>
+
+Nix requires GNU Make so you may need to invoke
+<span class="command"><strong>gmake</strong></span> instead.</p><p>When building from the Git repository, these should be preceded
+by the command:
+
+</p><pre class="screen">
+$ ./bootstrap.sh</pre><p>
+
+</p><p>The installation path can be specified by passing the
+<code class="option">--prefix=<em class="replaceable"><code>prefix</code></em></code> to
+<span class="command"><strong>configure</strong></span>. The default installation directory is
+<code class="filename">/usr/local</code>. You can change this to any location
+you like. You must have write permission to the
+<em class="replaceable"><code>prefix</code></em> path.</p><p>Nix keeps its <span class="emphasis"><em>store</em></span> (the place where
+packages are stored) in <code class="filename">/nix/store</code> by default.
+This can be changed using
+<code class="option">--with-store-dir=<em class="replaceable"><code>path</code></em></code>.</p><div class="warning"><h3 class="title">Warning</h3><p>It is best <span class="emphasis"><em>not</em></span> 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.</p></div><p>Nix keeps state (such as its database and log files) in
+<code class="filename">/nix/var</code> by default. This can be changed using
+<code class="option">--localstatedir=<em class="replaceable"><code>path</code></em></code>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-nix-security"></a>Chapter 6. Security</h2></div></div></div><p>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 <code class="systemitem">root</code>) who performs all package
+management operations. All other users can then use the installed
+packages, but they cannot perform package management operations
+themselves.</p><p>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.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-single-user"></a>6.1. Single-User Mode</h2></div></div></div><p>In single-user mode, all Nix operations that access the database
+in <code class="filename"><em class="replaceable"><code>prefix</code></em>/var/nix/db</code>
+or modify the Nix store in
+<code class="filename"><em class="replaceable"><code>prefix</code></em>/store</code> must be
+performed under the user ID that owns those directories. This is
+typically <code class="systemitem">root</code>. (If you
+install from RPM packages, that’s in fact the default ownership.)
+However, on single-user machines, it is often convenient to
+<span class="command"><strong>chown</strong></span> those directories to your normal user account
+so that you don’t have to <span class="command"><strong>su</strong></span> to <code class="systemitem">root</code> all the time.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-multi-user"></a>6.2. Multi-User Mode</h2></div></div></div><p>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.</p><p>To prevent this, the Nix store and database are owned by some
+privileged user (usually <code class="literal">root</code>) and builders are
+executed under special user accounts (usually named
+<code class="literal">nixbld1</code>, <code class="literal">nixbld2</code>, etc.). When a
+unprivileged user runs a Nix command, actions that operate on the Nix
+store (such as builds) are forwarded to a <span class="emphasis"><em>Nix
+daemon</em></span> running under the owner of the Nix store/database
+that performs the operation.</p><div class="note"><h3 class="title">Note</h3><p>Multi-user mode has one important limitation: only
+<code class="systemitem">root</code> and a set of trusted
+users specified in <code class="filename">nix.conf</code> can specify arbitrary
+binary caches. So while unprivileged users may install packages from
+arbitrary Nix expressions, they may not get pre-built
+binaries.</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301775792"></a>Setting up the build users</h3></div></div></div><p>The <span class="emphasis"><em>build users</em></span> are the special UIDs under
+which builds are performed. They should all be members of the
+<span class="emphasis"><em>build users group</em></span> <code class="literal">nixbld</code>.
+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:
+
+</p><pre class="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
+</pre><p>
+
+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.</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301772240"></a>Running the daemon</h3></div></div></div><p>The <a class="link" href="#sec-nix-daemon" title="nix-daemon">Nix daemon</a> should be
+started as follows (as <code class="literal">root</code>):
+
+</p><pre class="screen">
+$ nix-daemon</pre><p>
+
+You’ll want to put that line somewhere in your system’s boot
+scripts.</p><p>To let unprivileged users use the daemon, they should set the
+<a class="link" href="#envar-remote"><code class="envar">NIX_REMOTE</code> environment
+variable</a> to <code class="literal">daemon</code>. So you should put a
+line like
+
+</p><pre class="programlisting">
+export NIX_REMOTE=daemon</pre><p>
+
+into the users’ login scripts.</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301766816"></a>Restricting access</h3></div></div></div><p>To limit which users can perform Nix operations, you can use the
+permissions on the directory
+<code class="filename">/nix/var/nix/daemon-socket</code>. For instance, if you
+want to restrict the use of Nix to the members of a group called
+<code class="literal">nix-users</code>, do
+
+</p><pre class="screen">
+$ chgrp nix-users /nix/var/nix/daemon-socket
+$ chmod ug=rwx,o= /nix/var/nix/daemon-socket
+</pre><p>
+
+This way, users who are not in the <code class="literal">nix-users</code> group
+cannot connect to the Unix domain socket
+<code class="filename">/nix/var/nix/daemon-socket/socket</code>, so they cannot
+perform Nix operations.</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-env-variables"></a>Chapter 7. Environment Variables</h2></div></div></div><p>To use Nix, some environment variables should be set. In
+particular, <code class="envar">PATH</code> should contain the directories
+<code class="filename"><em class="replaceable"><code>prefix</code></em>/bin</code> and
+<code class="filename">~/.nix-profile/bin</code>. The first directory contains
+the Nix tools themselves, while <code class="filename">~/.nix-profile</code> is
+a symbolic link to the current <span class="emphasis"><em>user environment</em></span>
+(an automatically generated package consisting of symlinks to
+installed packages). The simplest way to set the required environment
+variables is to include the file
+<code class="filename"><em class="replaceable"><code>prefix</code></em>/etc/profile.d/nix.sh</code>
+in your <code class="filename">~/.profile</code> (or similar), like this:</p><pre class="screen">
+source <em class="replaceable"><code>prefix</code></em>/etc/profile.d/nix.sh</pre><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-nix-ssl-cert-file"></a>7.1. <code class="envar">NIX_SSL_CERT_FILE</code></h2></div></div></div><p>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
+<code class="envar">NIX_SSL_CERT_FILE</code>.</p><p>If you don't specify a <code class="envar">NIX_SSL_CERT_FILE</code>
+manually, Nix will install and use its own certificate
+bundle.</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Set the environment variable and install Nix</p><pre class="screen">
+$ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt
+$ sh &lt;(curl -L https://nixos.org/nix/install)
+</pre></li><li class="step"><p>In the shell profile and rc files (for example,
+ <code class="filename">/etc/bashrc</code>, <code class="filename">/etc/zshrc</code>),
+ add the following line:</p><pre class="programlisting">
+export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt
+</pre></li></ol></div><div class="note"><h3 class="title">Note</h3><p>You must not add the export and then do the install, as
+the Nix installer will detect the presense of Nix configuration, and
+abort.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-nix-ssl-cert-file-with-nix-daemon-and-macos"></a>7.1.1. <code class="envar">NIX_SSL_CERT_FILE</code> with macOS and the Nix daemon</h3></div></div></div><p>On macOS you must specify the environment variable for the Nix
+daemon service, then restart it:</p><pre class="screen">
+$ sudo launchctl setenv NIX_SSL_CERT_FILE /etc/ssl/my-certificate-bundle.crt
+$ sudo launchctl kickstart -k system/org.nixos.nix-daemon
+</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-installer-proxy-settings"></a>7.1.2. Proxy Environment Variables</h3></div></div></div><p>The Nix installer has special handling for these proxy-related
+environment variables:
+<code class="varname">http_proxy</code>, <code class="varname">https_proxy</code>,
+<code class="varname">ftp_proxy</code>, <code class="varname">no_proxy</code>,
+<code class="varname">HTTP_PROXY</code>, <code class="varname">HTTPS_PROXY</code>,
+<code class="varname">FTP_PROXY</code>, <code class="varname">NO_PROXY</code>.
+</p><p>If any of these variables are set when running the Nix installer,
+then the installer will create an override file at
+<code class="filename">/etc/systemd/system/nix-daemon.service.d/override.conf</code>
+so <span class="command"><strong>nix-daemon</strong></span> will use them.
+</p></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="ch-upgrading-nix"></a>Chapter 8. Upgrading Nix</h1></div></div></div><p>
+ Multi-user Nix users on macOS can upgrade Nix by running:
+ <span class="command"><strong>sudo -i sh -c 'nix-channel --update &amp;&amp;
+ nix-env -iA nixpkgs.nix &amp;&amp;
+ launchctl remove org.nixos.nix-daemon &amp;&amp;
+ launchctl load /Library/LaunchDaemons/org.nixos.nix-daemon.plist'</strong></span>
+ </p><p>
+ Single-user installations of Nix should run this:
+ <span class="command"><strong>nix-channel --update; nix-env -iA nixpkgs.nix nixpkgs.cacert</strong></span>
+ </p><p>
+ Multi-user Nix users on Linux should run this with sudo:
+ <span class="command"><strong>nix-channel --update; nix-env -iA nixpkgs.nix nixpkgs.cacert; systemctl daemon-reload; systemctl restart nix-daemon</strong></span>
+ </p></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="chap-package-management"></a>Part III. Package Management</h1></div></div></div><div class="partintro"><div></div><p>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 <span class="emphasis"><em>create</em></span> packages should consult
+<a class="xref" href="#chap-writing-nix-expressions" title="Part IV. Writing Nix Expressions">Part IV, “Writing Nix Expressions”</a>.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-basic-package-mgmt"></a>Chapter 9. Basic Package Management</h2></div></div></div><p>The main command for package management is <a class="link" href="#sec-nix-env" title="nix-env"><span class="command"><strong>nix-env</strong></span></a>. You can use
+it to install, upgrade, and erase packages, and to query what
+packages are installed or are available for installation.</p><p>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 <code class="envar">PATH</code>. Such a view on the set of
+installed applications is called a <span class="emphasis"><em>user
+environment</em></span>, which is just a directory tree consisting of
+symlinks to the files of the active applications. </p><p>Components are installed from a set of <span class="emphasis"><em>Nix
+expressions</em></span> 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.)</p><p>You can manually download the latest version of Nixpkgs from
+<a class="link" href="http://nixos.org/nixpkgs/download.html" target="_top">http://nixos.org/nixpkgs/download.html</a>. However,
+it’s much more convenient to use the Nixpkgs
+<span class="emphasis"><em>channel</em></span>, since it makes it easy to stay up to
+date with new versions of Nixpkgs. (Channels are described in more
+detail in <a class="xref" href="#sec-channels" title="Chapter 12. Channels">Chapter 12, <em>Channels</em></a>.) 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:
+
+</p><pre class="screen">
+$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
+$ nix-channel --update
+</pre><p>
+
+</p><div class="note"><h3 class="title">Note</h3><p>On NixOS, you’re automatically subscribed to a NixOS
+channel corresponding to your NixOS major release
+(e.g. <code class="uri">http://nixos.org/channels/nixos-14.12</code>). 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.</p></div><p>You can view the set of available packages in Nixpkgs:
+
+</p><pre class="screen">
+$ nix-env -qa
+aterm-2.2
+bash-3.0
+binutils-2.15
+bison-1.875d
+blackdown-1.4.2
+bzip2-1.0.2
+…</pre><p>
+
+The flag <code class="option">-q</code> specifies a query operation, and
+<code class="option">-a</code> 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
+<code class="option">-f</code> flag:
+
+</p><pre class="screen">
+$ nix-env -qaf <em class="replaceable"><code>/path/to/nixpkgs</code></em>
+</pre><p>
+
+where <em class="replaceable"><code>/path/to/nixpkgs</code></em> is where you’ve
+unpacked or checked out Nixpkgs.</p><p>You can select specific packages by name:
+
+</p><pre class="screen">
+$ nix-env -qa firefox
+firefox-34.0.5
+firefox-with-plugins-34.0.5
+</pre><p>
+
+and using regular expressions:
+
+</p><pre class="screen">
+$ nix-env -qa 'firefox.*'
+</pre><p>
+
+</p><p>It is also possible to see the <span class="emphasis"><em>status</em></span> of
+available packages, i.e., whether they are installed into the user
+environment and/or present in the system:
+
+</p><pre class="screen">
+$ nix-env -qas
+…
+-PS bash-3.0
+--S binutils-2.15
+IPS bison-1.875d
+…</pre><p>
+
+The first character (<code class="literal">I</code>) indicates whether the
+package is installed in your current user environment. The second
+(<code class="literal">P</code>) 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 (<code class="literal">S</code>) indicates
+whether there is a so-called <span class="emphasis"><em>substitute</em></span> 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.</p><p>You can install a package using <code class="literal">nix-env -i</code>.
+For instance,
+
+</p><pre class="screen">
+$ nix-env -i subversion</pre><p>
+
+will install the package called <code class="literal">subversion</code> (which
+is, of course, the <a class="link" href="http://subversion.tigris.org/" target="_top">Subversion version
+management system</a>).</p><div class="note"><h3 class="title">Note</h3><p>When you ask Nix to install a package, it will first try
+to get it in pre-compiled form from a <span class="emphasis"><em>binary
+cache</em></span>. By default, Nix will use the binary cache
+<code class="uri">https://cache.nixos.org</code>; 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 <code class="literal">nix-env
+-i subversion</code> 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
+<code class="uri">https://cache.nixos.org</code>. 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.</p></div><p>Naturally, packages can also be uninstalled:
+
+</p><pre class="screen">
+$ nix-env -e subversion</pre><p>
+
+</p><p>Upgrading to a new version is just as easy. If you have a new
+release of Nix Packages, you can do:
+
+</p><pre class="screen">
+$ nix-env -u subversion</pre><p>
+
+This will <span class="emphasis"><em>only</em></span> 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 <em class="parameter"><code>-i</code></em> instead of
+<em class="parameter"><code>-u</code></em>; <em class="parameter"><code>-i</code></em> will remove
+whatever version is already installed.</p><p>You can also upgrade all packages for which there are newer
+versions:
+
+</p><pre class="screen">
+$ nix-env -u</pre><p>
+
+</p><p>Sometimes it’s useful to be able to ask what
+<span class="command"><strong>nix-env</strong></span> would do, without actually doing it. For
+instance, to find out what packages would be upgraded by
+<code class="literal">nix-env -u</code>, you can do
+
+</p><pre class="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'</pre><p>
+
+</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="sec-profiles"></a>Chapter 10. Profiles</h2></div></div></div><p>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
+<span class="emphasis"><em>Nix store</em></span> (typically,
+<code class="filename">/nix/store</code>). For instance, a particular version
+of the Subversion package might be stored in a directory
+<code class="filename">/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/</code>,
+while another version might be stored in
+<code class="filename">/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2</code>.
+The long strings prefixed to the directory names are cryptographic
+hashes<a href="#ftn.idm139733301692864" class="footnote" id="idm139733301692864"><sup class="footnote">[1]</sup></a> of
+<span class="emphasis"><em>all</em></span> 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. <a class="xref" href="#fig-user-environments" title="Figure 10.1. User environments">Figure 10.1, “User environments”</a> shows a part of a typical Nix
+store.</p><div class="figure"><a id="fig-user-environments"></a><p class="title"><strong>Figure 10.1. User environments</strong></p><div class="figure-contents"><div class="mediaobject"><img src="figures/user-environments.png" alt="User environments" /></div></div></div><br class="figure-break" /><p>Of course, you wouldn’t want to type
+
+</p><pre class="screen">
+$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn</pre><p>
+
+every time you want to run Subversion. Of course we could set up the
+<code class="envar">PATH</code> environment variable to include the
+<code class="filename">bin</code> directory of every package we want to use,
+but this is not very convenient since changing <code class="envar">PATH</code>
+doesn’t take effect for already existing processes. The solution Nix
+uses is to create directory trees of symlinks to
+<span class="emphasis"><em>activated</em></span> packages. These are called
+<span class="emphasis"><em>user environments</em></span> and they are packages
+themselves (though automatically generated by
+<span class="command"><strong>nix-env</strong></span>), so they too reside in the Nix store. For
+instance, in <a class="xref" href="#fig-user-environments" title="Figure 10.1. User environments">Figure 10.1, “User environments”</a> the user
+environment <code class="filename">/nix/store/0c1p5z4kda11...-user-env</code>
+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
+
+</p><pre class="screen">
+$ nix-env -i subversion</pre><p>
+
+on a set of Nix expressions that contained Subversion 1.1.2.</p><p>This doesn’t in itself solve the problem, of course; you
+wouldn’t want to type
+<code class="filename">/nix/store/0c1p5z4kda11...-user-env/bin/svn</code>
+either. That’s why there are symlinks outside of the store that point
+to the user environments in the store; for instance, the symlinks
+<code class="filename">default-42-link</code> and
+<code class="filename">default-43-link</code> in the example. These are called
+<span class="emphasis"><em>generations</em></span> since every time you perform a
+<span class="command"><strong>nix-env</strong></span> operation, a new user environment is
+generated based on the current one. For instance, generation 43 was
+created from generation 42 when we did
+
+</p><pre class="screen">
+$ nix-env -i subversion firefox</pre><p>
+
+on a set of Nix expressions that contained Firefox and a new version
+of Subversion.</p><p>Generations are grouped together into
+<span class="emphasis"><em>profiles</em></span> so that different users don’t interfere
+with each other if they don’t want to. For example:
+
+</p><pre class="screen">
+$ ls -l /nix/var/nix/profiles/
+...
+lrwxrwxrwx 1 eelco ... default-42-link -&gt; /nix/store/0c1p5z4kda11...-user-env
+lrwxrwxrwx 1 eelco ... default-43-link -&gt; /nix/store/3aw2pdyx2jfc...-user-env
+lrwxrwxrwx 1 eelco ... default -&gt; default-43-link</pre><p>
+
+This shows a profile called <code class="filename">default</code>. The file
+<code class="filename">default</code> itself is actually a symlink that points
+to the current generation. When we do a <span class="command"><strong>nix-env</strong></span>
+operation, a new user environment and generation link are created
+based on the current one, and finally the <code class="filename">default</code>
+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.)</p><p>If you find that you want to undo a <span class="command"><strong>nix-env</strong></span>
+operation, you can just do
+
+</p><pre class="screen">
+$ nix-env --rollback</pre><p>
+
+which will just make the current generation link point at the previous
+link. E.g., <code class="filename">default</code> would be made to point at
+<code class="filename">default-42-link</code>. You can also switch to a
+specific generation:
+
+</p><pre class="screen">
+$ nix-env --switch-generation 43</pre><p>
+
+which in this example would roll forward to generation 43 again. You
+can also see all available generations:
+
+</p><pre class="screen">
+$ nix-env --list-generations</pre><p>You generally wouldn’t have
+<code class="filename">/nix/var/nix/profiles/<em class="replaceable"><code>some-profile</code></em>/bin</code>
+in your <code class="envar">PATH</code>. Rather, there is a symlink
+<code class="filename">~/.nix-profile</code> that points to your current
+profile. This means that you should put
+<code class="filename">~/.nix-profile/bin</code> in your <code class="envar">PATH</code>
+(and indeed, that’s what the initialisation script
+<code class="filename">/nix/etc/profile.d/nix.sh</code> does). This makes it
+easier to switch to a different profile. You can do that using the
+command <span class="command"><strong>nix-env --switch-profile</strong></span>:
+
+</p><pre class="screen">
+$ nix-env --switch-profile /nix/var/nix/profiles/my-profile
+
+$ nix-env --switch-profile /nix/var/nix/profiles/default</pre><p>
+
+These commands switch to the <code class="filename">my-profile</code> 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 <code class="filename">profiles</code>
+directory, since otherwise it might not be used as a root of the
+garbage collector (see <a class="xref" href="#sec-garbage-collection" title="Chapter 11. Garbage Collection">Chapter 11, <em>Garbage Collection</em></a>).</p><p>All <span class="command"><strong>nix-env</strong></span> operations work on the profile
+pointed to by <span class="command"><strong>~/.nix-profile</strong></span>, but you can override
+this using the <code class="option">--profile</code> option (abbreviation
+<code class="option">-p</code>):
+
+</p><pre class="screen">
+$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion</pre><p>
+
+This will <span class="emphasis"><em>not</em></span> change the
+<span class="command"><strong>~/.nix-profile</strong></span> symlink.</p><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm139733301692864" class="footnote"><p><a href="#idm139733301692864" class="para"><sup class="para">[1] </sup></a>160-bit truncations of SHA-256 hashes encoded in
+a base-32 notation, to be precise.</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="sec-garbage-collection"></a>Chapter 11. Garbage Collection</h2></div></div></div><p><span class="command"><strong>nix-env</strong></span> operations such as upgrades
+(<code class="option">-u</code>) and uninstall (<code class="option">-e</code>) 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.</p><p>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.</p><p>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.</p><p>To delete all old (non-current) generations of your current
+profile:
+
+</p><pre class="screen">
+$ nix-env --delete-generations old</pre><p>
+
+Instead of <code class="literal">old</code> you can also specify a list of
+generations, e.g.,
+
+</p><pre class="screen">
+$ nix-env --delete-generations 10 11 14</pre><p>
+
+To delete all generations older than a specified number of days
+(except the current generation), use the <code class="literal">d</code>
+suffix. For example,
+
+</p><pre class="screen">
+$ nix-env --delete-generations 14d</pre><p>
+
+deletes all generations older than two weeks.</p><p>After removing appropriate old generations you can run the
+garbage collector as follows:
+
+</p><pre class="screen">
+$ nix-store --gc</pre><p>
+
+The behaviour of the gargage collector is affected by the
+<code class="literal">keep-derivations</code> (default: true) and <code class="literal">keep-outputs</code>
+(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:
+
+</p><pre class="screen">
+$ nix-store --gc --print-dead</pre><p>
+
+Likewise, the option <code class="option">--print-live</code> will show the paths
+that <span class="emphasis"><em>won’t</em></span> be deleted.</p><p>There is also a convenient little utility
+<span class="command"><strong>nix-collect-garbage</strong></span>, which when invoked with the
+<code class="option">-d</code> (<code class="option">--delete-old</code>) switch deletes all
+old generations of all profiles in
+<code class="filename">/nix/var/nix/profiles</code>. So
+
+</p><pre class="screen">
+$ nix-collect-garbage -d</pre><p>
+
+is a quick and easy way to clean up your system.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-gc-roots"></a>11.1. Garbage Collector Roots</h2></div></div></div><p>The roots of the garbage collector are all store paths to which
+there are symlinks in the directory
+<code class="filename"><em class="replaceable"><code>prefix</code></em>/nix/var/nix/gcroots</code>.
+For instance, the following command makes the path
+<code class="filename">/nix/store/d718ef...-foo</code> a root of the collector:
+
+</p><pre class="screen">
+$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar</pre><p>
+
+That is, after this command, the garbage collector will not remove
+<code class="filename">/nix/store/d718ef...-foo</code> or any of its
+dependencies.</p><p>Subdirectories of
+<code class="filename"><em class="replaceable"><code>prefix</code></em>/nix/var/nix/gcroots</code>
+are also searched for symlinks. Symlinks to non-store paths are
+followed and searched for roots, but symlinks to non-store paths
+<span class="emphasis"><em>inside</em></span> the paths reached in that way are not
+followed to prevent infinite recursion.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="sec-channels"></a>Chapter 12. Channels</h2></div></div></div><p>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 <span class="command"><strong>nix-env</strong></span>.
+Fortunately, there’s a better way: <span class="emphasis"><em>Nix
+channels</em></span>.</p><p>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 <a class="link" href="#sec-nix-channel" title="nix-channel"><span class="command"><strong>nix-channel</strong></span></a> you
+can automatically stay up to date with whatever is available at that
+URL.</p><p>To see the list of official NixOS channels, visit <a class="link" href="https://nixos.org/channels" target="_top">https://nixos.org/channels</a>.</p><p>You can “subscribe” to a channel using
+<span class="command"><strong>nix-channel --add</strong></span>, e.g.,
+
+</p><pre class="screen">
+$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable</pre><p>
+
+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 <code class="filename">~/.nix-channels</code>,
+where it is read by subsequent calls to <span class="command"><strong>nix-channel
+--update</strong></span>.) You can “unsubscribe” using <span class="command"><strong>nix-channel
+--remove</strong></span>:
+
+</p><pre class="screen">
+$ nix-channel --remove nixpkgs
+</pre><p>
+</p><p>To obtain the latest Nix expressions available in a channel, do
+
+</p><pre class="screen">
+$ nix-channel --update</pre><p>
+
+This downloads and unpacks the Nix expressions in every channel
+(downloaded from <code class="literal"><em class="replaceable"><code>url</code></em>/nixexprs.tar.bz2</code>).
+It also makes the union of each channel’s Nix expressions available by
+default to <span class="command"><strong>nix-env</strong></span> operations (via the symlink
+<code class="filename">~/.nix-defexpr/channels</code>). Consequently, you can
+then say
+
+</p><pre class="screen">
+$ nix-env -u</pre><p>
+
+to upgrade all packages in your profile to the latest versions
+available in the subscribed channels.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="sec-sharing-packages"></a>Chapter 13. Sharing Packages Between Machines</h2></div></div></div><p>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.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-binary-cache-substituter"></a>13.1. Serving a Nix store via HTTP</h2></div></div></div><p>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 <span class="emphasis"><em>binary cache</em></span>
+mechanism that Nix usually uses to fetch pre-built binaries from
+<code class="uri">https://cache.nixos.org</code>.</p><p>The daemon that handles binary cache requests via HTTP,
+<span class="command"><strong>nix-serve</strong></span>, is not part of the Nix distribution, but
+you can install it from Nixpkgs:
+
+</p><pre class="screen">
+$ nix-env -i nix-serve
+</pre><p>
+
+You can then start the server, listening for HTTP connections on
+whatever port you like:
+
+</p><pre class="screen">
+$ nix-serve -p 8080
+</pre><p>
+
+To check whether it works, try the following on the client:
+
+</p><pre class="screen">
+$ curl http://avalon:8080/nix-cache-info
+</pre><p>
+
+which should print something like:
+
+</p><pre class="screen">
+StoreDir: /nix/store
+WantMassQuery: 1
+Priority: 30
+</pre><p>
+
+</p><p>On the client side, you can tell Nix to use your binary cache
+using <code class="option">--option extra-binary-caches</code>, e.g.:
+
+</p><pre class="screen">
+$ nix-env -i firefox --option extra-binary-caches http://avalon:8080/
+</pre><p>
+
+The option <code class="option">extra-binary-caches</code> tells Nix to use this
+binary cache in addition to your default caches, such as
+<code class="uri">https://cache.nixos.org</code>. Thus, for any path in the closure
+of Firefox, Nix will first check if the path is available on the
+server <code class="literal">avalon</code> or another binary caches. If not, it
+will fall back to building from source.</p><p>You can also tell Nix to always use your binary cache by adding
+a line to the <code class="filename"><a class="filename" href="#sec-conf-file" title="nix.conf">nix.conf</a></code>
+configuration file like this:
+
+</p><pre class="programlisting">
+binary-caches = http://avalon:8080/ https://cache.nixos.org/
+</pre><p>
+
+</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-copy-closure"></a>13.2. Copying Closures Via SSH</h2></div></div></div><p>The command <span class="command"><strong><a class="command" href="#sec-nix-copy-closure" title="nix-copy-closure">nix-copy-closure</a></strong></span> 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:
+
+</p><pre class="screen">
+$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)</pre><p>
+
+See <a class="xref" href="#sec-nix-copy-closure" title="nix-copy-closure"><span class="refentrytitle">nix-copy-closure</span>(1)</a> for details.</p><p>With <span class="command"><strong><a class="command" href="#refsec-nix-store-export" title="Operation --export">nix-store
+--export</a></strong></span> and <span class="command"><strong><a class="command" href="#refsec-nix-store-import" title="Operation --import">nix-store --import</a></strong></span> 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,
+
+</p><pre class="screen">
+$ nix-store --export $(nix-store -qR $(type -p firefox)) &gt; firefox.closure</pre><p>
+
+writes the closure of Firefox to a file. You can then copy this file
+to another machine and install the closure:
+
+</p><pre class="screen">
+$ nix-store --import &lt; firefox.closure</pre><p>
+
+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:
+
+</p><pre class="screen">
+$ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \
+ ssh alice@itchy.example.org "bunzip2 | nix-store --import"</pre><p>
+
+However, <span class="command"><strong>nix-copy-closure</strong></span> is generally more
+efficient because it only copies paths that are not already present in
+the target Nix store.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-ssh-substituter"></a>13.3. Serving a Nix store via SSH</h2></div></div></div><p>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 <code class="literal">avalon</code>:
+
+</p><pre class="screen">
+$ nix-env -i firefox --substituters ssh://alice@avalon
+</pre><p>
+
+This works similar to the binary cache substituter that Nix usually
+uses, only using SSH instead of HTTP: if a store path
+<code class="literal">P</code> is needed, Nix will first check if it’s available
+in the Nix store on <code class="literal">avalon</code>. If not, it will fall
+back to using the binary cache substituter, and then to building from
+source.</p><div class="note"><h3 class="title">Note</h3><p>The SSH substituter currently does not allow you to enter
+an SSH passphrase interactively. Therefore, you should use
+<span class="command"><strong>ssh-add</strong></span> to load the decrypted private key into
+<span class="command"><strong>ssh-agent</strong></span>.</p></div><p>You can also copy the closure of some store path, without
+installing it into your profile, e.g.
+
+</p><pre class="screen">
+$ nix-store -r /nix/store/m85bxg…-firefox-34.0.5 --substituters ssh://alice@avalon
+</pre><p>
+
+This is essentially equivalent to doing
+
+</p><pre class="screen">
+$ nix-copy-closure --from alice@avalon /nix/store/m85bxg…-firefox-34.0.5
+</pre><p>
+
+</p><p>You can use SSH’s <span class="emphasis"><em>forced command</em></span> 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 <code class="filename">sshd_config</code>
+to restrict the user <code class="literal">nix-ssh</code>:
+
+</p><pre class="programlisting">
+Match User nix-ssh
+ AllowAgentForwarding no
+ AllowTcpForwarding no
+ PermitTTY no
+ PermitTunnel no
+ X11Forwarding no
+ ForceCommand nix-store --serve
+Match All
+</pre><p>
+
+On NixOS, you can accomplish the same by adding the following to your
+<code class="filename">configuration.nix</code>:
+
+</p><pre class="programlisting">
+nix.sshServe.enable = true;
+nix.sshServe.keys = [ "ssh-dss AAAAB3NzaC1k... bob@example.org" ];
+</pre><p>
+
+where the latter line lists the public keys of users that are allowed
+to connect.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-s3-substituter"></a>13.4. Serving a Nix store via AWS S3 or S3-compatible Service</h2></div></div></div><p>Nix has built-in support for storing and fetching store paths
+from Amazon S3 and S3 compatible services. This uses the same
+<span class="emphasis"><em>binary</em></span> cache mechanism that Nix usually uses to
+fetch prebuilt binaries from <code class="uri">cache.nixos.org</code>.</p><p>The following options can be specified as URL parameters to
+the S3 URL:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">profile</code></span></dt><dd><p>
+ The name of the AWS configuration profile to use. By default
+ Nix will use the <code class="literal">default</code> profile.
+ </p></dd><dt><span class="term"><code class="literal">region</code></span></dt><dd><p>
+ The region of the S3 bucket. <code class="literal">us–east-1</code> by
+ default.
+ </p><p>
+ If your bucket is not in <code class="literal">us–east-1</code>, you
+ should always explicitly specify the region parameter.
+ </p></dd><dt><span class="term"><code class="literal">endpoint</code></span></dt><dd><p>
+ The URL to your S3-compatible service, for when not using
+ Amazon S3. Do not specify this value if you're using Amazon
+ S3.
+ </p><div class="note"><h3 class="title">Note</h3><p>This endpoint must support HTTPS and will use
+ path-based addressing instead of virtual host based
+ addressing.</p></div></dd><dt><span class="term"><code class="literal">scheme</code></span></dt><dd><p>
+ The scheme used for S3 requests, <code class="literal">https</code>
+ (default) or <code class="literal">http</code>. This option allows you to
+ disable HTTPS for binary caches which don't support it.
+ </p><div class="note"><h3 class="title">Note</h3><p>HTTPS should be used if the cache might contain
+ sensitive information.</p></div></dd></dl></div><p>In this example we will use the bucket named
+<code class="literal">example-nix-cache</code>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="ssec-s3-substituter-anonymous-reads"></a>13.4.1. Anonymous Reads to your S3-compatible binary cache</h3></div></div></div><p>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.</p><p>For AWS S3 the binary cache URL for example bucket will be
+ exactly <code class="uri">https://example-nix-cache.s3.amazonaws.com</code> or
+ <code class="uri">s3://example-nix-cache</code>. For S3 compatible binary caches,
+ consult that cache's documentation.</p><p>Your bucket will need the following bucket policy:</p><pre class="programlisting">
+{
+ "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": "*"
+ }
+ ]
+}
+</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="ssec-s3-substituter-authenticated-reads"></a>13.4.2. Authenticated Reads to your S3 binary cache</h3></div></div></div><p>For AWS S3 the binary cache URL for example bucket will be
+ exactly <code class="uri">s3://example-nix-cache</code>.</p><p>Nix will use the <a class="link" href="https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html" target="_top">default
+ credential provider chain</a> for authenticating requests to
+ Amazon S3.</p><p>Nix supports authenticated reads from Amazon S3 and S3
+ compatible binary caches.</p><p>Your bucket will need a bucket policy allowing the desired
+ users to perform the <code class="literal">s3:GetObject</code> and
+ <code class="literal">s3:GetBucketLocation</code> action on all objects in the
+ bucket. The anonymous policy in <a class="xref" href="#ssec-s3-substituter-anonymous-reads" title="13.4.1. Anonymous Reads to your S3-compatible binary cache">Section 13.4.1, “Anonymous Reads to your S3-compatible binary cache”</a> can be updated to
+ have a restricted <code class="literal">Principal</code> to support
+ this.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="ssec-s3-substituter-authenticated-writes"></a>13.4.3. Authenticated Writes to your S3-compatible binary cache</h3></div></div></div><p>Nix support fully supports writing to Amazon S3 and S3
+ compatible buckets. The binary cache URL for our example bucket will
+ be <code class="uri">s3://example-nix-cache</code>.</p><p>Nix will use the <a class="link" href="https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html" target="_top">default
+ credential provider chain</a> for authenticating requests to
+ Amazon S3.</p><p>Your account will need the following IAM policy to
+ upload to the cache:</p><pre class="programlisting">
+{
+ "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/*"
+ ]
+ }
+ ]
+}
+</pre><div class="example"><a id="idm139733301558256"></a><p class="title"><strong>Example 13.1. Uploading with a specific credential profile for Amazon S3</strong></p><div class="example-contents"><p><span class="command"><strong>nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;region=eu-west-2' nixpkgs.hello</strong></span></p></div></div><br class="example-break" /><div class="example"><a id="idm139733301556896"></a><p class="title"><strong>Example 13.2. Uploading to an S3-Compatible Binary Cache</strong></p><div class="example-contents"><p><span class="command"><strong>nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;scheme=https&amp;endpoint=minio.example.com' nixpkgs.hello</strong></span></p></div></div><br class="example-break" /></div></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="chap-writing-nix-expressions"></a>Part IV. Writing Nix Expressions</h1></div></div></div><div class="partintro"><div></div><p>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.</p><div class="note"><h3 class="title">Note</h3><p>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 <a class="link" href="http://nixos.org/nixpkgs/manual/" target="_top">its
+manual</a>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-simple-expression"></a>Chapter 14. A Simple Nix Expression</h2></div></div></div><p>This section shows how to add and test the <a class="link" href="http://www.gnu.org/software/hello/hello.html" target="_top">GNU Hello
+package</a> to the Nix Packages collection. Hello is a program
+that prints out the text <span class="quote">“<span class="quote">Hello, world!</span>”</span>.</p><p>To add a package to the Nix Packages collection, you generally
+need to do three things:
+
+</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>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.</p></li><li class="listitem"><p>Write a <span class="emphasis"><em>builder</em></span>. This is a
+ shell script<a href="#ftn.idm139733301545648" class="footnote" id="idm139733301545648"><sup class="footnote">[2]</sup></a> that actually builds the package from
+ the inputs.</p></li><li class="listitem"><p>Add the package to the file
+ <code class="filename">pkgs/top-level/all-packages.nix</code>. The Nix
+ expression written in the first step is a
+ <span class="emphasis"><em>function</em></span>; 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.</p></li></ol></div><p>
+
+</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-expression-syntax"></a>14.1. Expression Syntax</h2></div></div></div><div class="example"><a id="ex-hello-nix"></a><p class="title"><strong>Example 14.1. Nix expression for GNU Hello
+(<code class="filename">default.nix</code>)</strong></p><div class="example-contents"><pre class="programlisting">
+{ stdenv, fetchurl, perl }: <a id="ex-hello-nix-co-1"></a>(1)
+
+stdenv.mkDerivation { <a id="ex-hello-nix-co-2"></a>(2)
+ name = "hello-2.1.1"; <a id="ex-hello-nix-co-3"></a>(3)
+ builder = ./builder.sh; <a id="ex-hello-nix-co-4"></a>(4)
+ src = fetchurl { <a id="ex-hello-nix-co-5"></a>(5)
+ url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
+ sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
+ };
+ inherit perl; <a id="ex-hello-nix-co-6"></a>(6)
+}</pre></div></div><br class="example-break" /><p><a class="xref" href="#ex-hello-nix" title="Example 14.1. Nix expression for GNU Hello (default.nix)">Example 14.1, “Nix expression for GNU Hello
+(<code class="filename">default.nix</code>)”</a> shows a Nix expression for GNU
+Hello. It's actually already in the Nix Packages collection in
+<code class="filename">pkgs/applications/misc/hello/ex-1/default.nix</code>.
+It is customary to place each package in a separate directory and call
+the single Nix expression in that directory
+<code class="filename">default.nix</code>. The file has the following elements
+(referenced from the figure by number):
+
+</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-nix-co-1">(1)</a> </p></td><td valign="top" align="left"><p>This states that the expression is a
+ <span class="emphasis"><em>function</em></span> that expects to be called with three
+ arguments: <code class="varname">stdenv</code>, <code class="varname">fetchurl</code>,
+ and <code class="varname">perl</code>. They are needed to build Hello, but
+ we don't know how to build them here; that's why they are function
+ arguments. <code class="varname">stdenv</code> is a package that is used
+ by almost all Nix Packages packages; it provides a
+ <span class="quote">“<span class="quote">standard</span>”</span> 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
+ <span class="command"><strong>cp</strong></span>, <span class="command"><strong>grep</strong></span>,
+ <span class="command"><strong>tar</strong></span>, etc. <code class="varname">fetchurl</code> is a
+ function that downloads files. <code class="varname">perl</code> is the
+ Perl interpreter.</p><p>Nix functions generally have the form <code class="literal">{ x, y, ...,
+ z }: e</code> where <code class="varname">x</code>, <code class="varname">y</code>,
+ etc. are the names of the expected arguments, and where
+ <em class="replaceable"><code>e</code></em> 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.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-nix-co-2">(2)</a> </p></td><td valign="top" align="left"><p>So we have to build a package. Building something from
+ other stuff is called a <span class="emphasis"><em>derivation</em></span> in Nix (as
+ opposed to sources, which are built by humans instead of
+ computers). We perform a derivation by calling
+ <code class="varname">stdenv.mkDerivation</code>.
+ <code class="varname">mkDerivation</code> is a function provided by
+ <code class="varname">stdenv</code> that builds a package from a set of
+ <span class="emphasis"><em>attributes</em></span>. 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 <code class="literal">{
+ <em class="replaceable"><code>name1</code></em> =
+ <em class="replaceable"><code>expr1</code></em>; <em class="replaceable"><code>...</code></em>
+ <em class="replaceable"><code>nameN</code></em> =
+ <em class="replaceable"><code>exprN</code></em>; }</code>.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-nix-co-3">(3)</a> </p></td><td valign="top" align="left"><p>The attribute <code class="varname">name</code> specifies the symbolic
+ name and version of the package. Nix doesn't really care about
+ these things, but they are used by for instance <span class="command"><strong>nix-env
+ -q</strong></span> to show a <span class="quote">“<span class="quote">human-readable</span>”</span> name for
+ packages. This attribute is required by
+ <code class="varname">mkDerivation</code>.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-nix-co-4">(4)</a> </p></td><td valign="top" align="left"><p>The attribute <code class="varname">builder</code> specifies the
+ builder. This attribute can sometimes be omitted, in which case
+ <code class="varname">mkDerivation</code> will fill in a default builder
+ (which does a <code class="literal">configure; make; make install</code>, 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
+ <span class="command"><strong>./builder.sh</strong></span> refers to the shell script shown
+ in <a class="xref" href="#ex-hello-builder" title="Example 14.2. Build script for GNU Hello (builder.sh)">Example 14.2, “Build script for GNU Hello
+(<code class="filename">builder.sh</code>)”</a>, discussed below.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-nix-co-5">(5)</a> </p></td><td valign="top" align="left"><p>The builder has to know what the sources of the package
+ are. Here, the attribute <code class="varname">src</code> is bound to the
+ result of a call to the <span class="command"><strong>fetchurl</strong></span> 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.</p><p>Instead of <code class="varname">src</code> any other name could have
+ been used, and in fact there can be any number of sources (bound
+ to different attributes). However, <code class="varname">src</code> is
+ customary, and it's also expected by the default builder (which we
+ don't use in this example).</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-nix-co-6">(6)</a> </p></td><td valign="top" align="left"><p>Since the derivation requires Perl, we have to pass the
+ value of the <code class="varname">perl</code> function argument to the
+ builder. All attributes in the set are actually passed as
+ environment variables to the builder, so declaring an attribute
+
+ </p><pre class="programlisting">
+perl = perl;</pre><p>
+
+ will do the trick: it binds an attribute <code class="varname">perl</code>
+ to the function argument which also happens to be called
+ <code class="varname">perl</code>. However, it looks a bit silly, so there
+ is a shorter syntax. The <code class="literal">inherit</code> keyword
+ causes the specified attributes to be bound to whatever variables
+ with the same name happen to be in scope.</p></td></tr></table></div><p>
+
+</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-build-script"></a>14.2. Build Script</h2></div></div></div><div class="example"><a id="ex-hello-builder"></a><p class="title"><strong>Example 14.2. Build script for GNU Hello
+(<code class="filename">builder.sh</code>)</strong></p><div class="example-contents"><pre class="programlisting">
+source $stdenv/setup <a id="ex-hello-builder-co-1"></a>(1)
+
+PATH=$perl/bin:$PATH <a id="ex-hello-builder-co-2"></a>(2)
+
+tar xvfz $src <a id="ex-hello-builder-co-3"></a>(3)
+cd hello-*
+./configure --prefix=$out <a id="ex-hello-builder-co-4"></a>(4)
+make <a id="ex-hello-builder-co-5"></a>(5)
+make install</pre></div></div><br class="example-break" /><p><a class="xref" href="#ex-hello-builder" title="Example 14.2. Build script for GNU Hello (builder.sh)">Example 14.2, “Build script for GNU Hello
+(<code class="filename">builder.sh</code>)”</a> shows the builder referenced
+from Hello's Nix expression (stored in
+<code class="filename">pkgs/applications/misc/hello/ex-1/builder.sh</code>).
+The builder can actually be made a lot shorter by using the
+<span class="emphasis"><em>generic builder</em></span> functions provided by
+<code class="varname">stdenv</code>, but here we write out the build steps to
+elucidate what a builder does. It performs the following
+steps:</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-builder-co-1">(1)</a> </p></td><td valign="top" align="left"><p>When Nix runs a builder, it initially completely clears the
+ environment (except for the attributes declared in the
+ derivation). For instance, the <code class="envar">PATH</code> variable is
+ empty<a href="#ftn.idm139733301492640" class="footnote" id="idm139733301492640"><sup class="footnote">[3]</sup></a>. This is done to prevent
+ undeclared inputs from being used in the build process. If for
+ example the <code class="envar">PATH</code> contained
+ <code class="filename">/usr/bin</code>, then you might accidentally use
+ <code class="filename">/usr/bin/gcc</code>.</p><p>So the first step is to set up the environment. This is
+ done by calling the <code class="filename">setup</code> script of the
+ standard environment. The environment variable
+ <code class="envar">stdenv</code> points to the location of the standard
+ environment being used. (It wasn't specified explicitly as an
+ attribute in <a class="xref" href="#ex-hello-nix" title="Example 14.1. Nix expression for GNU Hello (default.nix)">Example 14.1, “Nix expression for GNU Hello
+(<code class="filename">default.nix</code>)”</a>, but
+ <code class="varname">mkDerivation</code> adds it automatically.)</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-builder-co-2">(2)</a> </p></td><td valign="top" align="left"><p>Since Hello needs Perl, we have to make sure that Perl is in
+ the <code class="envar">PATH</code>. The <code class="envar">perl</code> environment
+ variable points to the location of the Perl package (since it
+ was passed in as an attribute to the derivation), so
+ <code class="filename"><em class="replaceable"><code>$perl</code></em>/bin</code> is the
+ directory containing the Perl interpreter.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-builder-co-3">(3)</a> </p></td><td valign="top" align="left"><p>Now we have to unpack the sources. The
+ <code class="varname">src</code> attribute was bound to the result of
+ fetching the Hello source tarball from the network, so the
+ <code class="envar">src</code> environment variable points to the location in
+ the Nix store to which the tarball was downloaded. After
+ unpacking, we <span class="command"><strong>cd</strong></span> to the resulting source
+ directory.</p><p>The whole build is performed in a temporary directory
+ created in <code class="varname">/tmp</code>, 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.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-builder-co-4">(4)</a> </p></td><td valign="top" align="left"><p>GNU Hello is a typical Autoconf-based package, so we first
+ have to run its <code class="filename">configure</code> script. In Nix
+ every package is stored in a separate location in the Nix store,
+ for instance
+ <code class="filename">/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1</code>.
+ Nix computes this path by cryptographically hashing all attributes
+ of the derivation. The path is passed to the builder through the
+ <code class="envar">out</code> environment variable. So here we give
+ <code class="filename">configure</code> the parameter
+ <code class="literal">--prefix=$out</code> to cause Hello to be installed in
+ the expected location.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-builder-co-5">(5)</a> </p></td><td valign="top" align="left"><p>Finally we build Hello (<code class="literal">make</code>) and install
+ it into the location specified by <code class="envar">out</code>
+ (<code class="literal">make install</code>).</p></td></tr></table></div><p>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 <code class="option">-e</code> option,
+which causes the script to be aborted if any command fails without an
+error check.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-arguments"></a>14.3. Arguments and Variables</h2></div></div></div><div class="example"><a id="ex-hello-composition"></a><p class="title"><strong>Example 14.3. Composing GNU Hello
+(<code class="filename">all-packages.nix</code>)</strong></p><div class="example-contents"><pre class="programlisting">
+...
+
+rec { <a id="ex-hello-composition-co-1"></a>(1)
+
+ hello = import ../applications/misc/hello/ex-1 <a id="ex-hello-composition-co-2"></a>(2) { <a id="ex-hello-composition-co-3"></a>(3)
+ inherit fetchurl stdenv perl;
+ };
+
+ perl = import ../development/interpreters/perl { <a id="ex-hello-composition-co-4"></a>(4)
+ inherit fetchurl stdenv;
+ };
+
+ fetchurl = import ../build-support/fetchurl {
+ inherit stdenv; ...
+ };
+
+ stdenv = ...;
+
+}
+</pre></div></div><br class="example-break" /><p>The Nix expression in <a class="xref" href="#ex-hello-nix" title="Example 14.1. Nix expression for GNU Hello (default.nix)">Example 14.1, “Nix expression for GNU Hello
+(<code class="filename">default.nix</code>)”</a> 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
+<code class="filename">pkgs/top-level/all-packages.nix</code>, where all
+Nix expressions for packages are imported and called with the
+appropriate arguments. <a class="xref" href="#ex-hello-composition" title="Example 14.3. Composing GNU Hello (all-packages.nix)">Example 14.3, “Composing GNU Hello
+(<code class="filename">all-packages.nix</code>)”</a> shows
+some fragments of
+<code class="filename">all-packages.nix</code>.</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-composition-co-1">(1)</a> </p></td><td valign="top" align="left"><p>This file defines a set of attributes, all of which are
+ concrete derivations (i.e., not functions). In fact, we define a
+ <span class="emphasis"><em>mutually recursive</em></span> set of attributes. That
+ is, the attributes can refer to each other. This is precisely
+ what we want since we want to <span class="quote">“<span class="quote">plug</span>”</span> the
+ various packages into each other.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-composition-co-2">(2)</a> </p></td><td valign="top" align="left"><p>Here we <span class="emphasis"><em>import</em></span> 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 <a class="xref" href="#ex-hello-nix" title="Example 14.1. Nix expression for GNU Hello (default.nix)">Example 14.1, “Nix expression for GNU Hello
+(<code class="filename">default.nix</code>)”</a> in
+ <code class="filename">all-packages.nix</code> at this point. That
+ would be completely equivalent, but it would make the file rather
+ bulky.</p><p>Note that we refer to
+ <code class="filename">../applications/misc/hello/ex-1</code>, not
+ <code class="filename">../applications/misc/hello/ex-1/default.nix</code>.
+ When you try to import a directory, Nix automatically appends
+ <code class="filename">/default.nix</code> to the file name.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-composition-co-3">(3)</a> </p></td><td valign="top" align="left"><p>This is where the actual composition takes place. Here we
+ <span class="emphasis"><em>call</em></span> the function imported from
+ <code class="filename">../applications/misc/hello/ex-1</code> with a set
+ containing the things that the function expects, namely
+ <code class="varname">fetchurl</code>, <code class="varname">stdenv</code>, and
+ <code class="varname">perl</code>. We use inherit again to use the
+ attributes defined in the surrounding scope (we could also have
+ written <code class="literal">fetchurl = fetchurl;</code>, etc.).</p><p>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
+ <code class="varname">stdenv.mkDerivation</code> in <a class="xref" href="#ex-hello-nix" title="Example 14.1. Nix expression for GNU Hello (default.nix)">Example 14.1, “Nix expression for GNU Hello
+(<code class="filename">default.nix</code>)”</a>).</p><div class="note"><h3 class="title">Note</h3><p>Nixpkgs has a convenience function
+ <code class="function">callPackage</code> that imports and calls a
+ function, filling in any missing arguments by passing the
+ corresponding attribute from the Nixpkgs set, like this:
+
+</p><pre class="programlisting">
+hello = callPackage ../applications/misc/hello/ex-1 { };
+</pre><p>
+
+ If necessary, you can set or override arguments:
+
+</p><pre class="programlisting">
+hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; };
+</pre><p>
+
+ </p></div></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-composition-co-4">(4)</a> </p></td><td valign="top" align="left"><p>Likewise, we have to instantiate Perl,
+ <code class="varname">fetchurl</code>, and the standard environment.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-building-simple"></a>14.4. Building and Testing</h2></div></div></div><p>You can now try to build Hello. Of course, you could do
+<code class="literal">nix-env -i hello</code>, 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 <span class="command"><strong><a class="command" href="#sec-nix-build" title="nix-build">nix-build</a></strong></span>,
+which builds a Nix expression and creates a symlink named
+<code class="filename">result</code> in the current directory:
+
+</p><pre class="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
+<em class="replaceable"><code>...</code></em>
+
+$ ls -l result
+lrwxrwxrwx ... 2006-09-29 10:43 result -&gt; /nix/store/632d2b22514d...-hello-2.1.1
+
+$ ./result/bin/hello
+Hello, world!</pre><p>
+
+The <a class="link" href="#opt-attr"><code class="option">-A</code></a> option selects
+the <code class="literal">hello</code> attribute. This is faster than using the
+symbolic package name specified by the <code class="literal">name</code>
+attribute (which also happens to be <code class="literal">hello</code>) and is
+unambiguous (there can be multiple packages with the symbolic name
+<code class="literal">hello</code>, but there can be only one attribute in a set
+named <code class="literal">hello</code>).</p><p><span class="command"><strong>nix-build</strong></span> registers the
+<code class="filename">./result</code> symlink as a garbage collection root, so
+unless and until you delete the <code class="filename">./result</code> symlink,
+the output of the build will be safely kept on your system. You can
+use <span class="command"><strong>nix-build</strong></span>’s <code class="option"><a class="option" href="#opt-out-link">-o</a></code> switch to give the symlink another
+name.</p><p>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 <code class="envar">out</code> is now
+<span class="quote">“<span class="quote">valid</span>”</span>. 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 <code class="literal">make
+install</code>) and try again. Note that there is no
+<span class="quote">“<span class="quote">negative caching</span>”</span>: 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).</p><p>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:
+
+</p><pre class="screen">
+$ nix-build -A hello
+waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x'</pre><p>
+
+So it is always safe to run multiple instances of Nix in parallel
+(which isn’t the case with, say, <span class="command"><strong>make</strong></span>).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-generic-builder"></a>14.5. Generic Builder Syntax</h2></div></div></div><p>Recall from <a class="xref" href="#ex-hello-builder" title="Example 14.2. Build script for GNU Hello (builder.sh)">Example 14.2, “Build script for GNU Hello
+(<code class="filename">builder.sh</code>)”</a> that the builder
+looked something like this:
+
+</p><pre class="programlisting">
+PATH=$perl/bin:$PATH
+tar xvfz $src
+cd hello-*
+./configure --prefix=$out
+make
+make install</pre><p>
+
+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 <a class="xref" href="#ex-hello-builder2" title="Example 14.4. Build script using the generic build functions">Example 14.4, “Build script using the generic
+build functions”</a>.</p><div class="example"><a id="ex-hello-builder2"></a><p class="title"><strong>Example 14.4. Build script using the generic
+build functions</strong></p><div class="example-contents"><pre class="programlisting">
+buildInputs="$perl" <a id="ex-hello-builder2-co-1"></a>(1)
+
+source $stdenv/setup <a id="ex-hello-builder2-co-2"></a>(2)
+
+genericBuild <a id="ex-hello-builder2-co-3"></a>(3)</pre></div></div><br class="example-break" /><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-builder2-co-1">(1)</a> </p></td><td valign="top" align="left"><p>The <code class="envar">buildInputs</code> variable tells
+ <code class="filename">setup</code> to use the indicated packages as
+ <span class="quote">“<span class="quote">inputs</span>”</span>. This means that if a package provides a
+ <code class="filename">bin</code> subdirectory, it's added to
+ <code class="envar">PATH</code>; if it has a <code class="filename">include</code>
+ subdirectory, it's added to GCC's header search path; and so
+ on.<a href="#ftn.idm139733301420112" class="footnote" id="idm139733301420112"><sup class="footnote">[4]</sup></a>
+ </p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-builder2-co-2">(2)</a> </p></td><td valign="top" align="left"><p>The function <code class="function">genericBuild</code> is defined in
+ the file <code class="literal">$stdenv/setup</code>.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-hello-builder2-co-3">(3)</a> </p></td><td valign="top" align="left"><p>The final step calls the shell function
+ <code class="function">genericBuild</code>, which performs the steps that
+ were done explicitly in <a class="xref" href="#ex-hello-builder" title="Example 14.2. Build script for GNU Hello (builder.sh)">Example 14.2, “Build script for GNU Hello
+(<code class="filename">builder.sh</code>)”</a>. The
+ generic builder is smart enough to figure out whether to unpack
+ the sources using <span class="command"><strong>gzip</strong></span>,
+ <span class="command"><strong>bzip2</strong></span>, etc. It can be customised in many ways;
+ see the Nixpkgs manual for details.</p></td></tr></table></div><p>Discerning readers will note that the
+<code class="envar">buildInputs</code> could just as well have been set in the Nix
+expression, like this:
+
+</p><pre class="programlisting">
+ buildInputs = [ perl ];</pre><p>
+
+The <code class="varname">perl</code> attribute can then be removed, and the
+builder becomes even shorter:
+
+</p><pre class="programlisting">
+source $stdenv/setup
+genericBuild</pre><p>
+
+In fact, <code class="varname">mkDerivation</code> provides a default builder
+that looks exactly like that, so it is actually possible to omit the
+builder for Hello entirely.</p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm139733301545648" class="footnote"><p><a href="#idm139733301545648" class="para"><sup class="para">[2] </sup></a>In fact, it can be written in any
+ language, but typically it's a <span class="command"><strong>bash</strong></span> shell
+ script.</p></div><div id="ftn.idm139733301492640" class="footnote"><p><a href="#idm139733301492640" class="para"><sup class="para">[3] </sup></a>Actually, it's initialised to
+ <code class="filename">/path-not-set</code> to prevent Bash from setting it
+ to a default value.</p></div><div id="ftn.idm139733301420112" class="footnote"><p><a href="#idm139733301420112" class="para"><sup class="para">[4] </sup></a>How does it work? <code class="filename">setup</code>
+ tries to source the file
+ <code class="filename"><em class="replaceable"><code>pkg</code></em>/nix-support/setup-hook</code>
+ of all dependencies. These “setup hooks” can then set up whatever
+ environment variables they want; for instance, the setup hook for
+ Perl sets the <code class="envar">PERL5LIB</code> environment variable to
+ contain the <code class="filename">lib/site_perl</code> directories of all
+ inputs.</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-expression-language"></a>Chapter 15. Nix Expression Language</h2></div></div></div><p>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
+<span class="quote">“<span class="quote">normal</span>”</span> 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.</p><p>This section presents the various features of the
+language.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-values"></a>15.1. Values</h2></div></div></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301403360"></a>Simple Values</h3></div></div></div><p>Nix has the following basic data types:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="emphasis"><em>Strings</em></span> can be written in three
+ ways.</p><p>The most common way is to enclose the string between double
+ quotes, e.g., <code class="literal">"foo bar"</code>. Strings can span
+ multiple lines. The special characters <code class="literal">"</code> and
+ <code class="literal">\</code> and the character sequence
+ <code class="literal">${</code> must be escaped by prefixing them with a
+ backslash (<code class="literal">\</code>). Newlines, carriage returns and
+ tabs can be written as <code class="literal">\n</code>,
+ <code class="literal">\r</code> and <code class="literal">\t</code>,
+ respectively.</p><p>You can include the result of an expression into a string by
+ enclosing it in
+ <code class="literal">${<em class="replaceable"><code>...</code></em>}</code>, a feature
+ known as <span class="emphasis"><em>antiquotation</em></span>. 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
+
+</p><pre class="programlisting">
+"--with-freetype2-library=" + freetype + "/lib"</pre><p>
+
+ (where <code class="varname">freetype</code> is a derivation), you can
+ instead write the more natural
+
+</p><pre class="programlisting">
+"--with-freetype2-library=${freetype}/lib"</pre><p>
+
+ The latter is automatically translated to the former. A more
+ complicated example (from the Nix expression for <a class="link" href="http://www.trolltech.com/products/qt" target="_top">Qt</a>):
+
+</p><pre class="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"}
+";</pre><p>
+
+ 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., <code class="literal">"-thread"</code>),
+ some of which in turn contain expressions (e.g.,
+ <code class="literal">${mesa}</code>).</p><p>The second way to write string literals is as an
+ <span class="emphasis"><em>indented string</em></span>, which is enclosed between
+ pairs of <span class="emphasis"><em>double single-quotes</em></span>, like so:
+
+</p><pre class="programlisting">
+''
+ This is the first line.
+ This is the second line.
+ This is the third line.
+''</pre><p>
+
+ 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
+
+</p><pre class="programlisting">
+"This is the first line.\nThis is the second line.\n This is the third line.\n"</pre><p>
+
+ </p><p>Note that the whitespace and newline following the opening
+ <code class="literal">''</code> is ignored if there is no non-whitespace
+ text on the initial line.</p><p>Antiquotation
+ (<code class="literal">${<em class="replaceable"><code>expr</code></em>}</code>) is
+ supported in indented strings.</p><p>Since <code class="literal">${</code> and <code class="literal">''</code> have
+ special meaning in indented strings, you need a way to quote them.
+ <code class="literal">$</code> can be escaped by prefixing it with
+ <code class="literal">''</code> (that is, two single quotes), i.e.,
+ <code class="literal">''$</code>. <code class="literal">''</code> can be escaped by
+ prefixing it with <code class="literal">'</code>, i.e.,
+ <code class="literal">'''</code>. <code class="literal">$</code> removes any special meaning
+ from the following <code class="literal">$</code>. Linefeed, carriage-return and tab
+ characters can be written as <code class="literal">''\n</code>,
+ <code class="literal">''\r</code>, <code class="literal">''\t</code>, and <code class="literal">''\</code>
+ escapes any other character.
+
+ </p><p>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 <code class="literal">''</code> is much less
+ common than <code class="literal">"</code>. Example:
+
+</p><pre class="programlisting">
+stdenv.mkDerivation {
+ <em class="replaceable"><code>...</code></em>
+ postInstall =
+ ''
+ mkdir $out/bin $out/etc
+ cp foo $out/bin
+ echo "Hello World" &gt; $out/etc/foo.conf
+ ${if enableBar then "cp bar $out/bin" else ""}
+ '';
+ <em class="replaceable"><code>...</code></em>
+}
+</pre><p>
+
+ </p><p>Finally, as a convenience, <span class="emphasis"><em>URIs</em></span> as
+ defined in appendix B of <a class="link" href="http://www.ietf.org/rfc/rfc2396.txt" target="_top">RFC 2396</a>
+ can be written <span class="emphasis"><em>as is</em></span>, without quotes. For
+ instance, the string
+ <code class="literal">"http://example.org/foo.tar.bz2"</code>
+ can also be written as
+ <code class="literal">http://example.org/foo.tar.bz2</code>.</p></li><li class="listitem"><p>Numbers, which can be <span class="emphasis"><em>integers</em></span> (like
+ <code class="literal">123</code>) or <span class="emphasis"><em>floating point</em></span> (like
+ <code class="literal">123.43</code> or <code class="literal">.27e13</code>).</p><p>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.</p></li><li class="listitem"><p><span class="emphasis"><em>Paths</em></span>, e.g.,
+ <code class="filename">/bin/sh</code> or <code class="filename">./builder.sh</code>.
+ A path must contain at least one slash to be recognised as such; for
+ instance, <code class="filename">builder.sh</code> is not a
+ path<a href="#ftn.idm139733301368560" class="footnote" id="idm139733301368560"><sup class="footnote">[5]</sup></a>. 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
+ <code class="filename">/foo/bar/bla.nix</code> refers to
+ <code class="filename">../xyzzy/fnord.nix</code>, the absolute path is
+ <code class="filename">/foo/xyzzy/fnord.nix</code>.</p><p>If the first component of a path is a <code class="literal">~</code>,
+ it is interpreted as if the rest of the path were relative to the
+ user's home directory. e.g. <code class="filename">~/foo</code> would be
+ equivalent to <code class="filename">/home/edolstra/foo</code> for a user
+ whose home directory is <code class="filename">/home/edolstra</code>.
+ </p><p>Paths can also be specified between angle brackets, e.g.
+ <code class="literal">&lt;nixpkgs&gt;</code>. This means that the directories
+ listed in the environment variable
+ <code class="envar"><a class="envar" href="#env-NIX_PATH">NIX_PATH</a></code> will be searched
+ for the given file or directory name.
+ </p></li><li class="listitem"><p><span class="emphasis"><em>Booleans</em></span> with values
+ <code class="literal">true</code> and
+ <code class="literal">false</code>.</p></li><li class="listitem"><p>The null value, denoted as
+ <code class="literal">null</code>.</p></li></ul></div><p>
+
+</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301358208"></a>Lists</h3></div></div></div><p>Lists are formed by enclosing a whitespace-separated list of
+values between square brackets. For example,
+
+</p><pre class="programlisting">
+[ 123 ./foo.nix "abc" (f { x = y; }) ]</pre><p>
+
+defines a list of four elements, the last being the result of a call
+to the function <code class="varname">f</code>. Note that function calls have
+to be enclosed in parentheses. If they had been omitted, e.g.,
+
+</p><pre class="programlisting">
+[ 123 ./foo.nix "abc" f { x = y; } ]</pre><p>
+
+the result would be a list of five elements, the fourth one being a
+function and the fifth being a set.</p><p>Note that lists are only lazy in values, and they are strict in length.
+</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301354960"></a>Sets</h3></div></div></div><p>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.</p><p>Sets are just a list of name/value pairs (called
+<span class="emphasis"><em>attributes</em></span>) enclosed in curly brackets, where
+each value is an arbitrary expression terminated by a semicolon. For
+example:
+
+</p><pre class="programlisting">
+{ x = 123;
+ text = "Hello";
+ y = f { bla = 456; };
+}</pre><p>
+
+This defines a set with attributes named <code class="varname">x</code>,
+<code class="varname">text</code>, <code class="varname">y</code>. The order of the
+attributes is irrelevant. An attribute name may only occur
+once.</p><p>Attributes can be selected from a set using the
+<code class="literal">.</code> operator. For instance,
+
+</p><pre class="programlisting">
+{ a = "Foo"; b = "Bar"; }.a</pre><p>
+
+evaluates to <code class="literal">"Foo"</code>. It is possible to provide a
+default value in an attribute selection using the
+<code class="literal">or</code> keyword. For example,
+
+</p><pre class="programlisting">
+{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"</pre><p>
+
+will evaluate to <code class="literal">"Xyzzy"</code> because there is no
+<code class="varname">c</code> attribute in the set.</p><p>You can use arbitrary double-quoted strings as attribute
+names:
+
+</p><pre class="programlisting">
+{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}"
+</pre><p>
+
+This will evaluate to <code class="literal">123</code> (Assuming
+<code class="literal">bar</code> is antiquotable). In the case where an
+attribute name is just a single antiquotation, the quotes can be
+dropped:
+
+</p><pre class="programlisting">
+{ foo = 123; }.${bar} or 456 </pre><p>
+
+This will evaluate to <code class="literal">123</code> if
+<code class="literal">bar</code> evaluates to <code class="literal">"foo"</code> when
+coerced to a string and <code class="literal">456</code> otherwise (again
+assuming <code class="literal">bar</code> is antiquotable).</p><p>In the special case where an attribute name inside of a set declaration
+evaluates to <code class="literal">null</code> (which is normally an error, as
+<code class="literal">null</code> is not antiquotable), that attribute is simply not
+added to the set:
+
+</p><pre class="programlisting">
+{ ${if foo then "bar" else null} = true; }</pre><p>
+
+This will evaluate to <code class="literal">{}</code> if <code class="literal">foo</code>
+evaluates to <code class="literal">false</code>.</p><p>A set that has a <code class="literal">__functor</code> attribute whose value
+is callable (i.e. is itself a function or a set with a
+<code class="literal">__functor</code> attribute whose value is callable) can be
+applied as if it were a function, with the set itself passed in first
+, e.g.,
+
+</p><pre class="programlisting">
+let add = { __functor = self: x: x + self.x; };
+ inc = add // { x = 1; };
+in inc 1
+</pre><p>
+
+evaluates to <code class="literal">2</code>. 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.
+
+</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-constructs"></a>15.2. Language Constructs</h2></div></div></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301335376"></a>Recursive sets</h3></div></div></div><p>Recursive sets are just normal sets, but the attributes can
+refer to each other. For example,
+
+</p><pre class="programlisting">
+rec {
+ x = y;
+ y = 123;
+}.x
+</pre><p>
+
+evaluates to <code class="literal">123</code>. Note that without
+<code class="literal">rec</code> the binding <code class="literal">x = y;</code> would
+refer to the variable <code class="varname">y</code> 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.</p><p>Recursive sets of course introduce the danger of infinite
+recursion. For example,
+
+</p><pre class="programlisting">
+rec {
+ x = y;
+ y = x;
+}.x</pre><p>
+
+does not terminate<a href="#ftn.idm139733301331328" class="footnote" id="idm139733301331328"><sup class="footnote">[6]</sup></a>.</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="sect-let-expressions"></a>Let-expressions</h3></div></div></div><p>A let-expression allows you to define local variables for an
+expression. For instance,
+
+</p><pre class="programlisting">
+let
+ x = "foo";
+ y = "bar";
+in x + y</pre><p>
+
+evaluates to <code class="literal">"foobar"</code>.
+
+</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301327568"></a>Inheriting attributes</h3></div></div></div><p>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
+<code class="literal">inherit</code> keyword. For instance,
+
+</p><pre class="programlisting">
+let x = 123; in
+{ inherit x;
+ y = 456;
+}</pre><p>
+
+is equivalent to
+
+</p><pre class="programlisting">
+let x = 123; in
+{ x = x;
+ y = 456;
+}</pre><p>
+
+and both evaluate to <code class="literal">{ x = 123; y = 456; }</code>. (Note that
+this works because <code class="varname">x</code> is added to the lexical scope
+by the <code class="literal">let</code> construct.) It is also possible to
+inherit attributes from another set. For instance, in this fragment
+from <code class="filename">all-packages.nix</code>,
+
+</p><pre class="programlisting">
+ graphviz = (import ../tools/graphics/graphviz) {
+ inherit fetchurl stdenv libpng libjpeg expat x11 yacc;
+ inherit (xlibs) libXaw;
+ };
+
+ xlibs = {
+ libX11 = ...;
+ libXaw = ...;
+ ...
+ }
+
+ libpng = ...;
+ libjpg = ...;
+ ...</pre><p>
+
+the set used in the function call to the function defined in
+<code class="filename">../tools/graphics/graphviz</code> inherits a number of
+variables from the surrounding scope (<code class="varname">fetchurl</code>
+... <code class="varname">yacc</code>), but also inherits
+<code class="varname">libXaw</code> (the X Athena Widgets) from the
+<code class="varname">xlibs</code> (X11 client-side libraries) set.</p><p>
+Summarizing the fragment
+
+</p><pre class="programlisting">
+...
+inherit x y z;
+inherit (src-set) a b c;
+...</pre><p>
+
+is equivalent to
+
+</p><pre class="programlisting">
+...
+x = x; y = y; z = z;
+a = src-set.a; b = src-set.b; c = src-set.c;
+...</pre><p>
+
+when used while defining local variables in a let-expression or
+while defining a set.</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="ss-functions"></a>Functions</h3></div></div></div><p>Functions have the following form:
+
+</p><pre class="programlisting">
+<em class="replaceable"><code>pattern</code></em>: <em class="replaceable"><code>body</code></em></pre><p>
+
+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:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If a pattern is a single identifier, then the
+ function matches any argument. Example:
+
+ </p><pre class="programlisting">
+let negate = x: !x;
+ concat = x: y: x + y;
+in if negate true then concat "foo" "bar" else ""</pre><p>
+
+ Note that <code class="function">concat</code> 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.,
+
+ </p><pre class="programlisting">
+map (concat "foo") [ "bar" "bla" "abc" ]</pre><p>
+
+ evaluates to <code class="literal">[ "foobar" "foobla"
+ "fooabc" ]</code>.</p></li><li class="listitem"><p>A <span class="emphasis"><em>set pattern</em></span> of the form
+ <code class="literal">{ name1, name2, …, nameN }</code> matches a set
+ containing the listed attributes, and binds the values of those
+ attributes to variables in the function body. For example, the
+ function
+
+</p><pre class="programlisting">
+{ x, y, z }: z + y + x</pre><p>
+
+ can only be called with a set containing exactly the attributes
+ <code class="varname">x</code>, <code class="varname">y</code> and
+ <code class="varname">z</code>. No other attributes are allowed. If you want
+ to allow additional arguments, you can use an ellipsis
+ (<code class="literal">...</code>):
+
+</p><pre class="programlisting">
+{ x, y, z, ... }: z + y + x</pre><p>
+
+ This works on any set that contains at least the three named
+ attributes.</p><p>It is possible to provide <span class="emphasis"><em>default values</em></span>
+ for attributes, in which case they are allowed to be missing. A
+ default value is specified by writing
+ <code class="literal"><em class="replaceable"><code>name</code></em> ?
+ <em class="replaceable"><code>e</code></em></code>, where
+ <em class="replaceable"><code>e</code></em> is an arbitrary expression. For example,
+
+</p><pre class="programlisting">
+{ x, y ? "foo", z ? "bar" }: z + y + x</pre><p>
+
+ specifies a function that only requires an attribute named
+ <code class="varname">x</code>, but optionally accepts <code class="varname">y</code>
+ and <code class="varname">z</code>.</p></li><li class="listitem"><p>An <code class="literal">@</code>-pattern provides a means of referring
+ to the whole value being matched:
+
+</p><pre class="programlisting"> args@{ x, y, z, ... }: z + y + x + args.a</pre><p>
+
+but can also be written as:
+
+</p><pre class="programlisting"> { x, y, z, ... } @ args: z + y + x + args.a</pre><p>
+
+ Here <code class="varname">args</code> is bound to the entire argument, which
+ is further matched against the pattern <code class="literal">{ x, y, z,
+ ... }</code>. <code class="literal">@</code>-pattern makes mainly sense with an
+ ellipsis(<code class="literal">...</code>) as you can access attribute names as
+ <code class="literal">a</code>, using <code class="literal">args.a</code>, which was given as an
+ additional attribute to the function.
+ </p><div class="warning"><h3 class="title">Warning</h3><p>
+ The <code class="literal">args@</code> 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 <code class="literal">args</code>.
+ </p><p>
+ For instance
+</p><pre class="programlisting">
+let
+ function = args@{ a ? 23, ... }: args;
+in
+ function {}
+</pre><p>
+ will evaluate to an empty attribute set.
+ </p></div></li></ul></div><p>Note that functions do not have names. If you want to give them
+a name, you can bind them to an attribute, e.g.,
+
+</p><pre class="programlisting">
+let concat = { x, y }: x + y;
+in concat { x = "foo"; y = "bar"; }</pre><p>
+
+</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301295536"></a>Conditionals</h3></div></div></div><p>Conditionals look like this:
+
+</p><pre class="programlisting">
+if <em class="replaceable"><code>e1</code></em> then <em class="replaceable"><code>e2</code></em> else <em class="replaceable"><code>e3</code></em></pre><p>
+
+where <em class="replaceable"><code>e1</code></em> is an expression that should
+evaluate to a Boolean value (<code class="literal">true</code> or
+<code class="literal">false</code>).</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301291568"></a>Assertions</h3></div></div></div><p>Assertions are generally used to check that certain requirements
+on or between features and dependencies hold. They look like this:
+
+</p><pre class="programlisting">
+assert <em class="replaceable"><code>e1</code></em>; <em class="replaceable"><code>e2</code></em></pre><p>
+
+where <em class="replaceable"><code>e1</code></em> is an expression that should
+evaluate to a Boolean value. If it evaluates to
+<code class="literal">true</code>, <em class="replaceable"><code>e2</code></em> is returned;
+otherwise expression evaluation is aborted and a backtrace is printed.</p><div class="example"><a id="ex-subversion-nix"></a><p class="title"><strong>Example 15.1. Nix expression for Subversion</strong></p><div class="example-contents"><pre class="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 -&gt; db4 != null; <a id="ex-subversion-nix-co-1"></a>(1)
+assert httpServer -&gt; httpd != null &amp;&amp; httpd.expat == expat; <a id="ex-subversion-nix-co-2"></a>(2)
+assert sslSupport -&gt; openssl != null &amp;&amp; (httpServer -&gt; httpd.openssl == openssl); <a id="ex-subversion-nix-co-3"></a>(3)
+assert pythonBindings -&gt; swig != null &amp;&amp; swig.pythonSupport;
+assert javaSwigBindings -&gt; swig != null &amp;&amp; swig.javaSupport;
+assert javahlBindings -&gt; j2sdk != null;
+
+stdenv.mkDerivation {
+ name = "subversion-1.1.1";
+ ...
+ openssl = if sslSupport then openssl else null; <a id="ex-subversion-nix-co-4"></a>(4)
+ ...
+}</pre></div></div><br class="example-break" /><p><a class="xref" href="#ex-subversion-nix" title="Example 15.1. Nix expression for Subversion">Example 15.1, “Nix expression for Subversion”</a> show how assertions are
+used in the Nix expression for Subversion.</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#ex-subversion-nix-co-1">(1)</a> </p></td><td valign="top" align="left"><p>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
+ <code class="varname">localServer</code> argument set to
+ <code class="literal">true</code> but the <code class="varname">db4</code> argument
+ set to <code class="literal">null</code>, then the evaluation fails.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-subversion-nix-co-2">(2)</a> </p></td><td valign="top" align="left"><p>This is a more subtle condition: if Subversion is built with
+ Apache (<code class="literal">httpServer</code>) 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.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-subversion-nix-co-3">(3)</a> </p></td><td valign="top" align="left"><p>This assertion says that in order for Subversion to have SSL
+ support (so that it can access <code class="literal">https</code> URLs), an
+ OpenSSL library must be passed. Additionally, it says that
+ <span class="emphasis"><em>if</em></span> 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.)</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#ex-subversion-nix-co-4">(4)</a> </p></td><td valign="top" align="left"><p>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-<code class="literal">null</code> value was passed.
+ This prevents an unnecessary rebuild of Subversion if OpenSSL
+ changes.</p></td></tr></table></div></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301272384"></a>With-expressions</h3></div></div></div><p>A <span class="emphasis"><em>with-expression</em></span>,
+
+</p><pre class="programlisting">
+with <em class="replaceable"><code>e1</code></em>; <em class="replaceable"><code>e2</code></em></pre><p>
+
+introduces the set <em class="replaceable"><code>e1</code></em> into the lexical
+scope of the expression <em class="replaceable"><code>e2</code></em>. For instance,
+
+</p><pre class="programlisting">
+let as = { x = "foo"; y = "bar"; };
+in with as; x + y</pre><p>
+
+evaluates to <code class="literal">"foobar"</code> since the
+<code class="literal">with</code> adds the <code class="varname">x</code> and
+<code class="varname">y</code> attributes of <code class="varname">as</code> to the
+lexical scope in the expression <code class="literal">x + y</code>. The most
+common use of <code class="literal">with</code> is in conjunction with the
+<code class="function">import</code> function. E.g.,
+
+</p><pre class="programlisting">
+with (import ./definitions.nix); ...</pre><p>
+
+makes all attributes defined in the file
+<code class="filename">definitions.nix</code> available as if they were defined
+locally in a <code class="literal">let</code>-expression.</p><p>The bindings introduced by <code class="literal">with</code> do not shadow bindings
+introduced by other means, e.g.
+
+</p><pre class="programlisting">
+let a = 3; in with { a = 1; }; let a = 4; in with { a = 2; }; ...</pre><p>
+
+establishes the same scope as
+
+</p><pre class="programlisting">
+let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...</pre><p>
+
+</p></div><div class="simplesect"><div class="titlepage"><div><div><h3 class="title"><a id="idm139733301261632"></a>Comments</h3></div></div></div><p>Comments can be single-line, started with a <code class="literal">#</code>
+character, or inline/multi-line, enclosed within <code class="literal">/*
+... */</code>.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sec-language-operators"></a>15.3. Operators</h2></div></div></div><p><a class="xref" href="#table-operators" title="Table 15.1. Operators">Table 15.1, “Operators”</a> lists the operators in the
+Nix expression language, in order of precedence (from strongest to
+weakest binding).</p><div class="table"><a id="table-operators"></a><p class="title"><strong>Table 15.1. Operators</strong></p><div class="table-contents"><table class="table" summary="Operators" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Syntax</th><th>Associativity</th><th>Description</th><th>Precedence</th></tr></thead><tbody><tr><td>Select</td><td><em class="replaceable"><code>e</code></em> <code class="literal">.</code>
+ <em class="replaceable"><code>attrpath</code></em>
+ [ <code class="literal">or</code> <em class="replaceable"><code>def</code></em> ]
+ </td><td>none</td><td>Select attribute denoted by the attribute path
+ <em class="replaceable"><code>attrpath</code></em> from set
+ <em class="replaceable"><code>e</code></em>. (An attribute path is a
+ dot-separated list of attribute names.) If the attribute
+ doesn’t exist, return <em class="replaceable"><code>def</code></em> if
+ provided, otherwise abort evaluation.</td><td>1</td></tr><tr><td>Application</td><td><em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></td><td>left</td><td>Call function <em class="replaceable"><code>e1</code></em> with
+ argument <em class="replaceable"><code>e2</code></em>.</td><td>2</td></tr><tr><td>Arithmetic Negation</td><td><code class="literal">-</code> <em class="replaceable"><code>e</code></em></td><td>none</td><td>Arithmetic negation.</td><td>3</td></tr><tr><td>Has Attribute</td><td><em class="replaceable"><code>e</code></em> <code class="literal">?</code>
+ <em class="replaceable"><code>attrpath</code></em></td><td>none</td><td>Test whether set <em class="replaceable"><code>e</code></em> contains
+ the attribute denoted by <em class="replaceable"><code>attrpath</code></em>;
+ return <code class="literal">true</code> or
+ <code class="literal">false</code>.</td><td>4</td></tr><tr><td>List Concatenation</td><td><em class="replaceable"><code>e1</code></em> <code class="literal">++</code> <em class="replaceable"><code>e2</code></em></td><td>right</td><td>List concatenation.</td><td>5</td></tr><tr><td>Multiplication</td><td>
+ <em class="replaceable"><code>e1</code></em> <code class="literal">*</code> <em class="replaceable"><code>e2</code></em>,
+ </td><td>left</td><td>Arithmetic multiplication.</td><td>6</td></tr><tr><td>Division</td><td>
+ <em class="replaceable"><code>e1</code></em> <code class="literal">/</code> <em class="replaceable"><code>e2</code></em>
+ </td><td>left</td><td>Arithmetic division.</td><td>6</td></tr><tr><td>Addition</td><td>
+ <em class="replaceable"><code>e1</code></em> <code class="literal">+</code> <em class="replaceable"><code>e2</code></em>
+ </td><td>left</td><td>Arithmetic addition.</td><td>7</td></tr><tr><td>Subtraction</td><td>
+ <em class="replaceable"><code>e1</code></em> <code class="literal">-</code> <em class="replaceable"><code>e2</code></em>
+ </td><td>left</td><td>Arithmetic subtraction.</td><td>7</td></tr><tr><td>String Concatenation</td><td>
+ <em class="replaceable"><code>string1</code></em> <code class="literal">+</code> <em class="replaceable"><code>string2</code></em>
+ </td><td>left</td><td>String concatenation.</td><td>7</td></tr><tr><td>Not</td><td><code class="literal">!</code> <em class="replaceable"><code>e</code></em></td><td>none</td><td>Boolean negation.</td><td>8</td></tr><tr><td>Update</td><td><em class="replaceable"><code>e1</code></em> <code class="literal">//</code>
+ <em class="replaceable"><code>e2</code></em></td><td>right</td><td>Return a set consisting of the attributes in
+ <em class="replaceable"><code>e1</code></em> and
+ <em class="replaceable"><code>e2</code></em> (with the latter taking
+ precedence over the former in case of equally named
+ attributes).</td><td>9</td></tr><tr><td>Less Than</td><td>
+ <em class="replaceable"><code>e1</code></em> <code class="literal">&lt;</code> <em class="replaceable"><code>e2</code></em>,
+ </td><td>none</td><td>Arithmetic comparison.</td><td>10</td></tr><tr><td>Less Than or Equal To</td><td>
+ <em class="replaceable"><code>e1</code></em> <code class="literal">&lt;=</code> <em class="replaceable"><code>e2</code></em>
+ </td><td>none</td><td>Arithmetic comparison.</td><td>10</td></tr><tr><td>Greater Than</td><td>
+ <em class="replaceable"><code>e1</code></em> <code class="literal">&gt;</code> <em class="replaceable"><code>e2</code></em>
+ </td><td>none</td><td>Arithmetic comparison.</td><td>10</td></tr><tr><td>Greater Than or Equal To</td><td>
+ <em class="replaceable"><code>e1</code></em> <code class="literal">&gt;=</code> <em class="replaceable"><code>e2</code></em>
+ </td><td>none</td><td>Arithmetic comparison.</td><td>10</td></tr><tr><td>Equality</td><td>
+ <em class="replaceable"><code>e1</code></em> <code class="literal">==</code> <em class="replaceable"><code>e2</code></em>
+ </td><td>none</td><td>Equality.</td><td>11</td></tr><tr><td>Inequality</td><td>
+ <em class="replaceable"><code>e1</code></em> <code class="literal">!=</code> <em class="replaceable"><code>e2</code></em>
+ </td><td>none</td><td>Inequality.</td><td>11</td></tr><tr><td>Logical AND</td><td><em class="replaceable"><code>e1</code></em> <code class="literal">&amp;&amp;</code>
+ <em class="replaceable"><code>e2</code></em></td><td>left</td><td>Logical AND.</td><td>12</td></tr><tr><td>Logical OR</td><td><em class="replaceable"><code>e1</code></em> <code class="literal">||</code>
+ <em class="replaceable"><code>e2</code></em></td><td>left</td><td>Logical OR.</td><td>13</td></tr><tr><td>Logical Implication</td><td><em class="replaceable"><code>e1</code></em> <code class="literal">-&gt;</code>
+ <em class="replaceable"><code>e2</code></em></td><td>none</td><td>Logical implication (equivalent to
+ <code class="literal">!<em class="replaceable"><code>e1</code></em> ||
+ <em class="replaceable"><code>e2</code></em></code>).</td><td>14</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-derivation"></a>15.4. Derivations</h2></div></div></div><p>The most important built-in function is
+<code class="function">derivation</code>, 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.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a id="attr-system"></a>There must be an attribute named
+ <code class="varname">system</code> whose value must be a string specifying a
+ Nix platform identifier, such as <code class="literal">"i686-linux"</code> or
+ <code class="literal">"x86_64-darwin"</code><a href="#ftn.idm139733301168656" class="footnote" id="idm139733301168656"><sup class="footnote">[7]</sup></a> 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 <a class="xref" href="#chap-distributed-builds" title="Chapter 16. Remote Builds">Chapter 16, <em>Remote Builds</em></a>.)</p></li><li class="listitem"><p>There must be an attribute named
+ <code class="varname">name</code> whose value must be a string. This is used
+ as a symbolic name for the package by <span class="command"><strong>nix-env</strong></span>,
+ and it is appended to the output paths of the
+ derivation.</p></li><li class="listitem"><p>There must be an attribute named
+ <code class="varname">builder</code> 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.,
+ <code class="filename">./builder.sh</code>).</p></li><li class="listitem"><p>Every attribute is passed as an environment variable
+ to the builder. Attribute values are translated to environment
+ variables as follows:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Strings and numbers are just passed
+ verbatim.</p></li><li class="listitem"><p>A <span class="emphasis"><em>path</em></span> (e.g.,
+ <code class="filename">../foo/sources.tar</code>) 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.</p></li><li class="listitem"><p>A <span class="emphasis"><em>derivation</em></span> causes that
+ derivation to be built prior to the present derivation; its
+ default output path is put in the environment
+ variable.</p></li><li class="listitem"><p>Lists of the previous types are also allowed.
+ They are simply concatenated, separated by
+ spaces.</p></li><li class="listitem"><p><code class="literal">true</code> is passed as the string
+ <code class="literal">1</code>, <code class="literal">false</code> and
+ <code class="literal">null</code> are passed as an empty string.
+ </p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>The optional attribute <code class="varname">args</code>
+ specifies command-line arguments to be passed to the builder. It
+ should be a list.</p></li><li class="listitem"><p>The optional attribute <code class="varname">outputs</code>
+ specifies a list of symbolic outputs of the derivation. By default,
+ a derivation produces a single output path, denoted as
+ <code class="literal">out</code>. 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:
+</p><pre class="programlisting">
+outputs = [ "lib" "headers" "doc" ];
+</pre><p>
+ This will cause Nix to pass environment variables
+ <code class="literal">lib</code>, <code class="literal">headers</code> and
+ <code class="literal">doc</code> to the builder containing the intended store
+ paths of each output. The builder would typically do something like
+</p><pre class="programlisting">
+./configure --libdir=$lib/lib --includedir=$headers/include --docdir=$doc/share/doc
+</pre><p>
+ for an Autoconf-style package. You can refer to each output of a
+ derivation by selecting it as an attribute, e.g.
+</p><pre class="programlisting">
+buildInputs = [ pkg.lib pkg.headers ];
+</pre><p>
+ The first element of <code class="varname">outputs</code> determines the
+ <span class="emphasis"><em>default output</em></span>. Thus, you could also write
+</p><pre class="programlisting">
+buildInputs = [ pkg pkg.headers ];
+</pre><p>
+ since <code class="literal">pkg</code> is equivalent to
+ <code class="literal">pkg.lib</code>.</p></li></ul></div><p>The function <code class="function">mkDerivation</code> in the Nixpkgs
+standard environment is a wrapper around
+<code class="function">derivation</code> that adds a default value for
+<code class="varname">system</code> 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.</p><p>The builder is executed as follows:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A temporary directory is created under the directory
+ specified by <code class="envar">TMPDIR</code> (default
+ <code class="filename">/tmp</code>) where the build will take place. The
+ current directory is changed to this directory.</p></li><li class="listitem"><p>The environment is cleared and set to the derivation
+ attributes, as specified above.</p></li><li class="listitem"><p>In addition, the following variables are set:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><code class="envar">NIX_BUILD_TOP</code> contains the path of
+ the temporary directory for this build.</p></li><li class="listitem"><p>Also, <code class="envar">TMPDIR</code>,
+ <code class="envar">TEMPDIR</code>, <code class="envar">TMP</code>, <code class="envar">TEMP</code>
+ 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.</p></li><li class="listitem"><p><code class="envar">PATH</code> is set to
+ <code class="filename">/path-not-set</code> to prevent shells from
+ initialising it to their built-in default value.</p></li><li class="listitem"><p><code class="envar">HOME</code> is set to
+ <code class="filename">/homeless-shelter</code> to prevent programs from
+ using <code class="filename">/etc/passwd</code> or the like to find the
+ user's home directory, which could cause impurity. Usually, when
+ <code class="envar">HOME</code> is set, it is used as the location of the home
+ directory, even if it points to a non-existent
+ path.</p></li><li class="listitem"><p><code class="envar">NIX_STORE</code> is set to the path of the
+ top-level Nix store directory (typically,
+ <code class="filename">/nix/store</code>).</p></li><li class="listitem"><p>For each output declared in
+ <code class="varname">outputs</code>, 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 <code class="varname">name</code> attribute
+ and the output name. (The output name is omitted if it’s
+ <code class="literal">out</code>.)</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>A log of the combined standard output and error is
+ written to <code class="filename">/nix/var/log/nix</code>.</p></li><li class="listitem"><p>The builder is executed with the arguments specified
+ by the attribute <code class="varname">args</code>. If it exits with exit
+ code 0, it is considered to have succeeded.</p></li><li class="listitem"><p>The temporary directory is removed (unless the
+ <code class="option">-K</code> option was specified).</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>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
+ <code class="literal">setuid</code> and <code class="literal">setgid</code> 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.</p></li></ul></div><p>
+
+</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sec-advanced-attributes"></a>15.4.1. Advanced Attributes</h3></div></div></div><p>Derivations can declare some infrequently used optional
+attributes.</p><div class="variablelist"><dl class="variablelist"><dt><a id="adv-attr-allowedReferences"></a><span class="term"><code class="varname">allowedReferences</code></span></dt><dd><p>The optional attribute
+ <code class="varname">allowedReferences</code> specifies a list of legal
+ references (dependencies) of the output of the builder. For
+ example,
+
+</p><pre class="programlisting">
+allowedReferences = [];
+</pre><p>
+
+ 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 <code class="literal">"out"</code> 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.</p></dd><dt><a id="adv-attr-allowedRequisites"></a><span class="term"><code class="varname">allowedRequisites</code></span></dt><dd><p>This attribute is similar to
+ <code class="varname">allowedReferences</code>, but it specifies the legal
+ requisites of the whole closure, so all the dependencies
+ recursively. For example,
+
+</p><pre class="programlisting">
+allowedRequisites = [ foobar ];
+</pre><p>
+
+ enforces that the output of a derivation cannot have any other
+ runtime dependency than <code class="varname">foobar</code>, and in addition
+ it enforces that <code class="varname">foobar</code> itself doesn't
+ introduce any other dependency itself.</p></dd><dt><a id="adv-attr-disallowedReferences"></a><span class="term"><code class="varname">disallowedReferences</code></span></dt><dd><p>The optional attribute
+ <code class="varname">disallowedReferences</code> specifies a list of illegal
+ references (dependencies) of the output of the builder. For
+ example,
+
+</p><pre class="programlisting">
+disallowedReferences = [ foo ];
+</pre><p>
+
+ enforces that the output of a derivation cannot have a direct runtime
+ dependencies on the derivation <code class="varname">foo</code>.</p></dd><dt><a id="adv-attr-disallowedRequisites"></a><span class="term"><code class="varname">disallowedRequisites</code></span></dt><dd><p>This attribute is similar to
+ <code class="varname">disallowedReferences</code>, but it specifies illegal
+ requisites for the whole closure, so all the dependencies
+ recursively. For example,
+
+</p><pre class="programlisting">
+disallowedRequisites = [ foobar ];
+</pre><p>
+
+ enforces that the output of a derivation cannot have any
+ runtime dependency on <code class="varname">foobar</code> or any other derivation
+ depending recursively on <code class="varname">foobar</code>.</p></dd><dt><a id="adv-attr-exportReferencesGraph"></a><span class="term"><code class="varname">exportReferencesGraph</code></span></dt><dd><p>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
+ <code class="literal">[ <em class="replaceable"><code>name1</code></em>
+ <em class="replaceable"><code>path1</code></em> <em class="replaceable"><code>name2</code></em>
+ <em class="replaceable"><code>path2</code></em> <em class="replaceable"><code>...</code></em>
+ ]</code>. The references graph of each
+ <em class="replaceable"><code>pathN</code></em> will be stored in a text file
+ <em class="replaceable"><code>nameN</code></em> in the temporary build directory.
+ The text files have the format used by <span class="command"><strong>nix-store
+ --register-validity</strong></span> (with the deriver fields left
+ empty). For example, when the following derivation is built:
+
+</p><pre class="programlisting">
+derivation {
+ ...
+ exportReferencesGraph = [ "libfoo-graph" libfoo ];
+};
+</pre><p>
+
+ the references graph of <code class="literal">libfoo</code> is placed in the
+ file <code class="filename">libfoo-graph</code> in the temporary build
+ directory.</p><p><code class="varname">exportReferencesGraph</code> 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 <span class="command"><strong>cpio</strong></span>
+ 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).</p></dd><dt><a id="adv-attr-impureEnvVars"></a><span class="term"><code class="varname">impureEnvVars</code></span></dt><dd><p>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, <code class="function">fetchurl</code> in
+ Nixpkgs has the line
+
+</p><pre class="programlisting">
+impureEnvVars = [ "http_proxy" "https_proxy" <em class="replaceable"><code>...</code></em> ];
+</pre><p>
+
+ to make it use the proxy server configuration specified by the
+ user in the environment variables <code class="envar">http_proxy</code> and
+ friends.</p><p>This attribute is only allowed in <a class="link" href="#fixed-output-drvs">fixed-output derivations</a>, where
+ impurities such as these are okay since (the hash of) the output
+ is known in advance. It is ignored for all other
+ derivations.</p><div class="warning"><h3 class="title">Warning</h3><p><code class="varname">impureEnvVars</code> 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
+ <span class="command"><strong>nix-build</strong></span>.</p></div></dd><dt><a id="fixed-output-drvs"></a><span class="term"><a id="adv-attr-outputHash"></a><code class="varname">outputHash</code>, </span><span class="term"><a id="adv-attr-outputHashAlgo"></a><code class="varname">outputHashAlgo</code>, </span><span class="term"><a id="adv-attr-outputHashMode"></a><code class="varname">outputHashMode</code></span></dt><dd><p>These attributes declare that the derivation is a
+ so-called <span class="emphasis"><em>fixed-output derivation</em></span>, 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.</p><p>The rationale for fixed-output derivations is derivations
+ such as those produced by the <code class="function">fetchurl</code>
+ 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,
+
+</p><pre class="programlisting">
+fetchurl {
+ url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz";
+ sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
+}
+</pre><p>
+
+ 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 <code class="function">fetchurl</code>, e.g.,
+
+</p><pre class="programlisting">
+fetchurl {
+ url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
+ sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
+}
+</pre><p>
+
+ If a <code class="function">fetchurl</code> derivation was treated like a
+ normal derivation, the output paths of the derivation and
+ <span class="emphasis"><em>all derivations depending on it</em></span> 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.</p><p>For fixed-output derivations, on the other hand, the name of
+ the output path only depends on the <code class="varname">outputHash*</code>
+ and <code class="varname">name</code> attributes, while all other attributes
+ are ignored for the purpose of computing the output path. (The
+ <code class="varname">name</code> attribute is included because it is part
+ of the path.)</p><p>As an example, here is the (simplified) Nix expression for
+ <code class="varname">fetchurl</code>:
+
+</p><pre class="programlisting">
+{ stdenv, curl }: # The <span class="command"><strong>curl</strong></span> 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 <code class="varname">sha256</code>.
+ outputHashMode = "flat";
+ outputHashAlgo = "sha256";
+ outputHash = sha256;
+
+ inherit url;
+}
+</pre><p>
+
+ </p><p>The <code class="varname">outputHashAlgo</code> attribute specifies
+ the hash algorithm used to compute the hash. It can currently be
+ <code class="literal">"sha1"</code>, <code class="literal">"sha256"</code> or
+ <code class="literal">"sha512"</code>.</p><p>The <code class="varname">outputHashMode</code> attribute determines
+ how the hash is computed. It must be one of the following two
+ values:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">"flat"</code></span></dt><dd><p>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 <span class="command"><strong>sha256sum</strong></span> or
+ <span class="command"><strong>sha1sum</strong></span> produce).</p><p>This is the default.</p></dd><dt><span class="term"><code class="literal">"recursive"</code></span></dt><dd><p>The hash is computed over the NAR archive dump
+ of the output (i.e., the result of <a class="link" href="#refsec-nix-store-dump" title="Operation --dump"><span class="command"><strong>nix-store
+ --dump</strong></span></a>). In this case, the output can be
+ anything, including a directory tree.</p></dd></dl></div><p>
+
+ </p><p>The <code class="varname">outputHash</code> attribute, finally, must
+ be a string containing the hash in either hexadecimal or base-32
+ notation. (See the <a class="link" href="#sec-nix-hash" title="nix-hash"><span class="command"><strong>nix-hash</strong></span> command</a>
+ for information about converting to and from base-32
+ notation.)</p></dd><dt><a id="adv-attr-passAsFile"></a><span class="term"><code class="varname">passAsFile</code></span></dt><dd><p>A list of names of attributes that should be
+ passed via files rather than environment variables. For example,
+ if you have
+
+ </p><pre class="programlisting">
+passAsFile = ["big"];
+big = "a very long string";
+ </pre><p>
+
+ then when the builder runs, the environment variable
+ <code class="envar">bigPath</code> will contain the absolute path to a
+ temporary file containing <code class="literal">a very long
+ string</code>. That is, for any attribute
+ <em class="replaceable"><code>x</code></em> listed in
+ <code class="varname">passAsFile</code>, Nix will pass an environment
+ variable <code class="envar"><em class="replaceable"><code>x</code></em>Path</code> holding
+ the path of the file containing the value of attribute
+ <em class="replaceable"><code>x</code></em>. 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).</p></dd><dt><a id="adv-attr-preferLocalBuild"></a><span class="term"><code class="varname">preferLocalBuild</code></span></dt><dd><p>If this attribute is set to
+ <code class="literal">true</code> and <a class="link" href="#chap-distributed-builds" title="Chapter 16. Remote Builds">distributed building is
+ enabled</a>, 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.</p></dd><dt><a id="adv-attr-allowSubstitutes"></a><span class="term"><code class="varname">allowSubstitutes</code></span></dt><dd><p>If this attribute is set to
+ <code class="literal">false</code>, then Nix will always build this
+ derivation; it will not try to substitute its outputs. This is
+ useful for very trivial derivations (such as
+ <code class="function">writeText</code> in Nixpkgs) that are cheaper to
+ build than to substitute from a binary cache.</p><div class="note"><h3 class="title">Note</h3><p>You need to have a builder configured which satisfies
+ the derivation’s <code class="literal">system</code> attribute, since the
+ derivation cannot be substituted. Thus it is usually a good idea
+ to align <code class="literal">system</code> with
+ <code class="literal">builtins.currentSystem</code> when setting
+ <code class="literal">allowSubstitutes</code> to <code class="literal">false</code>.
+ For most trivial derivations this should be the case.
+ </p></div></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-builtins"></a>15.5. Built-in Functions</h2></div></div></div><p>This section lists the functions and constants built into the
+Nix expression evaluator. (The built-in function
+<code class="function">derivation</code> is discussed above.) Some built-ins,
+such as <code class="function">derivation</code>, 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 <code class="varname">builtins</code>
+built-in value, which is a set that contains all built-in functions
+and values. For instance, <code class="function">derivation</code> is also
+available as <code class="function">builtins.derivation</code>.</p><div class="variablelist"><dl class="variablelist"><dt><a id="builtin-abort"></a><span class="term"><code class="function">abort</code> <em class="replaceable"><code>s</code></em>, </span><span class="term"><code class="function">builtins.abort</code> <em class="replaceable"><code>s</code></em></span></dt><dd><p>Abort Nix expression evaluation, print error
+ message <em class="replaceable"><code>s</code></em>.</p></dd><dt><a id="builtin-add"></a><span class="term"><code class="function">builtins.add</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em>
+ </span></dt><dd><p>Return the sum of the numbers
+ <em class="replaceable"><code>e1</code></em> and
+ <em class="replaceable"><code>e2</code></em>.</p></dd><dt><a id="builtin-all"></a><span class="term"><code class="function">builtins.all</code>
+ <em class="replaceable"><code>pred</code></em> <em class="replaceable"><code>list</code></em></span></dt><dd><p>Return <code class="literal">true</code> if the function
+ <em class="replaceable"><code>pred</code></em> returns <code class="literal">true</code>
+ for all elements of <em class="replaceable"><code>list</code></em>,
+ and <code class="literal">false</code> otherwise.</p></dd><dt><a id="builtin-any"></a><span class="term"><code class="function">builtins.any</code>
+ <em class="replaceable"><code>pred</code></em> <em class="replaceable"><code>list</code></em></span></dt><dd><p>Return <code class="literal">true</code> if the function
+ <em class="replaceable"><code>pred</code></em> returns <code class="literal">true</code>
+ for at least one element of <em class="replaceable"><code>list</code></em>,
+ and <code class="literal">false</code> otherwise.</p></dd><dt><a id="builtin-attrNames"></a><span class="term"><code class="function">builtins.attrNames</code>
+ <em class="replaceable"><code>set</code></em></span></dt><dd><p>Return the names of the attributes in the set
+ <em class="replaceable"><code>set</code></em> in an alphabetically sorted list. For instance,
+ <code class="literal">builtins.attrNames { y = 1; x = "foo"; }</code>
+ evaluates to <code class="literal">[ "x" "y" ]</code>.</p></dd><dt><a id="builtin-attrValues"></a><span class="term"><code class="function">builtins.attrValues</code>
+ <em class="replaceable"><code>set</code></em></span></dt><dd><p>Return the values of the attributes in the set
+ <em class="replaceable"><code>set</code></em> in the order corresponding to the
+ sorted attribute names.</p></dd><dt><a id="builtin-baseNameOf"></a><span class="term"><code class="function">baseNameOf</code> <em class="replaceable"><code>s</code></em></span></dt><dd><p>Return the <span class="emphasis"><em>base name</em></span> of the
+ string <em class="replaceable"><code>s</code></em>, that is, everything following
+ the final slash in the string. This is similar to the GNU
+ <span class="command"><strong>basename</strong></span> command.</p></dd><dt><a id="builtin-bitAnd"></a><span class="term"><code class="function">builtins.bitAnd</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>Return the bitwise AND of the integers
+ <em class="replaceable"><code>e1</code></em> and
+ <em class="replaceable"><code>e2</code></em>.</p></dd><dt><a id="builtin-bitOr"></a><span class="term"><code class="function">builtins.bitOr</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>Return the bitwise OR of the integers
+ <em class="replaceable"><code>e1</code></em> and
+ <em class="replaceable"><code>e2</code></em>.</p></dd><dt><a id="builtin-bitXor"></a><span class="term"><code class="function">builtins.bitXor</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>Return the bitwise XOR of the integers
+ <em class="replaceable"><code>e1</code></em> and
+ <em class="replaceable"><code>e2</code></em>.</p></dd><dt><a id="builtin-builtins"></a><span class="term"><code class="varname">builtins</code></span></dt><dd><p>The set <code class="varname">builtins</code> contains all
+ the built-in functions and values. You can use
+ <code class="varname">builtins</code> to test for the availability of
+ features in the Nix installation, e.g.,
+
+</p><pre class="programlisting">
+if builtins ? getEnv then builtins.getEnv "PATH" else ""</pre><p>
+
+ This allows a Nix expression to fall back gracefully on older Nix
+ installations that don’t have the desired built-in
+ function.</p></dd><dt><a id="builtin-compareVersions"></a><span class="term"><code class="function">builtins.compareVersions</code>
+ <em class="replaceable"><code>s1</code></em> <em class="replaceable"><code>s2</code></em></span></dt><dd><p>Compare two strings representing versions and
+ return <code class="literal">-1</code> if version
+ <em class="replaceable"><code>s1</code></em> is older than version
+ <em class="replaceable"><code>s2</code></em>, <code class="literal">0</code> if they are
+ the same, and <code class="literal">1</code> if
+ <em class="replaceable"><code>s1</code></em> is newer than
+ <em class="replaceable"><code>s2</code></em>. The version comparison algorithm
+ is the same as the one used by <a class="link" href="#ssec-version-comparisons" title="Versions"><span class="command"><strong>nix-env
+ -u</strong></span></a>.</p></dd><dt><a id="builtin-concatLists"></a><span class="term"><code class="function">builtins.concatLists</code>
+ <em class="replaceable"><code>lists</code></em></span></dt><dd><p>Concatenate a list of lists into a single
+ list.</p></dd><dt><a id="builtin-concatStringsSep"></a><span class="term"><code class="function">builtins.concatStringsSep</code>
+ <em class="replaceable"><code>separator</code></em> <em class="replaceable"><code>list</code></em></span></dt><dd><p>Concatenate a list of strings with a separator
+ between each element, e.g. <code class="literal">concatStringsSep "/"
+ ["usr" "local" "bin"] == "usr/local/bin"</code></p></dd><dt><a id="builtin-currentSystem"></a><span class="term"><code class="varname">builtins.currentSystem</code></span></dt><dd><p>The built-in value <code class="varname">currentSystem</code>
+ evaluates to the Nix platform identifier for the Nix installation
+ on which the expression is being evaluated, such as
+ <code class="literal">"i686-linux"</code> or
+ <code class="literal">"x86_64-darwin"</code>.</p></dd><dt><a id="builtin-deepSeq"></a><span class="term"><code class="function">builtins.deepSeq</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>This is like <code class="literal">seq
+ <em class="replaceable"><code>e1</code></em>
+ <em class="replaceable"><code>e2</code></em></code>, except that
+ <em class="replaceable"><code>e1</code></em> is evaluated
+ <span class="emphasis"><em>deeply</em></span>: if it’s a list or set, its elements
+ or attributes are also evaluated recursively.</p></dd><dt><a id="builtin-derivation"></a><span class="term"><code class="function">derivation</code>
+ <em class="replaceable"><code>attrs</code></em>, </span><span class="term"><code class="function">builtins.derivation</code>
+ <em class="replaceable"><code>attrs</code></em></span></dt><dd><p><code class="function">derivation</code> is described in
+ <a class="xref" href="#ssec-derivation" title="15.4. Derivations">Section 15.4, “Derivations”</a>.</p></dd><dt><a id="builtin-dirOf"></a><span class="term"><code class="function">dirOf</code> <em class="replaceable"><code>s</code></em>, </span><span class="term"><code class="function">builtins.dirOf</code> <em class="replaceable"><code>s</code></em></span></dt><dd><p>Return the directory part of the string
+ <em class="replaceable"><code>s</code></em>, that is, everything before the final
+ slash in the string. This is similar to the GNU
+ <span class="command"><strong>dirname</strong></span> command.</p></dd><dt><a id="builtin-div"></a><span class="term"><code class="function">builtins.div</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>Return the quotient of the numbers
+ <em class="replaceable"><code>e1</code></em> and
+ <em class="replaceable"><code>e2</code></em>.</p></dd><dt><a id="builtin-elem"></a><span class="term"><code class="function">builtins.elem</code>
+ <em class="replaceable"><code>x</code></em> <em class="replaceable"><code>xs</code></em></span></dt><dd><p>Return <code class="literal">true</code> if a value equal to
+ <em class="replaceable"><code>x</code></em> occurs in the list
+ <em class="replaceable"><code>xs</code></em>, and <code class="literal">false</code>
+ otherwise.</p></dd><dt><a id="builtin-elemAt"></a><span class="term"><code class="function">builtins.elemAt</code>
+ <em class="replaceable"><code>xs</code></em> <em class="replaceable"><code>n</code></em></span></dt><dd><p>Return element <em class="replaceable"><code>n</code></em> from
+ the list <em class="replaceable"><code>xs</code></em>. Elements are counted
+ starting from 0. A fatal error occurs if the index is out of
+ bounds.</p></dd><dt><a id="builtin-fetchurl"></a><span class="term"><code class="function">builtins.fetchurl</code>
+ <em class="replaceable"><code>url</code></em></span></dt><dd><p>Download the specified URL and return the path of
+ the downloaded file. This function is not available if <a class="link" href="#conf-restrict-eval">restricted evaluation mode</a> is
+ enabled.</p></dd><dt><a id="builtin-fetchTarball"></a><span class="term"><code class="function">fetchTarball</code>
+ <em class="replaceable"><code>url</code></em>, </span><span class="term"><code class="function">builtins.fetchTarball</code>
+ <em class="replaceable"><code>url</code></em></span></dt><dd><p>Download the specified URL, unpack it and return
+ the path of the unpacked tree. The file must be a tape archive
+ (<code class="filename">.tar</code>) compressed with
+ <code class="literal">gzip</code>, <code class="literal">bzip2</code> or
+ <code class="literal">xz</code>. 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.
+
+</p><pre class="programlisting">
+with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz) {};
+
+stdenv.mkDerivation { … }
+</pre><p>
+ </p><p>The fetched tarball is cached for a certain amount of time
+ (1 hour by default) in <code class="filename">~/.cache/nix/tarballs/</code>.
+ You can change the cache timeout either on the command line with
+ <code class="option">--option tarball-ttl <em class="replaceable"><code>number of seconds</code></em></code> or
+ in the Nix configuration file with this option:
+ <code class="literal"><a class="xref" href="#conf-tarball-ttl"><code class="literal">tarball-ttl</code></a> <em class="replaceable"><code>number of seconds to cache</code></em></code>.
+ </p><p>Note that when obtaining the hash with <code class="varname">nix-prefetch-url
+ </code> the option <code class="varname">--unpack</code> is required.
+ </p><p>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 <code class="varname">url</code> and the attribute
+ <code class="varname">sha256</code>, e.g.
+
+</p><pre class="programlisting">
+with import (fetchTarball {
+ url = "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz";
+ sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2";
+}) {};
+
+stdenv.mkDerivation { … }
+</pre><p>
+
+ </p><p>This function is not available if <a class="link" href="#conf-restrict-eval">restricted evaluation mode</a> is
+ enabled.</p></dd><dt><a id="builtin-fetchGit"></a><span class="term">
+ <code class="function">builtins.fetchGit</code>
+ <em class="replaceable"><code>args</code></em>
+ </span></dt><dd><p>
+ Fetch a path from git. <em class="replaceable"><code>args</code></em> 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 <code class="varname">url</code> optional):
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">url</span></dt><dd><p>
+ The URL of the repo.
+ </p></dd><dt><span class="term">name</span></dt><dd><p>
+ The name of the directory the repo should be exported to
+ in the store. Defaults to the basename of the URL.
+ </p></dd><dt><span class="term">rev</span></dt><dd><p>
+ The git revision to fetch. Defaults to the tip of
+ <code class="varname">ref</code>.
+ </p></dd><dt><span class="term">ref</span></dt><dd><p>
+ The git ref to look for the requested revision under.
+ This is often a branch or tag name. Defaults to
+ <code class="literal">HEAD</code>.
+ </p><p>
+ By default, the <code class="varname">ref</code> value is prefixed
+ with <code class="literal">refs/heads/</code>. As of Nix 2.3.0
+ Nix will not prefix <code class="literal">refs/heads/</code> if
+ <code class="varname">ref</code> starts with <code class="literal">refs/</code>.
+ </p></dd><dt><span class="term">submodules</span></dt><dd><p>
+ A Boolean parameter that specifies whether submodules
+ should be checked out. Defaults to
+ <code class="literal">false</code>.
+ </p></dd></dl></div><div class="example"><a id="idm139733300931888"></a><p class="title"><strong>Example 15.2. Fetching a private repository over SSH</strong></p><div class="example-contents"><pre class="programlisting">builtins.fetchGit {
+ url = "git@github.com:my-secret/repository.git";
+ ref = "master";
+ rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
+}</pre></div></div><br class="example-break" /><div class="example"><a id="idm139733300930528"></a><p class="title"><strong>Example 15.3. Fetching an arbitrary ref</strong></p><div class="example-contents"><pre class="programlisting">builtins.fetchGit {
+ url = "https://github.com/NixOS/nix.git";
+ ref = "refs/heads/0.5-release";
+}</pre></div></div><br class="example-break" /><div class="example"><a id="idm139733300929216"></a><p class="title"><strong>Example 15.4. Fetching a repository's specific commit on an arbitrary branch</strong></p><div class="example-contents"><p>
+ 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 <code class="varname">ref</code> attribute.
+ </p><p>
+ 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 <code class="varname">ref</code> attribute as well.
+ </p><pre class="programlisting">builtins.fetchGit {
+ url = "https://github.com/nixos/nix.git";
+ rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
+ ref = "1.11-maintenance";
+}</pre><div class="note"><h3 class="title">Note</h3><p>
+ 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.
+ </p></div></div></div><br class="example-break" /><div class="example"><a id="idm139733300924656"></a><p class="title"><strong>Example 15.5. Fetching a repository's specific commit on the default branch</strong></p><div class="example-contents"><p>
+ If the revision you're looking for is in the default branch
+ of the git repository you may omit the
+ <code class="varname">ref</code> attribute.
+ </p><pre class="programlisting">builtins.fetchGit {
+ url = "https://github.com/nixos/nix.git";
+ rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
+}</pre></div></div><br class="example-break" /><div class="example"><a id="idm139733300922352"></a><p class="title"><strong>Example 15.6. Fetching a tag</strong></p><div class="example-contents"><pre class="programlisting">builtins.fetchGit {
+ url = "https://github.com/nixos/nix.git";
+ ref = "refs/tags/1.9";
+}</pre></div></div><br class="example-break" /><div class="example"><a id="idm139733300921056"></a><p class="title"><strong>Example 15.7. Fetching the latest version of a remote branch</strong></p><div class="example-contents"><p>
+ <code class="function">builtins.fetchGit</code> can behave impurely
+ fetch the latest version of a remote branch.
+ </p><div class="note"><h3 class="title">Note</h3><p>Nix will refetch the branch in accordance to
+ <a class="xref" href="#conf-tarball-ttl"><code class="literal">tarball-ttl</code></a>.</p></div><div class="note"><h3 class="title">Note</h3><p>This behavior is disabled in
+ <span class="emphasis"><em>Pure evaluation mode</em></span>.</p></div><pre class="programlisting">builtins.fetchGit {
+ url = "ssh://git@github.com/nixos/nix.git";
+ ref = "master";
+}</pre></div></div><br class="example-break" /></dd><dt><span class="term"><code class="function">builtins.filter</code>
+ <em class="replaceable"><code>f</code></em> <em class="replaceable"><code>xs</code></em></span></dt><dd><p>Return a list consisting of the elements of
+ <em class="replaceable"><code>xs</code></em> for which the function
+ <em class="replaceable"><code>f</code></em> returns
+ <code class="literal">true</code>.</p></dd><dt><a id="builtin-filterSource"></a><span class="term"><code class="function">builtins.filterSource</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>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 <code class="filename">source-dir</code> as
+ an input to a Nix expression, e.g.
+
+</p><pre class="programlisting">
+stdenv.mkDerivation {
+ ...
+ src = ./source-dir;
+}
+</pre><p>
+
+ However, if <code class="filename">source-dir</code> is a Subversion
+ working copy, then all those annoying <code class="filename">.svn</code>
+ subdirectories will also be copied to the store. Worse, the
+ contents of those directories may change a lot, causing lots of
+ spurious rebuilds. With <code class="function">filterSource</code> you
+ can filter out the <code class="filename">.svn</code> directories:
+
+</p><pre class="programlisting">
+ src = builtins.filterSource
+ (path: type: type != "directory" || baseNameOf path != ".svn")
+ ./source-dir;
+</pre><p>
+
+ </p><p>Thus, the first argument <em class="replaceable"><code>e1</code></em>
+ must be a predicate function that is called for each regular
+ file, directory or symlink in the source tree
+ <em class="replaceable"><code>e2</code></em>. If the function returns
+ <code class="literal">true</code>, 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 <code class="literal">"regular"</code>,
+ <code class="literal">"directory"</code>, <code class="literal">"symlink"</code> or
+ <code class="literal">"unknown"</code> (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
+ <code class="literal">true</code> for them, the copy will fail). If you
+ exclude a directory, the entire corresponding subtree of
+ <em class="replaceable"><code>e2</code></em> will be excluded.</p></dd><dt><a id="builtin-foldl-prime"></a><span class="term"><code class="function">builtins.foldl’</code>
+ <em class="replaceable"><code>op</code></em> <em class="replaceable"><code>nul</code></em> <em class="replaceable"><code>list</code></em></span></dt><dd><p>Reduce a list by applying a binary operator, from
+ left to right, e.g. <code class="literal">foldl’ op nul [x0 x1 x2 ...] = op (op
+ (op nul x0) x1) x2) ...</code>. The operator is applied
+ strictly, i.e., its arguments are evaluated first. For example,
+ <code class="literal">foldl’ (x: y: x + y) 0 [1 2 3]</code> evaluates to
+ 6.</p></dd><dt><a id="builtin-functionArgs"></a><span class="term"><code class="function">builtins.functionArgs</code>
+ <em class="replaceable"><code>f</code></em></span></dt><dd><p>
+ Return a set containing the names of the formal arguments expected
+ by the function <em class="replaceable"><code>f</code></em>.
+ The value of each attribute is a Boolean denoting whether the corresponding
+ argument has a default value. For instance,
+ <code class="literal">functionArgs ({ x, y ? 123}: ...) = { x = false; y = true; }</code>.
+ </p><p>"Formal argument" here refers to the attributes pattern-matched by
+ the function. Plain lambdas are not included, e.g.
+ <code class="literal">functionArgs (x: ...) = { }</code>.
+ </p></dd><dt><a id="builtin-fromJSON"></a><span class="term"><code class="function">builtins.fromJSON</code> <em class="replaceable"><code>e</code></em></span></dt><dd><p>Convert a JSON string to a Nix
+ value. For example,
+
+</p><pre class="programlisting">
+builtins.fromJSON ''{"x": [1, 2, 3], "y": null}''
+</pre><p>
+
+ returns the value <code class="literal">{ x = [ 1 2 3 ]; y = null;
+ }</code>.</p></dd><dt><a id="builtin-genList"></a><span class="term"><code class="function">builtins.genList</code>
+ <em class="replaceable"><code>generator</code></em> <em class="replaceable"><code>length</code></em></span></dt><dd><p>Generate list of size
+ <em class="replaceable"><code>length</code></em>, with each element
+ <em class="replaceable"><code>i</code></em> equal to the value returned by
+ <em class="replaceable"><code>generator</code></em> <code class="literal">i</code>. For
+ example,
+
+</p><pre class="programlisting">
+builtins.genList (x: x * x) 5
+</pre><p>
+
+ returns the list <code class="literal">[ 0 1 4 9 16 ]</code>.</p></dd><dt><a id="builtin-getAttr"></a><span class="term"><code class="function">builtins.getAttr</code>
+ <em class="replaceable"><code>s</code></em> <em class="replaceable"><code>set</code></em></span></dt><dd><p><code class="function">getAttr</code> returns the attribute
+ named <em class="replaceable"><code>s</code></em> from
+ <em class="replaceable"><code>set</code></em>. Evaluation aborts if the
+ attribute doesn’t exist. This is a dynamic version of the
+ <code class="literal">.</code> operator, since <em class="replaceable"><code>s</code></em>
+ is an expression rather than an identifier.</p></dd><dt><a id="builtin-getEnv"></a><span class="term"><code class="function">builtins.getEnv</code>
+ <em class="replaceable"><code>s</code></em></span></dt><dd><p><code class="function">getEnv</code> returns the value of
+ the environment variable <em class="replaceable"><code>s</code></em>, 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.</p><p><code class="function">getEnv</code> is used in Nix Packages to
+ locate the file <code class="filename">~/.nixpkgs/config.nix</code>, which
+ contains user-local settings for Nix Packages. (That is, it does
+ a <code class="literal">getEnv "HOME"</code> to locate the user’s home
+ directory.)</p></dd><dt><a id="builtin-hasAttr"></a><span class="term"><code class="function">builtins.hasAttr</code>
+ <em class="replaceable"><code>s</code></em> <em class="replaceable"><code>set</code></em></span></dt><dd><p><code class="function">hasAttr</code> returns
+ <code class="literal">true</code> if <em class="replaceable"><code>set</code></em> has an
+ attribute named <em class="replaceable"><code>s</code></em>, and
+ <code class="literal">false</code> otherwise. This is a dynamic version of
+ the <code class="literal">?</code> operator, since
+ <em class="replaceable"><code>s</code></em> is an expression rather than an
+ identifier.</p></dd><dt><a id="builtin-hashString"></a><span class="term"><code class="function">builtins.hashString</code>
+ <em class="replaceable"><code>type</code></em> <em class="replaceable"><code>s</code></em></span></dt><dd><p>Return a base-16 representation of the
+ cryptographic hash of string <em class="replaceable"><code>s</code></em>. The
+ hash algorithm specified by <em class="replaceable"><code>type</code></em> must
+ be one of <code class="literal">"md5"</code>, <code class="literal">"sha1"</code>,
+ <code class="literal">"sha256"</code> or <code class="literal">"sha512"</code>.</p></dd><dt><a id="builtin-hashFile"></a><span class="term"><code class="function">builtins.hashFile</code>
+ <em class="replaceable"><code>type</code></em> <em class="replaceable"><code>p</code></em></span></dt><dd><p>Return a base-16 representation of the
+ cryptographic hash of the file at path <em class="replaceable"><code>p</code></em>. The
+ hash algorithm specified by <em class="replaceable"><code>type</code></em> must
+ be one of <code class="literal">"md5"</code>, <code class="literal">"sha1"</code>,
+ <code class="literal">"sha256"</code> or <code class="literal">"sha512"</code>.</p></dd><dt><a id="builtin-head"></a><span class="term"><code class="function">builtins.head</code>
+ <em class="replaceable"><code>list</code></em></span></dt><dd><p>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
+ <code class="literal">[]</code>.</p></dd><dt><a id="builtin-import"></a><span class="term"><code class="function">import</code>
+ <em class="replaceable"><code>path</code></em>, </span><span class="term"><code class="function">builtins.import</code>
+ <em class="replaceable"><code>path</code></em></span></dt><dd><p>Load, parse and return the Nix expression in the
+ file <em class="replaceable"><code>path</code></em>. If <em class="replaceable"><code>path
+ </code></em> is a directory, the file <code class="filename">default.nix
+ </code> in that directory is loaded. Evaluation aborts if the
+ file doesn’t exist or contains an incorrect Nix expression.
+ <code class="function">import</code> 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.</p><div class="note"><h3 class="title">Note</h3><p>Unlike some languages, <code class="function">import</code> is a regular
+ function in Nix. Paths using the angle bracket syntax (e.g., <code class="function">
+ import</code> <em class="replaceable"><code>&lt;foo&gt;</code></em>) are normal path
+ values (see <a class="xref" href="#ssec-values" title="15.1. Values">Section 15.1, “Values”</a>).</p></div><p>A Nix expression loaded by <code class="function">import</code> must
+ not contain any <span class="emphasis"><em>free variables</em></span> (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
+
+</p><pre class="programlisting">
+rec {
+ x = 123;
+ y = import ./foo.nix;
+}</pre><p>
+
+ then the following <code class="filename">foo.nix</code> will give an
+ error:
+
+</p><pre class="programlisting">
+x + 456</pre><p>
+
+ since <code class="varname">x</code> is not in scope in
+ <code class="filename">foo.nix</code>. If you want <code class="varname">x</code>
+ to be available in <code class="filename">foo.nix</code>, you should pass
+ it as a function argument:
+
+</p><pre class="programlisting">
+rec {
+ x = 123;
+ y = import ./foo.nix x;
+}</pre><p>
+
+ and
+
+</p><pre class="programlisting">
+x: x + 456</pre><p>
+
+ (The function argument doesn’t have to be called
+ <code class="varname">x</code> in <code class="filename">foo.nix</code>; any name
+ would work.)</p></dd><dt><a id="builtin-intersectAttrs"></a><span class="term"><code class="function">builtins.intersectAttrs</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>Return a set consisting of the attributes in the
+ set <em class="replaceable"><code>e2</code></em> that also exist in the set
+ <em class="replaceable"><code>e1</code></em>.</p></dd><dt><a id="builtin-isAttrs"></a><span class="term"><code class="function">builtins.isAttrs</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return <code class="literal">true</code> if
+ <em class="replaceable"><code>e</code></em> evaluates to a set, and
+ <code class="literal">false</code> otherwise.</p></dd><dt><a id="builtin-isList"></a><span class="term"><code class="function">builtins.isList</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return <code class="literal">true</code> if
+ <em class="replaceable"><code>e</code></em> evaluates to a list, and
+ <code class="literal">false</code> otherwise.</p></dd><dt><a id="builtin-isFunction"></a><span class="term"><code class="function">builtins.isFunction</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return <code class="literal">true</code> if
+ <em class="replaceable"><code>e</code></em> evaluates to a function, and
+ <code class="literal">false</code> otherwise.</p></dd><dt><a id="builtin-isString"></a><span class="term"><code class="function">builtins.isString</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return <code class="literal">true</code> if
+ <em class="replaceable"><code>e</code></em> evaluates to a string, and
+ <code class="literal">false</code> otherwise.</p></dd><dt><a id="builtin-isInt"></a><span class="term"><code class="function">builtins.isInt</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return <code class="literal">true</code> if
+ <em class="replaceable"><code>e</code></em> evaluates to an int, and
+ <code class="literal">false</code> otherwise.</p></dd><dt><a id="builtin-isFloat"></a><span class="term"><code class="function">builtins.isFloat</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return <code class="literal">true</code> if
+ <em class="replaceable"><code>e</code></em> evaluates to a float, and
+ <code class="literal">false</code> otherwise.</p></dd><dt><a id="builtin-isBool"></a><span class="term"><code class="function">builtins.isBool</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return <code class="literal">true</code> if
+ <em class="replaceable"><code>e</code></em> evaluates to a bool, and
+ <code class="literal">false</code> otherwise.</p></dd><dt><span class="term"><code class="function">builtins.isPath</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return <code class="literal">true</code> if
+ <em class="replaceable"><code>e</code></em> evaluates to a path, and
+ <code class="literal">false</code> otherwise.</p></dd><dt><a id="builtin-isNull"></a><span class="term"><code class="function">isNull</code>
+ <em class="replaceable"><code>e</code></em>, </span><span class="term"><code class="function">builtins.isNull</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return <code class="literal">true</code> if
+ <em class="replaceable"><code>e</code></em> evaluates to <code class="literal">null</code>,
+ and <code class="literal">false</code> otherwise.</p><div class="warning"><h3 class="title">Warning</h3><p>This function is <span class="emphasis"><em>deprecated</em></span>;
+ just write <code class="literal">e == null</code> instead.</p></div></dd><dt><a id="builtin-length"></a><span class="term"><code class="function">builtins.length</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return the length of the list
+ <em class="replaceable"><code>e</code></em>.</p></dd><dt><a id="builtin-lessThan"></a><span class="term"><code class="function">builtins.lessThan</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>Return <code class="literal">true</code> if the number
+ <em class="replaceable"><code>e1</code></em> is less than the number
+ <em class="replaceable"><code>e2</code></em>, and <code class="literal">false</code>
+ otherwise. Evaluation aborts if either
+ <em class="replaceable"><code>e1</code></em> or <em class="replaceable"><code>e2</code></em>
+ does not evaluate to a number.</p></dd><dt><a id="builtin-listToAttrs"></a><span class="term"><code class="function">builtins.listToAttrs</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>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
+ <code class="varname">name</code> specifying the name of the attribute, and
+ an attribute <code class="varname">value</code> specifying its value.
+ Example:
+
+</p><pre class="programlisting">
+builtins.listToAttrs
+ [ { name = "foo"; value = 123; }
+ { name = "bar"; value = 456; }
+ ]
+</pre><p>
+
+ evaluates to
+
+</p><pre class="programlisting">
+{ foo = 123; bar = 456; }
+</pre><p>
+
+ </p></dd><dt><a id="builtin-map"></a><span class="term"><code class="function">map</code>
+ <em class="replaceable"><code>f</code></em> <em class="replaceable"><code>list</code></em>, </span><span class="term"><code class="function">builtins.map</code>
+ <em class="replaceable"><code>f</code></em> <em class="replaceable"><code>list</code></em></span></dt><dd><p>Apply the function <em class="replaceable"><code>f</code></em> to
+ each element in the list <em class="replaceable"><code>list</code></em>. For
+ example,
+
+</p><pre class="programlisting">
+map (x: "foo" + x) [ "bar" "bla" "abc" ]</pre><p>
+
+ evaluates to <code class="literal">[ "foobar" "foobla" "fooabc"
+ ]</code>.</p></dd><dt><a id="builtin-match"></a><span class="term"><code class="function">builtins.match</code>
+ <em class="replaceable"><code>regex</code></em> <em class="replaceable"><code>str</code></em></span></dt><dd><p>Returns a list if the <a class="link" href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04" target="_top">extended
+ POSIX regular expression</a> <em class="replaceable"><code>regex</code></em>
+ matches <em class="replaceable"><code>str</code></em> precisely, otherwise returns
+ <code class="literal">null</code>. Each item in the list is a regex group.
+
+</p><pre class="programlisting">
+builtins.match "ab" "abc"
+</pre><p>
+
+Evaluates to <code class="literal">null</code>.
+
+</p><pre class="programlisting">
+builtins.match "abc" "abc"
+</pre><p>
+
+Evaluates to <code class="literal">[ ]</code>.
+
+</p><pre class="programlisting">
+builtins.match "a(b)(c)" "abc"
+</pre><p>
+
+Evaluates to <code class="literal">[ "b" "c" ]</code>.
+
+</p><pre class="programlisting">
+builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO "
+</pre><p>
+
+Evaluates to <code class="literal">[ "foo" ]</code>.
+
+ </p></dd><dt><a id="builtin-mul"></a><span class="term"><code class="function">builtins.mul</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>Return the product of the numbers
+ <em class="replaceable"><code>e1</code></em> and
+ <em class="replaceable"><code>e2</code></em>.</p></dd><dt><a id="builtin-parseDrvName"></a><span class="term"><code class="function">builtins.parseDrvName</code>
+ <em class="replaceable"><code>s</code></em></span></dt><dd><p>Split the string <em class="replaceable"><code>s</code></em> 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 <code class="literal">{ name, version }</code>. Thus,
+ <code class="literal">builtins.parseDrvName "nix-0.12pre12876"</code>
+ returns <code class="literal">{ name = "nix"; version = "0.12pre12876";
+ }</code>.</p></dd><dt><a id="builtin-path"></a><span class="term">
+ <code class="function">builtins.path</code>
+ <em class="replaceable"><code>args</code></em>
+ </span></dt><dd><p>
+ An enrichment of the built-in path type, based on the attributes
+ present in <em class="replaceable"><code>args</code></em>. All are optional
+ except <code class="varname">path</code>:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">path</span></dt><dd><p>The underlying path.</p></dd><dt><span class="term">name</span></dt><dd><p>
+ 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 <code class="literal">@</code>.
+ </p></dd><dt><span class="term">filter</span></dt><dd><p>
+ A function of the type expected by
+ <a class="link" href="#builtin-filterSource">builtins.filterSource</a>,
+ with the same semantics.
+ </p></dd><dt><span class="term">recursive</span></dt><dd><p>
+ When <code class="literal">false</code>, when
+ <code class="varname">path</code> is added to the store it is with a
+ flat hash, rather than a hash of the NAR serialization of
+ the file. Thus, <code class="varname">path</code> must refer to a
+ regular file, not a directory. This allows similar
+ behavior to <code class="literal">fetchurl</code>. Defaults to
+ <code class="literal">true</code>.
+ </p></dd><dt><span class="term">sha256</span></dt><dd><p>
+ 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
+ <code class="literal">builtins.path</code> to be used even when the
+ <code class="literal">pure-eval</code> nix config option is on.
+ </p></dd></dl></div></dd><dt><a id="builtin-pathExists"></a><span class="term"><code class="function">builtins.pathExists</code>
+ <em class="replaceable"><code>path</code></em></span></dt><dd><p>Return <code class="literal">true</code> if the path
+ <em class="replaceable"><code>path</code></em> exists at evaluation time, and
+ <code class="literal">false</code> otherwise.</p></dd><dt><a id="builtin-placeholder"></a><span class="term"><code class="function">builtins.placeholder</code>
+ <em class="replaceable"><code>output</code></em></span></dt><dd><p>Return a placeholder string for the specified
+ <em class="replaceable"><code>output</code></em> that will be substituted by the
+ corresponding output path at build time. Typical outputs would be
+ <code class="literal">"out"</code>, <code class="literal">"bin"</code> or
+ <code class="literal">"dev"</code>.</p></dd><dt><a id="builtin-readDir"></a><span class="term"><code class="function">builtins.readDir</code>
+ <em class="replaceable"><code>path</code></em></span></dt><dd><p>Return the contents of the directory
+ <em class="replaceable"><code>path</code></em> as a set mapping directory entries
+ to the corresponding file type. For instance, if directory
+ <code class="filename">A</code> contains a regular file
+ <code class="filename">B</code> and another directory
+ <code class="filename">C</code>, then <code class="literal">builtins.readDir
+ ./A</code> will return the set
+
+</p><pre class="programlisting">
+{ B = "regular"; C = "directory"; }</pre><p>
+
+ The possible values for the file type are
+ <code class="literal">"regular"</code>, <code class="literal">"directory"</code>,
+ <code class="literal">"symlink"</code> and
+ <code class="literal">"unknown"</code>.</p></dd><dt><a id="builtin-readFile"></a><span class="term"><code class="function">builtins.readFile</code>
+ <em class="replaceable"><code>path</code></em></span></dt><dd><p>Return the contents of the file
+ <em class="replaceable"><code>path</code></em> as a string.</p></dd><dt><a id="builtin-removeAttrs"></a><span class="term"><code class="function">removeAttrs</code>
+ <em class="replaceable"><code>set</code></em> <em class="replaceable"><code>list</code></em>, </span><span class="term"><code class="function">builtins.removeAttrs</code>
+ <em class="replaceable"><code>set</code></em> <em class="replaceable"><code>list</code></em></span></dt><dd><p>Remove the attributes listed in
+ <em class="replaceable"><code>list</code></em> from
+ <em class="replaceable"><code>set</code></em>. The attributes don’t have to
+ exist in <em class="replaceable"><code>set</code></em>. For instance,
+
+</p><pre class="programlisting">
+removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</pre><p>
+
+ evaluates to <code class="literal">{ y = 2; }</code>.</p></dd><dt><a id="builtin-replaceStrings"></a><span class="term"><code class="function">builtins.replaceStrings</code>
+ <em class="replaceable"><code>from</code></em> <em class="replaceable"><code>to</code></em> <em class="replaceable"><code>s</code></em></span></dt><dd><p>Given string <em class="replaceable"><code>s</code></em>, replace
+ every occurrence of the strings in <em class="replaceable"><code>from</code></em>
+ with the corresponding string in
+ <em class="replaceable"><code>to</code></em>. For example,
+
+</p><pre class="programlisting">
+builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar"
+</pre><p>
+
+ evaluates to <code class="literal">"fabir"</code>.</p></dd><dt><a id="builtin-seq"></a><span class="term"><code class="function">builtins.seq</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>Evaluate <em class="replaceable"><code>e1</code></em>, then
+ evaluate and return <em class="replaceable"><code>e2</code></em>. This ensures
+ that a computation is strict in the value of
+ <em class="replaceable"><code>e1</code></em>.</p></dd><dt><a id="builtin-sort"></a><span class="term"><code class="function">builtins.sort</code>
+ <em class="replaceable"><code>comparator</code></em> <em class="replaceable"><code>list</code></em></span></dt><dd><p>Return <em class="replaceable"><code>list</code></em> in sorted
+ order. It repeatedly calls the function
+ <em class="replaceable"><code>comparator</code></em> with two elements. The
+ comparator should return <code class="literal">true</code> if the first
+ element is less than the second, and <code class="literal">false</code>
+ otherwise. For example,
+
+</p><pre class="programlisting">
+builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ]
+</pre><p>
+
+ produces the list <code class="literal">[ 42 77 147 249 483 526
+ ]</code>.</p><p>This is a stable sort: it preserves the relative order of
+ elements deemed equal by the comparator.</p></dd><dt><a id="builtin-split"></a><span class="term"><code class="function">builtins.split</code>
+ <em class="replaceable"><code>regex</code></em> <em class="replaceable"><code>str</code></em></span></dt><dd><p>Returns a list composed of non matched strings interleaved
+ with the lists of the <a class="link" href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04" target="_top">extended
+ POSIX regular expression</a> <em class="replaceable"><code>regex</code></em> matches
+ of <em class="replaceable"><code>str</code></em>. Each item in the lists of matched
+ sequences is a regex group.
+
+</p><pre class="programlisting">
+builtins.split "(a)b" "abc"
+</pre><p>
+
+Evaluates to <code class="literal">[ "" [ "a" ] "c" ]</code>.
+
+</p><pre class="programlisting">
+builtins.split "([ac])" "abc"
+</pre><p>
+
+Evaluates to <code class="literal">[ "" [ "a" ] "b" [ "c" ] "" ]</code>.
+
+</p><pre class="programlisting">
+builtins.split "(a)|(c)" "abc"
+</pre><p>
+
+Evaluates to <code class="literal">[ "" [ "a" null ] "b" [ null "c" ] "" ]</code>.
+
+</p><pre class="programlisting">
+builtins.split "([[:upper:]]+)" " FOO "
+</pre><p>
+
+Evaluates to <code class="literal">[ " " [ "FOO" ] " " ]</code>.
+
+ </p></dd><dt><a id="builtin-splitVersion"></a><span class="term"><code class="function">builtins.splitVersion</code>
+ <em class="replaceable"><code>s</code></em></span></dt><dd><p>Split a string representing a version into its
+ components, by the same version splitting logic underlying the
+ version comparison in <a class="link" href="#ssec-version-comparisons" title="Versions">
+ <span class="command"><strong>nix-env -u</strong></span></a>.</p></dd><dt><a id="builtin-stringLength"></a><span class="term"><code class="function">builtins.stringLength</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return the length of the string
+ <em class="replaceable"><code>e</code></em>. If <em class="replaceable"><code>e</code></em> is
+ not a string, evaluation is aborted.</p></dd><dt><a id="builtin-sub"></a><span class="term"><code class="function">builtins.sub</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>Return the difference between the numbers
+ <em class="replaceable"><code>e1</code></em> and
+ <em class="replaceable"><code>e2</code></em>.</p></dd><dt><a id="builtin-substring"></a><span class="term"><code class="function">builtins.substring</code>
+ <em class="replaceable"><code>start</code></em> <em class="replaceable"><code>len</code></em>
+ <em class="replaceable"><code>s</code></em></span></dt><dd><p>Return the substring of
+ <em class="replaceable"><code>s</code></em> from character position
+ <em class="replaceable"><code>start</code></em> (zero-based) up to but not
+ including <em class="replaceable"><code>start + len</code></em>. If
+ <em class="replaceable"><code>start</code></em> is greater than the length of the
+ string, an empty string is returned, and if <em class="replaceable"><code>start +
+ len</code></em> lies beyond the end of the string, only the
+ substring up to the end of the string is returned.
+ <em class="replaceable"><code>start</code></em> must be
+ non-negative. For example,
+
+</p><pre class="programlisting">
+builtins.substring 0 3 "nixos"
+</pre><p>
+
+ evaluates to <code class="literal">"nix"</code>.
+ </p></dd><dt><a id="builtin-tail"></a><span class="term"><code class="function">builtins.tail</code>
+ <em class="replaceable"><code>list</code></em></span></dt><dd><p>Return the second to last elements of a list;
+ abort evaluation if the argument isn’t a list or is an empty
+ list.</p></dd><dt><a id="builtin-throw"></a><span class="term"><code class="function">throw</code>
+ <em class="replaceable"><code>s</code></em>, </span><span class="term"><code class="function">builtins.throw</code>
+ <em class="replaceable"><code>s</code></em></span></dt><dd><p>Throw an error message
+ <em class="replaceable"><code>s</code></em>. This usually aborts Nix expression
+ evaluation, but in <span class="command"><strong>nix-env -qa</strong></span> 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
+ <code class="function">abort</code>).</p></dd><dt><a id="builtin-toFile"></a><span class="term"><code class="function">builtins.toFile</code>
+ <em class="replaceable"><code>name</code></em>
+ <em class="replaceable"><code>s</code></em></span></dt><dd><p>Store the string <em class="replaceable"><code>s</code></em> in a
+ file in the Nix store and return its path. The file has suffix
+ <em class="replaceable"><code>name</code></em>. This file can be used as an
+ input to derivations. One application is to write builders
+ “inline”. For instance, the following Nix expression combines
+ <a class="xref" href="#ex-hello-nix" title="Example 14.1. Nix expression for GNU Hello (default.nix)">Example 14.1, “Nix expression for GNU Hello
+(<code class="filename">default.nix</code>)”</a> and <a class="xref" href="#ex-hello-builder" title="Example 14.2. Build script for GNU Hello (builder.sh)">Example 14.2, “Build script for GNU Hello
+(<code class="filename">builder.sh</code>)”</a> into one file:
+
+</p><pre class="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;
+}</pre><p>
+
+ </p><p>It is even possible for one file to refer to another, e.g.,
+
+</p><pre class="programlisting">
+ builder = let
+ configFile = builtins.toFile "foo.conf" "
+ # This is some dummy configuration file.
+ <em class="replaceable"><code>...</code></em>
+ ";
+ in builtins.toFile "builder.sh" "
+ source $stdenv/setup
+ <em class="replaceable"><code>...</code></em>
+ cp ${configFile} $out/etc/foo.conf
+ ";</pre><p>
+
+ Note that <code class="literal">${configFile}</code> is an antiquotation
+ (see <a class="xref" href="#ssec-values" title="15.1. Values">Section 15.1, “Values”</a>), so the result of the
+ expression <code class="literal">configFile</code> (i.e., a path like
+ <code class="filename">/nix/store/m7p7jfny445k...-foo.conf</code>) will be
+ spliced into the resulting string.</p><p>It is however <span class="emphasis"><em>not</em></span> allowed to have files
+ mutually referring to each other, like so:
+
+</p><pre class="programlisting">
+let
+ foo = builtins.toFile "foo" "...${bar}...";
+ bar = builtins.toFile "bar" "...${foo}...";
+in foo</pre><p>
+
+ This is not allowed because it would cause a cyclic dependency in
+ the computation of the cryptographic hashes for
+ <code class="varname">foo</code> and <code class="varname">bar</code>.</p><p>It is also not possible to reference the result of a derivation.
+ If you are using Nixpkgs, the <code class="literal">writeTextFile</code> function is able to
+ do that.</p></dd><dt><a id="builtin-toJSON"></a><span class="term"><code class="function">builtins.toJSON</code> <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return a string containing a JSON representation
+ of <em class="replaceable"><code>e</code></em>. 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.</p></dd><dt><a id="builtin-toPath"></a><span class="term"><code class="function">builtins.toPath</code> <em class="replaceable"><code>s</code></em></span></dt><dd><p> DEPRECATED. Use <code class="literal">/. + "/path"</code>
+ to convert a string into an absolute path. For relative paths,
+ use <code class="literal">./. + "/path"</code>.
+ </p></dd><dt><a id="builtin-toString"></a><span class="term"><code class="function">toString</code> <em class="replaceable"><code>e</code></em>, </span><span class="term"><code class="function">builtins.toString</code> <em class="replaceable"><code>e</code></em></span></dt><dd><p>Convert the expression
+ <em class="replaceable"><code>e</code></em> to a string.
+ <em class="replaceable"><code>e</code></em> can be:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A string (in which case the string is returned unmodified).</p></li><li class="listitem"><p>A path (e.g., <code class="literal">toString /foo/bar</code> yields <code class="literal">"/foo/bar"</code>.</p></li><li class="listitem"><p>A set containing <code class="literal">{ __toString = self: ...; }</code>.</p></li><li class="listitem"><p>An integer.</p></li><li class="listitem"><p>A list, in which case the string representations of its elements are joined with spaces.</p></li><li class="listitem"><p>A Boolean (<code class="literal">false</code> yields <code class="literal">""</code>, <code class="literal">true</code> yields <code class="literal">"1"</code>).</p></li><li class="listitem"><p><code class="literal">null</code>, which yields the empty string.</p></li></ul></div></dd><dt><a id="builtin-toXML"></a><span class="term"><code class="function">builtins.toXML</code> <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return a string containing an XML representation
+ of <em class="replaceable"><code>e</code></em>. The main application for
+ <code class="function">toXML</code> is to communicate information with the
+ builder in a more structured format than plain environment
+ variables.</p><p><a class="xref" href="#ex-toxml" title="Example 15.8. Passing information to a builder using toXML">Example 15.8, “Passing information to a builder
+ using <code class="function">toXML</code>”</a> shows an example where this is
+ the case. The builder is supposed to generate the configuration
+ file for a <a class="link" href="http://jetty.mortbay.org/" target="_top">Jetty
+ servlet container</a>. A servlet container contains a number
+ of servlets (<code class="filename">*.war</code> files) each exported under
+ a specific URI prefix. So the servlet configuration is a list of
+ sets containing the <code class="varname">path</code> and
+ <code class="varname">war</code> of the servlet (<a class="xref" href="#ex-toxml-co-servlets">(3)</a>). 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
+ <code class="function">toXML</code>, which is unambiguous and can easily be
+ processed with the appropriate tools. For instance, in the
+ example an XSLT stylesheet (<a class="xref" href="#ex-toxml-co-stylesheet">(2)</a>) is applied to it (<a class="xref" href="#ex-toxml-co-apply">(1)</a>) to
+ generate the XML configuration file for the Jetty server. The XML
+ representation produced from <a class="xref" href="#ex-toxml-co-servlets">(3)</a> by <code class="function">toXML</code> is shown in <a class="xref" href="#ex-toxml-result" title="Example 15.9. XML representation produced by toXML">Example 15.9, “XML representation produced by
+ <code class="function">toXML</code>”</a>.</p><p>Note that <a class="xref" href="#ex-toxml" title="Example 15.8. Passing information to a builder using toXML">Example 15.8, “Passing information to a builder
+ using <code class="function">toXML</code>”</a> uses the <code class="function"><a class="function" href="#builtin-toFile">toFile</a></code> 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
+ <code class="literal">xsltproc ${stylesheet}
+ <em class="replaceable"><code>...</code></em></code>.</p><div class="example"><a id="ex-toxml"></a><p class="title"><strong>Example 15.8. Passing information to a builder
+ using <code class="function">toXML</code></strong></p><div class="example-contents"><pre class="programlisting">
+{ 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} - &gt; $out/server-conf.xml <a id="ex-toxml-co-apply"></a>(1)
+ ";
+
+ stylesheet = builtins.toFile "stylesheet.xsl" <a id="ex-toxml-co-stylesheet"></a>(2)
+ "&lt;?xml version='1.0' encoding='UTF-8'?&gt;
+ &lt;xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'&gt;
+ &lt;xsl:template match='/'&gt;
+ &lt;Configure&gt;
+ &lt;xsl:for-each select='/expr/list/attrs'&gt;
+ &lt;Call name='addWebApplication'&gt;
+ &lt;Arg&gt;&lt;xsl:value-of select=\"attr[@name = 'path']/string/@value\" /&gt;&lt;/Arg&gt;
+ &lt;Arg&gt;&lt;xsl:value-of select=\"attr[@name = 'war']/path/@value\" /&gt;&lt;/Arg&gt;
+ &lt;/Call&gt;
+ &lt;/xsl:for-each&gt;
+ &lt;/Configure&gt;
+ &lt;/xsl:template&gt;
+ &lt;/xsl:stylesheet&gt;
+ ";
+
+ servlets = builtins.toXML [ <a id="ex-toxml-co-servlets"></a>(3)
+ { path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; }
+ { path = "/wiki"; war = uberwiki + "/uberwiki.war"; }
+ ];
+})</pre></div></div><br class="example-break" /><div class="example"><a id="ex-toxml-result"></a><p class="title"><strong>Example 15.9. XML representation produced by
+ <code class="function">toXML</code></strong></p><div class="example-contents"><pre class="programlisting">&lt;?xml version='1.0' encoding='utf-8'?&gt;
+&lt;expr&gt;
+ &lt;list&gt;
+ &lt;attrs&gt;
+ &lt;attr name="path"&gt;
+ &lt;string value="/bugtracker" /&gt;
+ &lt;/attr&gt;
+ &lt;attr name="war"&gt;
+ &lt;path value="/nix/store/d1jh9pasa7k2...-jira/lib/atlassian-jira.war" /&gt;
+ &lt;/attr&gt;
+ &lt;/attrs&gt;
+ &lt;attrs&gt;
+ &lt;attr name="path"&gt;
+ &lt;string value="/wiki" /&gt;
+ &lt;/attr&gt;
+ &lt;attr name="war"&gt;
+ &lt;path value="/nix/store/y6423b1yi4sx...-uberwiki/uberwiki.war" /&gt;
+ &lt;/attr&gt;
+ &lt;/attrs&gt;
+ &lt;/list&gt;
+&lt;/expr&gt;</pre></div></div><br class="example-break" /></dd><dt><a id="builtin-trace"></a><span class="term"><code class="function">builtins.trace</code>
+ <em class="replaceable"><code>e1</code></em> <em class="replaceable"><code>e2</code></em></span></dt><dd><p>Evaluate <em class="replaceable"><code>e1</code></em> and print its
+ abstract syntax representation on standard error. Then return
+ <em class="replaceable"><code>e2</code></em>. This function is useful for
+ debugging.</p></dd><dt><a id="builtin-tryEval"></a><span class="term"><code class="function">builtins.tryEval</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Try to shallowly evaluate <em class="replaceable"><code>e</code></em>.
+ Return a set containing the attributes <code class="literal">success</code>
+ (<code class="literal">true</code> if <em class="replaceable"><code>e</code></em> evaluated
+ successfully, <code class="literal">false</code> if an error was thrown) and
+ <code class="literal">value</code>, equalling <em class="replaceable"><code>e</code></em>
+ if successful and <code class="literal">false</code> otherwise. Note that this
+ doesn't evaluate <em class="replaceable"><code>e</code></em> deeply, so
+ <code class="literal">let e = { x = throw ""; }; in (builtins.tryEval e).success
+ </code> will be <code class="literal">true</code>. Using <code class="literal">builtins.deepSeq
+ </code> one can get the expected result: <code class="literal">let e = { x = throw "";
+ }; in (builtins.tryEval (builtins.deepSeq e e)).success</code> will be
+ <code class="literal">false</code>.
+ </p></dd><dt><a id="builtin-typeOf"></a><span class="term"><code class="function">builtins.typeOf</code>
+ <em class="replaceable"><code>e</code></em></span></dt><dd><p>Return a string representing the type of the value
+ <em class="replaceable"><code>e</code></em>, namely <code class="literal">"int"</code>,
+ <code class="literal">"bool"</code>, <code class="literal">"string"</code>,
+ <code class="literal">"path"</code>, <code class="literal">"null"</code>,
+ <code class="literal">"set"</code>, <code class="literal">"list"</code>,
+ <code class="literal">"lambda"</code> or
+ <code class="literal">"float"</code>.</p></dd></dl></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm139733301368560" class="footnote"><p><a href="#idm139733301368560" class="para"><sup class="para">[5] </sup></a>It's parsed as an expression that selects the
+ attribute <code class="varname">sh</code> from the variable
+ <code class="varname">builder</code>.</p></div><div id="ftn.idm139733301331328" class="footnote"><p><a href="#idm139733301331328" class="para"><sup class="para">[6] </sup></a>Actually, Nix detects infinite
+recursion in this case and aborts (<span class="quote">“<span class="quote">infinite recursion
+encountered</span>”</span>).</p></div><div id="ftn.idm139733301168656" class="footnote"><p><a href="#idm139733301168656" class="para"><sup class="para">[7] </sup></a>To figure out
+ your platform identifier, look at the line <span class="quote">“<span class="quote">Checking for the
+ canonical Nix system name</span>”</span> in the output of Nix's
+ <code class="filename">configure</code> script.</p></div></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="part-advanced-topics"></a>Part V. Advanced Topics</h1></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="chap-distributed-builds"></a>Chapter 16. Remote Builds</h2></div></div></div><p>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 <code class="literal">x86_64-darwin</code> on an
+<code class="literal">i686-linux</code> machine, Nix can automatically forward
+the build to a <code class="literal">x86_64-darwin</code> machine, if
+available.</p><p>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.
+
+</p><pre class="screen">
+$ nix ping-store --store ssh://mac
+</pre><p>
+
+will try to connect to the machine named <code class="literal">mac</code>. It is
+possible to specify an SSH identity file as part of the remote store
+URI, e.g.
+
+</p><pre class="screen">
+$ nix ping-store --store ssh://mac?ssh-key=/home/alice/my-key
+</pre><p>
+
+Since builds should be non-interactive, the key should not have a
+passphrase. Alternatively, you can load identities ahead of time into
+<span class="command"><strong>ssh-agent</strong></span> or <span class="command"><strong>gpg-agent</strong></span>.</p><p>If you get the error
+
+</p><pre class="screen">
+bash: nix-store: command not found
+error: cannot connect to 'mac'
+</pre><p>
+
+then you need to ensure that the <code class="envar">PATH</code> of
+non-interactive login shells contains Nix.</p><div class="warning"><h3 class="title">Warning</h3><p>If you are building via the Nix daemon, it is the Nix
+daemon user account (that is, <code class="literal">root</code>) that should
+have SSH access to the remote machine. If you can’t or don’t want to
+configure <code class="literal">root</code> to be able to access to remote
+machine, you can use a private Nix store instead by passing
+e.g. <code class="literal">--store ~/my-nix</code>.</p></div><p>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 <code class="literal">x86_64-darwin</code> on a Linux machine:
+
+</p><pre class="screen">
+$ uname
+Linux
+
+$ nix build \
+ '(with import &lt;nixpkgs&gt; { system = "x86_64-darwin"; }; runCommand "foo" {} "uname &gt; $out")' \
+ --builders 'ssh://mac x86_64-darwin'
+[1/0/1 built, 0.0 MiB DL] building foo on ssh://mac
+
+$ cat ./result
+Darwin
+</pre><p>
+
+It is possible to specify multiple builders separated by a semicolon
+or a newline, e.g.
+
+</p><pre class="screen">
+ --builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd'
+</pre><p>
+</p><p>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 <code class="literal">-</code>.
+
+</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>The URI of the remote store in the format
+ <code class="literal">ssh://[<em class="replaceable"><code>username</code></em>@]<em class="replaceable"><code>hostname</code></em></code>,
+ e.g. <code class="literal">ssh://nix@mac</code> or
+ <code class="literal">ssh://mac</code>. For backward compatibility,
+ <code class="literal">ssh://</code> may be omitted. The hostname may be an
+ alias defined in your
+ <code class="filename">~/.ssh/config</code>.</p></li><li class="listitem"><p>A comma-separated list of Nix platform type
+ identifiers, such as <code class="literal">x86_64-darwin</code>. It is
+ possible for a machine to support multiple platform types, e.g.,
+ <code class="literal">i686-linux,x86_64-linux</code>. If omitted, this
+ defaults to the local platform type.</p></li><li class="listitem"><p>The SSH identity file to be used to log in to the
+ remote machine. If omitted, SSH will use its regular
+ identities.</p></li><li class="listitem"><p>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
+ <code class="literal">itchy</code> in the example will execute up to 8 builds
+ in parallel.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>A comma-separated list of <span class="emphasis"><em>supported
+ features</em></span>. If a derivation has the
+ <code class="varname">requiredSystemFeatures</code> attribute, then Nix will
+ only perform the derivation on a machine that has the specified
+ features. For instance, the attribute
+
+</p><pre class="programlisting">
+requiredSystemFeatures = [ "kvm" ];
+</pre><p>
+
+ will cause the build to be performed on a machine that has the
+ <code class="literal">kvm</code> feature.</p></li><li class="listitem"><p>A comma-separated list of <span class="emphasis"><em>mandatory
+ features</em></span>. A machine will only be used to build a
+ derivation if all of the machine’s mandatory features appear in the
+ derivation’s <code class="varname">requiredSystemFeatures</code>
+ attribute..</p></li></ol></div><p>
+
+For example, the machine specification
+
+</p><pre class="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
+</pre><p>
+
+specifies several machines that can perform
+<code class="literal">i686-linux</code> builds. However,
+<code class="literal">poochie</code> will only do builds that have the attribute
+
+</p><pre class="programlisting">
+requiredSystemFeatures = [ "benchmark" ];
+</pre><p>
+
+or
+
+</p><pre class="programlisting">
+requiredSystemFeatures = [ "benchmark" "kvm" ];
+</pre><p>
+
+<code class="literal">itchy</code> cannot do builds that require
+<code class="literal">kvm</code>, but <code class="literal">scratchy</code> does support
+such builds. For regular builds, <code class="literal">itchy</code> will be
+preferred over <code class="literal">scratchy</code> because it has a higher
+speed factor.</p><p>Remote builders can also be configured in
+<code class="filename">nix.conf</code>, e.g.
+
+</p><pre class="programlisting">
+builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd
+</pre><p>
+
+Finally, remote builders can be configured in a separate configuration
+file included in <code class="option">builders</code> via the syntax
+<code class="literal">@<em class="replaceable"><code>file</code></em></code>. For example,
+
+</p><pre class="programlisting">
+builders = @/etc/nix/machines
+</pre><p>
+
+causes the list of machines in <code class="filename">/etc/nix/machines</code>
+to be included. (This is the default.)</p><p>If you want the builders to use caches, you likely want to set
+the option <a class="link" href="#conf-builders-use-substitutes"><code class="literal">builders-use-substitutes</code></a>
+in your local <code class="filename">nix.conf</code>.</p><p>To build only on remote builders and disable building on the local machine,
+you can use the option <code class="option">--max-jobs 0</code>.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="chap-tuning-cores-and-jobs"></a>Chapter 17. Tuning Cores and Jobs</h2></div></div></div><p>Nix has two relevant settings with regards to how your CPU cores
+will be utilized: <a class="xref" href="#conf-cores"><code class="literal">cores</code></a> and
+<a class="xref" href="#conf-max-jobs"><code class="literal">max-jobs</code></a>. This chapter will talk about what
+they are, how they interact, and their configuration trade-offs.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><a class="xref" href="#conf-max-jobs"><code class="literal">max-jobs</code></a></span></dt><dd><p>
+ 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.
+ </p></dd><dt><span class="term"><a class="xref" href="#conf-cores"><code class="literal">cores</code></a></span></dt><dd><p>
+ Suggests how many cores each derivation should use. Similar to
+ <span class="command"><strong>make -j</strong></span>.
+ </p></dd></dl></div><p>The <a class="xref" href="#conf-cores"><code class="literal">cores</code></a> setting determines the value of
+<code class="envar">NIX_BUILD_CORES</code>. <code class="envar">NIX_BUILD_CORES</code> is equal
+to <a class="xref" href="#conf-cores"><code class="literal">cores</code></a>, unless <a class="xref" href="#conf-cores"><code class="literal">cores</code></a>
+equals <code class="literal">0</code>, in which case <code class="envar">NIX_BUILD_CORES</code>
+will be the total number of cores in the system.</p><p>The maximum number of consumed cores is a simple multiplication,
+<a class="xref" href="#conf-max-jobs"><code class="literal">max-jobs</code></a> * <code class="envar">NIX_BUILD_CORES</code>.</p><p>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:</p><div class="table"><a id="idm139733300537552"></a><p class="title"><strong>Table 17.1. Balancing 24 Build Cores</strong></p><div class="table-contents"><table><thead><tr>
+ <th><a class="xref" href="#conf-max-jobs"><code class="literal">max-jobs</code></a></th>
+ <th><a class="xref" href="#conf-cores"><code class="literal">cores</code></a></th>
+ <th><code class="envar">NIX_BUILD_CORES</code></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></div></div><br class="table-break" /><p>It is up to the derivations' build script to respect
+host's requested cores-per-build by following the value of the
+<code class="envar">NIX_BUILD_CORES</code> environment variable.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="chap-diff-hook"></a>Chapter 18. Verifying Build Reproducibility with <code class="option"><a class="option" href="#conf-diff-hook">diff-hook</a></code></h2></div><div><h3 class="subtitle"><em>Check build reproducibility by running builds multiple times
+and comparing their results.</em></h3></div></div></div><p>Specify a program with Nix's <a class="xref" href="#conf-diff-hook"><code class="literal">diff-hook</code></a> 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.</p><p>For purposes of demonstration, we'll use the following Nix file,
+<code class="filename">deterministic.nix</code> for testing:</p><pre class="programlisting">
+let
+ inherit (import &lt;nixpkgs&gt; {}) runCommand;
+in {
+ stable = runCommand "stable" {} ''
+ touch $out
+ '';
+
+ unstable = runCommand "unstable" {} ''
+ echo $RANDOM &gt; $out
+ '';
+}
+</pre><p>Additionally, <code class="filename">nix.conf</code> contains:
+
+</p><pre class="programlisting">
+diff-hook = /etc/nix/my-diff-hook
+run-diff-hook = true
+</pre><p>
+
+where <code class="filename">/etc/nix/my-diff-hook</code> is an executable
+file containing:
+
+</p><pre class="programlisting">
+#!/bin/sh
+exec &gt;&amp;2
+echo "For derivation $3:"
+/run/current-system/sw/bin/diff -r "$1" "$2"
+</pre><p>
+
+</p><p>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.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733300510624"></a>18.1. 
+ Spot-Checking Build Determinism
+ </h2></div></div></div><p>
+ Verify a path which already exists in the Nix store by passing
+ <code class="option">--check</code> to the build command.
+ </p><p>If the build passes and is deterministic, Nix will exit with a
+ status code of 0:</p><pre class="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
+</pre><p>If the build is not deterministic, Nix will exit with a status
+ code of 1:</p><pre class="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
+</pre><p>In the Nix daemon's log, we will now see:
+</p><pre class="screen">
+For derivation /nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv:
+1c1
+&lt; 8108
+---
+&gt; 30204
+</pre><p>
+</p><p>Using <code class="option">--check</code> with <code class="option">--keep-failed</code>
+ will cause Nix to keep the second build's output in a special,
+ <code class="literal">.check</code> path:</p><pre class="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'
+</pre><p>In particular, notice the
+ <code class="literal">/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check</code>
+ output. Nix has copied the build results to that directory where you
+ can examine it.</p><div class="note"><h3 class="title"><a id="check-dirs-are-unregistered"></a><code class="literal">.check</code> paths are not registered store paths</h3><p>Check paths are not protected against garbage collection,
+ and this path will be deleted on the next garbage collection.</p><p>The path is guaranteed to be alive for the duration of
+ <a class="xref" href="#conf-diff-hook"><code class="literal">diff-hook</code></a>'s execution, but may be deleted
+ any time after.</p><p>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.</p></div><p>
+ <code class="option">--check</code> 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:
+ </p><pre class="screen">
+error: some outputs of '/nix/store/hzi1h60z2qf0nb85iwnpvrai3j2w7rr6-unstable.drv' are not valid, so checking is not possible
+</pre><p>
+
+ Run the build without <code class="option">--check</code>, and then try with
+ <code class="option">--check</code> again.
+ </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733300495744"></a>18.2. 
+ Automatic and Optionally Enforced Determinism Verification
+ </h2></div></div></div><p>
+ Automatically verify every build at build time by executing the
+ build multiple times.
+ </p><p>
+ Setting <a class="xref" href="#conf-repeat"><code class="literal">repeat</code></a> and
+ <a class="xref" href="#conf-enforce-determinism"><code class="literal">enforce-determinism</code></a> in your
+ <code class="filename">nix.conf</code> permits the automated verification
+ of every build Nix performs.
+ </p><p>
+ The following configuration will run each build three times, and
+ will require the build to be deterministic:
+
+ </p><pre class="programlisting">
+enforce-determinism = true
+repeat = 2
+</pre><p>
+ </p><p>
+ Setting <a class="xref" href="#conf-enforce-determinism"><code class="literal">enforce-determinism</code></a> 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:
+
+ </p><pre class="programlisting">
+enforce-determinism = false
+repeat = 1
+</pre><p>
+ </p><p>
+ An example output of this configuration:
+ </p><pre class="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
+</pre><p>
+ </p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="chap-post-build-hook"></a>Chapter 19. Using the <code class="option"><a class="option" href="#conf-post-build-hook">post-build-hook</a></code></h2></div><div><h3 class="subtitle"><em>Uploading to an S3-compatible binary cache after each build</em></h3></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="chap-post-build-hook-caveats"></a>19.1. Implementation Caveats</h2></div></div></div><p>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.</p><p>The post build hook program runs after each executed build,
+ and blocks the build loop. The build loop exits if the hook program
+ fails.</p><p>Concretely, this implementation will make Nix slow or unusable
+ when the internet is slow or unreliable.</p><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733300481840"></a>19.2. Prerequisites</h2></div></div></div><p>
+ This tutorial assumes you have configured an S3-compatible binary cache
+ according to the instructions at
+ <a class="xref" href="#ssec-s3-substituter-authenticated-writes" title="13.4.3. Authenticated Writes to your S3-compatible binary cache">Section 13.4.3, “Authenticated Writes to your S3-compatible binary cache”</a>, and
+ that the <code class="literal">root</code> user's default AWS profile can
+ upload to the bucket.
+ </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733300479440"></a>19.3. Set up a Signing Key</h2></div></div></div><p>Use <span class="command"><strong>nix-store --generate-binary-cache-key</strong></span> 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.</p><pre class="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=
+</pre><p>Then, add the public key and the cache URL to your
+<code class="filename">nix.conf</code>'s <a class="xref" href="#conf-trusted-public-keys"><code class="literal">trusted-public-keys</code></a>
+and <a class="xref" href="#conf-substituters"><code class="literal">substituters</code></a> like:</p><pre class="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=
+</pre><p>We will restart the Nix daemon in a later step.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733300473952"></a>19.4. Implementing the build hook</h2></div></div></div><p>Write the following script to
+ <code class="filename">/etc/nix/upload-to-cache.sh</code>:
+ </p><pre class="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
+</pre><div class="note"><h3 class="title">Should <code class="literal">$OUT_PATHS</code> be quoted?</h3><p>
+ The <code class="literal">$OUT_PATHS</code> 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 <span class="command"><strong>nix sign-paths</strong></span>. Nix guarantees
+ the paths will not contain any spaces, however a store path
+ might contain glob characters. The <span class="command"><strong>set -f</strong></span>
+ disables globbing in the shell.
+ </p></div><p>
+ Then make sure the hook program is executable by the <code class="literal">root</code> user:
+ </p><pre class="screen">
+# chmod +x /etc/nix/upload-to-cache.sh
+</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733300467040"></a>19.5. Updating Nix Configuration</h2></div></div></div><p>Edit <code class="filename">/etc/nix/nix.conf</code> to run our hook,
+ by adding the following configuration snippet at the end:</p><pre class="programlisting">
+post-build-hook = /etc/nix/upload-to-cache.sh
+</pre><p>Then, restart the <span class="command"><strong>nix-daemon</strong></span>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733300464016"></a>19.6. Testing</h2></div></div></div><p>Build any derivation, for example:</p><pre class="screen">
+$ nix-build -E '(import &lt;nixpkgs&gt; {}).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
+</pre><p>Then delete the path from the store, and try substituting it from the binary cache:</p><pre class="screen">
+$ rm ./result
+$ nix-store --delete /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example
+</pre><p>Now, copy the path back from the cache:</p><pre class="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
+</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm139733300459088"></a>19.7. Conclusion</h2></div></div></div><p>
+ We now have a Nix installation configured to automatically sign and
+ upload every local build to a remote binary cache.
+ </p><p>
+ Before deploying this to production, be sure to consider the
+ implementation caveats in <a class="xref" href="#chap-post-build-hook-caveats" title="19.1. Implementation Caveats">Section 19.1, “Implementation Caveats”</a>.
+ </p></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="part-command-ref"></a>Part VI. Command Reference</h1></div></div></div><div class="partintro"><div></div><p>This section lists commands and options that you can use when you
+work with Nix.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="sec-common-options"></a>Chapter 20. Common Options</h2></div></div></div><p>Most Nix commands accept the following command-line options:</p><div class="variablelist"><a id="opt-common"></a><dl class="variablelist"><dt><span class="term"><code class="option">--help</code></span></dt><dd><p>Prints out a summary of the command syntax and
+ exits.</p></dd><dt><span class="term"><code class="option">--version</code></span></dt><dd><p>Prints out the Nix version number on standard output
+ and exits.</p></dd><dt><span class="term"><code class="option">--verbose</code> / <code class="option">-v</code></span></dt><dd><p>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.</p><p>This option may be specified repeatedly. Currently, the
+ following verbosity levels exist:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">0</span></dt><dd><p>“Errors only”: only print messages
+ explaining why the Nix invocation failed.</p></dd><dt><span class="term">1</span></dt><dd><p>“Informational”: print
+ <span class="emphasis"><em>useful</em></span> messages about what Nix is doing.
+ This is the default.</p></dd><dt><span class="term">2</span></dt><dd><p>“Talkative”: print more informational
+ messages.</p></dd><dt><span class="term">3</span></dt><dd><p>“Chatty”: print even more
+ informational messages.</p></dd><dt><span class="term">4</span></dt><dd><p>“Debug”: print debug
+ information.</p></dd><dt><span class="term">5</span></dt><dd><p>“Vomit”: print vast amounts of debug
+ information.</p></dd></dl></div></dd><dt><span class="term"><code class="option">--quiet</code></span></dt><dd><p>Decreases the level of verbosity of diagnostic messages
+ printed on standard error. This is the inverse option to
+ <code class="option">-v</code> / <code class="option">--verbose</code>.
+ </p><p>This option may be specified repeatedly. See the previous
+ verbosity levels list.</p></dd><dt><a id="opt-log-format"></a><span class="term"><code class="option">--log-format</code> <em class="replaceable"><code>format</code></em></span></dt><dd><p>This option can be used to change the output of the log format, with
+ <em class="replaceable"><code>format</code></em> being one of:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">raw</span></dt><dd><p>This is the raw format, as outputted by nix-build.</p></dd><dt><span class="term">internal-json</span></dt><dd><p>Outputs the logs in a structured manner. NOTE: the json schema is not guarantees to be stable between releases.</p></dd><dt><span class="term">bar</span></dt><dd><p>Only display a progress bar during the builds.</p></dd><dt><span class="term">bar-with-logs</span></dt><dd><p>Display the raw logs, with the progress bar at the bottom.</p></dd></dl></div></dd><dt><span class="term"><code class="option">--no-build-output</code> / <code class="option">-Q</code></span></dt><dd><p>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
+ <code class="filename"><em class="replaceable"><code>prefix</code></em>/nix/var/log/nix</code>.</p></dd><dt><a id="opt-max-jobs"></a><span class="term"><code class="option">--max-jobs</code> / <code class="option">-j</code>
+<em class="replaceable"><code>number</code></em></span></dt><dd><p>Sets the maximum number of build jobs that Nix will
+ perform in parallel to the specified number. Specify
+ <code class="literal">auto</code> to use the number of CPUs in the system.
+ The default is specified by the <a class="link" href="#conf-max-jobs"><code class="literal">max-jobs</code></a>
+ configuration setting, which itself defaults to
+ <code class="literal">1</code>. A higher value is useful on SMP systems or to
+ exploit I/O latency.</p><p> Setting it to <code class="literal">0</code> disallows building on the local
+ machine, which is useful when you want builds to happen only on remote
+ builders.</p></dd><dt><a id="opt-cores"></a><span class="term"><code class="option">--cores</code></span></dt><dd><p>Sets the value of the <code class="envar">NIX_BUILD_CORES</code>
+ 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 <code class="varname">enableParallelBuilding</code> is set to
+ <code class="literal">true</code>, the builder passes the
+ <code class="option">-j<em class="replaceable"><code>N</code></em></code> flag to GNU Make.
+ It defaults to the value of the <a class="link" href="#conf-cores"><code class="literal">cores</code></a>
+ configuration setting, if set, or <code class="literal">1</code> otherwise.
+ The value <code class="literal">0</code> means that the builder should use all
+ available CPU cores in the system.</p></dd><dt><a id="opt-max-silent-time"></a><span class="term"><code class="option">--max-silent-time</code></span></dt><dd><p>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 <a class="link" href="#conf-max-silent-time"><code class="literal">max-silent-time</code></a>
+ configuration setting. <code class="literal">0</code> means no
+ time-out.</p></dd><dt><a id="opt-timeout"></a><span class="term"><code class="option">--timeout</code></span></dt><dd><p>Sets the maximum number of seconds that a builder
+ can run. The default is specified by the <a class="link" href="#conf-timeout"><code class="literal">timeout</code></a>
+ configuration setting. <code class="literal">0</code> means no
+ timeout.</p></dd><dt><span class="term"><code class="option">--keep-going</code> / <code class="option">-k</code></span></dt><dd><p>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).</p></dd><dt><span class="term"><code class="option">--keep-failed</code> / <code class="option">-K</code></span></dt><dd><p>Specifies that in case of a build failure, the
+ temporary directory (usually in <code class="filename">/tmp</code>) in which
+ the build takes place should not be deleted. The path of the build
+ directory is printed as an informational message.
+ </p></dd><dt><span class="term"><code class="option">--fallback</code></span></dt><dd><p>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.</p><p>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).</p></dd><dt><span class="term"><code class="option">--no-build-hook</code></span></dt><dd><p>Disables the build hook mechanism. This allows to ignore remote
+ builders if they are setup on the machine.</p><p>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.</p></dd><dt><span class="term"><code class="option">--readonly-mode</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="option">--arg</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em></span></dt><dd><p>This option is accepted by
+ <span class="command"><strong>nix-env</strong></span>, <span class="command"><strong>nix-instantiate</strong></span>,
+ <span class="command"><strong>nix-shell</strong></span> and <span class="command"><strong>nix-build</strong></span>.
+ 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 <a class="link" href="#ss-functions" title="Functions">default value</a>
+ (e.g., <code class="literal">{ <em class="replaceable"><code>argName</code></em> ?
+ <em class="replaceable"><code>defaultValue</code></em> }:
+ <em class="replaceable"><code>...</code></em></code>). With
+ <code class="option">--arg</code>, 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 <em class="replaceable"><code>name</code></em>, it will call it with value
+ <em class="replaceable"><code>value</code></em>.</p><p>For instance, the top-level <code class="literal">default.nix</code> in
+ Nixpkgs is actually a function:
+
+</p><pre class="programlisting">
+{ # The system (e.g., `i686-linux') for which to build the packages.
+ system ? builtins.currentSystem
+ <em class="replaceable"><code>...</code></em>
+}: <em class="replaceable"><code>...</code></em></pre><p>
+
+ So if you call this Nix expression (e.g., when you do
+ <code class="literal">nix-env -i <em class="replaceable"><code>pkgname</code></em></code>),
+ the function will be called automatically using the value <a class="link" href="#builtin-currentSystem"><code class="literal">builtins.currentSystem</code></a>
+ for the <code class="literal">system</code> argument. You can override this
+ using <code class="option">--arg</code>, e.g., <code class="literal">nix-env -i
+ <em class="replaceable"><code>pkgname</code></em> --arg system
+ \"i686-freebsd\"</code>. (Note that since the argument is a Nix
+ string literal, you have to escape the quotes.)</p></dd><dt><span class="term"><code class="option">--argstr</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em></span></dt><dd><p>This option is like <code class="option">--arg</code>, only the
+ value is not a Nix expression but a string. So instead of
+ <code class="literal">--arg system \"i686-linux\"</code> (the outer quotes are
+ to keep the shell happy) you can say <code class="literal">--argstr system
+ i686-linux</code>.</p></dd><dt><a id="opt-attr"></a><span class="term"><code class="option">--attr</code> / <code class="option">-A</code>
+<em class="replaceable"><code>attrPath</code></em></span></dt><dd><p>Select an attribute from the top-level Nix
+ expression being evaluated. (<span class="command"><strong>nix-env</strong></span>,
+ <span class="command"><strong>nix-instantiate</strong></span>, <span class="command"><strong>nix-build</strong></span> and
+ <span class="command"><strong>nix-shell</strong></span> only.) The <span class="emphasis"><em>attribute
+ path</em></span> <em class="replaceable"><code>attrPath</code></em> is a sequence of
+ attribute names separated by dots. For instance, given a top-level
+ Nix expression <em class="replaceable"><code>e</code></em>, the attribute path
+ <code class="literal">xorg.xorgserver</code> would cause the expression
+ <code class="literal"><em class="replaceable"><code>e</code></em>.xorg.xorgserver</code> to
+ be used. See <a class="link" href="#refsec-nix-env-install-examples" title="Examples"><span class="command"><strong>nix-env
+ --install</strong></span></a> for some concrete examples.</p><p>In addition to attribute names, you can also specify array
+ indices. For instance, the attribute path
+ <code class="literal">foo.3.bar</code> selects the <code class="literal">bar</code>
+ attribute of the fourth element of the array in the
+ <code class="literal">foo</code> attribute of the top-level
+ expression.</p></dd><dt><span class="term"><code class="option">--expr</code> / <code class="option">-E</code></span></dt><dd><p>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.
+ (<span class="command"><strong>nix-instantiate</strong></span>, <span class="command"><strong>nix-build</strong></span>
+ and <span class="command"><strong>nix-shell</strong></span> only.)</p><p>For <span class="command"><strong>nix-shell</strong></span>, 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
+ <span class="emphasis"><em>built</em></span> packages ready for use, give your
+ expression to the <span class="command"><strong>nix-shell -p</strong></span> convenience flag
+ instead.</p></dd><dt><a id="opt-I"></a><span class="term"><code class="option">-I</code> <em class="replaceable"><code>path</code></em></span></dt><dd><p>Add a path to the Nix expression search path. This
+ option may be given multiple times. See the <code class="envar"><a class="envar" href="#env-NIX_PATH">NIX_PATH</a></code> environment variable for
+ information on the semantics of the Nix search path. Paths added
+ through <code class="option">-I</code> take precedence over
+ <code class="envar">NIX_PATH</code>.</p></dd><dt><span class="term"><code class="option">--option</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em></span></dt><dd><p>Set the Nix configuration option
+ <em class="replaceable"><code>name</code></em> to <em class="replaceable"><code>value</code></em>.
+ This overrides settings in the Nix configuration file (see
+ <span class="citerefentry"><span class="refentrytitle">nix.conf</span>(5)</span>).</p></dd><dt><span class="term"><code class="option">--repair</code></span></dt><dd><p>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
+ <span class="command"><strong>nix-store --repair-path</strong></span>.</p></dd></dl></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="sec-common-env"></a>Chapter 21. Common Environment Variables</h2></div></div></div><p>Most Nix commands interpret the following environment variables:</p><div class="variablelist"><a id="env-common"></a><dl class="variablelist"><dt><span class="term"><code class="envar">IN_NIX_SHELL</code></span></dt><dd><p>Indicator that tells if the current environment was set up by
+ <span class="command"><strong>nix-shell</strong></span>. Since Nix 2.0 the values are
+ <code class="literal">"pure"</code> and <code class="literal">"impure"</code></p></dd><dt><a id="env-NIX_PATH"></a><span class="term"><code class="envar">NIX_PATH</code></span></dt><dd><p>A colon-separated list of directories used to look up Nix
+ expressions enclosed in angle brackets (i.e.,
+ <code class="literal">&lt;<em class="replaceable"><code>path</code></em>&gt;</code>). For
+ instance, the value
+
+ </p><pre class="screen">
+/home/eelco/Dev:/etc/nixos</pre><p>
+
+ will cause Nix to look for paths relative to
+ <code class="filename">/home/eelco/Dev</code> and
+ <code class="filename">/etc/nixos</code>, in this order. It is also
+ possible to match paths against a prefix. For example, the value
+
+ </p><pre class="screen">
+nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</pre><p>
+
+ will cause Nix to search for
+ <code class="literal">&lt;nixpkgs/<em class="replaceable"><code>path</code></em>&gt;</code> in
+ <code class="filename">/home/eelco/Dev/nixpkgs-branch/<em class="replaceable"><code>path</code></em></code>
+ and
+ <code class="filename">/etc/nixos/nixpkgs/<em class="replaceable"><code>path</code></em></code>.</p><p>If a path in the Nix search path starts with
+ <code class="literal">http://</code> or <code class="literal">https://</code>, 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
+ <code class="envar">NIX_PATH</code> to
+
+ </p><pre class="screen">
+nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz</pre><p>
+
+ tells Nix to download the latest revision in the Nixpkgs/NixOS
+ 15.09 channel.</p><p>A following shorthand can be used to refer to the official channels:
+
+ </p><pre class="screen">nixpkgs=channel:nixos-15.09</pre><p>
+ </p><p>The search path can be extended using the <code class="option"><a class="option" href="#opt-I">-I</a></code> option, which takes precedence over
+ <code class="envar">NIX_PATH</code>.</p></dd><dt><span class="term"><code class="envar">NIX_IGNORE_SYMLINK_STORE</code></span></dt><dd><p>Normally, the Nix store directory (typically
+ <code class="filename">/nix/store</code>) 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
+ <code class="filename">/nix/store</code> resolving to different locations)
+ could yield different results. This is generally not a problem,
+ except when builds are deployed to machines where
+ <code class="filename">/nix/store</code> resolves differently. If you are
+ sure that you’re not going to do that, you can set
+ <code class="envar">NIX_IGNORE_SYMLINK_STORE</code> to <code class="envar">1</code>.</p><p>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 <code class="literal">bind</code> mount points, e.g.,
+
+ </p><pre class="screen">
+$ mkdir /nix
+$ mount -o bind /mnt/otherdisk/nix /nix</pre><p>
+
+ Consult the <span class="citerefentry"><span class="refentrytitle">mount</span>(8)</span> manual page for details.</p></dd><dt><span class="term"><code class="envar">NIX_STORE_DIR</code></span></dt><dd><p>Overrides the location of the Nix store (default
+ <code class="filename"><em class="replaceable"><code>prefix</code></em>/store</code>).</p></dd><dt><span class="term"><code class="envar">NIX_DATA_DIR</code></span></dt><dd><p>Overrides the location of the Nix static data
+ directory (default
+ <code class="filename"><em class="replaceable"><code>prefix</code></em>/share</code>).</p></dd><dt><span class="term"><code class="envar">NIX_LOG_DIR</code></span></dt><dd><p>Overrides the location of the Nix log directory
+ (default <code class="filename"><em class="replaceable"><code>prefix</code></em>/var/log/nix</code>).</p></dd><dt><span class="term"><code class="envar">NIX_STATE_DIR</code></span></dt><dd><p>Overrides the location of the Nix state directory
+ (default <code class="filename"><em class="replaceable"><code>prefix</code></em>/var/nix</code>).</p></dd><dt><span class="term"><code class="envar">NIX_CONF_DIR</code></span></dt><dd><p>Overrides the location of the system Nix configuration
+ directory (default
+ <code class="filename"><em class="replaceable"><code>prefix</code></em>/etc/nix</code>).</p></dd><dt><span class="term"><code class="envar">NIX_USER_CONF_FILES</code></span></dt><dd><p>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 <code class="literal">:</code> token.</p></dd><dt><span class="term"><code class="envar">TMPDIR</code></span></dt><dd><p>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
+ <code class="filename">/tmp</code>.</p></dd><dt><a id="envar-remote"></a><span class="term"><code class="envar">NIX_REMOTE</code></span></dt><dd><p>This variable should be set to
+ <code class="literal">daemon</code> if you want to use the Nix daemon to
+ execute Nix operations. This is necessary in <a class="link" href="#ssec-multi-user" title="6.2. Multi-User Mode">multi-user Nix installations</a>.
+ If the Nix daemon's Unix socket is at some non-standard path,
+ this variable should be set to <code class="literal">unix://path/to/socket</code>.
+ Otherwise, it should be left unset.</p></dd><dt><span class="term"><code class="envar">NIX_SHOW_STATS</code></span></dt><dd><p>If set to <code class="literal">1</code>, Nix will print some
+ evaluation statistics, such as the number of values
+ allocated.</p></dd><dt><span class="term"><code class="envar">NIX_COUNT_CALLS</code></span></dt><dd><p>If set to <code class="literal">1</code>, Nix will print how
+ often functions were called during Nix expression evaluation. This
+ is useful for profiling your Nix expressions.</p></dd><dt><span class="term"><code class="envar">GC_INITIAL_HEAP_SIZE</code></span></dt><dd><p>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.</p></dd></dl></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-main-commands"></a>Chapter 22. Main Commands</h2></div></div></div><p>This section lists commands and options that you can use when you
+work with Nix.</p><div class="refentry"><a id="sec-nix-env"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix-env — manipulate or query Nix user environments</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">nix-env</code> [<code class="option">--help</code>] [<code class="option">--version</code>] [
+ { <code class="option">--verbose</code> | <code class="option">-v</code> }
+...] [
+ <code class="option">--quiet</code>
+] [
+ <code class="option">--log-format</code>
+ <em class="replaceable"><code>format</code></em>
+] [
+ <code class="option">--no-build-output</code> | <code class="option">-Q</code>
+] [
+ { <code class="option">--max-jobs</code> | <code class="option">-j</code> }
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--cores</code>
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--max-silent-time</code>
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--timeout</code>
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--keep-going</code> | <code class="option">-k</code>
+] [
+ <code class="option">--keep-failed</code> | <code class="option">-K</code>
+] [<code class="option">--fallback</code>] [<code class="option">--readonly-mode</code>] [
+ <code class="option">-I</code>
+ <em class="replaceable"><code>path</code></em>
+] [
+ <code class="option">--option</code>
+ <em class="replaceable"><code>name</code></em>
+ <em class="replaceable"><code>value</code></em>
+]<br /> [<code class="option">--arg</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em>] [<code class="option">--argstr</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em>] [
+ { <code class="option">--file</code> | <code class="option">-f</code> }
+ <em class="replaceable"><code>path</code></em>
+ ] [
+ { <code class="option">--profile</code> | <code class="option">-p</code> }
+ <em class="replaceable"><code>path</code></em>
+ ] [
+ <code class="option">--system-filter</code>
+ <em class="replaceable"><code>system</code></em>
+ ] [<code class="option">--dry-run</code>] <em class="replaceable"><code>operation</code></em> [<em class="replaceable"><code>options</code></em>...] [<em class="replaceable"><code>arguments</code></em>...]</p></div></div><div class="refsection"><a id="idm139733300260096"></a><h2>Description</h2><p>The command <span class="command"><strong>nix-env</strong></span> 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.</p><p><span class="command"><strong>nix-env</strong></span> takes exactly one
+<span class="emphasis"><em>operation</em></span> flag which indicates the subcommand to
+be performed. These are documented below.</p></div><div class="refsection"><a id="idm139733300256528"></a><h2>Selectors</h2><p>Several commands, such as <span class="command"><strong>nix-env -q</strong></span> and
+<span class="command"><strong>nix-env -i</strong></span>, 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
+<span class="citerefentry"><span class="refentrytitle">regex</span>(7)</span>.)
+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:
+
+</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">firefox</code></span></dt><dd><p>Matches the package name
+ <code class="literal">firefox</code> and any version.</p></dd><dt><span class="term"><code class="literal">firefox-32.0</code></span></dt><dd><p>Matches the package name
+ <code class="literal">firefox</code> and version
+ <code class="literal">32.0</code>.</p></dd><dt><span class="term"><code class="literal">gtk\\+</code></span></dt><dd><p>Matches the package name
+ <code class="literal">gtk+</code>. The <code class="literal">+</code> 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.</p></dd><dt><span class="term"><code class="literal">.\*</code></span></dt><dd><p>Matches any package name. This is the default for
+ most commands.</p></dd><dt><span class="term"><code class="literal">'.*zip.*'</code></span></dt><dd><p>Matches any package name containing the string
+ <code class="literal">zip</code>. Note the dots: <code class="literal">'*zip*'</code>
+ does not work, because in a regular expression, the character
+ <code class="literal">*</code> is interpreted as a
+ quantifier.</p></dd><dt><span class="term"><code class="literal">'.*(firefox|chromium).*'</code></span></dt><dd><p>Matches any package name containing the strings
+ <code class="literal">firefox</code> or
+ <code class="literal">chromium</code>.</p></dd></dl></div><p>
+
+</p></div><div class="refsection"><a id="idm139733300238960"></a><h2>Common options</h2><p>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. <span class="phrase">See
+also <a class="xref" href="#sec-common-options" title="Chapter 20. Common Options">Chapter 20, <em>Common Options</em></a>.</span></p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--file</code> / <code class="option">-f</code> <em class="replaceable"><code>path</code></em></span></dt><dd><p>Specifies the Nix expression (designated below as
+ the <span class="emphasis"><em>active Nix expression</em></span>) used by the
+ <code class="option">--install</code>, <code class="option">--upgrade</code>, and
+ <code class="option">--query --available</code> operations to obtain
+ derivations. The default is
+ <code class="filename">~/.nix-defexpr</code>.</p><p>If the argument starts with <code class="literal">http://</code> or
+ <code class="literal">https://</code>, 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 <code class="filename">default.nix</code>.</p></dd><dt><span class="term"><code class="option">--profile</code> / <code class="option">-p</code> <em class="replaceable"><code>path</code></em></span></dt><dd><p>Specifies the profile to be used by those
+ operations that operate on a profile (designated below as the
+ <span class="emphasis"><em>active profile</em></span>). A profile is a sequence of
+ user environments called <span class="emphasis"><em>generations</em></span>, one of
+ which is the <span class="emphasis"><em>current
+ generation</em></span>.</p></dd><dt><span class="term"><code class="option">--dry-run</code></span></dt><dd><p>For the <code class="option">--install</code>,
+ <code class="option">--upgrade</code>, <code class="option">--uninstall</code>,
+ <code class="option">--switch-generation</code>,
+ <code class="option">--delete-generations</code> and
+ <code class="option">--rollback</code> operations, this flag will cause
+ <span class="command"><strong>nix-env</strong></span> to print what
+ <span class="emphasis"><em>would</em></span> be done if this flag had not been
+ specified, without actually doing it.</p><p><code class="option">--dry-run</code> also prints out which paths will
+ be <a class="link" href="#gloss-substitute" title="substitute">substituted</a> (i.e.,
+ downloaded) and which paths will be built from source (because no
+ substitute is available).</p></dd><dt><span class="term"><code class="option">--system-filter</code> <em class="replaceable"><code>system</code></em></span></dt><dd><p>By default, operations such as <code class="option">--query
+ --available</code> show derivations matching any platform. This
+ option allows you to use derivations for the specified platform
+ <em class="replaceable"><code>system</code></em>.</p></dd></dl></div></div><div class="refsection"><a id="idm139733300216432"></a><h2>Files</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">~/.nix-defexpr</code></span></dt><dd><p>The source for the default Nix
+ expressions used by the <code class="option">--install</code>,
+ <code class="option">--upgrade</code>, and <code class="option">--query
+ --available</code> operations to obtain derivations. The
+ <code class="option">--file</code> option may be used to override this
+ default.</p><p>If <code class="filename">~/.nix-defexpr</code> 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.</p><p>If <code class="filename">~/.nix-defexpr</code> is a directory
+ containing a <code class="filename">default.nix</code> file, that file
+ is loaded as in the above paragraph.</p><p>If <code class="filename">~/.nix-defexpr</code> is a directory without
+ a <code class="filename">default.nix</code> 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.
+ </p><p>For example, if <code class="filename">~/.nix-defexpr</code> contains
+ two files, <code class="filename">foo.nix</code> and <code class="filename">bar.nix</code>,
+ then the default Nix expression will essentially be
+
+</p><pre class="programlisting">
+{
+ foo = import ~/.nix-defexpr/foo.nix;
+ bar = import ~/.nix-defexpr/bar.nix;
+}</pre><p>
+
+ </p><p>The file <code class="filename">manifest.nix</code> is always ignored.
+ Subdirectories without a <code class="filename">default.nix</code> 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.</p><p>The command <span class="command"><strong>nix-channel</strong></span> places symlinks
+ to the downloaded Nix expressions from each subscribed channel in
+ this directory.</p></dd><dt><span class="term"><code class="filename">~/.nix-profile</code></span></dt><dd><p>A symbolic link to the user's current profile. By
+ default, this symlink points to
+ <code class="filename"><em class="replaceable"><code>prefix</code></em>/var/nix/profiles/default</code>.
+ The <code class="envar">PATH</code> environment variable should include
+ <code class="filename">~/.nix-profile/bin</code> for the user environment
+ to be visible to the user.</p></dd></dl></div></div><div class="refsection"><a id="rsec-nix-env-install"></a><h2>Operation <code class="option">--install</code></h2><div class="refsection"><a id="idm139733300198432"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-env</code> { <code class="option">--install</code> | <code class="option">-i</code> } [
+ { <code class="option">--prebuilt-only</code> | <code class="option">-b</code> }
+ ] [
+ { <code class="option">--attr</code> | <code class="option">-A</code> }
+ ] [<code class="option">--from-expression</code>] [<code class="option">-E</code>] [<code class="option">--from-profile</code> <em class="replaceable"><code>path</code></em>] [ <code class="option">--preserve-installed</code> | <code class="option">-P</code> ] [ <code class="option">--remove-all</code> | <code class="option">-r</code> ] <em class="replaceable"><code>args</code></em>... </p></div></div><div class="refsection"><a id="idm139733300182432"></a><h3>Description</h3><p>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 <em class="replaceable"><code>args</code></em> is added. The
+arguments <em class="replaceable"><code>args</code></em> map to store paths in a
+number of possible ways:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>By default, <em class="replaceable"><code>args</code></em> 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
+ <code class="option">--preserve-installed</code> is
+ specified.</p><p>If there are multiple derivations matching a name in
+ <em class="replaceable"><code>args</code></em> that have the same name (e.g.,
+ <code class="literal">gcc-3.3.6</code> and <code class="literal">gcc-4.1.1</code>), then
+ the derivation with the highest <span class="emphasis"><em>priority</em></span> is
+ used. A derivation can define a priority by declaring the
+ <code class="varname">meta.priority</code> attribute. This attribute should
+ be a number, with a higher value denoting a lower priority. The
+ default priority is <code class="literal">0</code>.</p><p>If there are multiple matching derivations with the same
+ priority, then the derivation with the highest version will be
+ installed.</p><p>You can force the installation of multiple derivations with
+ the same name by being specific about the versions. For instance,
+ <code class="literal">nix-env -i gcc-3.3.6 gcc-4.1.1</code> will install both
+ version of GCC (and will probably cause a user environment
+ conflict!).</p></li><li class="listitem"><p>If <a class="link" href="#opt-attr"><code class="option">--attr</code></a>
+ (<code class="option">-A</code>) is specified, the arguments are
+ <span class="emphasis"><em>attribute paths</em></span> 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 <code class="literal">nix-env -qaP</code>.</p></li><li class="listitem"><p>If <code class="option">--from-profile</code>
+ <em class="replaceable"><code>path</code></em> is given,
+ <em class="replaceable"><code>args</code></em> is a set of names denoting installed
+ store paths in the profile <em class="replaceable"><code>path</code></em>. This is
+ an easy way to copy user environment elements from one profile to
+ another.</p></li><li class="listitem"><p>If <code class="option">--from-expression</code> is given,
+ <em class="replaceable"><code>args</code></em> are Nix <a class="link" href="#ss-functions" title="Functions">functions</a> 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.</p></li><li class="listitem"><p>If <em class="replaceable"><code>args</code></em> are store
+ derivations, then these are <a class="link" href="#rsec-nix-store-realise" title="Operation --realise">realised</a>, and the resulting
+ output paths are installed.</p></li><li class="listitem"><p>If <em class="replaceable"><code>args</code></em> are store paths
+ that are not store derivations, then these are <a class="link" href="#rsec-nix-store-realise" title="Operation --realise">realised</a> and
+ installed.</p></li><li class="listitem"><p>By default all outputs are installed for each derivation.
+ That can be reduced by setting <code class="literal">meta.outputsToInstall</code>.
+ </p></li></ul></div><p>
+
+</p></div><div class="refsection"><a id="idm139733300160752"></a><h3>Flags</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--prebuilt-only</code> / <code class="option">-b</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="option">--preserve-installed</code>, </span><span class="term"><code class="option">-P</code></span></dt><dd><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.</p></dd><dt><span class="term"><code class="option">--remove-all</code>, </span><span class="term"><code class="option">-r</code></span></dt><dd><p>Remove all previously installed packages first.
+ This is equivalent to running <code class="literal">nix-env -e '.*'</code>
+ first, except that everything happens in a single
+ transaction.</p></dd></dl></div></div><div class="refsection"><a id="refsec-nix-env-install-examples"></a><h3>Examples</h3><p>To install a specific version of <span class="command"><strong>gcc</strong></span> from the
+active Nix expression:
+
+</p><pre class="screen">
+$ nix-env --install gcc-3.3.2
+installing `gcc-3.3.2'
+uninstalling `gcc-3.1'</pre><p>
+
+Note the previously installed version is removed, since
+<code class="option">--preserve-installed</code> was not specified.</p><p>To install an arbitrary version:
+
+</p><pre class="screen">
+$ nix-env --install gcc
+installing `gcc-3.3.2'</pre><p>
+
+</p><p>To install using a specific attribute:
+
+</p><pre class="screen">
+$ nix-env -i -A gcc40mips
+$ nix-env -i -A xorg.xorgserver</pre><p>
+
+</p><p>To install all derivations in the Nix expression <code class="filename">foo.nix</code>:
+
+</p><pre class="screen">
+$ nix-env -f ~/foo.nix -i '.*'</pre><p>
+
+</p><p>To copy the store path with symbolic name <code class="literal">gcc</code>
+from another profile:
+
+</p><pre class="screen">
+$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc</pre><p>
+
+</p><p>To install a specific store derivation (typically created by
+<span class="command"><strong>nix-instantiate</strong></span>):
+
+</p><pre class="screen">
+$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv</pre><p>
+
+</p><p>To install a specific output path:
+
+</p><pre class="screen">
+$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3</pre><p>
+
+</p><p>To install from a Nix expression specified on the command-line:
+
+</p><pre class="screen">
+$ nix-env -f ./foo.nix -i -E \
+ 'f: (f {system = "i686-linux";}).subversionWithJava'</pre><p>
+
+I.e., this evaluates to <code class="literal">(f: (f {system =
+"i686-linux";}).subversionWithJava) (import ./foo.nix)</code>, thus
+selecting the <code class="literal">subversionWithJava</code> attribute from the
+set returned by calling the function defined in
+<code class="filename">./foo.nix</code>.</p><p>A dry-run tells you which paths will be downloaded or built from
+source:
+
+</p><pre class="screen">
+$ nix-env -f '&lt;nixpkgs&gt;' -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
+ <em class="replaceable"><code>...</code></em></pre><p>
+
+</p><p>To install Firefox from the latest revision in the Nixpkgs/NixOS
+14.12 channel:
+
+</p><pre class="screen">
+$ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox
+</pre><p>
+
+</p></div></div><div class="refsection"><a id="rsec-nix-env-upgrade"></a><h2>Operation <code class="option">--upgrade</code></h2><div class="refsection"><a id="idm139733300136496"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-env</code> { <code class="option">--upgrade</code> | <code class="option">-u</code> } [
+ { <code class="option">--prebuilt-only</code> | <code class="option">-b</code> }
+ ] [
+ { <code class="option">--attr</code> | <code class="option">-A</code> }
+ ] [<code class="option">--from-expression</code>] [<code class="option">-E</code>] [<code class="option">--from-profile</code> <em class="replaceable"><code>path</code></em>] [ <code class="option">--lt</code> | <code class="option">--leq</code> | <code class="option">--eq</code> | <code class="option">--always</code> ] <em class="replaceable"><code>args</code></em>... </p></div></div><div class="refsection"><a id="idm139733300121104"></a><h3>Description</h3><p>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 <em class="replaceable"><code>args</code></em>. 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 <em class="replaceable"><code>args</code></em>
+matches no installed derivations.</p><p>For a description of how <em class="replaceable"><code>args</code></em> is
+mapped to a set of store paths, see <a class="link" href="#rsec-nix-env-install" title="Operation --install"><code class="option">--install</code></a>. If
+<em class="replaceable"><code>args</code></em> describes multiple store paths with
+the same symbolic name, only the one with the highest version is
+installed.</p></div><div class="refsection"><a id="idm139733300116496"></a><h3>Flags</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--lt</code></span></dt><dd><p>Only upgrade a derivation to newer versions. This
+ is the default.</p></dd><dt><span class="term"><code class="option">--leq</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="option">--eq</code></span></dt><dd><p><span class="emphasis"><em>Only</em></span> “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).</p></dd><dt><span class="term"><code class="option">--always</code></span></dt><dd><p>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.</p></dd></dl></div><p>For the other flags, see <code class="option"><a class="option" href="#rsec-nix-env-install" title="Operation --install">--install</a></code>.</p></div><div class="refsection"><a id="idm139733300106960"></a><h3>Examples</h3><pre class="screen">
+$ nix-env --upgrade gcc
+upgrading `gcc-3.3.1' to `gcc-3.4'
+
+$ nix-env -u gcc-3.3.2 --always <em class="lineannotation"><span class="lineannotation">(switch to a specific version)</span></em>
+upgrading `gcc-3.4' to `gcc-3.3.2'
+
+$ nix-env --upgrade pan
+<em class="lineannotation"><span class="lineannotation">(no upgrades available, so nothing happens)</span></em>
+
+$ nix-env -u <em class="lineannotation"><span class="lineannotation">(try to upgrade everything)</span></em>
+upgrading `hello-2.1.2' to `hello-2.1.3'
+upgrading `mozilla-1.2' to `mozilla-1.4'</pre></div><div class="refsection"><a id="ssec-version-comparisons"></a><h3>Versions</h3><p>The upgrade operation determines whether a derivation
+<code class="varname">y</code> is an upgrade of a derivation
+<code class="varname">x</code> by looking at their respective
+<code class="literal">name</code> attributes. The names (e.g.,
+<code class="literal">gcc-3.3.1</code> are split into two parts: the package
+name (<code class="literal">gcc</code>), and the version
+(<code class="literal">3.3.1</code>). The version part starts after the first
+dash not followed by a letter. <code class="varname">x</code> is considered an
+upgrade of <code class="varname">y</code> if their package names match, and the
+version of <code class="varname">y</code> is higher that that of
+<code class="varname">x</code>.</p><p>The versions are compared by splitting them into contiguous
+components of numbers and letters. E.g., <code class="literal">3.3.1pre5</code>
+is split into <code class="literal">[3, 3, 1, "pre", 5]</code>. These lists are
+then compared lexicographically (from left to right). Corresponding
+components <code class="varname">a</code> and <code class="varname">b</code> are compared
+as follows. If they are both numbers, integer comparison is used. If
+<code class="varname">a</code> is an empty string and <code class="varname">b</code> is a
+number, <code class="varname">a</code> is considered less than
+<code class="varname">b</code>. The special string component
+<code class="literal">pre</code> (for <span class="emphasis"><em>pre-release</em></span>) 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).</p><p>This is illustrated by the following examples:
+
+</p><pre class="screen">
+1.0 &lt; 2.3
+2.1 &lt; 2.3
+2.3 = 2.3
+2.5 &gt; 2.3
+3.1 &gt; 2.3
+2.3.1 &gt; 2.3
+2.3.1 &gt; 2.3a
+2.3pre1 &lt; 2.3
+2.3pre3 &lt; 2.3pre12
+2.3a &lt; 2.3c
+2.3pre1 &lt; 2.3c
+2.3pre1 &lt; 2.3q</pre><p>
+
+</p></div></div><div class="refsection"><a id="idm139733300091392"></a><h2>Operation <code class="option">--uninstall</code></h2><div class="refsection"><a id="idm139733300090560"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-env</code> { <code class="option">--uninstall</code> | <code class="option">-e</code> } <em class="replaceable"><code>drvnames</code></em>... </p></div></div><div class="refsection"><a id="idm139733300085776"></a><h3>Description</h3><p>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
+<em class="replaceable"><code>names</code></em> are removed.</p></div><div class="refsection"><a id="idm139733300084080"></a><h3>Examples</h3><pre class="screen">
+$ nix-env --uninstall gcc
+$ nix-env -e '.*' <em class="lineannotation"><span class="lineannotation">(remove everything)</span></em></pre></div></div><div class="refsection"><a id="rsec-nix-env-set"></a><h2>Operation <code class="option">--set</code></h2><div class="refsection"><a id="idm139733300080928"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-env</code> <code class="option">--set</code> <em class="replaceable"><code>drvname</code></em> </p></div></div><div class="refsection"><a id="idm139733300077824"></a><h3>Description</h3><p>The <code class="option">--set</code> operation modifies the current generation of a
+profile so that it contains exactly the specified derivation, and nothing else.
+</p></div><div class="refsection"><a id="idm139733300076176"></a><h3>Examples</h3><p>
+The following updates a profile such that its current generation will contain
+just Firefox:
+
+</p><pre class="screen">
+$ nix-env -p /nix/var/nix/profiles/browser --set firefox</pre><p>
+
+</p></div></div><div class="refsection"><a id="rsec-nix-env-set-flag"></a><h2>Operation <code class="option">--set-flag</code></h2><div class="refsection"><a id="idm139733300072736"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-env</code> <code class="option">--set-flag</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em> <em class="replaceable"><code>drvnames</code></em>... </p></div></div><div class="refsection"><a id="idm139733300067728"></a><h3>Description</h3><p>The <code class="option">--set-flag</code> 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
+<span class="command"><strong>nix-env</strong></span> or the user environment build
+script:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="varname">priority</code> can be changed to
+ resolve filename clashes. The user environment build script uses
+ the <code class="varname">meta.priority</code> 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
+ <code class="filename">bin/ld</code>, 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
+ <code class="filename">bin/ld</code> is symlinked in the user
+ environment.</p></li><li class="listitem"><p><code class="varname">keep</code> can be set to
+ <code class="literal">true</code> 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.</p></li><li class="listitem"><p><code class="varname">active</code> can be set to
+ <code class="literal">false</code> 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 <code class="literal">true</code> to re-enable the
+ package.</p></li></ul></div><p>
+
+</p></div><div class="refsection"><a id="idm139733300058816"></a><h3>Examples</h3><p>To prevent the currently installed Firefox from being upgraded:
+
+</p><pre class="screen">
+$ nix-env --set-flag keep true firefox</pre><p>
+
+After this, <span class="command"><strong>nix-env -u</strong></span> will ignore Firefox.</p><p>To disable the currently installed Firefox, then install a new
+Firefox while the old remains part of the profile:
+
+</p><pre class="screen">
+$ nix-env -q
+firefox-2.0.0.9 <em class="lineannotation"><span class="lineannotation">(the current one)</span></em>
+
+$ 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/<em class="replaceable"><code>...</code></em>-firefox-2.0.0.11/bin/firefox'
+ and `/nix/store/<em class="replaceable"><code>...</code></em>-firefox-2.0.0.9/bin/firefox'.
+<em class="lineannotation"><span class="lineannotation">(i.e., can’t have two active at the same time)</span></em>
+
+$ 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 <em class="lineannotation"><span class="lineannotation">(the enabled one)</span></em>
+firefox-2.0.0.9 <em class="lineannotation"><span class="lineannotation">(the disabled one)</span></em></pre><p>
+
+</p><p>To make files from <code class="literal">binutils</code> take precedence
+over files from <code class="literal">gcc</code>:
+
+</p><pre class="screen">
+$ nix-env --set-flag priority 5 binutils
+$ nix-env --set-flag priority 10 gcc</pre><p>
+
+</p></div></div><div class="refsection"><a id="idm139733300050640"></a><h2>Operation <code class="option">--query</code></h2><div class="refsection"><a id="idm139733300049808"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-env</code> { <code class="option">--query</code> | <code class="option">-q</code> } [ <code class="option">--installed</code> | <code class="option">--available</code> | <code class="option">-a</code> ]<br /> [
+ { <code class="option">--status</code> | <code class="option">-s</code> }
+ ] [
+ { <code class="option">--attr-path</code> | <code class="option">-P</code> }
+ ] [<code class="option">--no-name</code>] [
+ { <code class="option">--compare-versions</code> | <code class="option">-c</code> }
+ ] [<code class="option">--system</code>] [<code class="option">--drv-path</code>] [<code class="option">--out-path</code>] [<code class="option">--description</code>] [<code class="option">--meta</code>]<br /> [<code class="option">--xml</code>] [<code class="option">--json</code>] [
+ { <code class="option">--prebuilt-only</code> | <code class="option">-b</code> }
+ ] [
+ { <code class="option">--attr</code> | <code class="option">-A</code> }
+ <em class="replaceable"><code>attribute-path</code></em>
+ ]<br /> <em class="replaceable"><code>names</code></em>... </p></div></div><div class="refsection"><a id="idm139733300023312"></a><h3>Description</h3><p>The query operation displays information about either the store
+paths that are installed in the current generation of the active
+profile (<code class="option">--installed</code>), or the derivations that are
+available for installation in the active Nix expression
+(<code class="option">--available</code>). It only prints information about
+derivations whose symbolic name matches one of
+<em class="replaceable"><code>names</code></em>.</p><p>The derivations are sorted by their <code class="literal">name</code>
+attributes.</p></div><div class="refsection"><a id="idm139733300019760"></a><h3>Source selection</h3><p>The following flags specify the set of things on which the query
+operates.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--installed</code></span></dt><dd><p>The query operates on the store paths that are
+ installed in the current generation of the active profile. This
+ is the default.</p></dd><dt><span class="term"><code class="option">--available</code>, </span><span class="term"><code class="option">-a</code></span></dt><dd><p>The query operates on the derivations that are
+ available in the active Nix expression.</p></dd></dl></div></div><div class="refsection"><a id="idm139733300014832"></a><h3>Queries</h3><p>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 <code class="option">--no-name</code> is
+specified.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--xml</code></span></dt><dd><p>Print the result in an XML representation suitable
+ for automatic processing by other tools. The root element is
+ called <code class="literal">items</code>, which contains a
+ <code class="literal">item</code> element for each available or installed
+ derivation. The fields discussed below are all stored in
+ attributes of the <code class="literal">item</code>
+ elements.</p></dd><dt><span class="term"><code class="option">--json</code></span></dt><dd><p>Print the result in a JSON representation suitable
+ for automatic processing by other tools.</p></dd><dt><span class="term"><code class="option">--prebuilt-only</code> / <code class="option">-b</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="option">--status</code>, </span><span class="term"><code class="option">-s</code></span></dt><dd><p>Print the <span class="emphasis"><em>status</em></span> of the
+ derivation. The status consists of three characters. The first
+ is <code class="literal">I</code> or <code class="literal">-</code>, indicating
+ whether the derivation is currently installed in the current
+ generation of the active profile. This is by definition the case
+ for <code class="option">--installed</code>, but not for
+ <code class="option">--available</code>. The second is <code class="literal">P</code>
+ or <code class="literal">-</code>, 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 <code class="literal">S</code> or <code class="literal">-</code>, indicating
+ whether a substitute is available for the
+ derivation.</p></dd><dt><span class="term"><code class="option">--attr-path</code>, </span><span class="term"><code class="option">-P</code></span></dt><dd><p>Print the <span class="emphasis"><em>attribute path</em></span> of
+ the derivation, which can be used to unambiguously select it using
+ the <a class="link" href="#opt-attr"><code class="option">--attr</code> option</a>
+ available in commands that install derivations like
+ <code class="literal">nix-env --install</code>. This option only works
+ together with <code class="option">--available</code></p></dd><dt><span class="term"><code class="option">--no-name</code></span></dt><dd><p>Suppress printing of the <code class="literal">name</code>
+ attribute of each derivation.</p></dd><dt><span class="term"><code class="option">--compare-versions</code> /
+ <code class="option">-c</code></span></dt><dd><p>Compare installed versions to available versions,
+ or vice versa (if <code class="option">--available</code> 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:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">&lt;</code> <em class="replaceable"><code>version</code></em></span></dt><dd><p>A newer version of the package is available
+ or installed.</p></dd><dt><span class="term"><code class="literal">=</code> <em class="replaceable"><code>version</code></em></span></dt><dd><p>At most the same version of the package is
+ available or installed.</p></dd><dt><span class="term"><code class="literal">&gt;</code> <em class="replaceable"><code>version</code></em></span></dt><dd><p>Only older versions of the package are
+ available or installed.</p></dd><dt><span class="term"><code class="literal">- ?</code></span></dt><dd><p>No version of the package is available or
+ installed.</p></dd></dl></div><p>
+
+ </p></dd><dt><span class="term"><code class="option">--system</code></span></dt><dd><p>Print the <code class="literal">system</code> attribute of
+ the derivation.</p></dd><dt><span class="term"><code class="option">--drv-path</code></span></dt><dd><p>Print the path of the store
+ derivation.</p></dd><dt><span class="term"><code class="option">--out-path</code></span></dt><dd><p>Print the output path of the
+ derivation.</p></dd><dt><span class="term"><code class="option">--description</code></span></dt><dd><p>Print a short (one-line) description of the
+ derivation, if available. The description is taken from the
+ <code class="literal">meta.description</code> attribute of the
+ derivation.</p></dd><dt><span class="term"><code class="option">--meta</code></span></dt><dd><p>Print all of the meta-attributes of the
+ derivation. This option is only available with
+ <code class="option">--xml</code> or <code class="option">--json</code>.</p></dd></dl></div></div><div class="refsection"><a id="idm139733299975552"></a><h3>Examples</h3><p>To show installed packages:
+
+</p><pre class="screen">
+$ nix-env -q
+bison-1.875c
+docbook-xml-4.2
+firefox-1.0.4
+MPlayer-1.0pre7
+ORBit2-2.8.3
+<em class="replaceable"><code>…</code></em>
+</pre><p>
+
+</p><p>To show available packages:
+
+</p><pre class="screen">
+$ nix-env -qa
+firefox-1.0.7
+GConf-2.4.0.1
+MPlayer-1.0pre7
+ORBit2-2.8.3
+<em class="replaceable"><code>…</code></em>
+</pre><p>
+
+</p><p>To show the status of available packages:
+
+</p><pre class="screen">
+$ nix-env -qas
+-P- firefox-1.0.7 <em class="lineannotation"><span class="lineannotation">(not installed but present)</span></em>
+--S GConf-2.4.0.1 <em class="lineannotation"><span class="lineannotation">(not present, but there is a substitute for fast installation)</span></em>
+--S MPlayer-1.0pre3 <em class="lineannotation"><span class="lineannotation">(i.e., this is not the installed MPlayer, even though the version is the same!)</span></em>
+IP- ORBit2-2.8.3 <em class="lineannotation"><span class="lineannotation">(installed and by definition present)</span></em>
+<em class="replaceable"><code>…</code></em>
+</pre><p>
+
+</p><p>To show available packages in the Nix expression <code class="filename">foo.nix</code>:
+
+</p><pre class="screen">
+$ nix-env -f ./foo.nix -qa
+foo-1.2.3
+</pre><p>
+
+</p><p>To compare installed versions to what’s available:
+
+</p><pre class="screen">
+$ nix-env -qc
+<em class="replaceable"><code>...</code></em>
+acrobat-reader-7.0 - ? <em class="lineannotation"><span class="lineannotation">(package is not available at all)</span></em>
+autoconf-2.59 = 2.59 <em class="lineannotation"><span class="lineannotation">(same version)</span></em>
+firefox-1.0.4 &lt; 1.0.7 <em class="lineannotation"><span class="lineannotation">(a more recent version is available)</span></em>
+<em class="replaceable"><code>...</code></em>
+</pre><p>
+
+</p><p>To show all packages with “<code class="literal">zip</code>” in the name:
+
+</p><pre class="screen">
+$ nix-env -qa '.*zip.*'
+bzip2-1.0.6
+gzip-1.6
+zip-3.0
+<em class="replaceable"><code>…</code></em>
+</pre><p>
+
+</p><p>To show all packages with “<code class="literal">firefox</code>” or
+“<code class="literal">chromium</code>” in the name:
+
+</p><pre class="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
+<em class="replaceable"><code>…</code></em>
+</pre><p>
+
+</p><p>To show all packages in the latest revision of the Nixpkgs
+repository:
+
+</p><pre class="screen">
+$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
+</pre><p>
+
+</p></div></div><div class="refsection"><a id="idm139733299959008"></a><h2>Operation <code class="option">--switch-profile</code></h2><div class="refsection"><a id="idm139733299958176"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-env</code> { <code class="option">--switch-profile</code> | <code class="option">-S</code> } {<em class="replaceable"><code>path</code></em>}</p></div></div><div class="refsection"><a id="idm139733299953696"></a><h3>Description</h3><p>This operation makes <em class="replaceable"><code>path</code></em> the current
+profile for the user. That is, the symlink
+<code class="filename">~/.nix-profile</code> is made to point to
+<em class="replaceable"><code>path</code></em>.</p></div><div class="refsection"><a id="idm139733299951328"></a><h3>Examples</h3><pre class="screen">
+$ nix-env -S ~/my-profile</pre></div></div><div class="refsection"><a id="idm139733299949648"></a><h2>Operation <code class="option">--list-generations</code></h2><div class="refsection"><a id="idm139733299948816"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-env</code> <code class="option">--list-generations</code> </p></div></div><div class="refsection"><a id="idm139733299946528"></a><h3>Description</h3><p>This operation print a list of all the currently existing
+generations for the active profile. These may be switched to using
+the <code class="option">--switch-generation</code> operation. It also prints
+the creation date of the generation, and indicates the current
+generation.</p></div><div class="refsection"><a id="idm139733299944800"></a><h3>Examples</h3><pre class="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)</pre></div></div><div class="refsection"><a id="idm139733299943088"></a><h2>Operation <code class="option">--delete-generations</code></h2><div class="refsection"><a id="idm139733299942256"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-env</code> <code class="option">--delete-generations</code> <em class="replaceable"><code>generations</code></em>... </p></div></div><div class="refsection"><a id="idm139733299938880"></a><h3>Description</h3><p>This operation deletes the specified generations of the current
+profile. The generations can be a list of generation numbers, the
+special value <code class="literal">old</code> to delete all non-current
+generations, a value such as <code class="literal">30d</code> 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
+<code class="literal">+5</code> to keep the last <code class="literal">5</code> generations
+ignoring any newer than current, e.g., if <code class="literal">30</code> is the current
+generation <code class="literal">+5</code> will delete generation <code class="literal">25</code>
+and all older generations.
+Periodically deleting old generations is important to make garbage collection
+effective.</p></div><div class="refsection"><a id="idm139733299934384"></a><h3>Examples</h3><pre class="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</pre></div></div><div class="refsection"><a id="idm139733299932576"></a><h2>Operation <code class="option">--switch-generation</code></h2><div class="refsection"><a id="idm139733299931744"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-env</code> { <code class="option">--switch-generation</code> | <code class="option">-G</code> } {<em class="replaceable"><code>generation</code></em>}</p></div></div><div class="refsection"><a id="idm139733299927264"></a><h3>Description</h3><p>This operation makes generation number
+<em class="replaceable"><code>generation</code></em> the current generation of the
+active profile. That is, if the
+<code class="filename"><em class="replaceable"><code>profile</code></em></code> is the path to
+the active profile, then the symlink
+<code class="filename"><em class="replaceable"><code>profile</code></em></code> is made to
+point to
+<code class="filename"><em class="replaceable"><code>profile</code></em>-<em class="replaceable"><code>generation</code></em>-link</code>,
+which is in turn a symlink to the actual user environment in the Nix
+store.</p><p>Switching will fail if the specified generation does not exist.</p></div><div class="refsection"><a id="idm139733299922880"></a><h3>Examples</h3><pre class="screen">
+$ nix-env -G 42
+switching from generation 50 to 42</pre></div></div><div class="refsection"><a id="idm139733299921184"></a><h2>Operation <code class="option">--rollback</code></h2><div class="refsection"><a id="idm139733299920352"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-env</code> <code class="option">--rollback</code> </p></div></div><div class="refsection"><a id="idm139733299918064"></a><h3>Description</h3><p>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 <code class="option">--list-generations</code> and
+<code class="option">--switch-generation</code>.</p></div><div class="refsection"><a id="idm139733299915712"></a><h3>Examples</h3><pre class="screen">
+$ nix-env --rollback
+switching from generation 92 to 91
+
+$ nix-env --rollback
+error: no generation older than the current (91) exists</pre></div></div></div><div class="refentry"><div class="refentry.separator"><hr /></div><a id="sec-nix-build"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix-build — build a Nix expression</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">nix-build</code> [<code class="option">--help</code>] [<code class="option">--version</code>] [
+ { <code class="option">--verbose</code> | <code class="option">-v</code> }
+...] [
+ <code class="option">--quiet</code>
+] [
+ <code class="option">--log-format</code>
+ <em class="replaceable"><code>format</code></em>
+] [
+ <code class="option">--no-build-output</code> | <code class="option">-Q</code>
+] [
+ { <code class="option">--max-jobs</code> | <code class="option">-j</code> }
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--cores</code>
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--max-silent-time</code>
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--timeout</code>
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--keep-going</code> | <code class="option">-k</code>
+] [
+ <code class="option">--keep-failed</code> | <code class="option">-K</code>
+] [<code class="option">--fallback</code>] [<code class="option">--readonly-mode</code>] [
+ <code class="option">-I</code>
+ <em class="replaceable"><code>path</code></em>
+] [
+ <code class="option">--option</code>
+ <em class="replaceable"><code>name</code></em>
+ <em class="replaceable"><code>value</code></em>
+]<br /> [<code class="option">--arg</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em>] [<code class="option">--argstr</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em>] [
+ { <code class="option">--attr</code> | <code class="option">-A</code> }
+ <em class="replaceable"><code>attrPath</code></em>
+ ] [<code class="option">--no-out-link</code>] [<code class="option">--dry-run</code>] [
+ { <code class="option">--out-link</code> | <code class="option">-o</code> }
+ <em class="replaceable"><code>outlink</code></em>
+ ] <em class="replaceable"><code>paths</code></em>... </p></div></div><div class="refsection"><a id="idm139733299874432"></a><h2>Description</h2><p>The <span class="command"><strong>nix-build</strong></span> command builds the derivations
+described by the Nix expressions in <em class="replaceable"><code>paths</code></em>.
+If the build succeeds, it places a symlink to the result in the
+current directory. The symlink is called <code class="filename">result</code>.
+If there are multiple Nix expressions, or the Nix expressions evaluate
+to multiple derivations, multiple sequentially numbered symlinks are
+created (<code class="filename">result</code>, <code class="filename">result-2</code>,
+and so on).</p><p>If no <em class="replaceable"><code>paths</code></em> are specified, then
+<span class="command"><strong>nix-build</strong></span> will use <code class="filename">default.nix</code>
+in the current directory, if it exists.</p><p>If an element of <em class="replaceable"><code>paths</code></em> starts with
+<code class="literal">http://</code> or <code class="literal">https://</code>, 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
+<code class="filename">default.nix</code>.</p><p><span class="command"><strong>nix-build</strong></span> is essentially a wrapper around
+<a class="link" href="#sec-nix-instantiate" title="nix-instantiate"><span class="command"><strong>nix-instantiate</strong></span></a>
+(to translate a high-level Nix expression to a low-level store
+derivation) and <a class="link" href="#rsec-nix-store-realise" title="Operation --realise"><span class="command"><strong>nix-store
+--realise</strong></span></a> (to build the store derivation).</p><div class="warning"><h3 class="title">Warning</h3><p>The result of the build is automatically registered as
+a root of the Nix garbage collector. This root disappears
+automatically when the <code class="filename">result</code> symlink is deleted
+or renamed. So don’t rename the symlink.</p></div></div><div class="refsection"><a id="idm139733299863072"></a><h2>Options</h2><p>All options not listed here are passed to <span class="command"><strong>nix-store
+--realise</strong></span>, except for <code class="option">--arg</code> and
+<code class="option">--attr</code> / <code class="option">-A</code> which are passed to
+<span class="command"><strong>nix-instantiate</strong></span>. <span class="phrase">See
+also <a class="xref" href="#sec-common-options" title="Chapter 20. Common Options">Chapter 20, <em>Common Options</em></a>.</span></p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--no-out-link</code></span></dt><dd><p>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 <span class="command"><strong>nix-store
+ --gc</strong></span>.</p></dd><dt><span class="term"><code class="option">--dry-run</code></span></dt><dd><p>Show what store paths would be built or downloaded.</p></dd><dt><a id="opt-out-link"></a><span class="term"><code class="option">--out-link</code> /
+ <code class="option">-o</code> <em class="replaceable"><code>outlink</code></em></span></dt><dd><p>Change the name of the symlink to the output path
+ created from <code class="filename">result</code> to
+ <em class="replaceable"><code>outlink</code></em>.</p></dd></dl></div><p>The following common options are supported:</p></div><div class="refsection"><a id="idm139733299851056"></a><h2>Examples</h2><pre class="screen">
+$ nix-build '&lt;nixpkgs&gt;' -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 <em class="replaceable"><code>...</code></em> result -&gt; /nix/store/d18hyl92g30l...-firefox-1.5.0.7
+
+$ ls ./result/bin/
+firefox firefox-config</pre><p>If a derivation has multiple outputs,
+<span class="command"><strong>nix-build</strong></span> will build the default (first) output.
+You can also build all outputs:
+</p><pre class="screen">
+$ nix-build '&lt;nixpkgs&gt;' -A openssl.all
+</pre><p>
+This will create a symlink for each output named
+<code class="filename">result-<em class="replaceable"><code>outputname</code></em></code>.
+The suffix is omitted if the output name is <code class="literal">out</code>.
+So if <code class="literal">openssl</code> has outputs <code class="literal">out</code>,
+<code class="literal">bin</code> and <code class="literal">man</code>,
+<span class="command"><strong>nix-build</strong></span> will create symlinks
+<code class="literal">result</code>, <code class="literal">result-bin</code> and
+<code class="literal">result-man</code>. It’s also possible to build a specific
+output:
+</p><pre class="screen">
+$ nix-build '&lt;nixpkgs&gt;' -A openssl.man
+</pre><p>
+This will create a symlink <code class="literal">result-man</code>.</p><p>Build a Nix expression given on the command line:
+
+</p><pre class="screen">
+$ nix-build -E 'with import &lt;nixpkgs&gt; { }; runCommand "foo" { } "echo bar &gt; $out"'
+$ cat ./result
+bar
+</pre><p>
+
+</p><p>Build the GNU Hello package from the latest revision of the
+master branch of Nixpkgs:
+
+</p><pre class="screen">
+$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello
+</pre><p>
+
+</p></div></div><div class="refentry"><div class="refentry.separator"><hr /></div><a id="sec-nix-shell"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix-shell — start an interactive shell based on a Nix expression</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">nix-shell</code> [<code class="option">--arg</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em>] [<code class="option">--argstr</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em>] [
+ { <code class="option">--attr</code> | <code class="option">-A</code> }
+ <em class="replaceable"><code>attrPath</code></em>
+ ] [<code class="option">--command</code> <em class="replaceable"><code>cmd</code></em>] [<code class="option">--run</code> <em class="replaceable"><code>cmd</code></em>] [<code class="option">--exclude</code> <em class="replaceable"><code>regexp</code></em>] [<code class="option">--pure</code>] [<code class="option">--keep</code> <em class="replaceable"><code>name</code></em>] {
+ { <code class="option">--packages</code> | <code class="option">-p</code> }
+
+ { <em class="replaceable"><code>packages</code></em> | <em class="replaceable"><code>expressions</code></em> }
+ ...
+ | [<em class="replaceable"><code>path</code></em>]}</p></div></div><div class="refsection"><a id="idm139733299816608"></a><h2>Description</h2><p>The command <span class="command"><strong>nix-shell</strong></span> 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
+<em class="replaceable"><code>path</code></em> have been set to their corresponding
+values, and the script <code class="literal">$stdenv/setup</code> has been
+sourced. This is useful for reproducing the environment of a
+derivation for development.</p><p>If <em class="replaceable"><code>path</code></em> is not given,
+<span class="command"><strong>nix-shell</strong></span> defaults to
+<code class="filename">shell.nix</code> if it exists, and
+<code class="filename">default.nix</code> otherwise.</p><p>If <em class="replaceable"><code>path</code></em> starts with
+<code class="literal">http://</code> or <code class="literal">https://</code>, 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
+<code class="filename">default.nix</code>.</p><p>If the derivation defines the variable
+<code class="varname">shellHook</code>, it will be evaluated after
+<code class="literal">$stdenv/setup</code> has been sourced. Since this hook is
+not executed by regular Nix builds, it allows you to perform
+initialisation specific to <span class="command"><strong>nix-shell</strong></span>. For example,
+the derivation attribute
+
+</p><pre class="programlisting">
+shellHook =
+ ''
+ echo "Hello shell"
+ '';
+</pre><p>
+
+will cause <span class="command"><strong>nix-shell</strong></span> to print <code class="literal">Hello shell</code>.</p></div><div class="refsection"><a id="idm139733299806096"></a><h2>Options</h2><p>All options not listed here are passed to <span class="command"><strong>nix-store
+--realise</strong></span>, except for <code class="option">--arg</code> and
+<code class="option">--attr</code> / <code class="option">-A</code> which are passed to
+<span class="command"><strong>nix-instantiate</strong></span>. <span class="phrase">See
+also <a class="xref" href="#sec-common-options" title="Chapter 20. Common Options">Chapter 20, <em>Common Options</em></a>.</span></p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--command</code> <em class="replaceable"><code>cmd</code></em></span></dt><dd><p>In the environment of the derivation, run the
+ shell command <em class="replaceable"><code>cmd</code></em>. This command is
+ executed in an interactive shell. (Use <code class="option">--run</code> to
+ use a non-interactive shell instead.) However, a call to
+ <code class="literal">exit</code> is implicitly added to the command, so the
+ shell will exit after running the command. To prevent this, add
+ <code class="literal">return</code> at the end; e.g. <code class="literal">--command
+ "echo Hello; return"</code> will print <code class="literal">Hello</code>
+ and then drop you into the interactive shell. This can be useful
+ for doing any additional initialisation.</p></dd><dt><span class="term"><code class="option">--run</code> <em class="replaceable"><code>cmd</code></em></span></dt><dd><p>Like <code class="option">--command</code>, 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.</p></dd><dt><span class="term"><code class="option">--exclude</code> <em class="replaceable"><code>regexp</code></em></span></dt><dd><p>Do not build any dependencies whose store path
+ matches the regular expression <em class="replaceable"><code>regexp</code></em>.
+ This option may be specified multiple times.</p></dd><dt><span class="term"><code class="option">--pure</code></span></dt><dd><p>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
+ <code class="envar">HOME</code>, <code class="envar">USER</code> and
+ <code class="envar">DISPLAY</code>, are retained. Note that
+ <code class="filename">~/.bashrc</code> and (depending on your Bash
+ installation) <code class="filename">/etc/bashrc</code> are still sourced,
+ so any variables set there will affect the interactive
+ shell.</p></dd><dt><span class="term"><code class="option">--packages</code> / <code class="option">-p</code> <em class="replaceable"><code>packages</code></em>…</span></dt><dd><p>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,
+ <code class="literal">nix-shell -p libjpeg openjdk</code> will start a shell
+ in which the packages denoted by the attribute names
+ <code class="varname">libjpeg</code> and <code class="varname">openjdk</code> are
+ present.</p></dd><dt><span class="term"><code class="option">-i</code> <em class="replaceable"><code>interpreter</code></em></span></dt><dd><p>The chained script interpreter to be invoked by
+ <span class="command"><strong>nix-shell</strong></span>. Only applicable in
+ <code class="literal">#!</code>-scripts (described <a class="link" href="#ssec-nix-shell-shebang" title="Use as a #!-interpreter">below</a>).</p></dd><dt><span class="term"><code class="option">--keep</code> <em class="replaceable"><code>name</code></em></span></dt><dd><p>When a <code class="option">--pure</code> shell is started,
+ keep the listed environment variables.</p></dd></dl></div><p>The following common options are supported:</p></div><div class="refsection"><a id="idm139733299777888"></a><h2>Environment variables</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">NIX_BUILD_SHELL</code></span></dt><dd><p>Shell used to start the interactive environment.
+ Defaults to the <span class="command"><strong>bash</strong></span> found in <code class="envar">PATH</code>.</p></dd></dl></div></div><div class="refsection"><a id="idm139733299774576"></a><h2>Examples</h2><p>To build the dependencies of the package Pan, and start an
+interactive shell in which to build it:
+
+</p><pre class="screen">
+$ nix-shell '&lt;nixpkgs&gt;' -A pan
+[nix-shell]$ unpackPhase
+[nix-shell]$ cd pan-*
+[nix-shell]$ configurePhase
+[nix-shell]$ buildPhase
+[nix-shell]$ ./pan/gui/pan
+</pre><p>
+
+To clear the environment first, and do some additional automatic
+initialisation of the interactive shell:
+
+</p><pre class="screen">
+$ nix-shell '&lt;nixpkgs&gt;' -A pan --pure \
+ --command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
+</pre><p>
+
+Nix expressions can also be given on the command line using the
+<span class="command"><strong>-E</strong></span> and <span class="command"><strong>-p</strong></span> flags.
+For instance, the following starts a shell containing the packages
+<code class="literal">sqlite</code> and <code class="literal">libX11</code>:
+
+</p><pre class="screen">
+$ nix-shell -E 'with import &lt;nixpkgs&gt; { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""'
+</pre><p>
+
+A shorter way to do the same is:
+
+</p><pre class="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 …
+</pre><p>
+
+Note that <span class="command"><strong>-p</strong></span> accepts multiple full nix expressions that
+are valid in the <code class="literal">buildInputs = [ ... ]</code> shown above,
+not only package names. So the following is also legal:
+
+</p><pre class="screen">
+$ nix-shell -p sqlite 'git.override { withManual = false; }'
+</pre><p>
+
+The <span class="command"><strong>-p</strong></span> flag looks up Nixpkgs in the Nix search
+path. You can override it by passing <code class="option">-I</code> or setting
+<code class="envar">NIX_PATH</code>. For example, the following gives you a shell
+containing the Pan package from a specific revision of Nixpkgs:
+
+</p><pre class="screen">
+$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz
+
+[nix-shell:~]$ pan --version
+Pan 0.139
+</pre><p>
+
+</p></div><div class="refsection"><a id="ssec-nix-shell-shebang"></a><h2>Use as a <code class="literal">#!</code>-interpreter</h2><p>You can use <span class="command"><strong>nix-shell</strong></span> 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:
+
+</p><pre class="programlisting">
+#! /usr/bin/env nix-shell
+#! nix-shell -i <em class="replaceable"><code>real-interpreter</code></em> -p <em class="replaceable"><code>packages</code></em>
+</pre><p>
+
+where <em class="replaceable"><code>real-interpreter</code></em> is the “real” script
+interpreter that will be invoked by <span class="command"><strong>nix-shell</strong></span> after
+it has obtained the dependencies and initialised the environment, and
+<em class="replaceable"><code>packages</code></em> are the attribute names of the
+dependencies in Nixpkgs.</p><p>The lines starting with <code class="literal">#! nix-shell</code> specify
+<span class="command"><strong>nix-shell</strong></span> options (see above). Note that you cannot
+write <code class="literal">#! /usr/bin/env nix-shell -i ...</code> because
+many operating systems only allow one argument in
+<code class="literal">#!</code> lines.</p><p>For example, here is a Python script that depends on Python and
+the <code class="literal">prettytable</code> package:
+
+</p><pre class="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
+</pre><p>
+
+</p><p>Similarly, the following is a Perl script that specifies that it
+requires Perl and the <code class="literal">HTML::TokeParser::Simple</code> and
+<code class="literal">LWP</code> packages:
+
+</p><pre class="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-&gt;new(url =&gt; 'http://nixos.org/');
+
+while (my $token = $p-&gt;get_tag("a")) {
+ my $href = $token-&gt;get_attr("href");
+ print "$href\n" if $href;
+}
+</pre><p>
+
+</p><p>Sometimes you need to pass a simple Nix expression to customize
+a package like Terraform:
+
+</p><pre class="programlisting">
+#! /usr/bin/env nix-shell
+#! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])"
+
+terraform apply
+</pre><p>
+
+</p><div class="note"><h3 class="title">Note</h3><p>You must use double quotes (<code class="literal">"</code>) when
+passing a simple Nix expression in a nix-shell shebang.</p></div><p>
+</p><p>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):
+
+</p><pre class="programlisting">
+#! /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 &lt;- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/")
+ body &lt;- getResponseBody resp
+ let tags = filter (isTagOpenName "a") $ parseTags body
+ let tags' = map (fromAttrib "href") tags
+ mapM_ putStrLn $ filter (/= "") tags'
+</pre><p>
+
+If you want to be even more precise, you can specify a specific
+revision of Nixpkgs:
+
+</p><pre class="programlisting">
+#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz
+</pre><p>
+
+</p><p>The examples above all used <code class="option">-p</code> 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:
+
+</p><pre class="programlisting">
+#! /usr/bin/env nix-shell
+#! nix-shell deps.nix -i python
+</pre><p>
+
+where the file <code class="filename">deps.nix</code> in the same directory
+as the <code class="literal">#!</code>-script contains:
+
+</p><pre class="programlisting">
+with import &lt;nixpkgs&gt; {};
+
+runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
+</pre><p>
+
+</p></div></div><div class="refentry"><div class="refentry.separator"><hr /></div><a id="sec-nix-store"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix-store — manipulate or query the Nix store</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">nix-store</code> [<code class="option">--help</code>] [<code class="option">--version</code>] [
+ { <code class="option">--verbose</code> | <code class="option">-v</code> }
+...] [
+ <code class="option">--quiet</code>
+] [
+ <code class="option">--log-format</code>
+ <em class="replaceable"><code>format</code></em>
+] [
+ <code class="option">--no-build-output</code> | <code class="option">-Q</code>
+] [
+ { <code class="option">--max-jobs</code> | <code class="option">-j</code> }
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--cores</code>
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--max-silent-time</code>
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--timeout</code>
+ <em class="replaceable"><code>number</code></em>
+] [
+ <code class="option">--keep-going</code> | <code class="option">-k</code>
+] [
+ <code class="option">--keep-failed</code> | <code class="option">-K</code>
+] [<code class="option">--fallback</code>] [<code class="option">--readonly-mode</code>] [
+ <code class="option">-I</code>
+ <em class="replaceable"><code>path</code></em>
+] [
+ <code class="option">--option</code>
+ <em class="replaceable"><code>name</code></em>
+ <em class="replaceable"><code>value</code></em>
+]<br /> [<code class="option">--add-root</code> <em class="replaceable"><code>path</code></em>] [<code class="option">--indirect</code>] <em class="replaceable"><code>operation</code></em> [<em class="replaceable"><code>options</code></em>...] [<em class="replaceable"><code>arguments</code></em>...]</p></div></div><div class="refsection"><a id="idm139733299713504"></a><h2>Description</h2><p>The command <span class="command"><strong>nix-store</strong></span> performs primitive
+operations on the Nix store. You generally do not need to run this
+command manually.</p><p><span class="command"><strong>nix-store</strong></span> takes exactly one
+<span class="emphasis"><em>operation</em></span> flag which indicates the subcommand to
+be performed. These are documented below.</p></div><div class="refsection"><a id="idm139733299710208"></a><h2>Common options</h2><p>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. <span class="phrase">See
+also <a class="xref" href="#sec-common-options" title="Chapter 20. Common Options">Chapter 20, <em>Common Options</em></a> for a list of common
+options.</span></p><div class="variablelist"><dl class="variablelist"><dt><a id="opt-add-root"></a><span class="term"><code class="option">--add-root</code> <em class="replaceable"><code>path</code></em></span></dt><dd><p>Causes the result of a realisation
+ (<code class="option">--realise</code> and <code class="option">--force-realise</code>)
+ to be registered as a root of the garbage collector<span class="phrase"> (see <a class="xref" href="#ssec-gc-roots" title="11.1. Garbage Collector Roots">Section 11.1, “Garbage Collector Roots”</a>)</span>. The root is stored in
+ <em class="replaceable"><code>path</code></em>, which must be inside a directory
+ that is scanned for roots by the garbage collector (i.e.,
+ typically in a subdirectory of
+ <code class="filename">/nix/var/nix/gcroots/</code>)
+ <span class="emphasis"><em>unless</em></span> the <code class="option">--indirect</code> flag
+ is used.</p><p>If there are multiple results, then multiple symlinks will
+ be created by sequentially numbering symlinks beyond the first one
+ (e.g., <code class="filename">foo</code>, <code class="filename">foo-2</code>,
+ <code class="filename">foo-3</code>, and so on).</p></dd><dt><span class="term"><code class="option">--indirect</code></span></dt><dd><p>In conjunction with <code class="option">--add-root</code>, this option
+ allows roots to be stored <span class="emphasis"><em>outside</em></span> of the GC
+ roots directory. This is useful for commands such as
+ <span class="command"><strong>nix-build</strong></span> 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.</p><p>The <code class="option">--indirect</code> flag causes a uniquely named
+ symlink to <em class="replaceable"><code>path</code></em> to be stored in
+ <code class="filename">/nix/var/nix/gcroots/auto/</code>. For instance,
+
+ </p><pre class="screen">
+$ nix-store --add-root /home/eelco/bla/result --indirect -r <em class="replaceable"><code>...</code></em>
+
+$ ls -l /nix/var/nix/gcroots/auto
+lrwxrwxrwx 1 ... 2005-03-13 21:10 dn54lcypm8f8... -&gt; /home/eelco/bla/result
+
+$ ls -l /home/eelco/bla/result
+lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -&gt; /nix/store/1r11343n6qd4...-f-spot-0.0.10</pre><p>
+
+ Thus, when <code class="filename">/home/eelco/bla/result</code> is removed,
+ the GC root in the <code class="filename">auto</code> directory becomes a
+ dangling symlink and will be ignored by the collector.</p><div class="warning"><h3 class="title">Warning</h3><p>Note that it is not possible to move or rename
+ indirect GC roots, since the symlink in the
+ <code class="filename">auto</code> directory will still point to the old
+ location.</p></div></dd></dl></div></div><div class="refsection"><a id="rsec-nix-store-realise"></a><h2>Operation <code class="option">--realise</code></h2><div class="refsection"><a id="idm139733299689136"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> { <code class="option">--realise</code> | <code class="option">-r</code> } <em class="replaceable"><code>paths</code></em>... [<code class="option">--dry-run</code>]</p></div></div><div class="refsection"><a id="idm139733299683808"></a><h3>Description</h3><p>The operation <code class="option">--realise</code> essentially “builds”
+the specified store paths. Realisation is a somewhat overloaded term:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If the store path is a
+ <span class="emphasis"><em>derivation</em></span>, realisation ensures that the output
+ paths of the derivation are <a class="link" href="#gloss-validity" title="validity">valid</a> (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 <a class="link" href="#gloss-substitute" title="substitute">substitutes</a> that produce the
+ outputs (e.g., by downloading them). Finally, the outputs can be
+ produced by performing the build action described by the
+ derivation.</p></li><li class="listitem"><p>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.</p></li></ul></div><p>
+
+</p><p>The output path of each derivation is printed on standard
+output. (For non-derivations argument, the argument itself is
+printed.)</p><p>The following flags are available:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--dry-run</code></span></dt><dd><p>Print on standard error a description of what
+ packages would be built or downloaded, without actually performing
+ the operation.</p></dd><dt><span class="term"><code class="option">--ignore-unknown</code></span></dt><dd><p>If a non-derivation path does not have a
+ substitute, then silently ignore it.</p></dd><dt><span class="term"><code class="option">--check</code></span></dt><dd><p>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 <code class="option">-K</code>, if an output path is not identical to
+ the corresponding output from the previous build, the new output
+ path is left in
+ <code class="filename">/nix/store/<em class="replaceable"><code>name</code></em>.check.</code></p><p>See also the <code class="option">build-repeat</code> 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.</p></dd></dl></div><p>Special exit codes:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">100</code></span></dt><dd><p>Generic build failure, the builder process
+ returned with a non-zero exit code.</p></dd><dt><span class="term"><code class="literal">101</code></span></dt><dd><p>Build timeout, the build was aborted because it
+ did not complete within the specified <a class="link" href="#conf-timeout"><code class="literal">timeout</code></a>.
+ </p></dd><dt><span class="term"><code class="literal">102</code></span></dt><dd><p>Hash mismatch, the build output was rejected
+ because it does not match the specified <a class="link" href="#fixed-output-drvs"><code class="varname">outputHash</code></a>.
+ </p></dd><dt><span class="term"><code class="literal">104</code></span></dt><dd><p>Not deterministic, the build succeeded in check
+ mode but the resulting output is not binary reproducable.</p></dd></dl></div><p>With the <code class="option">--keep-going</code> flag it's possible for
+multiple failures to occur, in this case the 1xx status codes are or combined
+using binary or. </p><pre class="screen">
+1100100
+ ^^^^
+ |||`- timeout
+ ||`-- output hash mismatch
+ |`--- build failure
+ `---- not deterministic
+</pre></div><div class="refsection"><a id="idm139733299659648"></a><h3>Examples</h3><p>This operation is typically used to build store derivations
+produced by <a class="link" href="#sec-nix-instantiate" title="nix-instantiate"><span class="command"><strong>nix-instantiate</strong></span></a>:
+
+</p><pre class="screen">
+$ nix-store -r $(nix-instantiate ./test.nix)
+/nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1</pre><p>
+
+This is essentially what <a class="link" href="#sec-nix-build" title="nix-build"><span class="command"><strong>nix-build</strong></span></a> does.</p><p>To test whether a previously-built derivation is deterministic:
+
+</p><pre class="screen">
+$ nix-build '&lt;nixpkgs&gt;' -A hello --check -K
+</pre><p>
+
+</p></div></div><div class="refsection"><a id="rsec-nix-store-serve"></a><h2>Operation <code class="option">--serve</code></h2><div class="refsection"><a id="idm139733299653424"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--serve</code> [<code class="option">--write</code>]</p></div></div><div class="refsection"><a id="idm139733299650592"></a><h3>Description</h3><p>The operation <code class="option">--serve</code> 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.
+</p><p>The following flags are available:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--write</code></span></dt><dd><p>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.</p></dd></dl></div></div><div class="refsection"><a id="idm139733299646640"></a><h3>Examples</h3><p>To turn a host into a build server, the
+<code class="filename">authorized_keys</code> file can be used to provide build
+access to a given SSH public key:
+
+</p><pre class="screen">
+$ cat &lt;&lt;EOF &gt;&gt;/root/.ssh/authorized_keys
+command="nice -n20 nix-store --serve --write" ssh-rsa AAAAB3NzaC1yc2EAAAA...
+EOF
+</pre><p>
+
+</p></div></div><div class="refsection"><a id="rsec-nix-store-gc"></a><h2>Operation <code class="option">--gc</code></h2><div class="refsection"><a id="idm139733299642624"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--gc</code> [ <code class="option">--print-roots</code> | <code class="option">--print-live</code> | <code class="option">--print-dead</code> ] [<code class="option">--max-freed</code> <em class="replaceable"><code>bytes</code></em>]</p></div></div><div class="refsection"><a id="idm139733299636544"></a><h3>Description</h3><p>Without additional flags, the operation <code class="option">--gc</code>
+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.</p><p>The following suboperations may be specified:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--print-roots</code></span></dt><dd><p>This operation prints on standard output the set
+ of roots used by the garbage collector. What constitutes a root
+ is described in <a class="xref" href="#ssec-gc-roots" title="11.1. Garbage Collector Roots">Section 11.1, “Garbage Collector Roots”</a>.</p></dd><dt><span class="term"><code class="option">--print-live</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="option">--print-dead</code></span></dt><dd><p>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.</p></dd></dl></div><p>By default, all unreachable paths are deleted. The following
+options control what gets deleted and in what order:
+
+</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--max-freed</code> <em class="replaceable"><code>bytes</code></em></span></dt><dd><p>Keep deleting paths until at least
+ <em class="replaceable"><code>bytes</code></em> bytes have been deleted, then
+ stop. The argument <em class="replaceable"><code>bytes</code></em> can be
+ followed by the multiplicative suffix <code class="literal">K</code>,
+ <code class="literal">M</code>, <code class="literal">G</code> or
+ <code class="literal">T</code>, denoting KiB, MiB, GiB or TiB
+ units.</p></dd></dl></div><p>
+
+</p><p>The behaviour of the collector is also influenced by the <a class="link" href="#conf-keep-outputs"><code class="literal">keep-outputs</code></a>
+and <a class="link" href="#conf-keep-derivations"><code class="literal">keep-derivations</code></a>
+variables in the Nix configuration file.</p><p>By default, the collector prints the total number of freed bytes
+when it finishes (or when it is interrupted). With
+<code class="option">--print-dead</code>, it prints the number of bytes that would
+be freed.</p></div><div class="refsection"><a id="idm139733299619488"></a><h3>Examples</h3><p>To delete all unreachable paths, just do:
+
+</p><pre class="screen">
+$ nix-store --gc
+deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv'
+<em class="replaceable"><code>...</code></em>
+8825586 bytes freed (8.42 MiB)</pre><p>
+
+</p><p>To delete at least 100 MiBs of unreachable paths:
+
+</p><pre class="screen">
+$ nix-store --gc --max-freed $((100 * 1024 * 1024))</pre><p>
+
+</p></div></div><div class="refsection"><a id="idm139733299615968"></a><h2>Operation <code class="option">--delete</code></h2><div class="refsection"><a id="idm139733299615136"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--delete</code> [<code class="option">--ignore-liveness</code>] <em class="replaceable"><code>paths</code></em>... </p></div></div><div class="refsection"><a id="idm139733299611216"></a><h3>Description</h3><p>The operation <code class="option">--delete</code> deletes the store paths
+<em class="replaceable"><code>paths</code></em> 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 <code class="literal">nix-store --gc</code>. Thus,
+<code class="literal">--delete</code> is a more targeted version of
+<code class="literal">--gc</code>.</p><p>With the option <code class="option">--ignore-liveness</code>, 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).</p></div><div class="refsection"><a id="idm139733299606528"></a><h3>Example</h3><pre class="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</pre></div></div><div class="refsection"><a id="refsec-nix-store-query"></a><h2>Operation <code class="option">--query</code></h2><div class="refsection"><a id="idm139733299603504"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> { <code class="option">--query</code> | <code class="option">-q</code> } { <code class="option">--outputs</code> | <code class="option">--requisites</code> | <code class="option">-R</code> | <code class="option">--references</code> | <code class="option">--referrers</code> | <code class="option">--referrers-closure</code> | <code class="option">--deriver</code> | <code class="option">-d</code> | <code class="option">--graph</code> | <code class="option">--tree</code> | <code class="option">--binding</code> <em class="replaceable"><code>name</code></em> | <code class="option">-b</code> <em class="replaceable"><code>name</code></em> | <code class="option">--hash</code> | <code class="option">--size</code> | <code class="option">--roots</code> } [<code class="option">--use-output</code>] [<code class="option">-u</code>] [<code class="option">--force-realise</code>] [<code class="option">-f</code>] <em class="replaceable"><code>paths</code></em>... </p></div></div><div class="refsection"><a id="idm139733299583008"></a><h3>Description</h3><p>The operation <code class="option">--query</code> 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
+<code class="option">--outputs</code>.</p><p>The paths <em class="replaceable"><code>paths</code></em> 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.</p></div><div class="refsection"><a id="idm139733299579920"></a><h3>Common query options</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--use-output</code>, </span><span class="term"><code class="option">-u</code></span></dt><dd><p>For each argument to the query that is a store
+ derivation, apply the query to the output path of the derivation
+ instead.</p></dd><dt><span class="term"><code class="option">--force-realise</code>, </span><span class="term"><code class="option">-f</code></span></dt><dd><p>Realise each argument to the query first (see
+ <a class="link" href="#rsec-nix-store-realise" title="Operation --realise"><span class="command"><strong>nix-store
+ --realise</strong></span></a>).</p></dd></dl></div></div><div class="refsection"><a id="nixref-queries"></a><h3>Queries</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--outputs</code></span></dt><dd><p>Prints out the <a class="link" href="#gloss-output-path" title="output path">output paths</a> of the store
+ derivations <em class="replaceable"><code>paths</code></em>. These are the paths
+ that will be produced when the derivation is
+ built.</p></dd><dt><span class="term"><code class="option">--requisites</code>, </span><span class="term"><code class="option">-R</code></span></dt><dd><p>Prints out the <a class="link" href="#gloss-closure" title="closure">closure</a> of the store path
+ <em class="replaceable"><code>paths</code></em>.</p><p>This query has one option:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--include-outputs</code></span></dt><dd><p>Also include the output path of store
+ derivations, and their closures.</p></dd></dl></div><p>This query can be used to implement various kinds of
+ deployment. A <span class="emphasis"><em>source deployment</em></span> is obtained
+ by distributing the closure of a store derivation. A
+ <span class="emphasis"><em>binary deployment</em></span> is obtained by distributing
+ the closure of an output path. A <span class="emphasis"><em>cache
+ deployment</em></span> (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 <code class="option">--include-outputs</code>.</p></dd><dt><span class="term"><code class="option">--references</code></span></dt><dd><p>Prints the set of <a class="link" href="#gloss-reference" title="reference">references</a> of the store paths
+ <em class="replaceable"><code>paths</code></em>, that is, their immediate
+ dependencies. (For <span class="emphasis"><em>all</em></span> dependencies, use
+ <code class="option">--requisites</code>.)</p></dd><dt><span class="term"><code class="option">--referrers</code></span></dt><dd><p>Prints the set of <span class="emphasis"><em>referrers</em></span> of
+ the store paths <em class="replaceable"><code>paths</code></em>, that is, the
+ store paths currently existing in the Nix store that refer to one
+ of <em class="replaceable"><code>paths</code></em>. Note that contrary to the
+ references, the set of referrers is not constant; it can change as
+ store paths are added or removed.</p></dd><dt><span class="term"><code class="option">--referrers-closure</code></span></dt><dd><p>Prints the closure of the set of store paths
+ <em class="replaceable"><code>paths</code></em> under the referrers relation; that
+ is, all store paths that directly or indirectly refer to one of
+ <em class="replaceable"><code>paths</code></em>. These are all the path currently
+ in the Nix store that are dependent on
+ <em class="replaceable"><code>paths</code></em>.</p></dd><dt><span class="term"><code class="option">--deriver</code>, </span><span class="term"><code class="option">-d</code></span></dt><dd><p>Prints the <a class="link" href="#gloss-deriver" title="deriver">deriver</a> of the store paths
+ <em class="replaceable"><code>paths</code></em>. 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
+ <code class="literal">unknown-deriver</code> is printed.</p></dd><dt><span class="term"><code class="option">--graph</code></span></dt><dd><p>Prints the references graph of the store paths
+ <em class="replaceable"><code>paths</code></em> in the format of the
+ <span class="command"><strong>dot</strong></span> tool of AT&amp;T's <a class="link" href="http://www.graphviz.org/" target="_top">Graphviz package</a>.
+ 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.</p></dd><dt><span class="term"><code class="option">--tree</code></span></dt><dd><p>Prints the references graph of the store paths
+ <em class="replaceable"><code>paths</code></em> 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.</p></dd><dt><span class="term"><code class="option">--graphml</code></span></dt><dd><p>Prints the references graph of the store paths
+ <em class="replaceable"><code>paths</code></em> in the <a class="link" href="http://graphml.graphdrawing.org/" target="_top">GraphML</a> 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.</p></dd><dt><span class="term"><code class="option">--binding</code> <em class="replaceable"><code>name</code></em>, </span><span class="term"><code class="option">-b</code> <em class="replaceable"><code>name</code></em></span></dt><dd><p>Prints the value of the attribute
+ <em class="replaceable"><code>name</code></em> (i.e., environment variable) of
+ the store derivations <em class="replaceable"><code>paths</code></em>. It is an
+ error for a derivation to not have the specified
+ attribute.</p></dd><dt><span class="term"><code class="option">--hash</code></span></dt><dd><p>Prints the SHA-256 hash of the contents of the
+ store paths <em class="replaceable"><code>paths</code></em> (that is, the hash of
+ the output of <span class="command"><strong>nix-store --dump</strong></span> on the given
+ paths). Since the hash is stored in the Nix database, this is a
+ fast operation.</p></dd><dt><span class="term"><code class="option">--size</code></span></dt><dd><p>Prints the size in bytes of the contents of the
+ store paths <em class="replaceable"><code>paths</code></em> — to be precise, the
+ size of the output of <span class="command"><strong>nix-store --dump</strong></span> 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.</p></dd><dt><span class="term"><code class="option">--roots</code></span></dt><dd><p>Prints the garbage collector roots that point,
+ directly or indirectly, at the store paths
+ <em class="replaceable"><code>paths</code></em>.</p></dd></dl></div></div><div class="refsection"><a id="idm139733299531008"></a><h3>Examples</h3><p>Print the closure (runtime dependencies) of the
+<span class="command"><strong>svn</strong></span> program in the current user environment:
+
+</p><pre class="screen">
+$ nix-store -qR $(which svn)
+/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
+/nix/store/9lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4
+<em class="replaceable"><code>...</code></em></pre><p>
+
+</p><p>Print the build-time dependencies of <span class="command"><strong>svn</strong></span>:
+
+</p><pre class="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
+<em class="replaceable"><code>... lots of other paths ...</code></em></pre><p>
+
+The difference with the previous example is that we ask the closure of
+the derivation (<code class="option">-qd</code>), not the closure of the output
+path that contains <span class="command"><strong>svn</strong></span>.</p><p>Show the build-time dependencies as a tree:
+
+</p><pre class="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
+<em class="replaceable"><code>...</code></em></pre><p>
+
+</p><p>Show all paths that depend on the same OpenSSL library as
+<span class="command"><strong>svn</strong></span>:
+
+</p><pre class="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</pre><p>
+
+</p><p>Show all paths that directly or indirectly depend on the Glibc
+(C library) used by <span class="command"><strong>svn</strong></span>:
+
+</p><pre class="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
+<em class="replaceable"><code>...</code></em></pre><p>
+
+Note that <span class="command"><strong>ldd</strong></span> is a command that prints out the
+dynamic libraries used by an ELF executable.</p><p>Make a picture of the runtime dependency graph of the current
+user environment:
+
+</p><pre class="screen">
+$ nix-store -q --graph ~/.nix-profile | dot -Tps &gt; graph.ps
+$ gv graph.ps</pre><p>
+
+</p><p>Show every garbage collector root that points to a store path
+that depends on <span class="command"><strong>svn</strong></span>:
+
+</p><pre class="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
+</pre><p>
+
+</p></div></div><div class="refsection"><a id="idm139733299516176"></a><h2>Operation <code class="option">--add</code></h2><div class="refsection"><a id="idm139733299515344"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--add</code> <em class="replaceable"><code>paths</code></em>... </p></div></div><div class="refsection"><a id="idm139733299511968"></a><h3>Description</h3><p>The operation <code class="option">--add</code> adds the specified paths to
+the Nix store. It prints the resulting paths in the Nix store on
+standard output.</p></div><div class="refsection"><a id="idm139733299510336"></a><h3>Example</h3><pre class="screen">
+$ nix-store --add ./foo.c
+/nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c</pre></div></div><div class="refsection"><a id="idm139733299508688"></a><h2>Operation <code class="option">--add-fixed</code></h2><div class="refsection"><a id="idm139733299507856"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> [<code class="option">--recursive</code>] <code class="option">--add-fixed</code> <em class="replaceable"><code>algorithm</code></em> <em class="replaceable"><code>paths</code></em>... </p></div></div><div class="refsection"><a id="idm139733299503120"></a><h3>Description</h3><p>The operation <code class="option">--add-fixed</code> adds the specified paths to
+the Nix store. Unlike <code class="option">--add</code> 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.
+</p><p>This operation has the following options:
+
+</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--recursive</code></span></dt><dd><p>
+ Use recursive instead of flat hashing mode, used when adding directories
+ to the store.
+ </p></dd></dl></div><p>
+
+</p></div><div class="refsection"><a id="idm139733299498592"></a><h3>Example</h3><pre class="screen">
+$ nix-store --add-fixed sha256 ./hello-2.10.tar.gz
+/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz</pre></div></div><div class="refsection"><a id="refsec-nix-store-verify"></a><h2>Operation <code class="option">--verify</code></h2><div class="refsection"><a id="idm139733299495712"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--verify</code> [<code class="option">--check-contents</code>] [<code class="option">--repair</code>]</p></div></div><div class="refsection"><a id="idm139733299492208"></a><h3>Description</h3><p>The operation <code class="option">--verify</code> 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.</p><p>This operation has the following options:
+
+</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--check-contents</code></span></dt><dd><p>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, <code class="option">--check-contents</code> is obviously quite
+ slow.</p></dd><dt><span class="term"><code class="option">--repair</code></span></dt><dd><p>If any valid path is missing from the store, or
+ (if <code class="option">--check-contents</code> is given) the contents of a
+ valid path has been modified, then try to repair the path by
+ redownloading it. See <span class="command"><strong>nix-store --repair-path</strong></span>
+ for details.</p></dd></dl></div><p>
+
+</p></div></div><div class="refsection"><a id="idm139733299484592"></a><h2>Operation <code class="option">--verify-path</code></h2><div class="refsection"><a id="idm139733299483760"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--verify-path</code> <em class="replaceable"><code>paths</code></em>... </p></div></div><div class="refsection"><a id="idm139733299480256"></a><h3>Description</h3><p>The operation <code class="option">--verify-path</code> 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.</p></div><div class="refsection"><a id="idm139733299478288"></a><h3>Example</h3><p>To verify the integrity of the <span class="command"><strong>svn</strong></span> command and all its dependencies:
+
+</p><pre class="screen">
+$ nix-store --verify-path $(nix-store -qR $(which svn))
+</pre><p>
+
+</p></div></div><div class="refsection"><a id="idm139733299475792"></a><h2>Operation <code class="option">--repair-path</code></h2><div class="refsection"><a id="idm139733299474960"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--repair-path</code> <em class="replaceable"><code>paths</code></em>... </p></div></div><div class="refsection"><a id="idm139733299471456"></a><h3>Description</h3><p>The operation <code class="option">--repair-path</code> attempts to
+“repair” the specified paths by redownloading them using the available
+substituters. If no substitutes are available, then repair is not
+possible.</p><div class="warning"><h3 class="title">Warning</h3><p>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).</p></div></div><div class="refsection"><a id="idm139733299468768"></a><h3>Example</h3><pre class="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'...
+…
+</pre></div></div><div class="refsection"><a id="refsec-nix-store-dump"></a><h2>Operation <code class="option">--dump</code></h2><div class="refsection"><a id="idm139733299465056"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--dump</code> <em class="replaceable"><code>path</code></em> </p></div></div><div class="refsection"><a id="idm139733299461824"></a><h3>Description</h3><p>The operation <code class="option">--dump</code> produces a NAR (Nix
+ARchive) file containing the contents of the file system tree rooted
+at <em class="replaceable"><code>path</code></em>. The archive is written to
+standard output.</p><p>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.</p><p>Also, a NAR archive is <span class="emphasis"><em>canonical</em></span>, 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 <a class="link" href="#refsec-nix-store-query" title="Operation --query"><code class="literal">nix-store -q
+--hash</code></a>) are SHA-256 hashes of the NAR dump of each
+store path.</p><p>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).</p><p>A Nix archive can be unpacked using <code class="literal">nix-store
+--restore</code>.</p></div></div><div class="refsection"><a id="idm139733299454672"></a><h2>Operation <code class="option">--restore</code></h2><div class="refsection"><a id="idm139733299453840"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--restore</code> <em class="replaceable"><code>path</code></em> </p></div></div><div class="refsection"><a id="idm139733299450608"></a><h3>Description</h3><p>The operation <code class="option">--restore</code> unpacks a NAR archive
+to <em class="replaceable"><code>path</code></em>, which must not already exist. The
+archive is read from standard input.</p></div></div><div class="refsection"><a id="refsec-nix-store-export"></a><h2>Operation <code class="option">--export</code></h2><div class="refsection"><a id="idm139733299446736"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--export</code> <em class="replaceable"><code>paths</code></em>... </p></div></div><div class="refsection"><a id="idm139733299443232"></a><h3>Description</h3><p>The operation <code class="option">--export</code> writes a serialisation
+of the specified store paths to standard output in a format that can
+be imported into another Nix store with <span class="command"><strong><a class="command" href="#refsec-nix-store-import" title="Operation --import">nix-store --import</a></strong></span>. This
+is like <span class="command"><strong><a class="command" href="#refsec-nix-store-dump" title="Operation --dump">nix-store
+--dump</a></strong></span>, 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).</p><p>This command does not produce a <span class="emphasis"><em>closure</em></span> 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:
+
+</p><pre class="screen">
+$ nix-store --export $(nix-store -qR <em class="replaceable"><code>paths</code></em>) &gt; out</pre><p>
+
+To import the whole closure again, run:
+
+</p><pre class="screen">
+$ nix-store --import &lt; out</pre><p>
+
+</p></div></div><div class="refsection"><a id="refsec-nix-store-import"></a><h2>Operation <code class="option">--import</code></h2><div class="refsection"><a id="idm139733299435520"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--import</code> </p></div></div><div class="refsection"><a id="idm139733299433104"></a><h3>Description</h3><p>The operation <code class="option">--import</code> reads a serialisation of
+a set of store paths produced by <span class="command"><strong><a class="command" href="#refsec-nix-store-export" title="Operation --export">nix-store --export</a></strong></span> 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.</p></div></div><div class="refsection"><a id="idm139733299429888"></a><h2>Operation <code class="option">--optimise</code></h2><div class="refsection"><a id="idm139733299429056"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--optimise</code> </p></div></div><div class="refsection"><a id="idm139733299426640"></a><h3>Description</h3><p>The operation <code class="option">--optimise</code> 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.</p><p>After completion, or when the command is interrupted, a report
+on the achieved savings is printed on standard error.</p><p>Use <code class="option">-vv</code> or <code class="option">-vvv</code> to get some
+progress indication.</p></div><div class="refsection"><a id="idm139733299423328"></a><h3>Example</h3><pre class="screen">
+$ nix-store --optimise
+hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1'
+<em class="replaceable"><code>...</code></em>
+541838819 bytes (516.74 MiB) freed by hard-linking 54143 files;
+there are 114486 files with equal contents out of 215894 files in total
+</pre></div></div><div class="refsection"><a id="idm139733299421120"></a><h2>Operation <code class="option">--read-log</code></h2><div class="refsection"><a id="idm139733299420288"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> { <code class="option">--read-log</code> | <code class="option">-l</code> } <em class="replaceable"><code>paths</code></em>... </p></div></div><div class="refsection"><a id="idm139733299415376"></a><h3>Description</h3><p>The operation <code class="option">--read-log</code> 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.</p><p>Build logs are kept in
+<code class="filename">/nix/var/log/nix/drvs</code>. 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.</p></div><div class="refsection"><a id="idm139733299412560"></a><h3>Example</h3><pre class="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
+<em class="replaceable"><code>...</code></em>
+</pre></div></div><div class="refsection"><a id="idm139733299410368"></a><h2>Operation <code class="option">--dump-db</code></h2><div class="refsection"><a id="idm139733299409536"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--dump-db</code> [<em class="replaceable"><code>paths</code></em>...]</p></div></div><div class="refsection"><a id="idm139733299406304"></a><h3>Description</h3><p>The operation <code class="option">--dump-db</code> writes a dump of the
+Nix database to standard output. It can be loaded into an empty Nix
+store using <code class="option">--load-db</code>. This is useful for making
+backups and when migrating to different database schemas.</p><p>By default, <code class="option">--dump-db</code> 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
+<code class="option">--export</code>, the user is responsible for passing all the
+store paths for a closure. See <code class="option">--export</code> for an
+example.</p></div></div><div class="refsection"><a id="idm139733299401712"></a><h2>Operation <code class="option">--load-db</code></h2><div class="refsection"><a id="idm139733299400880"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--load-db</code> </p></div></div><div class="refsection"><a id="idm139733299398464"></a><h3>Description</h3><p>The operation <code class="option">--load-db</code> reads a dump of the Nix
+database created by <code class="option">--dump-db</code> from standard input and
+loads it into the Nix database.</p></div></div><div class="refsection"><a id="idm139733299395904"></a><h2>Operation <code class="option">--print-env</code></h2><div class="refsection"><a id="idm139733299395072"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code> <code class="option">--print-env</code> <em class="replaceable"><code>drvpath</code></em> </p></div></div><div class="refsection"><a id="idm139733299391840"></a><h3>Description</h3><p>The operation <code class="option">--print-env</code> 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 <code class="envar">_args</code>.</p></div><div class="refsection"><a id="idm139733299389744"></a><h3>Example</h3><pre class="screen">
+$ nix-store --print-env $(nix-instantiate '&lt;nixpkgs&gt;' -A firefox)
+<em class="replaceable"><code>…</code></em>
+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'
+</pre></div></div><div class="refsection"><a id="rsec-nix-store-generate-binary-cache-key"></a><h2>Operation <code class="option">--generate-binary-cache-key</code></h2><div class="refsection"><a id="idm139733299386016"></a><h3>Synopsis</h3><div class="cmdsynopsis"><p><code class="command">nix-store</code>
+ <code class="option">--generate-binary-cache-key</code>
+ <code class="option">key-name</code>
+ <code class="option">secret-key-file</code>
+ <code class="option">public-key-file</code>
+ </p></div></div><div class="refsection"><a id="idm139733299382080"></a><h3>Description</h3><p>This command generates an <a class="link" href="http://ed25519.cr.yp.to/" target="_top">Ed25519 key pair</a> that can
+be used to create a signed binary cache. It takes three mandatory
+parameters:
+
+</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>A key name, such as
+ <code class="literal">cache.example.org-1</code>, 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. <code class="literal">cache.example.org</code>) with a suffix denoting
+ the number of the key (to be incremented every time you need to
+ revoke a key).</p></li><li class="listitem"><p>The file name where the secret key is to be
+ stored.</p></li><li class="listitem"><p>The file name where the public key is to be
+ stored.</p></li></ol></div><p>
+
+</p></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-utilities"></a>Chapter 23. Utilities</h2></div></div></div><p>This section lists utilities that you can use when you
+work with Nix.</p><div class="refentry"><a id="sec-nix-channel"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix-channel — manage Nix channels</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">nix-channel</code> { <code class="option">--add</code> <em class="replaceable"><code>url</code></em> [<em class="replaceable"><code>name</code></em>] | <code class="option">--remove</code> <em class="replaceable"><code>name</code></em> | <code class="option">--list</code> | <code class="option">--update</code> [<em class="replaceable"><code>names</code></em>...] | <code class="option">--rollback</code> [<em class="replaceable"><code>generation</code></em>] }</p></div></div><div class="refsection"><a id="idm139733299360672"></a><h2>Description</h2><p>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. <span class="phrase">See also <a class="xref" href="#sec-channels" title="Chapter 12. Channels">Chapter 12, <em>Channels</em></a>.</span></p><p>To see the list of official NixOS channels, visit <a class="link" href="https://nixos.org/channels" target="_top">https://nixos.org/channels</a>.</p><p>This command has the following operations:
+
+</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--add</code> <em class="replaceable"><code>url</code></em> [<em class="replaceable"><code>name</code></em>]</span></dt><dd><p>Adds a channel named
+ <em class="replaceable"><code>name</code></em> with URL
+ <em class="replaceable"><code>url</code></em> to the list of subscribed channels.
+ If <em class="replaceable"><code>name</code></em> is omitted, it defaults to the
+ last component of <em class="replaceable"><code>url</code></em>, with the
+ suffixes <code class="literal">-stable</code> or
+ <code class="literal">-unstable</code> removed.</p></dd><dt><span class="term"><code class="option">--remove</code> <em class="replaceable"><code>name</code></em></span></dt><dd><p>Removes the channel named
+ <em class="replaceable"><code>name</code></em> from the list of subscribed
+ channels.</p></dd><dt><span class="term"><code class="option">--list</code></span></dt><dd><p>Prints the names and URLs of all subscribed
+ channels on standard output.</p></dd><dt><span class="term"><code class="option">--update</code> [<em class="replaceable"><code>names</code></em>…]</span></dt><dd><p>Downloads the Nix expressions of all subscribed
+ channels (or only those included in
+ <em class="replaceable"><code>names</code></em> if specified) and makes them the
+ default for <span class="command"><strong>nix-env</strong></span> operations (by symlinking
+ them from the directory
+ <code class="filename">~/.nix-defexpr</code>).</p></dd><dt><span class="term"><code class="option">--rollback</code> [<em class="replaceable"><code>generation</code></em>]</span></dt><dd><p>Reverts the previous call to <span class="command"><strong>nix-channel
+ --update</strong></span>. Optionally, you can specify a specific channel
+ generation number to restore.</p></dd></dl></div><p>
+
+</p><p>Note that <code class="option">--add</code> does not automatically perform
+an update.</p><p>The list of subscribed channels is stored in
+<code class="filename">~/.nix-channels</code>.</p></div><div class="refsection"><a id="idm139733299340240"></a><h2>Examples</h2><p>To subscribe to the Nixpkgs channel and install the GNU Hello package:</p><pre class="screen">
+$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
+$ nix-channel --update
+$ nix-env -iA nixpkgs.hello</pre><p>You can revert channel updates using <code class="option">--rollback</code>:</p><pre class="screen">
+$ nix-instantiate --eval -E '(import &lt;nixpkgs&gt; {}).lib.version'
+"14.04.527.0e935f1"
+
+$ nix-channel --rollback
+switching from generation 483 to 482
+
+$ nix-instantiate --eval -E '(import &lt;nixpkgs&gt; {}).lib.version'
+"14.04.526.dbadfad"
+</pre></div><div class="refsection"><a id="idm139733299336912"></a><h2>Files</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">/nix/var/nix/profiles/per-user/<em class="replaceable"><code>username</code></em>/channels</code></span></dt><dd><p><span class="command"><strong>nix-channel</strong></span> uses a
+ <span class="command"><strong>nix-env</strong></span> profile to keep track of previous
+ versions of the subscribed channels. Every time you run
+ <span class="command"><strong>nix-channel --update</strong></span>, a new channel generation
+ (that is, a symlink to the channel Nix expressions in the Nix store)
+ is created. This enables <span class="command"><strong>nix-channel --rollback</strong></span>
+ to revert to previous versions.</p></dd><dt><span class="term"><code class="filename">~/.nix-defexpr/channels</code></span></dt><dd><p>This is a symlink to
+ <code class="filename">/nix/var/nix/profiles/per-user/<em class="replaceable"><code>username</code></em>/channels</code>. It
+ ensures that <span class="command"><strong>nix-env</strong></span> can find your channels. In
+ a multi-user installation, you may also have
+ <code class="filename">~/.nix-defexpr/channels_root</code>, which links to
+ the channels of the root user.</p></dd></dl></div></div><div class="refsection"><a id="idm139733299328928"></a><h2>Channel format</h2><p>A channel URL should point to a directory containing the
+following files:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">nixexprs.tar.xz</code></span></dt><dd><p>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 <code class="filename">default.nix</code>
+ that serves as the channel’s “entry point”.</p></dd></dl></div></div></div><div class="refentry"><div class="refentry.separator"><hr /></div><a id="sec-nix-collect-garbage"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix-collect-garbage — delete unreachable store paths</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">nix-collect-garbage</code> [<code class="option">--delete-old</code>] [<code class="option">-d</code>] [<code class="option">--delete-older-than</code> <em class="replaceable"><code>period</code></em>] [<code class="option">--max-freed</code> <em class="replaceable"><code>bytes</code></em>] [<code class="option">--dry-run</code>]</p></div></div><div class="refsection"><a id="idm139733299315776"></a><h2>Description</h2><p>The command <span class="command"><strong>nix-collect-garbage</strong></span> is mostly an
+alias of <a class="link" href="#rsec-nix-store-gc" title="Operation --gc"><span class="command"><strong>nix-store
+--gc</strong></span></a>, that is, it deletes all unreachable paths in
+the Nix store to clean up your system. However, it provides two
+additional options: <code class="option">-d</code> (<code class="option">--delete-old</code>),
+which deletes all old generations of all profiles in
+<code class="filename">/nix/var/nix/profiles</code> by invoking
+<code class="literal">nix-env --delete-generations old</code> on all profiles
+(of course, this makes rollbacks to previous configurations
+impossible); and
+<code class="option">--delete-older-than</code> <em class="replaceable"><code>period</code></em>,
+where period is a value such as <code class="literal">30d</code>, which deletes
+all generations older than the specified number of days in all profiles
+in <code class="filename">/nix/var/nix/profiles</code> (except for the generations
+that were active at that point in time).
+</p></div><div class="refsection"><a id="idm139733299309536"></a><h2>Example</h2><p>To delete from the Nix store everything that is not used by the
+current generations of each profile, do
+
+</p><pre class="screen">
+$ nix-collect-garbage -d</pre><p>
+
+</p></div></div><div class="refentry"><div class="refentry.separator"><hr /></div><a id="sec-nix-copy-closure"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix-copy-closure — copy a closure to or from a remote machine via SSH</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">nix-copy-closure</code> [ <code class="option">--to</code> | <code class="option">--from</code> ] [<code class="option">--gzip</code>] [<code class="option">--include-outputs</code>] [ <code class="option">--use-substitutes</code> | <code class="option">-s</code> ] [<code class="option">-v</code>]
+ <em class="replaceable"><code>user@</code></em><em class="replaceable"><code>machine</code></em>
+ <em class="replaceable"><code>paths</code></em> </p></div></div><div class="refsection"><a id="idm139733299294048"></a><h2>Description</h2><p><span class="command"><strong>nix-copy-closure</strong></span> gives you an easy and
+efficient way to exchange software between machines. Given one or
+more Nix store <em class="replaceable"><code>paths</code></em> on the local
+machine, <span class="command"><strong>nix-copy-closure</strong></span> 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
+<span class="command"><strong>ssh</strong></span> (Secure Shell) command. With the
+<code class="option">--from</code>, the direction is reversed:
+the closure of <em class="replaceable"><code>paths</code></em> on a remote machine is
+copied to the Nix store on the local machine.</p><p>This command is efficient because it only sends the store paths
+that are missing on the target machine.</p><p>Since <span class="command"><strong>nix-copy-closure</strong></span> calls
+<span class="command"><strong>ssh</strong></span>, you may be asked to type in the appropriate
+password or passphrase. In fact, you may be asked
+<span class="emphasis"><em>twice</em></span> because <span class="command"><strong>nix-copy-closure</strong></span>
+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
+<span class="command"><strong>ssh-agent</strong></span>.</p><div class="refsection"><a id="idm139733299286896"></a><h3>Options</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--to</code></span></dt><dd><p>Copy the closure of
+ <em class="replaceable"><code>paths</code></em> from the local Nix store to the
+ Nix store on <em class="replaceable"><code>machine</code></em>. This is the
+ default.</p></dd><dt><span class="term"><code class="option">--from</code></span></dt><dd><p>Copy the closure of
+ <em class="replaceable"><code>paths</code></em> from the Nix store on
+ <em class="replaceable"><code>machine</code></em> to the local Nix
+ store.</p></dd><dt><span class="term"><code class="option">--gzip</code></span></dt><dd><p>Enable compression of the SSH
+ connection.</p></dd><dt><span class="term"><code class="option">--include-outputs</code></span></dt><dd><p>Also copy the outputs of store derivations
+ included in the closure.</p></dd><dt><span class="term"><code class="option">--use-substitutes</code> / <code class="option">-s</code></span></dt><dd><p>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 <code class="literal">nixos.org</code> (the default
+ binary cache server) is fast.</p></dd><dt><span class="term"><code class="option">-v</code></span></dt><dd><p>Show verbose output.</p></dd></dl></div></div><div class="refsection"><a id="idm139733299274272"></a><h3>Environment variables</h3><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">NIX_SSHOPTS</code></span></dt><dd><p>Additional options to be passed to
+ <span class="command"><strong>ssh</strong></span> on the command line.</p></dd></dl></div></div><div class="refsection"><a id="idm139733299271440"></a><h3>Examples</h3><p>Copy Firefox with all its dependencies to a remote machine:
+
+</p><pre class="screen">
+$ nix-copy-closure --to alice@itchy.labs $(type -tP firefox)</pre><p>
+
+</p><p>Copy Subversion from a remote machine and then install it into a
+user environment:
+
+</p><pre class="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
+</pre><p>
+
+</p></div></div></div><div class="refentry"><div class="refentry.separator"><hr /></div><a id="sec-nix-daemon"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix-daemon — Nix multi-user support daemon</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">nix-daemon</code> </p></div></div><div class="refsection"><a id="idm139733299262736"></a><h2>Description</h2><p>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.</p></div></div><div class="refentry"><div class="refentry.separator"><hr /></div><a id="sec-nix-hash"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix-hash — compute the cryptographic hash of a path</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">nix-hash</code> [<code class="option">--flat</code>] [<code class="option">--base32</code>] [<code class="option">--truncate</code>] [<code class="option">--type</code> <em class="replaceable"><code>hashAlgo</code></em>] <em class="replaceable"><code>path</code></em>... </p></div><div class="cmdsynopsis"><p><code class="command">nix-hash</code> <code class="option">--to-base16</code> <em class="replaceable"><code>hash</code></em>... </p></div><div class="cmdsynopsis"><p><code class="command">nix-hash</code> <code class="option">--to-base32</code> <em class="replaceable"><code>hash</code></em>... </p></div></div><div class="refsection"><a id="idm139733299246496"></a><h2>Description</h2><p>The command <span class="command"><strong>nix-hash</strong></span> computes the
+cryptographic hash of the contents of each
+<em class="replaceable"><code>path</code></em> 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 <span class="command"><strong>nix-prefetch-url</strong></span> you have to
+specify multiple arguments, see below for an example.</p><p>The hash is computed over a <span class="emphasis"><em>serialisation</em></span>
+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 <span class="emphasis"><em>NAR format</em></span> produced by <a class="link" href="#refsec-nix-store-dump" title="Operation --dump"><span class="command"><strong>nix-store</strong></span>
+<code class="option">--dump</code></a>. Thus, <code class="literal">nix-hash
+<em class="replaceable"><code>path</code></em></code> yields the same
+cryptographic hash as <code class="literal">nix-store --dump
+<em class="replaceable"><code>path</code></em> | md5sum</code>.</p></div><div class="refsection"><a id="idm139733299239440"></a><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--flat</code></span></dt><dd><p>Print the cryptographic hash of the contents of
+ each regular file <em class="replaceable"><code>path</code></em>. That is, do
+ not compute the hash over the dump of
+ <em class="replaceable"><code>path</code></em>. The result is identical to that
+ produced by the GNU commands <span class="command"><strong>md5sum</strong></span> and
+ <span class="command"><strong>sha1sum</strong></span>.</p></dd><dt><span class="term"><code class="option">--base32</code></span></dt><dd><p>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
+ <code class="function">fetchurl</code>).</p></dd><dt><span class="term"><code class="option">--truncate</code></span></dt><dd><p>Truncate hashes longer than 160 bits (such as
+ SHA-256) to 160 bits.</p></dd><dt><span class="term"><code class="option">--type</code> <em class="replaceable"><code>hashAlgo</code></em></span></dt><dd><p>Use the specified cryptographic hash algorithm,
+ which can be one of <code class="literal">md5</code>,
+ <code class="literal">sha1</code>, and
+ <code class="literal">sha256</code>.</p></dd><dt><span class="term"><code class="option">--to-base16</code></span></dt><dd><p>Don’t hash anything, but convert the base-32 hash
+ representation <em class="replaceable"><code>hash</code></em> to
+ hexadecimal.</p></dd><dt><span class="term"><code class="option">--to-base32</code></span></dt><dd><p>Don’t hash anything, but convert the hexadecimal
+ hash representation <em class="replaceable"><code>hash</code></em> to
+ base-32.</p></dd></dl></div></div><div class="refsection"><a id="idm139733299224832"></a><h2>Examples</h2><p>Computing the same hash as <span class="command"><strong>nix-prefetch-url</strong></span>:
+</p><pre class="screen">
+$ nix-prefetch-url file://&lt;(echo test)
+1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
+$ nix-hash --type sha256 --flat --base32 &lt;(echo test)
+1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
+</pre><p>
+</p><p>Computing hashes:
+
+</p><pre class="screen">
+$ mkdir test
+$ echo "hello" &gt; test/world
+
+$ nix-hash test/ <em class="lineannotation"><span class="lineannotation">(MD5 hash; default)</span></em>
+8179d3caeff1869b5ba1744e5a245c04
+
+$ nix-store --dump test/ | md5sum <em class="lineannotation"><span class="lineannotation">(for comparison)</span></em>
+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</pre><p>
+
+</p><p>Converting between hexadecimal and base-32:
+
+</p><pre class="screen">
+$ nix-hash --type sha1 --to-base32 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
+nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
+
+$ nix-hash --type sha1 --to-base16 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
+e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6</pre><p>
+
+</p></div></div><div class="refentry"><div class="refentry.separator"><hr /></div><a id="sec-nix-instantiate"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix-instantiate — instantiate store derivations from Nix expressions</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">nix-instantiate</code> [ <code class="option">--parse</code> |
+ <code class="option">--eval</code>
+ [<code class="option">--strict</code>]
+ [<code class="option">--json</code>]
+ [<code class="option">--xml</code>]
+ ] [<code class="option">--read-write-mode</code>] [<code class="option">--arg</code> <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em>] [
+ { <code class="option">--attr</code> | <code class="option">-A</code> }
+ <em class="replaceable"><code>attrPath</code></em>
+ ] [<code class="option">--add-root</code> <em class="replaceable"><code>path</code></em>] [<code class="option">--indirect</code>] [ <code class="option">--expr</code> | <code class="option">-E</code> ] <em class="replaceable"><code>files</code></em>... </p></div><div class="cmdsynopsis"><p><code class="command">nix-instantiate</code> <code class="option">--find-file</code> <em class="replaceable"><code>files</code></em>... </p></div></div><div class="refsection"><a id="idm139733299196816"></a><h2>Description</h2><p>The command <span class="command"><strong>nix-instantiate</strong></span> generates <a class="link" href="#gloss-derivation" title="derivation">store derivations</a> from (high-level)
+Nix expressions. It evaluates the Nix expressions in each of
+<em class="replaceable"><code>files</code></em> (which defaults to
+<em class="replaceable"><code>./default.nix</code></em>). 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.</p><p>If <em class="replaceable"><code>files</code></em> is the character
+<code class="literal">-</code>, then a Nix expression will be read from standard
+input.</p><p>See also <a class="xref" href="#sec-common-options" title="Chapter 20. Common Options">Chapter 20, <em>Common Options</em></a> for a list of common options.</p></div><div class="refsection"><a id="idm139733299190864"></a><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--add-root</code> <em class="replaceable"><code>path</code></em>, </span><span class="term"><code class="option">--indirect</code></span></dt><dd><p>See the <a class="link" href="#opt-add-root">corresponding
+ options</a> in <span class="command"><strong>nix-store</strong></span>.</p></dd><dt><span class="term"><code class="option">--parse</code></span></dt><dd><p>Just parse the input files, and print their
+ abstract syntax trees on standard output in ATerm
+ format.</p></dd><dt><span class="term"><code class="option">--eval</code></span></dt><dd><p>Just parse and evaluate the input files, and print
+ the resulting values on standard output. No instantiation of
+ store derivations takes place.</p></dd><dt><span class="term"><code class="option">--find-file</code></span></dt><dd><p>Look up the given files in Nix’s search path (as
+ specified by the <code class="envar"><a class="envar" href="#env-NIX_PATH">NIX_PATH</a></code>
+ environment variable). If found, print the corresponding absolute
+ paths on standard output. For instance, if
+ <code class="envar">NIX_PATH</code> is
+ <code class="literal">nixpkgs=/home/alice/nixpkgs</code>, then
+ <code class="literal">nix-instantiate --find-file nixpkgs/default.nix</code>
+ will print
+ <code class="literal">/home/alice/nixpkgs/default.nix</code>.</p></dd><dt><span class="term"><code class="option">--strict</code></span></dt><dd><p>When used with <code class="option">--eval</code>,
+ recursively evaluate list elements and attributes. Normally, such
+ sub-expressions are left unevaluated (since the Nix expression
+ language is lazy).</p><div class="warning"><h3 class="title">Warning</h3><p>This option can cause non-termination, because lazy
+ data structures can be infinitely large.</p></div></dd><dt><span class="term"><code class="option">--json</code></span></dt><dd><p>When used with <code class="option">--eval</code>, print the resulting
+ value as an JSON representation of the abstract syntax tree rather
+ than as an ATerm.</p></dd><dt><span class="term"><code class="option">--xml</code></span></dt><dd><p>When used with <code class="option">--eval</code>, 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 <a class="link" href="#builtin-toXML"><code class="function">toXML</code> built-in</a>.
+ </p></dd><dt><span class="term"><code class="option">--read-write-mode</code></span></dt><dd><p>When used with <code class="option">--eval</code>, 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.</p></dd></dl></div></div><div class="refsection"><a id="idm139733299169472"></a><h2>Examples</h2><p>Instantiating store derivations from a Nix expression, and
+building them using <span class="command"><strong>nix-store</strong></span>:
+
+</p><pre class="screen">
+$ nix-instantiate test.nix <em class="lineannotation"><span class="lineannotation">(instantiate)</span></em>
+/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
+
+$ nix-store -r $(nix-instantiate test.nix) <em class="lineannotation"><span class="lineannotation">(build)</span></em>
+<em class="replaceable"><code>...</code></em>
+/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 <em class="lineannotation"><span class="lineannotation">(output path)</span></em>
+
+$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
+dr-xr-xr-x 2 eelco users 4096 1970-01-01 01:00 lib
+...</pre><p>
+
+</p><p>You can also give a Nix expression on the command line:
+
+</p><pre class="screen">
+$ nix-instantiate -E 'with import &lt;nixpkgs&gt; { }; hello'
+/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
+</pre><p>
+
+This is equivalent to:
+
+</p><pre class="screen">
+$ nix-instantiate '&lt;nixpkgs&gt;' -A hello
+</pre><p>
+
+</p><p>Parsing and evaluating Nix expressions:
+
+</p><pre class="screen">
+$ nix-instantiate --parse -E '1 + 2'
+1 + 2
+
+$ nix-instantiate --eval -E '1 + 2'
+3
+
+$ nix-instantiate --eval --xml -E '1 + 2'
+&lt;?xml version='1.0' encoding='utf-8'?&gt;
+&lt;expr&gt;
+ &lt;int value="3" /&gt;
+&lt;/expr&gt;</pre><p>
+
+</p><p>The difference between non-strict and strict evaluation:
+
+</p><pre class="screen">
+$ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }'
+<em class="replaceable"><code>...</code></em>
+ &lt;attr name="x"&gt;
+ &lt;string value="foo" /&gt;
+ &lt;/attr&gt;
+ &lt;attr name="y"&gt;
+ &lt;unevaluated /&gt;
+ &lt;/attr&gt;
+<em class="replaceable"><code>...</code></em></pre><p>
+
+Note that <code class="varname">y</code> is left unevaluated (the XML
+representation doesn’t attempt to show non-normal forms).
+
+</p><pre class="screen">
+$ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }'
+<em class="replaceable"><code>...</code></em>
+ &lt;attr name="x"&gt;
+ &lt;string value="foo" /&gt;
+ &lt;/attr&gt;
+ &lt;attr name="y"&gt;
+ &lt;string value="foo" /&gt;
+ &lt;/attr&gt;
+<em class="replaceable"><code>...</code></em></pre><p>
+
+</p></div></div><div class="refentry"><div class="refentry.separator"><hr /></div><a id="sec-nix-prefetch-url"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix-prefetch-url — copy a file from a URL into the store and print its hash</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">nix-prefetch-url</code> [<code class="option">--version</code>] [<code class="option">--type</code> <em class="replaceable"><code>hashAlgo</code></em>] [<code class="option">--print-path</code>] [<code class="option">--unpack</code>] [<code class="option">--name</code> <em class="replaceable"><code>name</code></em>] <em class="replaceable"><code>url</code></em> [<em class="replaceable"><code>hash</code></em>]</p></div></div><div class="refsection"><a id="idm139733299148080"></a><h2>Description</h2><p>The command <span class="command"><strong>nix-prefetch-url</strong></span> downloads the
+file referenced by the URL <em class="replaceable"><code>url</code></em>, prints its
+cryptographic hash, and copies it into the Nix store. The file name
+in the store is
+<code class="filename"><em class="replaceable"><code>hash</code></em>-<em class="replaceable"><code>baseName</code></em></code>,
+where <em class="replaceable"><code>baseName</code></em> is everything following the
+final slash in <em class="replaceable"><code>url</code></em>.</p><p>This command is just a convenience for Nix expression writers.
+Often a Nix expression fetches some source distribution from the
+network using the <code class="literal">fetchurl</code> expression contained in
+Nixpkgs. However, <code class="literal">fetchurl</code> requires a
+cryptographic hash. If you don't know the hash, you would have to
+download the file first, and then <code class="literal">fetchurl</code> would
+download it again when you build your Nix expression. Since
+<code class="literal">fetchurl</code> uses the same name for the downloaded file
+as <span class="command"><strong>nix-prefetch-url</strong></span>, the redundant download can be
+avoided.</p><p>If <em class="replaceable"><code>hash</code></em> 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.</p><p>This command prints the hash on standard output. Additionally,
+if the option <code class="option">--print-path</code> is used, the path of the
+downloaded file in the Nix store is also printed.</p></div><div class="refsection"><a id="idm139733299139072"></a><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--type</code> <em class="replaceable"><code>hashAlgo</code></em></span></dt><dd><p>Use the specified cryptographic hash algorithm,
+ which can be one of <code class="literal">md5</code>,
+ <code class="literal">sha1</code>, and
+ <code class="literal">sha256</code>.</p></dd><dt><span class="term"><code class="option">--print-path</code></span></dt><dd><p>Print the store path of the downloaded file on
+ standard output.</p></dd><dt><span class="term"><code class="option">--unpack</code></span></dt><dd><p>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
+ <code class="varname">fetchzip</code> or
+ <code class="varname">fetchFromGitHub</code>.</p></dd><dt><span class="term"><code class="option">--name</code> <em class="replaceable"><code>name</code></em></span></dt><dd><p>Override the name of the file in the Nix store. By
+ default, this is
+ <code class="literal"><em class="replaceable"><code>hash</code></em>-<em class="replaceable"><code>basename</code></em></code>,
+ where <em class="replaceable"><code>basename</code></em> is the last component of
+ <em class="replaceable"><code>url</code></em>. Overriding the name is necessary
+ when <em class="replaceable"><code>basename</code></em> contains characters that
+ are not allowed in Nix store paths.</p></dd></dl></div></div><div class="refsection"><a id="idm139733299126752"></a><h2>Examples</h2><pre class="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
+</pre></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="ch-files"></a>Chapter 24. Files</h2></div></div></div><p>This section lists configuration files that you can use when you
+work with Nix.</p><div class="refentry"><a id="sec-conf-file"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>nix.conf — Nix configuration file</p></div><div class="refsection"><a id="idm139733299118992"></a><h2>Description</h2><p>By default Nix reads settings from the following places:</p><p>The system-wide configuration file
+<code class="filename"><em class="replaceable"><code>sysconfdir</code></em>/nix/nix.conf</code>
+(i.e. <code class="filename">/etc/nix/nix.conf</code> on most systems), or
+<code class="filename">$NIX_CONF_DIR/nix.conf</code> if
+<code class="envar">NIX_CONF_DIR</code> is set. Values loaded in this file are not forwarded to the Nix daemon. The
+client assumes that the daemon has already loaded them.
+</p><p>User-specific configuration files:</p><p>
+ If <code class="envar">NIX_USER_CONF_FILES</code> is set, then each path separated by
+ <code class="literal">:</code> will be loaded in reverse order.
+</p><p>
+ Otherwise it will look for <code class="filename">nix/nix.conf</code> files in
+ <code class="envar">XDG_CONFIG_DIRS</code> and <code class="envar">XDG_CONFIG_HOME</code>.
+
+ The default location is <code class="filename">$HOME/.config/nix.conf</code> if
+ those environment variables are unset.
+</p><p>The configuration files consist of
+<code class="literal"><em class="replaceable"><code>name</code></em> =
+<em class="replaceable"><code>value</code></em></code> pairs, one per line. Other
+files can be included with a line like <code class="literal">include
+<em class="replaceable"><code>path</code></em></code>, where
+<em class="replaceable"><code>path</code></em> is interpreted relative to the current
+conf file and a missing file is an error unless
+<code class="literal">!include</code> is used instead.
+Comments start with a <code class="literal">#</code> character. Here is an
+example configuration file:</p><pre class="programlisting">
+keep-outputs = true # Nice for developers
+keep-derivations = true # Idem
+</pre><p>You can override settings on the command line using the
+<code class="option">--option</code> flag, e.g. <code class="literal">--option keep-outputs
+false</code>.</p><p>The following settings are currently available:
+
+</p><div class="variablelist"><dl class="variablelist"><dt><a id="conf-allowed-uris"></a><span class="term"><code class="literal">allowed-uris</code></span></dt><dd><p>A list of URI prefixes to which access is allowed in
+ restricted evaluation mode. For example, when set to
+ <code class="literal">https://github.com/NixOS</code>, builtin functions
+ such as <code class="function">fetchGit</code> are allowed to access
+ <code class="literal">https://github.com/NixOS/patchelf.git</code>.</p></dd><dt><a id="conf-allow-import-from-derivation"></a><span class="term"><code class="literal">allow-import-from-derivation</code></span></dt><dd><p>By default, Nix allows you to <code class="function">import</code> 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.</p></dd><dt><a id="conf-allow-new-privileges"></a><span class="term"><code class="literal">allow-new-privileges</code></span></dt><dd><p>(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 <span class="command"><strong>sudo</strong></span> or <span class="command"><strong>ping</strong></span> will
+ fail. (Note that in sandbox builds, no such programs are available
+ unless you bind-mount them into the sandbox via the
+ <code class="option">sandbox-paths</code> 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).</p></dd><dt><a id="conf-allowed-users"></a><span class="term"><code class="literal">allowed-users</code></span></dt><dd><p>A list of names of users (separated by whitespace) that
+ are allowed to connect to the Nix daemon. As with the
+ <code class="option">trusted-users</code> option, you can specify groups by
+ prefixing them with <code class="literal">@</code>. Also, you can allow
+ all users by specifying <code class="literal">*</code>. The default is
+ <code class="literal">*</code>.</p><p>Note that trusted users are always allowed to connect.</p></dd><dt><a id="conf-auto-optimise-store"></a><span class="term"><code class="literal">auto-optimise-store</code></span></dt><dd><p>If set to <code class="literal">true</code>, 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 <code class="literal">false</code> (the
+ default), you can still run <span class="command"><strong>nix-store
+ --optimise</strong></span> to get rid of duplicate
+ files.</p></dd><dt><a id="conf-builders"></a><span class="term"><code class="literal">builders</code></span></dt><dd><p>A list of machines on which to perform builds. <span class="phrase">See <a class="xref" href="#chap-distributed-builds" title="Chapter 16. Remote Builds">Chapter 16, <em>Remote Builds</em></a> for details.</span></p></dd><dt><a id="conf-builders-use-substitutes"></a><span class="term"><code class="literal">builders-use-substitutes</code></span></dt><dd><p>If set to <code class="literal">true</code>, 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
+ <code class="literal">cache.nixos.org</code>), 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 <code class="literal">false</code>.</p></dd><dt><a id="conf-build-users-group"></a><span class="term"><code class="literal">build-users-group</code></span></dt><dd><p>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.</p><p>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
+ <code class="filename">/etc/group</code>). Those user accounts should not
+ be used for any other purpose!</p><p>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.)</p><p>The build users should have permission to create files in
+ the Nix store, but not delete them. Therefore,
+ <code class="filename">/nix/store</code> should be owned by the Nix
+ account, its group should be the group specified here, and its
+ mode should be <code class="literal">1775</code>.</p><p>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 <code class="envar">NIX_REMOTE</code> is empty, the uid under which the Nix
+ daemon runs if <code class="envar">NIX_REMOTE</code> is
+ <code class="literal">daemon</code>). Obviously, this should not be used in
+ multi-user settings with untrusted users.</p></dd><dt><a id="conf-compress-build-log"></a><span class="term"><code class="literal">compress-build-log</code></span></dt><dd><p>If set to <code class="literal">true</code> (the default),
+ build logs written to <code class="filename">/nix/var/log/nix/drvs</code>
+ will be compressed on the fly using bzip2. Otherwise, they will
+ not be compressed.</p></dd><dt><a id="conf-connect-timeout"></a><span class="term"><code class="literal">connect-timeout</code></span></dt><dd><p>The timeout (in seconds) for establishing connections in
+ the binary cache substituter. It corresponds to
+ <span class="command"><strong>curl</strong></span>’s <code class="option">--connect-timeout</code>
+ option.</p></dd><dt><a id="conf-cores"></a><span class="term"><code class="literal">cores</code></span></dt><dd><p>Sets the value of the
+ <code class="envar">NIX_BUILD_CORES</code> 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
+ <code class="varname">enableParallelBuilding</code> is set to
+ <code class="literal">true</code>, the builder passes the
+ <code class="option">-j<em class="replaceable"><code>N</code></em></code> flag to GNU Make.
+ It can be overridden using the <code class="option"><a class="option" href="#opt-cores">--cores</a></code> command line switch and
+ defaults to <code class="literal">1</code>. The value <code class="literal">0</code>
+ means that the builder should use all available CPU cores in the
+ system.</p><p>See also <a class="xref" href="#chap-tuning-cores-and-jobs" title="Chapter 17. Tuning Cores and Jobs">Chapter 17, <em>Tuning Cores and Jobs</em></a>.</p></dd><dt><a id="conf-diff-hook"></a><span class="term"><code class="literal">diff-hook</code></span></dt><dd><p>
+ Absolute path to an executable capable of diffing build results.
+ The hook executes if <a class="xref" href="#conf-run-diff-hook"><code class="literal">run-diff-hook</code></a> 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.
+ </p><p>
+ 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.
+ </p><p>The diff hook program receives three parameters:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ A path to the previous build's results
+ </p></li><li class="listitem"><p>
+ A path to the current build's results
+ </p></li><li class="listitem"><p>
+ The path to the build's derivation
+ </p></li><li class="listitem"><p>
+ The path to the build's scratch directory. This directory
+ will exist only if the build was run with
+ <code class="option">--keep-failed</code>.
+ </p></li></ol></div><p>
+ 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.
+ </p><p>When using the Nix daemon, <code class="literal">diff-hook</code> must
+ be set in the <code class="filename">nix.conf</code> configuration file, and
+ cannot be passed at the command line.
+ </p></dd><dt><a id="conf-enforce-determinism"></a><span class="term"><code class="literal">enforce-determinism</code></span></dt><dd><p>See <a class="xref" href="#conf-repeat"><code class="literal">repeat</code></a>.</p></dd><dt><a id="conf-extra-sandbox-paths"></a><span class="term"><code class="literal">extra-sandbox-paths</code></span></dt><dd><p>A list of additional paths appended to
+ <code class="option">sandbox-paths</code>. Useful if you want to extend
+ its default value.</p></dd><dt><a id="conf-extra-platforms"></a><span class="term"><code class="literal">extra-platforms</code></span></dt><dd><p>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.</p></dd><dt><a id="conf-extra-substituters"></a><span class="term"><code class="literal">extra-substituters</code></span></dt><dd><p>Additional binary caches appended to those
+ specified in <code class="option">substituters</code>. When used by
+ unprivileged users, untrusted substituters (i.e. those not listed
+ in <code class="option">trusted-substituters</code>) are silently
+ ignored.</p></dd><dt><a id="conf-fallback"></a><span class="term"><code class="literal">fallback</code></span></dt><dd><p>If set to <code class="literal">true</code>, Nix will fall
+ back to building from source if a binary substitute fails. This
+ is equivalent to the <code class="option">--fallback</code> flag. The
+ default is <code class="literal">false</code>.</p></dd><dt><a id="conf-fsync-metadata"></a><span class="term"><code class="literal">fsync-metadata</code></span></dt><dd><p>If set to <code class="literal">true</code>, changes to the
+ Nix store metadata (in <code class="filename">/nix/var/nix/db</code>) are
+ synchronously flushed to disk. This improves robustness in case
+ of system crashes, but reduces performance. The default is
+ <code class="literal">true</code>.</p></dd><dt><a id="conf-hashed-mirrors"></a><span class="term"><code class="literal">hashed-mirrors</code></span></dt><dd><p>A list of web servers used by
+ <code class="function">builtins.fetchurl</code> to obtain files by hash.
+ Given a hash type <em class="replaceable"><code>ht</code></em> and a base-16 hash
+ <em class="replaceable"><code>h</code></em>, Nix will try to download the file
+ from
+ <code class="literal">hashed-mirror/<em class="replaceable"><code>ht</code></em>/<em class="replaceable"><code>h</code></em></code>.
+ This allows files to be downloaded even if they have disappeared
+ from their original URI. For example, given the hashed mirror
+ <code class="literal">http://tarballs.example.com/</code>, when building the
+ derivation
+
+</p><pre class="programlisting">
+builtins.fetchurl {
+ url = "https://example.org/foo-1.2.3.tar.xz";
+ sha256 = "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae";
+}
+</pre><p>
+
+ Nix will attempt to download this file from
+ <code class="literal">http://tarballs.example.com/sha256/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae</code>
+ first. If it is not available there, if will try the original URI.</p></dd><dt><a id="conf-http-connections"></a><span class="term"><code class="literal">http-connections</code></span></dt><dd><p>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.</p></dd><dt><a id="conf-keep-build-log"></a><span class="term"><code class="literal">keep-build-log</code></span></dt><dd><p>If set to <code class="literal">true</code> (the default),
+ Nix will write the build log of a derivation (i.e. the standard
+ output and error of its builder) to the directory
+ <code class="filename">/nix/var/log/nix/drvs</code>. The build log can be
+ retrieved using the command <span class="command"><strong>nix-store -l
+ <em class="replaceable"><code>path</code></em></strong></span>.</p></dd><dt><a id="conf-keep-derivations"></a><span class="term"><code class="literal">keep-derivations</code></span></dt><dd><p>If <code class="literal">true</code> (default), the garbage
+ collector will keep the derivations from which non-garbage store
+ paths were built. If <code class="literal">false</code>, they will be
+ deleted unless explicitly registered as a root (or reachable from
+ other roots).</p><p>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
+ <code class="literal">keep-outputs</code> is also turned on).</p></dd><dt><a id="conf-keep-env-derivations"></a><span class="term"><code class="literal">keep-env-derivations</code></span></dt><dd><p>If <code class="literal">false</code> (default), derivations
+ are not stored in Nix user environments. That is, the derivations of
+ any build-time-only dependencies may be garbage-collected.</p><p>If <code class="literal">true</code>, 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
+ (<span class="command"><strong>nix-env --delete-generations</strong></span>). To prevent
+ build-time-only dependencies from being collected, you should also
+ turn on <code class="literal">keep-outputs</code>.</p><p>The difference between this option and
+ <code class="literal">keep-derivations</code> is that this one is
+ “sticky”: it applies to any user environment created while this
+ option was enabled, while <code class="literal">keep-derivations</code>
+ only applies at the moment the garbage collector is
+ run.</p></dd><dt><a id="conf-keep-outputs"></a><span class="term"><code class="literal">keep-outputs</code></span></dt><dd><p>If <code class="literal">true</code>, the garbage collector
+ will keep the outputs of non-garbage derivations. If
+ <code class="literal">false</code> (default), outputs will be deleted unless
+ they are GC roots themselves (or reachable from other roots).</p><p>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 <code class="literal">true</code>.</p></dd><dt><a id="conf-max-build-log-size"></a><span class="term"><code class="literal">max-build-log-size</code></span></dt><dd><p>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 <code class="literal">0</code> (the
+ default) means that there is no limit.</p></dd><dt><a id="conf-max-free"></a><span class="term"><code class="literal">max-free</code></span></dt><dd><p>When a garbage collection is triggered by the
+ <code class="literal">min-free</code> option, it stops as soon as
+ <code class="literal">max-free</code> bytes are available. The default is
+ infinity (i.e. delete all garbage).</p></dd><dt><a id="conf-max-jobs"></a><span class="term"><code class="literal">max-jobs</code></span></dt><dd><p>This option defines the maximum number of jobs
+ that Nix will try to build in parallel. The default is
+ <code class="literal">1</code>. The special value <code class="literal">auto</code>
+ causes Nix to use the number of CPUs in your system. <code class="literal">0</code>
+ is useful when using remote builders to prevent any local builds (except for
+ <code class="literal">preferLocalBuild</code> derivation attribute which executes locally
+ regardless). It can be
+ overridden using the <code class="option"><a class="option" href="#opt-max-jobs">--max-jobs</a></code> (<code class="option">-j</code>)
+ command line switch.</p><p>See also <a class="xref" href="#chap-tuning-cores-and-jobs" title="Chapter 17. Tuning Cores and Jobs">Chapter 17, <em>Tuning Cores and Jobs</em></a>.</p></dd><dt><a id="conf-max-silent-time"></a><span class="term"><code class="literal">max-silent-time</code></span></dt><dd><p>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 <code class="option"><a class="option" href="#opt-max-silent-time">--max-silent-time</a></code> command
+ line switch.</p><p>The value <code class="literal">0</code> means that there is no
+ timeout. This is also the default.</p></dd><dt><a id="conf-min-free"></a><span class="term"><code class="literal">min-free</code></span></dt><dd><p>When free disk space in <code class="filename">/nix/store</code>
+ drops below <code class="literal">min-free</code> during a build, Nix
+ performs a garbage-collection until <code class="literal">max-free</code>
+ bytes are available or there is no more garbage. A value of
+ <code class="literal">0</code> (the default) disables this feature.</p></dd><dt><a id="conf-narinfo-cache-negative-ttl"></a><span class="term"><code class="literal">narinfo-cache-negative-ttl</code></span></dt><dd><p>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.</p></dd><dt><a id="conf-narinfo-cache-positive-ttl"></a><span class="term"><code class="literal">narinfo-cache-positive-ttl</code></span></dt><dd><p>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.
+ </p></dd><dt><a id="conf-netrc-file"></a><span class="term"><code class="literal">netrc-file</code></span></dt><dd><p>If set to an absolute path to a <code class="filename">netrc</code>
+ 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
+ <code class="filename">$NIX_CONF_DIR/netrc</code>.</p><p>The <code class="filename">netrc</code> file consists of a list of
+ accounts in the following format:
+
+</p><pre class="screen">
+machine <em class="replaceable"><code>my-machine</code></em>
+login <em class="replaceable"><code>my-username</code></em>
+password <em class="replaceable"><code>my-password</code></em>
+</pre><p>
+
+ For the exact syntax, see <a class="link" href="https://ec.haxx.se/usingcurl-netrc.html" target="_top">the
+ <code class="literal">curl</code> documentation.</a></p><div class="note"><h3 class="title">Note</h3><p>This must be an absolute path, and <code class="literal">~</code>
+ is not resolved. For example, <code class="filename">~/.netrc</code> won't
+ resolve to your home directory's <code class="filename">.netrc</code>.</p></div></dd><dt><a id="conf-plugin-files"></a><span class="term"><code class="literal">plugin-files</code></span></dt><dd><p>
+ 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
+ <code class="literal">nix</code> command, and RegisterSetting to add new
+ nix config settings. See the constructors for those types for
+ more details.
+ </p><p>
+ 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.
+ </p><p>
+ If an entry in the list is a directory, all files in the
+ directory are loaded as plugins (non-recursively).
+ </p></dd><dt><a id="conf-pre-build-hook"></a><span class="term"><code class="literal">pre-build-hook</code></span></dt><dd><p>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.
+ </p><p>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:</p><div class="variablelist"><dl class="variablelist"><dt><a id="extra-sandbox-paths"></a><span class="term"><code class="literal">extra-sandbox-paths</code></span></dt><dd><p>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
+ <code class="literal">sandbox-paths</code>.</p></dd></dl></div></dd><dt><a id="conf-post-build-hook"></a><span class="term"><code class="literal">post-build-hook</code></span></dt><dd><p>Optional. The path to a program to execute after each build.</p><p>This option is only settable in the global
+ <code class="filename">nix.conf</code>, or on the command line by trusted
+ users.</p><p>When using the nix-daemon, the daemon executes the hook as
+ <code class="literal">root</code>. If the nix-daemon is not involved, the
+ hook runs as the user executing the nix-build.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The hook executes after an evaluation-time build.</p></li><li class="listitem"><p>The hook does not execute on substituted paths.</p></li><li class="listitem"><p>The hook's output always goes to the user's terminal.</p></li><li class="listitem"><p>If the hook fails, the build succeeds but no further builds execute.</p></li><li class="listitem"><p>The hook executes synchronously, and blocks other builds from progressing while it runs.</p></li></ul></div><p>The program executes with no arguments. The program's environment
+ contains the following environment variables:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">DRV_PATH</code></span></dt><dd><p>The derivation for the built paths.</p><p>Example:
+ <code class="literal">/nix/store/5nihn1a7pa8b25l9zafqaqibznlvvp3f-bash-4.4-p23.drv</code>
+ </p></dd><dt><span class="term"><code class="envar">OUT_PATHS</code></span></dt><dd><p>Output paths of the built derivation, separated by a space character.</p><p>Example:
+ <code class="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</code>.
+ </p></dd></dl></div><p>See <a class="xref" href="#chap-post-build-hook" title="Chapter 19. Using the post-build-hook">Chapter 19, <em>Using the <code class="option"><a class="option" href="#conf-post-build-hook">post-build-hook</a></code></em></a> for an example
+ implementation.</p></dd><dt><a id="conf-repeat"></a><span class="term"><code class="literal">repeat</code></span></dt><dd><p>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 <a class="xref" href="#conf-enforce-determinism"><code class="literal">enforce-determinism</code></a> is
+ true, the build is rejected and the resulting store paths are not
+ registered as “valid” in Nix’s database.</p></dd><dt><a id="conf-require-sigs"></a><span class="term"><code class="literal">require-sigs</code></span></dt><dd><p>If set to <code class="literal">true</code> (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
+ <code class="option">trusted-public-keys</code> or
+ <code class="option">secret-key-files</code>. Set to <code class="literal">false</code>
+ to disable signature checking.</p></dd><dt><a id="conf-restrict-eval"></a><span class="term"><code class="literal">restrict-eval</code></span></dt><dd><p>If set to <code class="literal">true</code>, the Nix evaluator will
+ not allow access to any files outside of the Nix search path (as
+ set via the <code class="envar">NIX_PATH</code> environment variable or the
+ <code class="option">-I</code> option), or to URIs outside of
+ <code class="option">allowed-uri</code>. The default is
+ <code class="literal">false</code>.</p></dd><dt><a id="conf-run-diff-hook"></a><span class="term"><code class="literal">run-diff-hook</code></span></dt><dd><p>
+ If true, enable the execution of <a class="xref" href="#conf-diff-hook"><code class="literal">diff-hook</code></a>.
+ </p><p>
+ When using the Nix daemon, <code class="literal">run-diff-hook</code> must
+ be set in the <code class="filename">nix.conf</code> configuration file,
+ and cannot be passed at the command line.
+ </p></dd><dt><a id="conf-sandbox"></a><span class="term"><code class="literal">sandbox</code></span></dt><dd><p>If set to <code class="literal">true</code>, builds will be
+ performed in a <span class="emphasis"><em>sandboxed environment</em></span>, 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 <code class="filename">/proc</code>,
+ <code class="filename">/dev</code>, <code class="filename">/dev/shm</code> and
+ <code class="filename">/dev/pts</code> (on Linux), and the paths configured with the
+ <a class="link" href="#conf-sandbox-paths"><code class="literal">sandbox-paths</code>
+ option</a>. This is useful to prevent undeclared dependencies
+ on files in directories such as <code class="filename">/usr/bin</code>. 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).</p><p>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 <a class="link" href="#conf-build-users-group">“build users”
+ feature</a> to perform the actual builds under different users
+ than root).</p><p>If this option is set to <code class="literal">relaxed</code>, then
+ fixed-output derivations and derivations that have the
+ <code class="varname">__noChroot</code> attribute set to
+ <code class="literal">true</code> do not run in sandboxes.</p><p>The default is <code class="literal">true</code> on Linux and
+ <code class="literal">false</code> on all other platforms.</p></dd><dt><a id="conf-sandbox-dev-shm-size"></a><span class="term"><code class="literal">sandbox-dev-shm-size</code></span></dt><dd><p>This option determines the maximum size of the
+ <code class="literal">tmpfs</code> filesystem mounted on
+ <code class="filename">/dev/shm</code> in Linux sandboxes. For the format,
+ see the description of the <code class="option">size</code> option of
+ <code class="literal">tmpfs</code> in
+ <span class="citerefentry"><span class="refentrytitle">mount</span>(8)</span>. The
+ default is <code class="literal">50%</code>.</p></dd><dt><a id="conf-sandbox-paths"></a><span class="term"><code class="literal">sandbox-paths</code></span></dt><dd><p>A list of paths bind-mounted into Nix sandbox
+ environments. You can use the syntax
+ <code class="literal"><em class="replaceable"><code>target</code></em>=<em class="replaceable"><code>source</code></em></code>
+ to mount a path in a different location in the sandbox; for
+ instance, <code class="literal">/bin=/nix-bin</code> will mount the path
+ <code class="literal">/nix-bin</code> as <code class="literal">/bin</code> inside the
+ sandbox. If <em class="replaceable"><code>source</code></em> is followed by
+ <code class="literal">?</code>, then it is not an error if
+ <em class="replaceable"><code>source</code></em> does not exist; for example,
+ <code class="literal">/dev/nvidiactl?</code> specifies that
+ <code class="filename">/dev/nvidiactl</code> will only be mounted in the
+ sandbox if it exists in the host filesystem.</p><p>Depending on how Nix was built, the default value for this option
+ may be empty or provide <code class="filename">/bin/sh</code> as a
+ bind-mount of <span class="command"><strong>bash</strong></span>.</p></dd><dt><a id="conf-secret-key-files"></a><span class="term"><code class="literal">secret-key-files</code></span></dt><dd><p>A whitespace-separated list of files containing
+ secret (private) keys. These are used to sign locally-built
+ paths. They can be generated using <span class="command"><strong>nix-store
+ --generate-binary-cache-key</strong></span>. The corresponding public
+ key can be distributed to other users, who can add it to
+ <code class="option">trusted-public-keys</code> in their
+ <code class="filename">nix.conf</code>.</p></dd><dt><a id="conf-show-trace"></a><span class="term"><code class="literal">show-trace</code></span></dt><dd><p>Causes Nix to print out a stack trace in case of Nix
+ expression evaluation errors.</p></dd><dt><a id="conf-substitute"></a><span class="term"><code class="literal">substitute</code></span></dt><dd><p>If set to <code class="literal">true</code> (default), Nix
+ will use binary substitutes if available. This option can be
+ disabled to force building from source.</p></dd><dt><a id="conf-stalled-download-timeout"></a><span class="term"><code class="literal">stalled-download-timeout</code></span></dt><dd><p>The timeout (in seconds) for receiving data from servers
+ during download. Nix cancels idle downloads after this timeout's
+ duration.</p></dd><dt><a id="conf-substituters"></a><span class="term"><code class="literal">substituters</code></span></dt><dd><p>A list of URLs of substituters, separated by
+ whitespace. The default is
+ <code class="literal">https://cache.nixos.org</code>.</p></dd><dt><a id="conf-system"></a><span class="term"><code class="literal">system</code></span></dt><dd><p>This option specifies the canonical Nix system
+ name of the current installation, such as
+ <code class="literal">i686-linux</code> or
+ <code class="literal">x86_64-darwin</code>. Nix can only build derivations
+ whose <code class="literal">system</code> 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 <code class="literal">x86_64-linux</code> and
+ <code class="literal">i686-linux</code>.</p><p>It defaults to the canonical Nix system name detected by
+ <code class="filename">configure</code> at build time.</p></dd><dt><a id="conf-system-features"></a><span class="term"><code class="literal">system-features</code></span></dt><dd><p>A set of system “features” supported by this
+ machine, e.g. <code class="literal">kvm</code>. Derivations can express a
+ dependency on such features through the derivation attribute
+ <code class="varname">requiredSystemFeatures</code>. For example, the
+ attribute
+
+</p><pre class="programlisting">
+requiredSystemFeatures = [ "kvm" ];
+</pre><p>
+
+ ensures that the derivation can only be built on a machine with
+ the <code class="literal">kvm</code> feature.</p><p>This setting by default includes <code class="literal">kvm</code> if
+ <code class="filename">/dev/kvm</code> is accessible, and the
+ pseudo-features <code class="literal">nixos-test</code>,
+ <code class="literal">benchmark</code> and <code class="literal">big-parallel</code>
+ that are used in Nixpkgs to route builds to specific
+ machines.</p></dd><dt><a id="conf-tarball-ttl"></a><span class="term"><code class="literal">tarball-ttl</code></span></dt><dd><p>Default: <code class="literal">3600</code> seconds.</p><p>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.
+ </p><p>Setting the TTL to <code class="literal">0</code> forces Nix to always
+ check if the tarball is up to date.</p><p>Nix caches tarballs in
+ <code class="filename">$XDG_CACHE_HOME/nix/tarballs</code>.</p><p>Files fetched via <code class="envar">NIX_PATH</code>,
+ <code class="function">fetchGit</code>, <code class="function">fetchMercurial</code>,
+ <code class="function">fetchTarball</code>, and <code class="function">fetchurl</code>
+ respect this TTL.
+ </p></dd><dt><a id="conf-timeout"></a><span class="term"><code class="literal">timeout</code></span></dt><dd><p>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 <code class="option"><a class="option" href="#opt-timeout">--timeout</a></code> command line
+ switch.</p><p>The value <code class="literal">0</code> means that there is no
+ timeout. This is also the default.</p></dd><dt><a id="conf-trace-function-calls"></a><span class="term"><code class="literal">trace-function-calls</code></span></dt><dd><p>Default: <code class="literal">false</code>.</p><p>If set to <code class="literal">true</code>, 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.</p><div class="informalexample"><pre class="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
+</pre></div><p>The <code class="literal">undefined position</code> means the function
+ call is a builtin.</p><p>Use the <code class="literal">contrib/stack-collapse.py</code> script
+ distributed with the Nix source code to convert the trace logs
+ in to a format suitable for <span class="command"><strong>flamegraph.pl</strong></span>.</p></dd><dt><a id="conf-trusted-public-keys"></a><span class="term"><code class="literal">trusted-public-keys</code></span></dt><dd><p>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:
+ <code class="literal">cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
+ hydra.nixos.org-1:CNHJZBh9K4tP3EKF6FkkgeVYsS3ohTl+oS0Qa8bezVs=</code>.</p></dd><dt><a id="conf-trusted-substituters"></a><span class="term"><code class="literal">trusted-substituters</code></span></dt><dd><p>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 <code class="literal">--option
+ substituters <em class="replaceable"><code>urls</code></em></code> on the
+ command line. Unprivileged users are only allowed to pass a
+ subset of the URLs listed in <code class="literal">substituters</code> and
+ <code class="literal">trusted-substituters</code>.</p></dd><dt><a id="conf-trusted-users"></a><span class="term"><code class="literal">trusted-users</code></span></dt><dd><p>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 <code class="literal">@</code>; for instance,
+ <code class="literal">@wheel</code> means all users in the
+ <code class="literal">wheel</code> group. The default is
+ <code class="literal">root</code>.</p><div class="warning"><h3 class="title">Warning</h3><p>Adding a user to <code class="option">trusted-users</code>
+ is essentially equivalent to giving that user root access to the
+ system. For example, the user can set
+ <code class="option">sandbox-paths</code> and thereby obtain read access to
+ directories that are otherwise inacessible to
+ them.</p></div></dd></dl></div><p>
+</p><div class="refsection"><a id="idm139733298856336"></a><h3>Deprecated Settings</h3><p>
+
+</p><div class="variablelist"><dl class="variablelist"><dt><a id="conf-binary-caches"></a><span class="term"><code class="literal">binary-caches</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">binary-caches</code> is now an alias to
+ <a class="xref" href="#conf-substituters"><code class="literal">substituters</code></a>.</p></dd><dt><a id="conf-binary-cache-public-keys"></a><span class="term"><code class="literal">binary-cache-public-keys</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">binary-cache-public-keys</code> is now an alias to
+ <a class="xref" href="#conf-trusted-public-keys"><code class="literal">trusted-public-keys</code></a>.</p></dd><dt><a id="conf-build-compress-log"></a><span class="term"><code class="literal">build-compress-log</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-compress-log</code> is now an alias to
+ <a class="xref" href="#conf-compress-build-log"><code class="literal">compress-build-log</code></a>.</p></dd><dt><a id="conf-build-cores"></a><span class="term"><code class="literal">build-cores</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-cores</code> is now an alias to
+ <a class="xref" href="#conf-cores"><code class="literal">cores</code></a>.</p></dd><dt><a id="conf-build-extra-chroot-dirs"></a><span class="term"><code class="literal">build-extra-chroot-dirs</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-extra-chroot-dirs</code> is now an alias to
+ <a class="xref" href="#conf-extra-sandbox-paths"><code class="literal">extra-sandbox-paths</code></a>.</p></dd><dt><a id="conf-build-extra-sandbox-paths"></a><span class="term"><code class="literal">build-extra-sandbox-paths</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-extra-sandbox-paths</code> is now an alias to
+ <a class="xref" href="#conf-extra-sandbox-paths"><code class="literal">extra-sandbox-paths</code></a>.</p></dd><dt><a id="conf-build-fallback"></a><span class="term"><code class="literal">build-fallback</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-fallback</code> is now an alias to
+ <a class="xref" href="#conf-fallback"><code class="literal">fallback</code></a>.</p></dd><dt><a id="conf-build-max-jobs"></a><span class="term"><code class="literal">build-max-jobs</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-max-jobs</code> is now an alias to
+ <a class="xref" href="#conf-max-jobs"><code class="literal">max-jobs</code></a>.</p></dd><dt><a id="conf-build-max-log-size"></a><span class="term"><code class="literal">build-max-log-size</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-max-log-size</code> is now an alias to
+ <a class="xref" href="#conf-max-build-log-size"><code class="literal">max-build-log-size</code></a>.</p></dd><dt><a id="conf-build-max-silent-time"></a><span class="term"><code class="literal">build-max-silent-time</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-max-silent-time</code> is now an alias to
+ <a class="xref" href="#conf-max-silent-time"><code class="literal">max-silent-time</code></a>.</p></dd><dt><a id="conf-build-repeat"></a><span class="term"><code class="literal">build-repeat</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-repeat</code> is now an alias to
+ <a class="xref" href="#conf-repeat"><code class="literal">repeat</code></a>.</p></dd><dt><a id="conf-build-timeout"></a><span class="term"><code class="literal">build-timeout</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-timeout</code> is now an alias to
+ <a class="xref" href="#conf-timeout"><code class="literal">timeout</code></a>.</p></dd><dt><a id="conf-build-use-chroot"></a><span class="term"><code class="literal">build-use-chroot</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-use-chroot</code> is now an alias to
+ <a class="xref" href="#conf-sandbox"><code class="literal">sandbox</code></a>.</p></dd><dt><a id="conf-build-use-sandbox"></a><span class="term"><code class="literal">build-use-sandbox</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-use-sandbox</code> is now an alias to
+ <a class="xref" href="#conf-sandbox"><code class="literal">sandbox</code></a>.</p></dd><dt><a id="conf-build-use-substitutes"></a><span class="term"><code class="literal">build-use-substitutes</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">build-use-substitutes</code> is now an alias to
+ <a class="xref" href="#conf-substitute"><code class="literal">substitute</code></a>.</p></dd><dt><a id="conf-gc-keep-derivations"></a><span class="term"><code class="literal">gc-keep-derivations</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">gc-keep-derivations</code> is now an alias to
+ <a class="xref" href="#conf-keep-derivations"><code class="literal">keep-derivations</code></a>.</p></dd><dt><a id="conf-gc-keep-outputs"></a><span class="term"><code class="literal">gc-keep-outputs</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">gc-keep-outputs</code> is now an alias to
+ <a class="xref" href="#conf-keep-outputs"><code class="literal">keep-outputs</code></a>.</p></dd><dt><a id="conf-env-keep-derivations"></a><span class="term"><code class="literal">env-keep-derivations</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">env-keep-derivations</code> is now an alias to
+ <a class="xref" href="#conf-keep-env-derivations"><code class="literal">keep-env-derivations</code></a>.</p></dd><dt><a id="conf-extra-binary-caches"></a><span class="term"><code class="literal">extra-binary-caches</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">extra-binary-caches</code> is now an alias to
+ <a class="xref" href="#conf-extra-substituters"><code class="literal">extra-substituters</code></a>.</p></dd><dt><a id="conf-trusted-binary-caches"></a><span class="term"><code class="literal">trusted-binary-caches</code></span></dt><dd><p><span class="emphasis"><em>Deprecated:</em></span>
+ <code class="literal">trusted-binary-caches</code> is now an alias to
+ <a class="xref" href="#conf-trusted-substituters"><code class="literal">trusted-substituters</code></a>.</p></dd></dl></div><p>
+</p></div></div></div></div></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="part-glossary"></a>Appendix A. Glossary</h1></div></div></div><div class="glosslist"><dl><dt><a id="gloss-derivation"></a><span class="glossterm">derivation</span></dt><dd class="glossdef"><p>A description of a build action. The result of a
+ derivation is a store object. Derivations are typically specified
+ in Nix expressions using the <a class="link" href="#ssec-derivation" title="15.4. Derivations"><code class="function">derivation</code>
+ primitive</a>. These are translated into low-level
+ <span class="emphasis"><em>store derivations</em></span> (implicitly by
+ <span class="command"><strong>nix-env</strong></span> and <span class="command"><strong>nix-build</strong></span>, or
+ explicitly by <span class="command"><strong>nix-instantiate</strong></span>).</p></dd><dt><span class="glossterm">store</span></dt><dd class="glossdef"><p>The location in the file system where store objects
+ live. Typically <code class="filename">/nix/store</code>.</p></dd><dt><span class="glossterm">store path</span></dt><dd class="glossdef"><p>The location in the file system of a store object,
+ i.e., an immediate child of the Nix store
+ directory.</p></dd><dt><span class="glossterm">store object</span></dt><dd class="glossdef"><p>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).</p></dd><dt><a id="gloss-substitute"></a><span class="glossterm">substitute</span></dt><dd class="glossdef"><p>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.</p></dd><dt><span class="glossterm">purity</span></dt><dd class="glossdef"><p>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.</p></dd><dt><span class="glossterm">Nix expression</span></dt><dd class="glossdef"><p>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.</p></dd><dt><a id="gloss-reference"></a><span class="glossterm">reference</span></dt><dd class="glossdef"><p>A store path <code class="varname">P</code> is said to have a
+ reference to a store path <code class="varname">Q</code> if the store object
+ at <code class="varname">P</code> contains the path <code class="varname">Q</code>
+ somewhere. The <span class="emphasis"><em>references</em></span> of a store path are
+ the set of store paths to which it has a reference.
+ </p><p>A derivation can reference other derivations and sources
+ (but not output paths), whereas an output path only references other
+ output paths.
+ </p></dd><dt><a id="gloss-reachable"></a><span class="glossterm">reachable</span></dt><dd class="glossdef"><p>A store path <code class="varname">Q</code> is reachable from
+ another store path <code class="varname">P</code> if <code class="varname">Q</code> is in the
+ <a class="link" href="#gloss-closure" title="closure">closure</a> of the
+ <a class="link" href="#gloss-reference" title="reference">references</a> relation.
+ </p></dd><dt><a id="gloss-closure"></a><span class="glossterm">closure</span></dt><dd class="glossdef"><p>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 <a class="link" href="#gloss-reference" title="reference">references</a> 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
+ <span class="command"><strong>nix-store -qR</strong></span> prints out closures of store paths.
+ </p><p>As an example, if the store object at path <code class="varname">P</code> contains
+ a reference to path <code class="varname">Q</code>, then <code class="varname">Q</code> is
+ in the closure of <code class="varname">P</code>. Further, if <code class="varname">Q</code>
+ references <code class="varname">R</code> then <code class="varname">R</code> is also in
+ the closure of <code class="varname">P</code>.
+ </p></dd><dt><a id="gloss-output-path"></a><span class="glossterm">output path</span></dt><dd class="glossdef"><p>A store path produced by a derivation.</p></dd><dt><a id="gloss-deriver"></a><span class="glossterm">deriver</span></dt><dd class="glossdef"><p>The deriver of an <a class="link" href="#gloss-output-path" title="output path">output path</a> is the store
+ derivation that built it.</p></dd><dt><a id="gloss-validity"></a><span class="glossterm">validity</span></dt><dd class="glossdef"><p>A store path is considered
+ <span class="emphasis"><em>valid</em></span> 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.</p></dd><dt><a id="gloss-user-env"></a><span class="glossterm">user environment</span></dt><dd class="glossdef"><p>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 <a class="link" href="#sec-nix-env" title="nix-env"><span class="command"><strong>nix-env</strong></span></a>. See <a class="xref" href="#sec-profiles" title="Chapter 10. Profiles">Chapter 10, <em>Profiles</em></a>.</p></dd><dt><a id="gloss-profile"></a><span class="glossterm">profile</span></dt><dd class="glossdef"><p>A symlink to the current <a class="link" href="#gloss-user-env" title="user environment">user environment</a> of a user, e.g.,
+ <code class="filename">/nix/var/nix/profiles/default</code>.</p></dd><dt><a id="gloss-nar"></a><span class="glossterm">NAR</span></dt><dd class="glossdef"><p>A <span class="emphasis"><em>N</em></span>ix
+ <span class="emphasis"><em>AR</em></span>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
+ <span class="command"><strong>nix-store --dump</strong></span> and <span class="command"><strong>nix-store
+ --restore</strong></span>.</p></dd></dl></div></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="chap-hacking"></a>Appendix B. Hacking</h1></div></div></div><p>This section provides some notes on how to hack on Nix. To get
+the latest version of Nix from GitHub:
+</p><pre class="screen">
+$ git clone https://github.com/NixOS/nix.git
+$ cd nix
+</pre><p>
+</p><p>To build Nix for the current operating system/architecture use
+
+</p><pre class="screen">
+$ nix-build
+</pre><p>
+
+or if you have a flakes-enabled nix:
+
+</p><pre class="screen">
+$ nix build
+</pre><p>
+
+This will build <code class="literal">defaultPackage</code> attribute defined in the <code class="literal">flake.nix</code> 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.
+
+</p><pre class="screen">
+nix-build -A defaultPackage.x86_64-linux
+</pre><p>
+
+</p><p>To build all dependencies and start a shell in which all
+environment variables are set up so that those dependencies can be
+found:
+</p><pre class="screen">
+$ nix-shell
+</pre><p>
+To build Nix itself in this shell:
+</p><pre class="screen">
+[nix-shell]$ ./bootstrap.sh
+[nix-shell]$ ./configure $configureFlags
+[nix-shell]$ make -j $NIX_BUILD_CORES
+</pre><p>
+To install it in <code class="literal">$(pwd)/inst</code> and test it:
+</p><pre class="screen">
+[nix-shell]$ make install
+[nix-shell]$ make installcheck
+[nix-shell]$ ./inst/bin/nix --version
+nix (Nix) 2.4
+</pre><p>
+
+If you have a flakes-enabled nix you can replace:
+
+</p><pre class="screen">
+$ nix-shell
+</pre><p>
+
+by:
+
+</p><pre class="screen">
+$ nix develop
+</pre><p>
+
+</p></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="sec-relnotes"></a>Appendix C. Nix Release Notes</h1></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-2.3"></a>C.1. Release 2.3 (2019-09-04)</h2></div></div></div><p>This is primarily a bug fix release. However, it makes some
+incompatible changes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>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.</p></li></ul></div><p>It also has the following changes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="function">builtins.fetchGit</code>'s <code class="varname">ref</code>
+ argument now allows specifying an absolute remote ref.
+ Nix will automatically prefix <code class="varname">ref</code> with
+ <code class="literal">refs/heads</code> only if <code class="varname">ref</code> doesn't
+ already begin with <code class="literal">refs/</code>.
+ </p></li><li class="listitem"><p>The installer now enables sandboxing by default on Linux when the
+ system has the necessary kernel support.
+ </p></li><li class="listitem"><p>The <code class="literal">max-jobs</code> setting now defaults to 1.</p></li><li class="listitem"><p>New builtin functions:
+ <code class="literal">builtins.isPath</code>,
+ <code class="literal">builtins.hashFile</code>.
+ </p></li><li class="listitem"><p>The <span class="command"><strong>nix</strong></span> command has a new
+ <code class="option">--print-build-logs</code> (<code class="option">-L</code>) 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.
+ </p></li><li class="listitem"><p>Builds are now executed in a pseudo-terminal, and the
+ <code class="envar">TERM</code> environment variable is set to
+ <code class="literal">xterm-256color</code>. This allows many programs
+ (e.g. <span class="command"><strong>gcc</strong></span>, <span class="command"><strong>clang</strong></span>,
+ <span class="command"><strong>cmake</strong></span>) to print colorized log output.</p></li><li class="listitem"><p>Add <code class="option">--no-net</code> convenience flag. This flag
+ disables substituters; sets the <code class="literal">tarball-ttl</code>
+ 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.</p></li><li class="listitem"><p>Add a <code class="literal">post-build-hook</code> setting to run a
+ program after a build has succeeded.</p></li><li class="listitem"><p>Add a <code class="literal">trace-function-calls</code> setting to log
+ the duration of Nix function calls to stderr.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-2.2"></a>C.2. Release 2.2 (2019-01-11)</h2></div></div></div><p>This is primarily a bug fix release. It also has the following
+changes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>In derivations that use structured attributes (i.e. that
+ specify set the <code class="varname">__structuredAttrs</code> attribute to
+ <code class="literal">true</code> to cause all attributes to be passed to
+ the builder in JSON format), you can now specify closure checks
+ per output, e.g.:
+
+</p><pre class="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;
+};
+</pre><p>
+
+ </p></li><li class="listitem"><p>The derivation attribute
+ <code class="varname">requiredSystemFeatures</code> 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 <code class="varname">system-features</code>.</p><p>By default, <code class="varname">system-features</code> includes
+ <code class="literal">kvm</code> if <code class="filename">/dev/kvm</code>
+ exists. For compatibility, it also includes the pseudo-features
+ <code class="literal">nixos-test</code>, <code class="literal">benchmark</code> and
+ <code class="literal">big-parallel</code> which are used by Nixpkgs to route
+ builds to particular Hydra build machines.</p></li><li class="listitem"><p>Sandbox builds are now enabled by default on Linux.</p></li><li class="listitem"><p>The new command <span class="command"><strong>nix doctor</strong></span> shows
+ potential issues with your Nix installation.</p></li><li class="listitem"><p>The <code class="literal">fetchGit</code> 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.</p></li><li class="listitem"><p>The <code class="literal">dirOf</code> builtin function now works on
+ relative paths.</p></li><li class="listitem"><p>Nix now supports <a class="link" href="https://www.w3.org/TR/SRI/" target="_top">SRI hashes</a>,
+ allowing the hash algorithm and hash to be specified in a single
+ string. For example, you can write:
+
+</p><pre class="programlisting">
+import &lt;nix/fetchurl.nix&gt; {
+ url = https://nixos.org/releases/nix/nix-2.1.3/nix-2.1.3.tar.xz;
+ hash = "sha256-XSLa0FjVyADWWhFfkZ2iKTjFDda6mMXjoYMXLRSYQKQ=";
+};
+</pre><p>
+
+ instead of
+
+</p><pre class="programlisting">
+import &lt;nix/fetchurl.nix&gt; {
+ url = https://nixos.org/releases/nix/nix-2.1.3/nix-2.1.3.tar.xz;
+ sha256 = "5d22dad058d5c800d65a115f919da22938c50dd6ba98c5e3a183172d149840a4";
+};
+</pre><p>
+
+ </p><p>In fixed-output derivations, the
+ <code class="varname">outputHashAlgo</code> attribute is no longer mandatory
+ if <code class="varname">outputHash</code> specifies the hash.</p><p><span class="command"><strong>nix hash-file</strong></span> and <span class="command"><strong>nix
+ hash-path</strong></span> 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.</p></li><li class="listitem"><p>Integers are now 64 bits on all platforms.</p></li><li class="listitem"><p>The evaluator now prints profiling statistics (enabled via
+ the <code class="envar">NIX_SHOW_STATS</code> and
+ <code class="envar">NIX_COUNT_CALLS</code> environment variables) in JSON
+ format.</p></li><li class="listitem"><p>The option <code class="option">--xml</code> in <span class="command"><strong>nix-store
+ --query</strong></span> has been removed. Instead, there now is an
+ option <code class="option">--graphml</code> to output the dependency graph
+ in GraphML format.</p></li><li class="listitem"><p>All <code class="filename">nix-*</code> commands are now symlinks to
+ <code class="filename">nix</code>. This saves a bit of disk space.</p></li><li class="listitem"><p><span class="command"><strong>nix repl</strong></span> now uses
+ <code class="literal">libeditline</code> or
+ <code class="literal">libreadline</code>.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-2.1"></a>C.3. Release 2.1 (2018-09-02)</h2></div></div></div><p>This is primarily a bug fix release. It also reduces memory
+consumption in certain situations. In addition, it has the following
+new features:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The Nix installer will no longer default to the Multi-User
+ installation for macOS. You can still <a class="link" href="#sect-multi-user-installation" title="4.2. Multi User Installation">instruct the installer to
+ run in multi-user mode</a>.
+ </p></li><li class="listitem"><p>The Nix installer now supports performing a Multi-User
+ installation for Linux computers which are running systemd. You
+ can <a class="link" href="#sect-multi-user-installation" title="4.2. Multi User Installation">select a Multi-User installation</a> by passing the
+ <code class="option">--daemon</code> flag to the installer: <span class="command"><strong>sh &lt;(curl
+ https://nixos.org/nix/install) --daemon</strong></span>.
+ </p><p>The multi-user installer cannot handle systems with SELinux.
+ If your system has SELinux enabled, you can <a class="link" href="#sect-single-user-installation" title="4.1. Single User Installation">force the installer to run
+ in single-user mode</a>.</p></li><li class="listitem"><p>New builtin functions:
+ <code class="literal">builtins.bitAnd</code>,
+ <code class="literal">builtins.bitOr</code>,
+ <code class="literal">builtins.bitXor</code>,
+ <code class="literal">builtins.fromTOML</code>,
+ <code class="literal">builtins.concatMap</code>,
+ <code class="literal">builtins.mapAttrs</code>.
+ </p></li><li class="listitem"><p>The S3 binary cache store now supports uploading NARs larger
+ than 5 GiB.</p></li><li class="listitem"><p>The S3 binary cache store now supports uploading to
+ S3-compatible services with the <code class="literal">endpoint</code>
+ option.</p></li><li class="listitem"><p>The flag <code class="option">--fallback</code> is no longer required
+ to recover from disappeared NARs in binary caches.</p></li><li class="listitem"><p><span class="command"><strong>nix-daemon</strong></span> now respects
+ <code class="option">--store</code>.</p></li><li class="listitem"><p><span class="command"><strong>nix run</strong></span> now respects
+ <code class="varname">nix-support/propagated-user-env-packages</code>.</p></li></ul></div><p>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.
+</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-2.0"></a>C.4. Release 2.0 (2018-02-22)</h2></div></div></div><p>The following incompatible changes have been made:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The manifest-based substituter mechanism
+ (<span class="command"><strong>download-using-manifests</strong></span>) has been <a class="link" href="https://github.com/NixOS/nix/commit/867967265b80946dfe1db72d40324b4f9af988ed" target="_top">removed</a>. It
+ has been superseded by the binary cache substituter mechanism
+ since several years. As a result, the following programs have been
+ removed:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><span class="command"><strong>nix-pull</strong></span></p></li><li class="listitem"><p><span class="command"><strong>nix-generate-patches</strong></span></p></li><li class="listitem"><p><span class="command"><strong>bsdiff</strong></span></p></li><li class="listitem"><p><span class="command"><strong>bspatch</strong></span></p></li></ul></div><p>
+ </p></li><li class="listitem"><p>The “copy from other stores” substituter mechanism
+ (<span class="command"><strong>copy-from-other-stores</strong></span> and the
+ <code class="envar">NIX_OTHER_STORES</code> 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. <code class="literal">--substituters /mnt</code>), or to build into a
+ chroot store (e.g. <code class="literal">--store /mnt --substituters /</code>).</p></li><li class="listitem"><p>The command <span class="command"><strong>nix-push</strong></span> has been removed as
+ part of the effort to eliminate Nix's dependency on Perl. You can
+ use <span class="command"><strong>nix copy</strong></span> instead, e.g. <code class="literal">nix copy
+ --to file:///tmp/my-binary-cache <em class="replaceable"><code>paths…</code></em></code></p></li><li class="listitem"><p>The “nested” log output feature (<code class="option">--log-type
+ pretty</code>) has been removed. As a result,
+ <span class="command"><strong>nix-log2xml</strong></span> was also removed.</p></li><li class="listitem"><p>OpenSSL-based signing has been <a class="link" href="https://github.com/NixOS/nix/commit/f435f8247553656774dd1b2c88e9de5d59cab203" target="_top">removed</a>. This
+ feature was never well-supported. A better alternative is provided
+ by the <code class="option">secret-key-files</code> and
+ <code class="option">trusted-public-keys</code> options.</p></li><li class="listitem"><p>Failed build caching has been <a class="link" href="https://github.com/NixOS/nix/commit/8cffec84859cec8b610a2a22ab0c4d462a9351ff" target="_top">removed</a>. This
+ feature was introduced to support the Hydra continuous build
+ system, but Hydra no longer uses it.</p></li><li class="listitem"><p><code class="filename">nix-mode.el</code> has been removed from
+ Nix. It is now <a class="link" href="https://github.com/NixOS/nix-mode" target="_top">a separate
+ repository</a> and can be installed through the MELPA package
+ repository.</p></li></ul></div><p>This release has the following new features:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>It introduces a new command named <span class="command"><strong>nix</strong></span>,
+ which is intended to eventually replace all
+ <span class="command"><strong>nix-*</strong></span> commands with a more consistent and
+ better designed user interface. It currently provides replacements
+ for some (but not all) of the functionality provided by
+ <span class="command"><strong>nix-store</strong></span>, <span class="command"><strong>nix-build</strong></span>,
+ <span class="command"><strong>nix-shell -p</strong></span>, <span class="command"><strong>nix-env -qa</strong></span>,
+ <span class="command"><strong>nix-instantiate --eval</strong></span>,
+ <span class="command"><strong>nix-push</strong></span> and
+ <span class="command"><strong>nix-copy-closure</strong></span>. It has the following major
+ features:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>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:
+
+ </p><pre class="screen">nix copy --to ssh://machine nixpkgs.hello</pre><p>
+ </p><pre class="screen">nix copy --to ssh://machine /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10</pre><p>
+ </p><pre class="screen">nix copy --to ssh://machine '(with import &lt;nixpkgs&gt; {}; hello)'</pre><p>
+
+ By contrast, <span class="command"><strong>nix-copy-closure</strong></span> only accepted
+ store paths as arguments.</p></li><li class="listitem"><p>It is self-documenting: <code class="option">--help</code> shows
+ all available command-line arguments. If
+ <code class="option">--help</code> is given after a subcommand, it shows
+ examples for that subcommand. <span class="command"><strong>nix
+ --help-config</strong></span> shows all configuration
+ options.</p></li><li class="listitem"><p>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 <span class="command"><strong>nix
+ log</strong></span>.</p></li><li class="listitem"><p>It <a class="link" href="https://github.com/NixOS/nix/commit/b8283773bd64d7da6859ed520ee19867742a03ba" target="_top">provides</a>
+ all <code class="filename">nix.conf</code> configuration options as
+ command line flags. For example, instead of <code class="literal">--option
+ http-connections 100</code> you can write
+ <code class="literal">--http-connections 100</code>. Boolean options can
+ be written as
+ <code class="literal">--<em class="replaceable"><code>foo</code></em></code> or
+ <code class="literal">--no-<em class="replaceable"><code>foo</code></em></code>
+ (e.g. <code class="option">--no-auto-optimise-store</code>).</p></li><li class="listitem"><p>Many subcommands have a <code class="option">--json</code> flag to
+ write results to stdout in JSON format.</p></li></ul></div><div class="warning"><h3 class="title">Warning</h3><p>Please note that the <span class="command"><strong>nix</strong></span> command
+ is a work in progress and the interface is subject to
+ change.</p></div><p>It provides the following high-level (“porcelain”)
+ subcommands:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><span class="command"><strong>nix build</strong></span> is a replacement for
+ <span class="command"><strong>nix-build</strong></span>.</p></li><li class="listitem"><p><span class="command"><strong>nix run</strong></span> executes a command in an
+ environment in which the specified packages are available. It
+ is (roughly) a replacement for <span class="command"><strong>nix-shell
+ -p</strong></span>. Unlike that command, it does not execute the
+ command in a shell, and has a flag (<span class="command"><strong>-c</strong></span>)
+ that specifies the unquoted command line to be
+ executed.</p><p>It is particularly useful in conjunction with chroot
+ stores, allowing Linux users who do not have permission to
+ install Nix in <span class="command"><strong>/nix/store</strong></span> to still use
+ binary substitutes that assume
+ <span class="command"><strong>/nix/store</strong></span>. For example,
+
+ </p><pre class="screen">nix run --store ~/my-nix nixpkgs.hello -c hello --greeting 'Hi everybody!'</pre><p>
+
+ downloads (or if not substitutes are available, builds) the
+ GNU Hello package into
+ <code class="filename">~/my-nix/nix/store</code>, then runs
+ <span class="command"><strong>hello</strong></span> in a mount namespace where
+ <code class="filename">~/my-nix/nix/store</code> is mounted onto
+ <span class="command"><strong>/nix/store</strong></span>.</p></li><li class="listitem"><p><span class="command"><strong>nix search</strong></span> replaces <span class="command"><strong>nix-env
+ -qa</strong></span>. It searches the available packages for
+ occurrences of a search string in the attribute name, package
+ name or description. Unlike <span class="command"><strong>nix-env -qa</strong></span>, it
+ has a cache to speed up subsequent searches.</p></li><li class="listitem"><p><span class="command"><strong>nix copy</strong></span> copies paths between
+ arbitrary Nix stores, generalising
+ <span class="command"><strong>nix-copy-closure</strong></span> and
+ <span class="command"><strong>nix-push</strong></span>.</p></li><li class="listitem"><p><span class="command"><strong>nix repl</strong></span> replaces the external
+ program <span class="command"><strong>nix-repl</strong></span>. It provides an
+ interactive environment for evaluating and building Nix
+ expressions. Note that it uses <code class="literal">linenoise-ng</code>
+ instead of GNU Readline.</p></li><li class="listitem"><p><span class="command"><strong>nix upgrade-nix</strong></span> 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.)</p></li><li class="listitem"><p><span class="command"><strong>nix verify</strong></span> checks whether store paths
+ are unmodified and/or “trusted” (see below). It replaces
+ <span class="command"><strong>nix-store --verify</strong></span> and <span class="command"><strong>nix-store
+ --verify-path</strong></span>.</p></li><li class="listitem"><p><span class="command"><strong>nix log</strong></span> 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 <code class="uri">cache.nixos.org</code>, which now provides build
+ logs).</p></li><li class="listitem"><p><span class="command"><strong>nix edit</strong></span> opens the source code of a
+ package in your editor.</p></li><li class="listitem"><p><span class="command"><strong>nix eval</strong></span> replaces
+ <span class="command"><strong>nix-instantiate --eval</strong></span>.</p></li><li class="listitem"><p><span class="command"><strong><a class="command" href="https://github.com/NixOS/nix/commit/d41c5eb13f4f3a37d80dbc6d3888644170c3b44a" target="_top">nix
+ why-depends</a></strong></span> shows why one store path has another in
+ its closure. This is primarily useful to finding the causes of
+ closure bloat. For example,
+
+ </p><pre class="screen">nix why-depends nixpkgs.vlc nixpkgs.libdrm.dev</pre><p>
+
+ shows a chain of files and fragments of file contents that
+ cause the VLC package to have the “dev” output of
+ <code class="literal">libdrm</code> in its closure — an undesirable
+ situation.</p></li><li class="listitem"><p><span class="command"><strong>nix path-info</strong></span> shows information about
+ store paths, replacing <span class="command"><strong>nix-store -q</strong></span>. A
+ useful feature is the option <code class="option">--closure-size</code>
+ (<code class="option">-S</code>). For example, the following command show
+ the closure sizes of every path in the current NixOS system
+ closure, sorted by size:
+
+ </p><pre class="screen">nix path-info -rS /run/current-system | sort -nk2</pre><p>
+
+ </p></li><li class="listitem"><p><span class="command"><strong>nix optimise-store</strong></span> replaces
+ <span class="command"><strong>nix-store --optimise</strong></span>. The main difference
+ is that it has a progress indicator.</p></li></ul></div><p>A number of low-level (“plumbing”) commands are also
+ available:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><span class="command"><strong>nix ls-store</strong></span> and <span class="command"><strong>nix
+ ls-nar</strong></span> list the contents of a store path or NAR
+ file. The former is primarily useful in conjunction with
+ remote stores, e.g.
+
+ </p><pre class="screen">nix ls-store --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10</pre><p>
+
+ lists the contents of path in a binary cache.</p></li><li class="listitem"><p><span class="command"><strong>nix cat-store</strong></span> and <span class="command"><strong>nix
+ cat-nar</strong></span> allow extracting a file from a store path or
+ NAR file.</p></li><li class="listitem"><p><span class="command"><strong>nix dump-path</strong></span> writes the contents of
+ a store path to stdout in NAR format. This replaces
+ <span class="command"><strong>nix-store --dump</strong></span>.</p></li><li class="listitem"><p><span class="command"><strong><a class="command" href="https://github.com/NixOS/nix/commit/e8d6ee7c1b90a2fe6d824f1a875acc56799ae6e2" target="_top">nix
+ show-derivation</a></strong></span> displays a store derivation in JSON
+ format. This is an alternative to
+ <span class="command"><strong>pp-aterm</strong></span>.</p></li><li class="listitem"><p><span class="command"><strong><a class="command" href="https://github.com/NixOS/nix/commit/970366266b8df712f5f9cedb45af183ef5a8357f" target="_top">nix
+ add-to-store</a></strong></span> replaces <span class="command"><strong>nix-store
+ --add</strong></span>.</p></li><li class="listitem"><p><span class="command"><strong>nix sign-paths</strong></span> signs store
+ paths.</p></li><li class="listitem"><p><span class="command"><strong>nix copy-sigs</strong></span> copies signatures from
+ one store to another.</p></li><li class="listitem"><p><span class="command"><strong>nix show-config</strong></span> shows all
+ configuration options and their current values.</p></li></ul></div></li><li class="listitem"><p>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
+ <span class="command"><strong>download-from-binary-cache</strong></span>) are now subclasses
+ of the abstract <code class="classname">Store</code> class. This allows
+ many Nix commands to operate on such store types. For example,
+ <span class="command"><strong>nix path-info</strong></span> shows information about paths in
+ your local Nix store, while <span class="command"><strong>nix path-info --store
+ https://cache.nixos.org/</strong></span> shows information about paths
+ in the specified binary cache. Similarly,
+ <span class="command"><strong>nix-copy-closure</strong></span>, <span class="command"><strong>nix-push</strong></span>
+ and substitution are all instances of the general notion of
+ copying paths between different kinds of Nix stores.</p><p>Stores are specified using an URI-like syntax,
+ e.g. <code class="uri">https://cache.nixos.org/</code> or
+ <code class="uri">ssh://machine</code>. The following store types are supported:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><code class="classname">LocalStore</code> (stori URI
+ <code class="literal">local</code> or an absolute path) and the misnamed
+ <code class="classname">RemoteStore</code> (<code class="literal">daemon</code>)
+ provide access to a local Nix store, the latter via the Nix
+ daemon. You can use <code class="literal">auto</code> 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 <code class="envar">NIX_REMOTE</code>
+ environment variable to use the Nix daemon.</p><p>As noted above, <code class="classname">LocalStore</code> now
+ supports chroot builds, allowing the “physical” location of
+ the Nix store
+ (e.g. <code class="filename">/home/alice/nix/store</code>) to differ
+ from its “logical” location (typically
+ <code class="filename">/nix/store</code>). This allows non-root users
+ to use Nix while still getting the benefits from prebuilt
+ binaries from <code class="uri">cache.nixos.org</code>.</p></li><li class="listitem"><p><code class="classname">BinaryCacheStore</code> is the abstract
+ superclass of all binary cache stores. It supports writing
+ build logs and NAR content listings in JSON format.</p></li><li class="listitem"><p><code class="classname">HttpBinaryCacheStore</code>
+ (<code class="literal">http://</code>, <code class="literal">https://</code>)
+ supports binary caches via HTTP or HTTPS. If the server
+ supports <code class="literal">PUT</code> requests, it supports
+ uploading store paths via commands such as <span class="command"><strong>nix
+ copy</strong></span>.</p></li><li class="listitem"><p><code class="classname">LocalBinaryCacheStore</code>
+ (<code class="literal">file://</code>) supports binary caches in the
+ local filesystem.</p></li><li class="listitem"><p><code class="classname">S3BinaryCacheStore</code>
+ (<code class="literal">s3://</code>) supports binary caches stored in
+ Amazon S3, if enabled at compile time.</p></li><li class="listitem"><p><code class="classname">LegacySSHStore</code> (<code class="literal">ssh://</code>)
+ is used to implement remote builds and
+ <span class="command"><strong>nix-copy-closure</strong></span>.</p></li><li class="listitem"><p><code class="classname">SSHStore</code>
+ (<code class="literal">ssh-ng://</code>) supports arbitrary Nix
+ operations on a remote machine via the same protocol used by
+ <span class="command"><strong>nix-daemon</strong></span>.</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>Security has been improved in various ways:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>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.</p><p>Locally-built paths are signed automatically using the
+ secret keys specified by the <code class="option">secret-key-files</code>
+ store option. Secret/public key pairs can be generated using
+ <span class="command"><strong>nix-store
+ --generate-binary-cache-key</strong></span>.</p><p>In addition, locally-built store paths are marked as
+ “ultimately trusted”, but this bit is not propagated when
+ paths are copied between stores.</p></li><li class="listitem"><p>Content-addressable store paths no longer require
+ signatures — they can be imported into a store by unprivileged
+ users even if they lack signatures.</p></li><li class="listitem"><p>The command <span class="command"><strong>nix verify</strong></span> checks whether
+ the specified paths are trusted, i.e., have a certain number
+ of trusted signatures, are ultimately trusted, or are
+ content-addressed.</p></li><li class="listitem"><p>Substitutions from binary caches <a class="link" href="https://github.com/NixOS/nix/commit/ecbc3fedd3d5bdc5a0e1a0a51b29062f2874ac8b" target="_top">now</a>
+ require signatures by default. This was already the case on
+ NixOS.</p></li><li class="listitem"><p>In Linux sandbox builds, we <a class="link" href="https://github.com/NixOS/nix/commit/eba840c8a13b465ace90172ff76a0db2899ab11b" target="_top">now</a>
+ use <code class="filename">/build</code> instead of
+ <code class="filename">/tmp</code> as the temporary build
+ directory. This fixes potential security problems when a build
+ accidentally stores its <code class="envar">TMPDIR</code> in some
+ security-sensitive place, such as an RPATH.</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p><span class="emphasis"><em>Pure evaluation mode</em></span>. With the
+ <code class="literal">--pure-eval</code> 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
+ <code class="function">builtins.getEnv</code>, but more importantly,
+ <span class="emphasis"><em>all</em></span> filesystem or network access unless a content hash
+ or commit hash is specified. For example, calls to
+ <code class="function">builtins.fetchGit</code> are only allowed if a
+ <code class="varname">rev</code> attribute is specified.</p><p>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,
+ <span class="command"><strong>nixos-rebuild</strong></span> might build configurations from a
+ Nix expression in a Git repository in pure mode. That expression
+ might fetch other repositories such as Nixpkgs via
+ <code class="function">builtins.fetchGit</code>. 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.</p></li><li class="listitem"><p>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
+ <code class="option">enforce-determinism</code> is set to
+ <code class="literal">false</code>, it’s <a class="link" href="https://github.com/NixOS/nix/commit/8bdf83f936adae6f2c907a6d2541e80d4120f051" target="_top">no
+ longer</a> a fatal error if build rounds produce different
+ output. Also, a hook named <code class="option">diff-hook</code> is <a class="link" href="https://github.com/NixOS/nix/commit/9a313469a4bdea2d1e8df24d16289dc2a172a169" target="_top">provided</a>
+ to allow you to run tools such as <span class="command"><strong>diffoscope</strong></span>
+ when build rounds produce different output.</p></li><li class="listitem"><p>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. <code class="literal">--option builders
+ 'ssh://my-mac x86_64-darwin'</code>. The environment variable
+ <code class="envar">NIX_BUILD_HOOK</code> has been removed and is no longer
+ needed. The environment variable <code class="envar">NIX_REMOTE_SYSTEMS</code>
+ is still supported for compatibility, but it is also possible to
+ specify builders in <span class="command"><strong>nix.conf</strong></span> by setting the
+ option <code class="literal">builders =
+ @<em class="replaceable"><code>path</code></em></code>.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p><span class="command"><strong>nix-shell</strong></span> <a class="link" href="https://github.com/NixOS/nix/commit/ea59f39326c8e9dc42dfed4bcbf597fbce58797c" target="_top">now</a>
+ sets the <code class="varname">IN_NIX_SHELL</code> 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
+ <code class="varname">lib.inNixShell</code> to check this variable during
+ evaluation.</p></li><li class="listitem"><p><code class="envar">NIX_PATH</code> is now lazy, so URIs in the path are
+ only downloaded if they are needed for evaluation.</p></li><li class="listitem"><p>You can now use
+ <code class="uri">channel:<em class="replaceable"><code>channel-name</code></em></code> as a
+ short-hand for
+ <code class="uri">https://nixos.org/channels/<em class="replaceable"><code>channel-name</code></em>/nixexprs.tar.xz</code>. For
+ example, <code class="literal">nix-build channel:nixos-15.09 -A hello</code>
+ will build the GNU Hello package from the
+ <code class="literal">nixos-15.09</code> channel. In the future, this may
+ use Git to fetch updates more efficiently.</p></li><li class="listitem"><p>When <code class="option">--no-build-output</code> is given, the last
+ 10 lines of the build log will be shown if a build
+ fails.</p></li><li class="listitem"><p>Networking has been improved:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>HTTP/2 is now supported. This makes binary cache lookups
+ <a class="link" href="https://github.com/NixOS/nix/commit/90ad02bf626b885a5dd8967894e2eafc953bdf92" target="_top">much
+ more efficient</a>.</p></li><li class="listitem"><p>We now retry downloads on many HTTP errors, making
+ binary caches substituters more resilient to temporary
+ failures.</p></li><li class="listitem"><p>HTTP credentials can now be configured via the standard
+ <code class="filename">netrc</code> mechanism.</p></li><li class="listitem"><p>If S3 support is enabled at compile time,
+ <code class="uri">s3://</code> URIs are <a class="link" href="https://github.com/NixOS/nix/commit/9ff9c3f2f80ba4108e9c945bbfda2c64735f987b" target="_top">supported</a>
+ in all places where Nix allows URIs.</p></li><li class="listitem"><p>Brotli compression is now supported. In particular,
+ <code class="uri">cache.nixos.org</code> build logs are now compressed using
+ Brotli.</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> <a class="link" href="https://github.com/NixOS/nix/commit/b0cb11722626e906a73f10dd9a0c9eea29faf43a" target="_top">now</a>
+ ignores packages with bad derivation names (in particular those
+ starting with a digit or containing a dot).</p></li><li class="listitem"><p>Many configuration options have been renamed, either because
+ they were unnecessarily verbose
+ (e.g. <code class="option">build-use-sandbox</code> is now just
+ <code class="option">sandbox</code>) or to reflect generalised behaviour
+ (e.g. <code class="option">binary-caches</code> is now
+ <code class="option">substituters</code> because it allows arbitrary store
+ URIs). The old names are still supported for compatibility.</p></li><li class="listitem"><p>The <code class="option">max-jobs</code> option can <a class="link" href="https://github.com/NixOS/nix/commit/7251d048fa812d2551b7003bc9f13a8f5d4c95a5" target="_top">now</a>
+ be set to <code class="literal">auto</code> to use the number of CPUs in the
+ system.</p></li><li class="listitem"><p>Hashes can <a class="link" href="https://github.com/NixOS/nix/commit/c0015e87af70f539f24d2aa2bc224a9d8b84276b" target="_top">now</a>
+ be specified in base-64 format, in addition to base-16 and the
+ non-standard base-32.</p></li><li class="listitem"><p><span class="command"><strong>nix-shell</strong></span> now uses
+ <code class="varname">bashInteractive</code> from Nixpkgs, rather than the
+ <span class="command"><strong>bash</strong></span> command that happens to be in the caller’s
+ <code class="envar">PATH</code>. This is especially important on macOS where
+ the <span class="command"><strong>bash</strong></span> provided by the system is seriously
+ outdated and cannot execute <code class="literal">stdenv</code>’s setup
+ script.</p></li><li class="listitem"><p>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 <code class="option">min-free</code> and
+ <code class="option">max-free</code> options.</p></li><li class="listitem"><p><span class="command"><strong>nix-store -q --roots</strong></span> and
+ <span class="command"><strong>nix-store --gc --print-roots</strong></span> now show temporary
+ and in-memory roots.</p></li><li class="listitem"><p>
+ Nix can now be extended with plugins. See the documentation of
+ the <code class="option">plugin-files</code> option for more details.
+ </p></li></ul></div><p>The Nix language has the following new features:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>It supports floating point numbers. They are based on the
+ C++ <code class="literal">float</code> type and are supported by the
+ existing numerical operators. Export and import to and from JSON
+ and XML works, too.</p></li><li class="listitem"><p>Derivation attributes can now reference the outputs of the
+ derivation using the <code class="function">placeholder</code> builtin
+ function. For example, the attribute
+
+</p><pre class="programlisting">
+configureFlags = "--prefix=${placeholder "out"} --includedir=${placeholder "dev"}";
+</pre><p>
+
+ will cause the <code class="envar">configureFlags</code> environment variable
+ to contain the actual store paths corresponding to the
+ <code class="literal">out</code> and <code class="literal">dev</code> outputs.</p></li></ul></div><p>
+
+</p><p>The following builtin functions are new or extended:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="function"><a class="function" href="https://github.com/NixOS/nix/commit/38539b943a060d9cdfc24d6e5d997c0885b8aa2f" target="_top">builtins.fetchGit</a></code>
+ allows Git repositories to be fetched at evaluation time. Thus it
+ differs from the <code class="function">fetchgit</code> 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.
+
+ </p><pre class="programlisting">imports = [ (builtins.fetchGit https://github.com/edolstra/dwarffs + "/module.nix") ];</pre><p>
+
+ </p></li><li class="listitem"><p>Similarly, <code class="function">builtins.fetchMercurial</code>
+ allows you to fetch Mercurial repositories.</p></li><li class="listitem"><p><code class="function">builtins.path</code> generalises
+ <code class="function">builtins.filterSource</code> and path literals
+ (e.g. <code class="literal">./foo</code>). It allows specifying a store path
+ name that differs from the source path name
+ (e.g. <code class="literal">builtins.path { path = ./foo; name = "bar";
+ }</code>) and also supports filtering out unwanted
+ files.</p></li><li class="listitem"><p><code class="function">builtins.fetchurl</code> and
+ <code class="function">builtins.fetchTarball</code> now support
+ <code class="varname">sha256</code> and <code class="varname">name</code>
+ attributes.</p></li><li class="listitem"><p><code class="function"><a class="function" href="https://github.com/NixOS/nix/commit/b8867a0239b1930a16f9ef3f7f3e864b01416dff" target="_top">builtins.split</a></code>
+ splits a string using a POSIX extended regular expression as the
+ separator.</p></li><li class="listitem"><p><code class="function"><a class="function" href="https://github.com/NixOS/nix/commit/26d92017d3b36cff940dcb7d1611c42232edb81a" target="_top">builtins.partition</a></code>
+ partitions the elements of a list into two lists, depending on a
+ Boolean predicate.</p></li><li class="listitem"><p><code class="literal">&lt;nix/fetchurl.nix&gt;</code> now uses the
+ content-addressable tarball cache at
+ <code class="uri">http://tarballs.nixos.org/</code>, just like
+ <code class="function">fetchurl</code> in
+ Nixpkgs. (f2682e6e18a76ecbfb8a12c17e3a0ca15c084197)</p></li><li class="listitem"><p>In restricted and pure evaluation mode, builtin functions
+ that download from the network (such as
+ <code class="function">fetchGit</code>) are permitted to fetch underneath a
+ list of URI prefixes specified in the option
+ <code class="option">allowed-uris</code>.</p></li></ul></div><p>
+
+</p><p>The Nix build environment has the following changes:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Values such as Booleans, integers, (nested) lists and
+ attribute sets can <a class="link" href="https://github.com/NixOS/nix/commit/6de33a9c675b187437a2e1abbcb290981a89ecb1" target="_top">now</a>
+ be passed to builders in a non-lossy way. If the special attribute
+ <code class="varname">__structuredAttrs</code> is set to
+ <code class="literal">true</code>, the other derivation attributes are
+ serialised in JSON format and made available to the builder via
+ the file <code class="envar">.attrs.json</code> in the builder’s temporary
+ directory. This obviates the need for
+ <code class="varname">passAsFile</code> since JSON files have no size
+ restrictions, unlike process environments.</p><p><a class="link" href="https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699" target="_top">As
+ a convenience to Bash builders</a>, Nix writes a script named
+ <code class="envar">.attrs.sh</code> 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 <code class="literal">hardening.format =
+ true</code> ends up as the Bash associative array element
+ <code class="literal">${hardening[format]}</code>.</p></li><li class="listitem"><p>Builders can <a class="link" href="https://github.com/NixOS/nix/commit/88e6bb76de5564b3217be9688677d1c89101b2a3" target="_top">now</a>
+ communicate what build phase they are in by writing messages to
+ the file descriptor specified in <code class="envar">NIX_LOG_FD</code>. The
+ current phase is shown by the <span class="command"><strong>nix</strong></span> progress
+ indicator.
+ </p></li><li class="listitem"><p>In Linux sandbox builds, we <a class="link" href="https://github.com/NixOS/nix/commit/a2d92bb20e82a0957067ede60e91fab256948b41" target="_top">now</a>
+ provide a default <code class="filename">/bin/sh</code> (namely
+ <code class="filename">ash</code> from BusyBox).</p></li><li class="listitem"><p>In structured attribute mode,
+ <code class="varname">exportReferencesGraph</code> <a class="link" href="https://github.com/NixOS/nix/commit/c2b0d8749f7e77afc1c4b3e8dd36b7ee9720af4a" target="_top">exports</a>
+ 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.</p></li><li class="listitem"><p>Builds are <a class="link" href="https://github.com/NixOS/nix/commit/21948deed99a3295e4d5666e027a6ca42dc00b40" target="_top">now</a>
+ 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.</p></li><li class="listitem"><p>The <code class="option">sandbox-paths</code> configuration
+ option can now specify optional paths by appending a
+ <code class="literal">?</code>, e.g. <code class="literal">/dev/nvidiactl?</code> will
+ bind-mount <code class="varname">/dev/nvidiactl</code> only if it
+ exists.</p></li><li class="listitem"><p>On Linux, builds are now executed in a user
+ namespace with UID 1000 and GID 100.</p></li></ul></div><p>
+
+</p><p>A number of significant internal changes were made:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>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,
+ <code class="literal">nix-perl</code>.</p></li><li class="listitem"><p>All <code class="classname">Store</code> classes are now
+ thread-safe. <code class="classname">RemoteStore</code> supports multiple
+ concurrent connections to the daemon. This is primarily useful in
+ multi-threaded programs such as
+ <span class="command"><strong>hydra-queue-runner</strong></span>.</p></li></ul></div><p>
+
+</p><p>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.
+</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.11.10"></a>C.5. Release 1.11.10 (2017-06-12)</h2></div></div></div><p>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 <code class="literal">nixbld</code>
+user. Such a binary could then be used by an attacker to assume a
+<code class="literal">nixbld</code> identity and interfere with subsequent
+builds running under the same UID.</p><p>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.</p><p>Thanks go to Linus Heckemann for discovering and reporting this
+bug.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.11"></a>C.6. Release 1.11 (2016-01-19)</h2></div></div></div><p>This is primarily a bug fix release. It also has a number of new
+features:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="command"><strong>nix-prefetch-url</strong></span> can now download URLs
+ specified in a Nix expression. For example,
+
+</p><pre class="screen">
+$ nix-prefetch-url -A hello.src
+</pre><p>
+
+ will prefetch the file specified by the
+ <code class="function">fetchurl</code> call in the attribute
+ <code class="literal">hello.src</code> from the Nix expression in the
+ current directory, and print the cryptographic hash of the
+ resulting file on stdout. This differs from <code class="literal">nix-build -A
+ hello.src</code> in that it doesn't verify the hash, and is
+ thus useful when you’re updating a Nix expression.</p><p>You can also prefetch the result of functions that unpack a
+ tarball, such as <code class="function">fetchFromGitHub</code>. For example:
+
+</p><pre class="screen">
+$ nix-prefetch-url --unpack https://github.com/NixOS/patchelf/archive/0.8.tar.gz
+</pre><p>
+
+ or from a Nix expression:
+
+</p><pre class="screen">
+$ nix-prefetch-url -A nix-repl.src
+</pre><p>
+
+ </p></li><li class="listitem"><p>The builtin function
+ <code class="function">&lt;nix/fetchurl.nix&gt;</code> 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 <span class="command"><strong>xz</strong></span>.</p></li><li class="listitem"><p>Nix now supports SHA-512 hashes for verifying fixed-output
+ derivations, and in <code class="function">builtins.hashString</code>.</p></li><li class="listitem"><p>
+ The new flag <code class="option">--option build-repeat
+ <em class="replaceable"><code>N</code></em></code> will cause every build to
+ be executed <em class="replaceable"><code>N</code></em>+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
+ <code class="option">--check</code> option to repeat a previously succeeded
+ build. However, with <code class="option">--check</code>, 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.)
+ </p></li><li class="listitem"><p>
+ The options <code class="option">--check</code> and <code class="option">--option
+ build-repeat <em class="replaceable"><code>N</code></em></code>, if they
+ detect a difference between two runs of the same derivation and
+ <code class="option">-K</code> is given, will make the output of the other
+ run available under
+ <code class="filename"><em class="replaceable"><code>store-path</code></em>-check</code>. This
+ makes it easier to investigate the non-determinism using tools
+ like <span class="command"><strong>diffoscope</strong></span>, e.g.,
+
+</p><pre class="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
+…
+</pre><p>
+
+ </p></li><li class="listitem"><p>Improved FreeBSD support.</p></li><li class="listitem"><p><span class="command"><strong>nix-env -qa --xml --meta</strong></span> now prints
+ license information.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>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.
+ </p></li></ul></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.10"></a>C.7. Release 1.10 (2015-09-03)</h2></div></div></div><p>This is primarily a bug fix release. It also has a number of new
+features:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A number of builtin functions have been added to reduce
+ Nixpkgs/NixOS evaluation time and memory consumption:
+ <code class="function">all</code>,
+ <code class="function">any</code>,
+ <code class="function">concatStringsSep</code>,
+ <code class="function">foldl’</code>,
+ <code class="function">genList</code>,
+ <code class="function">replaceStrings</code>,
+ <code class="function">sort</code>.
+ </p></li><li class="listitem"><p>The garbage collector is more robust when the disk is full.</p></li><li class="listitem"><p>Nix supports a new API for building derivations that doesn’t
+ require a <code class="literal">.drv</code> 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.</p></li><li class="listitem"><p>The function <code class="literal">&lt;nix/fetchurl.nix&gt;</code> now
+ uses a <span class="emphasis"><em>builtin</em></span> 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.</p></li><li class="listitem"><p><code class="option">--version -v</code> now prints some configuration
+ information, in particular what compile-time optional features are
+ enabled, and the paths of various directories.</p></li><li class="listitem"><p>Build users have their supplementary groups set correctly.</p></li></ul></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.9"></a>C.8. Release 1.9 (2015-06-12)</h2></div></div></div><p>In addition to the usual bug fixes, this release has the
+following new features:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Signed binary cache support. You can enable signature
+ checking by adding the following to <code class="filename">nix.conf</code>:
+
+</p><pre class="programlisting">
+signed-binary-caches = *
+binary-cache-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
+</pre><p>
+
+ This will prevent Nix from downloading any binary from the cache
+ that is not signed by one of the keys listed in
+ <code class="option">binary-cache-public-keys</code>.</p><p>Signature checking is only supported if you built Nix with
+ the <code class="literal">libsodium</code> package.</p><p>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.</p></li><li class="listitem"><p>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:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>In <span class="command"><strong>nix-env</strong></span>:
+
+</p><pre class="screen">
+$ nix-env -f https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox
+</pre><p>
+
+ This installs Firefox from the latest tested and built revision
+ of the NixOS 14.12 channel.</p></li><li class="listitem"><p>In <span class="command"><strong>nix-build</strong></span> and
+ <span class="command"><strong>nix-shell</strong></span>:
+
+</p><pre class="screen">
+$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello
+</pre><p>
+
+ This builds GNU Hello from the latest revision of the Nixpkgs
+ master branch.</p></li><li class="listitem"><p>In the Nix search path (as specified via
+ <code class="envar">NIX_PATH</code> or <code class="option">-I</code>). For example, to
+ start a shell containing the Pan package from a specific version
+ of Nixpkgs:
+
+</p><pre class="screen">
+$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz
+</pre><p>
+
+ </p></li><li class="listitem"><p>In <span class="command"><strong>nixos-rebuild</strong></span> (on NixOS):
+
+</p><pre class="screen">
+$ nixos-rebuild test -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-unstable.tar.gz
+</pre><p>
+
+ </p></li><li class="listitem"><p>In Nix expressions, via the new builtin function <code class="function">fetchTarball</code>:
+
+</p><pre class="programlisting">
+with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {}; …
+</pre><p>
+
+ (This is not allowed in restricted mode.)</p></li></ul></div></li><li class="listitem"><p><span class="command"><strong>nix-shell</strong></span> improvements:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><span class="command"><strong>nix-shell</strong></span> now has a flag
+ <code class="option">--run</code> to execute a command in the
+ <span class="command"><strong>nix-shell</strong></span> environment,
+ e.g. <code class="literal">nix-shell --run make</code>. This is like
+ the existing <code class="option">--command</code> flag, except that it
+ uses a non-interactive shell (ensuring that hitting Ctrl-C won’t
+ drop you into the child shell).</p></li><li class="listitem"><p><span class="command"><strong>nix-shell</strong></span> can now be used as
+ a <code class="literal">#!</code>-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:
+
+</p><pre class="programlisting">
+#! /usr/bin/env nix-shell
+#! nix-shell -i runghc -p haskellPackages.ghc haskellPackages.HTTP
+
+import Network.HTTP
+
+main = do
+ resp &lt;- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/")
+ body &lt;- getResponseBody resp
+ print (take 100 body)
+</pre><p>
+
+ Of course, the dependencies are cached in the Nix store, so the
+ second invocation of this script will be much
+ faster.</p></li></ul></div></li><li class="listitem"><p>Chroot improvements:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Chroot builds are now supported on Mac OS X
+ (using its sandbox mechanism).</p></li><li class="listitem"><p>If chroots are enabled, they are now used for
+ all derivations, including fixed-output derivations (such as
+ <code class="function">fetchurl</code>). 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
+ <code class="option">build-use-chroot</code> to
+ <code class="literal">relaxed</code>.</p></li><li class="listitem"><p>On Linux, if chroots are enabled, builds are
+ performed in a private PID namespace once again. (This
+ functionality was lost in Nix 1.8.)</p></li><li class="listitem"><p>Store paths listed in
+ <code class="option">build-chroot-dirs</code> are now automatically
+ expanded to their closure. For instance, if you want
+ <code class="filename">/nix/store/…-bash/bin/sh</code> mounted in your
+ chroot as <code class="filename">/bin/sh</code>, you only need to say
+ <code class="literal">build-chroot-dirs =
+ /bin/sh=/nix/store/…-bash/bin/sh</code>; it is no longer
+ necessary to specify the dependencies of Bash.</p></li></ul></div></li><li class="listitem"><p>The new derivation attribute
+ <code class="varname">passAsFile</code> 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 <code class="function">writeTextFile</code> uses
+ this.</p></li><li class="listitem"><p>You can now use <code class="literal">~</code> in Nix file
+ names to refer to your home directory, e.g. <code class="literal">import
+ ~/.nixpkgs/config.nix</code>.</p></li><li class="listitem"><p>Nix has a new option <code class="option">restrict-eval</code>
+ that allows limiting what paths the Nix evaluator has access to. By
+ passing <code class="literal">--option restrict-eval true</code> 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).</p></li><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> now only creates a new
+ “generation” symlink in <code class="filename">/nix/var/nix/profiles</code>
+ if something actually changed.</p></li><li class="listitem"><p>The environment variable <code class="envar">NIX_PAGER</code>
+ can now be set to override <code class="envar">PAGER</code>. You can set it to
+ <code class="literal">cat</code> to disable paging for Nix commands
+ only.</p></li><li class="listitem"><p>Failing <code class="literal">&lt;...&gt;</code>
+ lookups now show position information.</p></li><li class="listitem"><p>Improved Boehm GC use: we disabled scanning for
+ interior pointers, which should reduce the “<code class="literal">Repeated
+ allocation of very large block</code>” warnings and associated
+ retention of memory.</p></li></ul></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.8"></a>C.9. Release 1.8 (2014-12-14)</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Breaking change: to address a race condition, the
+ remote build hook mechanism now uses <span class="command"><strong>nix-store
+ --serve</strong></span> on the remote machine. This requires build slaves
+ to be updated to Nix 1.8.</p></li><li class="listitem"><p>Nix now uses HTTPS instead of HTTP to access the
+ default binary cache,
+ <code class="literal">cache.nixos.org</code>.</p></li><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> selectors are now regular
+ expressions. For instance, you can do
+
+</p><pre class="screen">
+$ nix-env -qa '.*zip.*'
+</pre><p>
+
+ to query all packages with a name containing
+ <code class="literal">zip</code>.</p></li><li class="listitem"><p><span class="command"><strong>nix-store --read-log</strong></span> 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
+
+</p><pre class="programlisting">
+log-servers = http://hydra.nixos.org/log
+</pre><p>
+
+then it will try to get logs from
+<code class="literal">http://hydra.nixos.org/log/<em class="replaceable"><code>base name of the
+store path</code></em></code>. This allows you to do things like:
+
+</p><pre class="screen">
+$ nix-store -l $(which xterm)
+</pre><p>
+
+ and get a log even if <span class="command"><strong>xterm</strong></span> wasn't built
+ locally.</p></li><li class="listitem"><p>New builtin functions:
+ <code class="function">attrValues</code>, <code class="function">deepSeq</code>,
+ <code class="function">fromJSON</code>, <code class="function">readDir</code>,
+ <code class="function">seq</code>.</p></li><li class="listitem"><p><span class="command"><strong>nix-instantiate --eval</strong></span> now has a
+ <code class="option">--json</code> flag to print the resulting value in JSON
+ format.</p></li><li class="listitem"><p><span class="command"><strong>nix-copy-closure</strong></span> now uses
+ <span class="command"><strong>nix-store --serve</strong></span> on the remote side to send or
+ receive closures. This fixes a race condition between
+ <span class="command"><strong>nix-copy-closure</strong></span> and the garbage
+ collector.</p></li><li class="listitem"><p>Derivations can specify the new special attribute
+ <code class="varname">allowedRequisites</code>, which has a similar meaning to
+ <code class="varname">allowedReferences</code>. 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.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>The Nix daemon has new configuration options
+ <code class="option">allowed-users</code> (specifying the users and groups that
+ are allowed to connect to the daemon) and
+ <code class="option">trusted-users</code> (specifying the users and groups that
+ can perform privileged operations like specifying untrusted binary
+ caches).</p></li><li class="listitem"><p>The configuration option
+ <code class="option">build-cores</code> now defaults to the number of available
+ CPU cores.</p></li><li class="listitem"><p>Build users are now used by default when Nix is
+ invoked as root. This prevents builds from accidentally running as
+ root.</p></li><li class="listitem"><p>Nix now includes systemd units and Upstart
+ jobs.</p></li><li class="listitem"><p>Speed improvements to <span class="command"><strong>nix-store
+ --optimise</strong></span>.</p></li><li class="listitem"><p>Language change: the <code class="literal">==</code> operator
+ now ignores string contexts (the “dependencies” of a
+ string).</p></li><li class="listitem"><p>Nix now filters out Nix-specific ANSI escape
+ sequences on standard error. They are supposed to be invisible, but
+ some terminals show them anyway.</p></li><li class="listitem"><p>Various commands now automatically pipe their output
+ into the pager as specified by the <code class="envar">PAGER</code> environment
+ variable.</p></li><li class="listitem"><p>Several improvements to reduce memory consumption in
+ the evaluator.</p></li></ul></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.7"></a>C.10. Release 1.7 (2014-04-11)</h2></div></div></div><p>In addition to the usual bug fixes, this release has the
+following new features:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Antiquotation is now allowed inside of quoted attribute
+ names (e.g. <code class="literal">set."${foo}"</code>). 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
+ <code class="literal">set.${foo}</code>). If an attribute name inside of a
+ set declaration evaluates to <code class="literal">null</code> (e.g.
+ <code class="literal">{ ${null} = false; }</code>), then that attribute is
+ not added to the set.</p></li><li class="listitem"><p>Experimental support for cryptographically signed binary
+ caches. See <a class="link" href="https://github.com/NixOS/nix/commit/0fdf4da0e979f992db75cc17376e455ddc5a96d8" target="_top">the
+ commit for details</a>.</p></li><li class="listitem"><p>An experimental new substituter,
+ <span class="command"><strong>download-via-ssh</strong></span>, that fetches binaries from
+ remote machines via SSH. Specifying the flags <code class="literal">--option
+ use-ssh-substituter true --option ssh-substituter-hosts
+ <em class="replaceable"><code>user@hostname</code></em></code> will cause Nix
+ to download binaries from the specified machine, if it has
+ them.</p></li><li class="listitem"><p><span class="command"><strong>nix-store -r</strong></span> and
+ <span class="command"><strong>nix-build</strong></span> have a new flag,
+ <code class="option">--check</code>, 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:
+
+</p><pre class="screen">
+$ nix-build '&lt;nixpkgs&gt;' -A patchelf
+<em class="replaceable"><code>…</code></em>
+$ nix-build '&lt;nixpkgs&gt;' -A patchelf --check
+<em class="replaceable"><code>…</code></em>
+error: derivation `/nix/store/1ipvxs…-patchelf-0.6' may not be deterministic:
+ hash mismatch in output `/nix/store/4pc1dm…-patchelf-0.6.drv'
+</pre><p>
+
+ </p></li><li class="listitem"><p>The <span class="command"><strong>nix-instantiate</strong></span> flags
+ <code class="option">--eval-only</code> and <code class="option">--parse-only</code>
+ have been renamed to <code class="option">--eval</code> and
+ <code class="option">--parse</code>, respectively.</p></li><li class="listitem"><p><span class="command"><strong>nix-instantiate</strong></span>,
+ <span class="command"><strong>nix-build</strong></span> and <span class="command"><strong>nix-shell</strong></span> now
+ have a flag <code class="option">--expr</code> (or <code class="option">-E</code>) that
+ allows you to specify the expression to be evaluated as a command
+ line argument. For instance, <code class="literal">nix-instantiate --eval -E
+ '1 + 2'</code> will print <code class="literal">3</code>.</p></li><li class="listitem"><p><span class="command"><strong>nix-shell</strong></span> improvements:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>It has a new flag, <code class="option">--packages</code> (or
+ <code class="option">-p</code>), that sets up a build environment
+ containing the specified packages from Nixpkgs. For example,
+ the command
+
+</p><pre class="screen">
+$ nix-shell -p sqlite xorg.libX11 hello
+</pre><p>
+
+ will start a shell in which the given packages are
+ present.</p></li><li class="listitem"><p>It now uses <code class="filename">shell.nix</code> as the
+ default expression, falling back to
+ <code class="filename">default.nix</code> if the former doesn’t
+ exist. This makes it convenient to have a
+ <code class="filename">shell.nix</code> in your project to set up a
+ nice development environment.</p></li><li class="listitem"><p>It evaluates the derivation attribute
+ <code class="varname">shellHook</code>, if set. Since
+ <code class="literal">stdenv</code> does not normally execute this hook,
+ it allows you to do <span class="command"><strong>nix-shell</strong></span>-specific
+ setup.</p></li><li class="listitem"><p>It preserves the user’s timezone setting.</p></li></ul></div></li><li class="listitem"><p>In chroots, Nix now sets up a <code class="filename">/dev</code>
+ containing only a minimal set of devices (such as
+ <code class="filename">/dev/null</code>). Note that it only does this if
+ you <span class="emphasis"><em>don’t</em></span> have <code class="filename">/dev</code>
+ listed in your <code class="option">build-chroot-dirs</code> setting;
+ otherwise, it will bind-mount the <code class="literal">/dev</code> from
+ outside the chroot.</p><p>Similarly, if you don’t have <code class="filename">/dev/pts</code> listed
+ in <code class="option">build-chroot-dirs</code>, Nix will mount a private
+ <code class="literal">devpts</code> filesystem on the chroot’s
+ <code class="filename">/dev/pts</code>.</p></li><li class="listitem"><p>New built-in function: <code class="function">builtins.toJSON</code>,
+ which returns a JSON representation of a value.</p></li><li class="listitem"><p><span class="command"><strong>nix-env -q</strong></span> has a new flag
+ <code class="option">--json</code> to print a JSON representation of the
+ installed or available packages.</p></li><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> now supports meta attributes with
+ more complex values, such as attribute sets.</p></li><li class="listitem"><p>The <code class="option">-A</code> flag now allows attribute names with
+ dots in them, e.g.
+
+</p><pre class="screen">
+$ nix-instantiate --eval '&lt;nixos&gt;' -A 'config.systemd.units."nscd.service".text'
+</pre><p>
+
+ </p></li><li class="listitem"><p>The <code class="option">--max-freed</code> option to
+ <span class="command"><strong>nix-store --gc</strong></span> now accepts a unit
+ specifier. For example, <code class="literal">nix-store --gc --max-freed
+ 1G</code> will free up to 1 gigabyte of disk space.</p></li><li class="listitem"><p><span class="command"><strong>nix-collect-garbage</strong></span> has a new flag
+ <code class="option">--delete-older-than</code>
+ <em class="replaceable"><code>N</code></em><code class="literal">d</code>, which deletes
+ all user environment generations older than
+ <em class="replaceable"><code>N</code></em> days. Likewise, <span class="command"><strong>nix-env
+ --delete-generations</strong></span> accepts a
+ <em class="replaceable"><code>N</code></em><code class="literal">d</code> age limit.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>There is a new symbol <code class="literal">__curPos</code> that
+ expands to an attribute set containing its file name and line and
+ column numbers, e.g. <code class="literal">{ file = "foo.nix"; line = 10;
+ column = 5; }</code>. There also is a new builtin function,
+ <code class="varname">unsafeGetAttrPos</code>, that returns the position of
+ an attribute. This is used by Nixpkgs to provide location
+ information in error messages, e.g.
+
+</p><pre class="screen">
+$ nix-build '&lt;nixpkgs&gt;' -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’
+</pre><p>
+
+ </p></li><li class="listitem"><p>The garbage collector is now more concurrent with other Nix
+ processes because it releases certain locks earlier.</p></li><li class="listitem"><p>The binary tarball installer has been improved. You can now
+ install Nix by running:
+
+</p><pre class="screen">
+$ bash &lt;(curl https://nixos.org/nix/install)
+</pre><p>
+
+ </p></li><li class="listitem"><p>More evaluation errors include position information. For
+ instance, selecting a missing attribute will print something like
+
+</p><pre class="screen">
+error: attribute `nixUnstabl' missing, at /etc/nixos/configurations/misc/eelco/mandark.nix:216:15
+</pre><p>
+
+ </p></li><li class="listitem"><p>The command <span class="command"><strong>nix-setuid-helper</strong></span> is
+ gone.</p></li><li class="listitem"><p>Nix no longer uses Automake, but instead has a
+ non-recursive, GNU Make-based build system.</p></li><li class="listitem"><p>All installed libraries now have the prefix
+ <code class="literal">libnix</code>. In particular, this gets rid of
+ <code class="literal">libutil</code>, which could clash with libraries with
+ the same name from other packages.</p></li><li class="listitem"><p>Nix now requires a compiler that supports C++11.</p></li></ul></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.6.1"></a>C.11. Release 1.6.1 (2013-10-28)</h2></div></div></div><p>This is primarily a bug fix release. Changes of interest
+are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Nix 1.6 accidentally changed the semantics of antiquoted
+ paths in strings, such as <code class="literal">"${/foo}/bar"</code>. This
+ release reverts to the Nix 1.5.3 behaviour.</p></li><li class="listitem"><p>Previously, Nix optimised expressions such as
+ <code class="literal">"${<em class="replaceable"><code>expr</code></em>}"</code> to
+ <em class="replaceable"><code>expr</code></em>. Thus it neither checked whether
+ <em class="replaceable"><code>expr</code></em> could be coerced to a string, nor
+ applied such coercions. This meant that
+ <code class="literal">"${123}"</code> evaluatued to <code class="literal">123</code>,
+ and <code class="literal">"${./foo}"</code> evaluated to
+ <code class="literal">./foo</code> (even though
+ <code class="literal">"${./foo} "</code> evaluates to
+ <code class="literal">"/nix/store/<em class="replaceable"><code>hash</code></em>-foo "</code>).
+ Nix now checks the type of antiquoted expressions and
+ applies coercions.</p></li><li class="listitem"><p>Nix now shows the exact position of undefined variables. In
+ particular, undefined variable errors in a <code class="literal">with</code>
+ previously didn't show <span class="emphasis"><em>any</em></span> position
+ information, so this makes it a lot easier to fix such
+ errors.</p></li><li class="listitem"><p>Undefined variables are now treated consistently.
+ Previously, the <code class="function">tryEval</code> function would catch
+ undefined variables inside a <code class="literal">with</code> but not
+ outside. Now <code class="function">tryEval</code> never catches undefined
+ variables.</p></li><li class="listitem"><p>Bash completion in <span class="command"><strong>nix-shell</strong></span> now works
+ correctly.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>New built-in function: <code class="function">builtins.typeOf</code>,
+ which returns the type of its argument as a string.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.6.0"></a>C.12. Release 1.6 (2013-09-10)</h2></div></div></div><p>In addition to the usual bug fixes, this release has several new
+features:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The command <span class="command"><strong>nix-build --run-env</strong></span> has been
+ renamed to <span class="command"><strong>nix-shell</strong></span>.</p></li><li class="listitem"><p><span class="command"><strong>nix-shell</strong></span> now sources
+ <code class="filename">$stdenv/setup</code> <span class="emphasis"><em>inside</em></span> the
+ interactive shell, rather than in a parent shell. This ensures
+ that shell functions defined by <code class="literal">stdenv</code> can be
+ used in the interactive shell.</p></li><li class="listitem"><p><span class="command"><strong>nix-shell</strong></span> has a new flag
+ <code class="option">--pure</code> to clear the environment, so you get an
+ environment that more closely corresponds to the “real” Nix build.
+ </p></li><li class="listitem"><p><span class="command"><strong>nix-shell</strong></span> now sets the shell prompt
+ (<code class="envar">PS1</code>) to ensure that Nix shells are distinguishable
+ from your regular shells.</p></li><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> no longer requires a
+ <code class="literal">*</code> argument to match all packages, so
+ <code class="literal">nix-env -qa</code> is equivalent to <code class="literal">nix-env
+ -qa '*'</code>.</p></li><li class="listitem"><p><span class="command"><strong>nix-env -i</strong></span> has a new flag
+ <code class="option">--remove-all</code> (<code class="option">-r</code>) to remove all
+ previous packages from the profile. This makes it easier to do
+ declarative package management similar to NixOS’s
+ <code class="option">environment.systemPackages</code>. For instance, if you
+ have a specification <code class="filename">my-packages.nix</code> like this:
+
+</p><pre class="programlisting">
+with import &lt;nixpkgs&gt; {};
+[ thunderbird
+ geeqie
+ ...
+]
+</pre><p>
+
+ then after any change to this file, you can run:
+
+</p><pre class="screen">
+$ nix-env -f my-packages.nix -ir
+</pre><p>
+
+ to update your profile to match the specification.</p></li><li class="listitem"><p>The ‘<code class="literal">with</code>’ 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:
+
+</p><pre class="programlisting">
+let
+ pkgs = with pkgs; { foo = "old"; bar = foo; } // overrides;
+ overrides = { foo = "new"; };
+in pkgs.bar
+</pre><p>
+
+ This evaluates to <code class="literal">"new"</code>, while previously it
+ gave an “infinite recursion” error.</p></li><li class="listitem"><p>Nix now has proper integer arithmetic operators. For
+ instance, you can write <code class="literal">x + y</code> instead of
+ <code class="literal">builtins.add x y</code>, or <code class="literal">x &lt;
+ y</code> instead of <code class="literal">builtins.lessThan x y</code>.
+ The comparison operators also work on strings.</p></li><li class="listitem"><p>On 64-bit systems, Nix integers are now 64 bits rather than
+ 32 bits.</p></li><li class="listitem"><p>When using the Nix daemon, the <span class="command"><strong>nix-daemon</strong></span>
+ 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.</p></li><li class="listitem"><p>If a stack overflow occurs in the Nix evaluator, you now get
+ a proper error message (rather than “Segmentation fault”) on some
+ systems.</p></li><li class="listitem"><p>In addition to directories, you can now bind-mount regular
+ files in chroots through the (now misnamed) option
+ <code class="option">build-chroot-dirs</code>.</p></li></ul></div><p>This release has contributions from Domen Kožar, Eelco Dolstra,
+Florian Friesdorf, Gergely Risko, Ivan Kozik, Ludovic Courtès and Shea
+Levy.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.5.2"></a>C.13. Release 1.5.2 (2013-05-13)</h2></div></div></div><p>This is primarily a bug fix release. It has contributions from
+Eelco Dolstra, Lluís Batlle i Rossell and Shea Levy.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.5"></a>C.14. Release 1.5 (2013-02-27)</h2></div></div></div><p>This is a brown paper bag release to fix a regression introduced
+by the hard link security fix in 1.4.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.4"></a>C.15. Release 1.4 (2013-02-26)</h2></div></div></div><p>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 (<a class="link" href="https://github.com/NixOS/nix/commit/5526a282b5b44e9296e61e07d7d2626a79141ac4" target="_top">details</a>).</p><p>There are also the following improvements:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>New built-in function:
+ <code class="function">builtins.hashString</code>.</p></li><li class="listitem"><p>Build logs are now stored in
+ <code class="filename">/nix/var/log/nix/drvs/<em class="replaceable"><code>XX</code></em>/</code>,
+ where <em class="replaceable"><code>XX</code></em> is the first two characters of
+ the derivation. This is useful on machines that keep a lot of build
+ logs (such as Hydra servers).</p></li><li class="listitem"><p>The function <code class="function">corepkgs/fetchurl</code>
+ can now make the downloaded file executable. This will allow
+ getting rid of all bootstrap binaries in the Nixpkgs source
+ tree.</p></li><li class="listitem"><p>Language change: The expression <code class="literal">"${./path}
+ ..."</code> now evaluates to a string instead of a
+ path.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.3"></a>C.16. Release 1.3 (2013-01-04)</h2></div></div></div><p>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.)</p><p>This release has contributions from Eelco Dolstra and Stuart
+Pernsteiner.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.2"></a>C.17. Release 1.2 (2012-12-06)</h2></div></div></div><p>This release has the following improvements and changes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Nix has a new binary substituter mechanism: the
+ <span class="emphasis"><em>binary cache</em></span>. 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 <code class="option">binary-caches</code> contains a
+ list of URLs of binary caches. For instance, doing
+</p><pre class="screen">
+$ nix-env -i thunderbird --option binary-caches http://cache.nixos.org
+</pre><p>
+ will install Thunderbird and its dependencies, using the available
+ pre-built binaries in <code class="uri">http://cache.nixos.org</code>.
+ 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 <span class="command"><strong>nix-pull</strong></span> to
+ update your manifest. It’s also more scalable because you don’t
+ need to redownload a giant manifest file every time.
+ </p><p>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
+ (<code class="uri">http://nixos.org/channels</code>) you automatically get the
+ cache <code class="uri">http://cache.nixos.org</code>.</p><p>Binary caches are created using <span class="command"><strong>nix-push</strong></span>.
+ For details on the operation and format of binary caches, see the
+ <span class="command"><strong>nix-push</strong></span> manpage. More details are provided in
+ <a class="link" href="https://nixos.org/nix-dev/2012-September/009826.html" target="_top">this
+ nix-dev posting</a>.</p></li><li class="listitem"><p>Multiple output support should now be usable. A derivation
+ can declare that it wants to produce multiple store paths by
+ saying something like
+</p><pre class="programlisting">
+outputs = [ "lib" "headers" "doc" ];
+</pre><p>
+ This will cause Nix to pass the intended store path of each output
+ to the builder through the environment variables
+ <code class="literal">lib</code>, <code class="literal">headers</code> and
+ <code class="literal">doc</code>. Other packages can refer to a specific
+ output by referring to
+ <code class="literal"><em class="replaceable"><code>pkg</code></em>.<em class="replaceable"><code>output</code></em></code>,
+ e.g.
+</p><pre class="programlisting">
+buildInputs = [ pkg.lib pkg.headers ];
+</pre><p>
+ If you install a package with multiple outputs using
+ <span class="command"><strong>nix-env</strong></span>, each output path will be symlinked
+ into the user environment.</p></li><li class="listitem"><p>Dashes are now valid as part of identifiers and attribute
+ names.</p></li><li class="listitem"><p>The new operation <span class="command"><strong>nix-store --repair-path</strong></span>
+ allows corrupted or missing store paths to be repaired by
+ redownloading them. <span class="command"><strong>nix-store --verify --check-contents
+ --repair</strong></span> will scan and repair all paths in the Nix
+ store. Similarly, <span class="command"><strong>nix-env</strong></span>,
+ <span class="command"><strong>nix-build</strong></span>, <span class="command"><strong>nix-instantiate</strong></span>
+ and <span class="command"><strong>nix-store --realise</strong></span> have a
+ <code class="option">--repair</code> flag to detect and fix bad paths by
+ rebuilding or redownloading them.</p></li><li class="listitem"><p>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:
+
+</p><pre class="screen">
+$ mount --bind /nix/store /nix/store
+$ mount -o remount,ro,bind /nix/store
+</pre><p>
+
+ Nix will automatically make <code class="filename">/nix/store</code>
+ writable as needed (using a private mount namespace) to allow
+ modifications.</p></li><li class="listitem"><p>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 <code class="literal">auto-optimise-store</code> to
+ <code class="literal">true</code> (disabled by default).</p></li><li class="listitem"><p>Nix now supports <span class="command"><strong>xz</strong></span> compression for NARs
+ in addition to <span class="command"><strong>bzip2</strong></span>. It compresses about 30%
+ better on typical archives and decompresses about twice as
+ fast.</p></li><li class="listitem"><p>Basic Nix expression evaluation profiling: setting the
+ environment variable <code class="envar">NIX_COUNT_CALLS</code> to
+ <code class="literal">1</code> will cause Nix to print how many times each
+ primop or function was executed.</p></li><li class="listitem"><p>New primops: <code class="varname">concatLists</code>,
+ <code class="varname">elem</code>, <code class="varname">elemAt</code> and
+ <code class="varname">filter</code>.</p></li><li class="listitem"><p>The command <span class="command"><strong>nix-copy-closure</strong></span> has a new
+ flag <code class="option">--use-substitutes</code> (<code class="option">-s</code>) to
+ download missing paths on the target machine using the substitute
+ mechanism.</p></li><li class="listitem"><p>The command <span class="command"><strong>nix-worker</strong></span> has been renamed
+ to <span class="command"><strong>nix-daemon</strong></span>. Support for running the Nix
+ worker in “slave” mode has been removed.</p></li><li class="listitem"><p>The <code class="option">--help</code> flag of every Nix command now
+ invokes <span class="command"><strong>man</strong></span>.</p></li><li class="listitem"><p>Chroot builds are now supported on systemd machines.</p></li></ul></div><p>This release has contributions from Eelco Dolstra, Florian
+Friesdorf, Mats Erik Andersson and Shea Levy.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.1"></a>C.18. Release 1.1 (2012-07-18)</h2></div></div></div><p>This release has the following improvements:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>On Linux, when doing a chroot build, Nix now uses various
+ namespace features provided by the Linux kernel to improve
+ build isolation. Namely:
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>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.</p></li><li class="listitem"><p>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
+ <span class="emphasis"><em>are</em></span> visible from the outside (though with
+ different PIDs).</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>The UTS namespace ensures that builders see a
+ hostname of <code class="literal">localhost</code> rather than the actual
+ hostname.</p></li><li class="listitem"><p>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.</p></li></ul></div><p>
+ </p></li><li class="listitem"><p>Build logs are now compressed using
+ <span class="command"><strong>bzip2</strong></span>. The command <span class="command"><strong>nix-store
+ -l</strong></span> decompresses them on the fly. This can be disabled
+ by setting the option <code class="literal">build-compress-log</code> to
+ <code class="literal">false</code>.</p></li><li class="listitem"><p>The creation of build logs in
+ <code class="filename">/nix/var/log/nix/drvs</code> can be disabled by
+ setting the new option <code class="literal">build-keep-log</code> to
+ <code class="literal">false</code>. This is useful, for instance, for Hydra
+ build machines.</p></li><li class="listitem"><p>Nix now reserves some space in
+ <code class="filename">/nix/var/nix/db/reserved</code> 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.</p></li><li class="listitem"><p>Added a basic <code class="function">fetchurl</code> function. This
+ is not intended to replace the <code class="function">fetchurl</code> 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
+ <code class="literal">import &lt;nix/fetchurl.nix&gt; { url =
+ <em class="replaceable"><code>url</code></em>; sha256 =
+ "<em class="replaceable"><code>hash</code></em>"; }</code>. (Shea Levy)</p></li><li class="listitem"><p>Improved RPM spec file. (Michel Alexandre Salim)</p></li><li class="listitem"><p>Support for on-demand socket-based activation in the Nix
+ daemon with <span class="command"><strong>systemd</strong></span>.</p></li><li class="listitem"><p>Added a manpage for
+ <span class="citerefentry"><span class="refentrytitle">nix.conf</span>(5)</span>.</p></li><li class="listitem"><p>When using the Nix daemon, the <code class="option">-s</code> flag in
+ <span class="command"><strong>nix-env -qa</strong></span> is now much faster.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-1.0"></a>C.19. Release 1.0 (2012-05-11)</h2></div></div></div><p>There have been numerous improvements and bug fixes since the
+previous release. Here are the most significant:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>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 <code class="option">--enable-gc</code> configure
+ option.</p></li><li class="listitem"><p>Nix now uses SQLite for its database. This is faster and
+ more flexible than the old <span class="emphasis"><em>ad hoc</em></span> format.
+ SQLite is also used to cache the manifests in
+ <code class="filename">/nix/var/nix/manifests</code>, resulting in a
+ significant speedup.</p></li><li class="listitem"><p>Nix now has an search path for expressions. The search path
+ is set using the environment variable <code class="envar">NIX_PATH</code> and
+ the <code class="option">-I</code> 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
+ <code class="literal">&lt;nixpkgs/default.nix&gt;</code> looks for a file
+ <code class="filename">nixpkgs/default.nix</code> relative to every element
+ in the search path.</p></li><li class="listitem"><p>The new command <span class="command"><strong>nix-build --run-env</strong></span>
+ 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.</p></li><li class="listitem"><p>The new command <span class="command"><strong>nix-store --verify-path</strong></span>
+ verifies that the contents of a store path have not
+ changed.</p></li><li class="listitem"><p>The new command <span class="command"><strong>nix-store --print-env</strong></span>
+ prints out the environment of a derivation in a format that can be
+ evaluated by a shell.</p></li><li class="listitem"><p>Attribute names can now be arbitrary strings. For instance,
+ you can write <code class="literal">{ "foo-1.2" = …; "bla bla" = …; }."bla
+ bla"</code>.</p></li><li class="listitem"><p>Attribute selection can now provide a default value using
+ the <code class="literal">or</code> operator. For instance, the expression
+ <code class="literal">x.y.z or e</code> evaluates to the attribute
+ <code class="literal">x.y.z</code> if it exists, and <code class="literal">e</code>
+ otherwise.</p></li><li class="listitem"><p>The right-hand side of the <code class="literal">?</code> operator can
+ now be an attribute path, e.g., <code class="literal">attrs ?
+ a.b.c</code>.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>The Nix store garbage collector is faster and holds the
+ global lock for a shorter amount of time.</p></li><li class="listitem"><p>The option <code class="option">--timeout</code> (corresponding to the
+ configuration setting <code class="literal">build-timeout</code>) 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
+ <code class="literal">--max-silent-time</code> is ineffective.</p></li><li class="listitem"><p>Nix development has moved to GitHub (<a class="link" href="https://github.com/NixOS/nix" target="_top">https://github.com/NixOS/nix</a>).</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-0.16"></a>C.20. Release 0.16 (2010-08-17)</h2></div></div></div><p>This release has the following improvements:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The Nix expression evaluator is now much faster in most
+ cases: typically, <a class="link" href="http://www.mail-archive.com/nix-dev@cs.uu.nl/msg04113.html" target="_top">3
+ to 8 times compared to the old implementation</a>. It also
+ uses less memory. It no longer depends on the ATerm
+ library.</p></li><li class="listitem"><p>
+ Support for configurable parallelism inside builders. Build
+ scripts have always had the ability to perform multiple build
+ actions in parallel (for instance, by running <span class="command"><strong>make -j
+ 2</strong></span>), but this was not desirable because the number of
+ actions to be performed in parallel was not configurable. Nix
+ now has an option <code class="option">--cores
+ <em class="replaceable"><code>N</code></em></code> as well as a configuration
+ setting <code class="varname">build-cores =
+ <em class="replaceable"><code>N</code></em></code> that causes the
+ environment variable <code class="envar">NIX_BUILD_CORES</code> to be set to
+ <em class="replaceable"><code>N</code></em> when the builder is invoked. The
+ builder can use this at its discretion to perform a parallel
+ build, e.g., by calling <span class="command"><strong>make -j
+ <em class="replaceable"><code>N</code></em></strong></span>. In Nixpkgs, this can be
+ enabled on a per-package basis by setting the derivation
+ attribute <code class="varname">enableParallelBuilding</code> to
+ <code class="literal">true</code>.
+ </p></li><li class="listitem"><p><span class="command"><strong>nix-store -q</strong></span> now supports XML output
+ through the <code class="option">--xml</code> flag.</p></li><li class="listitem"><p>Several bug fixes.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-0.15"></a>C.21. Release 0.15 (2010-03-17)</h2></div></div></div><p>This is a bug-fix release. Among other things, it fixes
+building on Mac OS X (Snow Leopard), and improves the contents of
+<code class="filename">/etc/passwd</code> and <code class="filename">/etc/group</code>
+in <code class="literal">chroot</code> builds.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-0.14"></a>C.22. Release 0.14 (2010-02-04)</h2></div></div></div><p>This release has the following improvements:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>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.</p></li><li class="listitem"><p>Added a new operation, <span class="command"><strong>nix-store --query
+ --roots</strong></span>, that shows the garbage collector roots that
+ directly or indirectly point to the given store paths.</p></li><li class="listitem"><p>Removed support for converting Berkeley DB-based Nix
+ databases to the new schema.</p></li><li class="listitem"><p>Removed the <code class="option">--use-atime</code> and
+ <code class="option">--max-atime</code> garbage collector options. They were
+ not very useful in practice.</p></li><li class="listitem"><p>On Windows, Nix now requires Cygwin 1.7.x.</p></li><li class="listitem"><p>A few bug fixes.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-0.13"></a>C.23. Release 0.13 (2009-11-05)</h2></div></div></div><p>This is primarily a bug fix release. It has some new
+features:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Syntactic sugar for writing nested attribute sets. Instead of
+
+</p><pre class="programlisting">
+{
+ foo = {
+ bar = 123;
+ xyzzy = true;
+ };
+ a = { b = { c = "d"; }; };
+}
+</pre><p>
+
+ you can write
+
+</p><pre class="programlisting">
+{
+ foo.bar = 123;
+ foo.xyzzy = true;
+ a.b.c = "d";
+}
+</pre><p>
+
+ This is useful, for instance, in NixOS configuration files.</p></li><li class="listitem"><p>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.)</p></li><li class="listitem"><p>Support <code class="literal">i686-linux</code> builds directly on
+ <code class="literal">x86_64-linux</code> Nix installations. This is
+ implemented using the <code class="function">personality()</code> syscall,
+ which causes <span class="command"><strong>uname</strong></span> to return
+ <code class="literal">i686</code> in child processes.</p></li><li class="listitem"><p>Various improvements to the <code class="literal">chroot</code>
+ support. Building in a <code class="literal">chroot</code> works quite well
+ now.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>Support for large (&gt; 4 GiB) files in NAR archives.</p></li><li class="listitem"><p>Various (performance) improvements to the remote build
+ mechanism.</p></li><li class="listitem"><p>New primops: <code class="varname">builtins.addErrorContext</code> (to
+ add a string to stack traces — useful for debugging),
+ <code class="varname">builtins.isBool</code>,
+ <code class="varname">builtins.isString</code>,
+ <code class="varname">builtins.isInt</code>,
+ <code class="varname">builtins.intersectAttrs</code>.</p></li><li class="listitem"><p>OpenSolaris support (Sander van der Burg).</p></li><li class="listitem"><p>Stack traces are no longer displayed unless the
+ <code class="option">--show-trace</code> option is used.</p></li><li class="listitem"><p>The scoping rules for <code class="literal">inherit
+ (<em class="replaceable"><code>e</code></em>) ...</code> in recursive
+ attribute sets have changed. The expression
+ <em class="replaceable"><code>e</code></em> can now refer to the attributes
+ defined in the containing set.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-0.12"></a>C.24. Release 0.12 (2008-11-20)</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>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.</p><p>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
+ <code class="filename">configure</code> option
+ <code class="option">--disable-old-db-compat</code>.</p><p>After the automatic conversion to the new schema, you can
+ delete the old Berkeley DB files:
+
+ </p><pre class="screen">
+$ cd /nix/var/nix/db
+$ rm __db* log.* derivers references referrers reserved validpaths DB_CONFIG</pre><p>
+
+ The new metadata is stored in the directories
+ <code class="filename">/nix/var/nix/db/info</code> and
+ <code class="filename">/nix/var/nix/db/referrer</code>. 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.</p><p>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 <code class="literal">ext3</code> default nowadays) it
+ usually takes up much less space.</p></li><li class="listitem"><p>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 <code class="literal">sshfs</code>. The environment
+ variable <code class="envar">NIX_OTHER_STORES</code> specifies the locations of
+ the remote Nix directories,
+ e.g. <code class="literal">/mnt/remote-fs/nix</code>.</p></li><li class="listitem"><p>New <span class="command"><strong>nix-store</strong></span> operations
+ <code class="option">--dump-db</code> and <code class="option">--load-db</code> to dump
+ and reload the Nix database.</p></li><li class="listitem"><p>The garbage collector has a number of new options to
+ allow only some of the garbage to be deleted. The option
+ <code class="option">--max-freed <em class="replaceable"><code>N</code></em></code> tells the
+ collector to stop after at least <em class="replaceable"><code>N</code></em> bytes
+ have been deleted. The option <code class="option">--max-links
+ <em class="replaceable"><code>N</code></em></code> tells it to stop after the
+ link count on <code class="filename">/nix/store</code> has dropped below
+ <em class="replaceable"><code>N</code></em>. This is useful for very large Nix
+ stores on filesystems with a 32000 subdirectories limit (like
+ <code class="literal">ext3</code>). The option <code class="option">--use-atime</code>
+ causes store paths to be deleted in order of ascending last access
+ time. This allows non-recently used stuff to be deleted. The
+ option <code class="option">--max-atime <em class="replaceable"><code>time</code></em></code>
+ specifies an upper limit to the last accessed time of paths that may
+ be deleted. For instance,
+
+ </p><pre class="screen">
+ $ nix-store --gc -v --max-atime $(date +%s -d "2 months ago")</pre><p>
+
+ deletes everything that hasn’t been accessed in two months.</p></li><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> 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 <span class="command"><strong>nix-env -i / -u / -e</strong></span>
+ operations on the same profile in parallel. If a
+ <span class="command"><strong>nix-env</strong></span> 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.</p></li><li class="listitem"><p>The option <code class="option">--dry-run</code> is now
+ supported by <span class="command"><strong>nix-store -r</strong></span> and
+ <span class="command"><strong>nix-build</strong></span>.</p></li><li class="listitem"><p>The information previously shown by
+ <code class="option">--dry-run</code> (i.e., which derivations will be built
+ and which paths will be substituted) is now always shown by
+ <span class="command"><strong>nix-env</strong></span>, <span class="command"><strong>nix-store -r</strong></span> and
+ <span class="command"><strong>nix-build</strong></span>. The total download size of
+ substitutable paths is now also shown. For instance, a build will
+ show something like
+
+ </p><pre class="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
+ ...</pre><p>
+
+ </p></li><li class="listitem"><p>Language features:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>@-patterns as in Haskell. For instance, in a
+ function definition
+
+ </p><pre class="programlisting">f = args @ {x, y, z}: <em class="replaceable"><code>...</code></em>;</pre><p>
+
+ <code class="varname">args</code> refers to the argument as a whole, which
+ is further pattern-matched against the attribute set pattern
+ <code class="literal">{x, y, z}</code>.</p></li><li class="listitem"><p>“<code class="literal">...</code>” (ellipsis) patterns.
+ An attribute set pattern can now say <code class="literal">...</code> at
+ the end of the attribute name list to specify that the function
+ takes <span class="emphasis"><em>at least</em></span> the listed attributes, while
+ ignoring additional attributes. For instance,
+
+ </p><pre class="programlisting">{stdenv, fetchurl, fuse, ...}: <em class="replaceable"><code>...</code></em></pre><p>
+
+ defines a function that accepts any attribute set that includes
+ at least the three listed attributes.</p></li><li class="listitem"><p>New primops:
+ <code class="varname">builtins.parseDrvName</code> (split a package name
+ string like <code class="literal">"nix-0.12pre12876"</code> into its name
+ and version components, e.g. <code class="literal">"nix"</code> and
+ <code class="literal">"0.12pre12876"</code>),
+ <code class="varname">builtins.compareVersions</code> (compare two version
+ strings using the same algorithm that <span class="command"><strong>nix-env</strong></span>
+ uses), <code class="varname">builtins.length</code> (efficiently compute
+ the length of a list), <code class="varname">builtins.mul</code> (integer
+ multiplication), <code class="varname">builtins.div</code> (integer
+ division).
+
+ </p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p><span class="command"><strong>nix-prefetch-url</strong></span> now supports
+ <code class="literal">mirror://</code> URLs, provided that the environment
+ variable <code class="envar">NIXPKGS_ALL</code> points at a Nixpkgs
+ tree.</p></li><li class="listitem"><p>Removed the commands
+ <span class="command"><strong>nix-pack-closure</strong></span> and
+ <span class="command"><strong>nix-unpack-closure</strong></span>. You can do almost the same
+ thing but much more efficiently by doing <code class="literal">nix-store --export
+ $(nix-store -qR <em class="replaceable"><code>paths</code></em>) &gt; closure</code> and
+ <code class="literal">nix-store --import &lt;
+ closure</code>.</p></li><li class="listitem"><p>Lots of bug fixes, including a big performance bug in
+ the handling of <code class="literal">with</code>-expressions.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ssec-relnotes-0.11"></a>C.25. Release 0.11 (2007-12-31)</h2></div></div></div><p>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:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>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.</p></li><li class="listitem"><p>The new command <span class="command"><strong>nix-copy-closure</strong></span>
+ 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
+ <span class="command"><strong>ssh</strong></span>.</p></li><li class="listitem"><p>A new kind of string literal: strings between double
+ single-quotes (<code class="literal">''</code>) 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 <code class="literal">''</code> is less common in
+ most languages than <code class="literal">"</code>.</p></li><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> <code class="option">--set</code>
+ modifies the current generation of a profile so that it contains
+ exactly the specified derivation, and nothing else. For example,
+ <code class="literal">nix-env -p /nix/var/nix/profiles/browser --set
+ firefox</code> lets the profile named
+ <code class="filename">browser</code> contain just Firefox.</p></li><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> now maintains
+ meta-information about installed packages in profiles. The
+ meta-information is the contents of the <code class="varname">meta</code>
+ attribute of derivations, such as <code class="varname">description</code> or
+ <code class="varname">homepage</code>. The command <code class="literal">nix-env -q --xml
+ --meta</code> shows all meta-information.</p></li><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> now uses the
+ <code class="varname">meta.priority</code> 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
+ <code class="filename">bin/ld</code>, 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
+ <code class="filename">bin/ld</code> is symlinked in the user
+ environment.</p></li><li class="listitem"><p><span class="command"><strong>nix-env -i / -u</strong></span>: 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.</p><p>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.,
+ <code class="literal">gcc-4.2.0rc1</code>) which should not be installed even
+ though it is the highest version, except when it is explicitly
+ selected (e.g., <code class="literal">nix-env -i
+ gcc-4.2.0rc1</code>).</p></li><li class="listitem"><p><span class="command"><strong>nix-env --set-flag</strong></span> allows meta
+ attributes of installed packages to be modified. There are several
+ attributes that can be usefully modified, because they affect the
+ behaviour of <span class="command"><strong>nix-env</strong></span> or the user environment
+ build script:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><code class="varname">meta.priority</code> can be changed
+ to resolve filename clashes (see above).</p></li><li class="listitem"><p><code class="varname">meta.keep</code> can be set to
+ <code class="literal">true</code> to prevent the package from being
+ upgraded or replaced. Useful if you want to hang on to an older
+ version of a package.</p></li><li class="listitem"><p><code class="varname">meta.active</code> can be set to
+ <code class="literal">false</code> 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 <code class="literal">true</code> to re-enable the
+ package.</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p><span class="command"><strong>nix-env -q</strong></span> now has a flag
+ <code class="option">--prebuilt-only</code> (<code class="option">-b</code>) that causes
+ <span class="command"><strong>nix-env</strong></span> 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 <code class="option">-b</code> flag is also available in
+ <span class="command"><strong>nix-env -i</strong></span> and <span class="command"><strong>nix-env -u</strong></span> to
+ filter out derivations for which no pre-built binary is
+ available.</p></li><li class="listitem"><p>The new option <code class="option">--argstr</code> (in
+ <span class="command"><strong>nix-env</strong></span>, <span class="command"><strong>nix-instantiate</strong></span> and
+ <span class="command"><strong>nix-build</strong></span>) is like <code class="option">--arg</code>, except
+ that the value is a string. For example, <code class="literal">--argstr system
+ i686-linux</code> is equivalent to <code class="literal">--arg system
+ \"i686-linux\"</code> (note that <code class="option">--argstr</code>
+ prevents annoying quoting around shell arguments).</p></li><li class="listitem"><p><span class="command"><strong>nix-store</strong></span> has a new operation
+ <code class="option">--read-log</code> (<code class="option">-l</code>)
+ <em class="parameter"><code>paths</code></em> that shows the build log of the given
+ paths.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>The option <code class="option">--max-silent-time</code>
+ (corresponding to the configuration setting
+ <code class="literal">build-max-silent-time</code>) allows you to set a
+ timeout on builds — if a build produces no output on
+ <code class="literal">stdout</code> or <code class="literal">stderr</code> for the given
+ number of seconds, it is terminated. This is useful for recovering
+ automatically from builds that are stuck in an infinite
+ loop.</p></li><li class="listitem"><p><span class="command"><strong>nix-channel</strong></span>: each subscribed
+ channel is its own attribute in the top-level expression generated
+ for the channel. This allows disambiguation (e.g. <code class="literal">nix-env
+ -i -A nixpkgs_unstable.firefox</code>).</p></li><li class="listitem"><p>The substitutes table has been removed from the
+ database. This makes operations such as <span class="command"><strong>nix-pull</strong></span>
+ and <span class="command"><strong>nix-channel --update</strong></span> much, much
+ faster.</p></li><li class="listitem"><p><span class="command"><strong>nix-pull</strong></span> now supports
+ bzip2-compressed manifests. This speeds up
+ channels.</p></li><li class="listitem"><p><span class="command"><strong>nix-prefetch-url</strong></span> now has a
+ limited form of caching. This is used by
+ <span class="command"><strong>nix-channel</strong></span> to prevent unnecessary downloads when
+ the channel hasn’t changed.</p></li><li class="listitem"><p><span class="command"><strong>nix-prefetch-url</strong></span> now by default
+ computes the SHA-256 hash of the file instead of the MD5 hash. In
+ calls to <code class="function">fetchurl</code> you should pass the
+ <code class="literal">sha256</code> attribute instead of
+ <code class="literal">md5</code>. You can pass either a hexadecimal or a
+ base-32 encoding of the hash.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>The new command <span class="command"><strong>nix-store
+ --optimise</strong></span> 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%.</p></li><li class="listitem"><p><code class="filename">~/.nix-defexpr</code> 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 <span class="command"><strong>nix-env
+ --import</strong></span> (which set the
+ <code class="filename">~/.nix-defexpr</code> symlink) is
+ removed.</p></li><li class="listitem"><p>Derivations can specify the new special attribute
+ <code class="varname">allowedReferences</code> to enforce that the references
+ in the output of a derivation are a subset of a declared set of
+ paths. For example, if <code class="varname">allowedReferences</code> 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.</p></li><li class="listitem"><p>The new attribute
+ <code class="varname">exportReferencesGraph</code> 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.</p></li><li class="listitem"><p>Fixed-output derivations (like
+ <code class="function">fetchurl</code>) can define the attribute
+ <code class="varname">impureEnvVars</code> to allow external environment
+ variables to be passed to builders. This is used in Nixpkgs to
+ support proxy configuration, among other things.</p></li><li class="listitem"><p>Several new built-in functions:
+ <code class="function">builtins.attrNames</code>,
+ <code class="function">builtins.filterSource</code>,
+ <code class="function">builtins.isAttrs</code>,
+ <code class="function">builtins.isFunction</code>,
+ <code class="function">builtins.listToAttrs</code>,
+ <code class="function">builtins.stringLength</code>,
+ <code class="function">builtins.sub</code>,
+ <code class="function">builtins.substring</code>,
+ <code class="function">throw</code>,
+ <code class="function">builtins.trace</code>,
+ <code class="function">builtins.readFile</code>.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ch-relnotes-0.10.1"></a>C.26. Release 0.10.1 (2006-10-11)</h2></div></div></div><p>This release fixes two somewhat obscure bugs that occur when
+evaluating Nix expressions that are stored inside the Nix store
+(<code class="literal">NIX-67</code>). These do not affect most users.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ch-relnotes-0.10"></a>C.27. Release 0.10 (2006-10-06)</h2></div></div></div><div class="note"><h3 class="title">Note</h3><p>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
+
+</p><pre class="screen">
+$ nix-store --clear-substitutes</pre><p>
+
+first.</p></div><div class="warning"><h3 class="title">Warning</h3><p>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.</p></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> usability improvements:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>An option <code class="option">--compare-versions</code>
+ (or <code class="option">-c</code>) has been added to <span class="command"><strong>nix-env
+ --query</strong></span> 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 <code class="literal">nix-env -qc \*</code>.</p></li><li class="listitem"><p><code class="literal">nix-env --query</code> now takes as
+ arguments a list of package names about which to show
+ information, just like <code class="option">--install</code>, etc.: for
+ example, <code class="literal">nix-env -q gcc</code>. Note that to show
+ all derivations, you need to specify
+ <code class="literal">\*</code>.</p></li><li class="listitem"><p><code class="literal">nix-env -i
+ <em class="replaceable"><code>pkgname</code></em></code> will now install
+ the highest available version of
+ <em class="replaceable"><code>pkgname</code></em>, rather than installing all
+ available versions (which would probably give collisions)
+ (<code class="literal">NIX-31</code>).</p></li><li class="listitem"><p><code class="literal">nix-env (-i|-u) --dry-run</code> now
+ shows exactly which missing paths will be built or
+ substituted.</p></li><li class="listitem"><p><code class="literal">nix-env -qa --description</code>
+ shows human-readable descriptions of packages, provided that
+ they have a <code class="literal">meta.description</code> attribute (which
+ most packages in Nixpkgs don’t have yet).</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>New language features:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Reference scanning (which happens after each
+ build) is much faster and takes a constant amount of
+ memory.</p></li><li class="listitem"><p>String interpolation. Expressions like
+
+</p><pre class="programlisting">
+"--with-freetype2-library=" + freetype + "/lib"</pre><p>
+
+ can now be written as
+
+</p><pre class="programlisting">
+"--with-freetype2-library=${freetype}/lib"</pre><p>
+
+ You can write arbitrary expressions within
+ <code class="literal">${<em class="replaceable"><code>...</code></em>}</code>, not just
+ identifiers.</p></li><li class="listitem"><p>Multi-line string literals.</p></li><li class="listitem"><p>String concatenations can now involve
+ derivations, as in the example <code class="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 <code class="literal">freetype</code>. The
+ evaluator now properly propagates this information.
+ Consequently, the subpath operator (<code class="literal">~</code>) has
+ been deprecated.</p></li><li class="listitem"><p>Default values of function arguments can now
+ refer to other function arguments; that is, all arguments are in
+ scope in the default values
+ (<code class="literal">NIX-45</code>).</p></li><li class="listitem"><p>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 <code class="varname">builtins</code>, allowing one to test for
+ the availability of primop in a backwards-compatible
+ way.</p></li><li class="listitem"><p>Real let-expressions: <code class="literal">let x = ...;
+ ... z = ...; in ...</code>.</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>New commands <span class="command"><strong>nix-pack-closure</strong></span> and
+ <span class="command"><strong>nix-unpack-closure</strong></span> 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.</p></li><li class="listitem"><p>XML support:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><code class="literal">nix-env -q --xml</code> prints the
+ installed or available packages in an XML representation for
+ easy processing by other tools.</p></li><li class="listitem"><p><code class="literal">nix-instantiate --eval-only
+ --xml</code> prints an XML representation of the resulting
+ term. (The new flag <code class="option">--strict</code> forces ‘deep’
+ evaluation of the result, i.e., list elements and attributes are
+ evaluated recursively.)</p></li><li class="listitem"><p>In Nix expressions, the primop
+ <code class="function">builtins.toXML</code> converts a term to an XML
+ representation. This is primarily useful for passing structured
+ information to builders.</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>You can now unambiguously specify which derivation to
+ build or install in <span class="command"><strong>nix-env</strong></span>,
+ <span class="command"><strong>nix-instantiate</strong></span> and <span class="command"><strong>nix-build</strong></span>
+ using the <code class="option">--attr</code> / <code class="option">-A</code> flags, which
+ takes an attribute name as argument. (Unlike symbolic package names
+ such as <code class="literal">subversion-1.4.0</code>, attribute names in an
+ attribute set are unique.) For instance, a quick way to perform a
+ test build of a package in Nixpkgs is <code class="literal">nix-build
+ pkgs/top-level/all-packages.nix -A
+ <em class="replaceable"><code>foo</code></em></code>. <code class="literal">nix-env -q
+ --attr</code> shows the attribute names corresponding to each
+ derivation.</p></li><li class="listitem"><p>If the top-level Nix expression used by
+ <span class="command"><strong>nix-env</strong></span>, <span class="command"><strong>nix-instantiate</strong></span> or
+ <span class="command"><strong>nix-build</strong></span> evaluates to a function whose arguments
+ all have default values, the function will be called automatically.
+ Also, the new command-line switch <code class="option">--arg
+ <em class="replaceable"><code>name</code></em>
+ <em class="replaceable"><code>value</code></em></code> can be used to specify
+ function arguments on the command line.</p></li><li class="listitem"><p><code class="literal">nix-install-package --url
+ <em class="replaceable"><code>URL</code></em></code> allows a package to be
+ installed directly from the given URL.</p></li><li class="listitem"><p>Nix now works behind an HTTP proxy server; just set
+ the standard environment variables <code class="envar">http_proxy</code>,
+ <code class="envar">https_proxy</code>, <code class="envar">ftp_proxy</code> or
+ <code class="envar">all_proxy</code> appropriately. Functions such as
+ <code class="function">fetchurl</code> in Nixpkgs also respect these
+ variables.</p></li><li class="listitem"><p><code class="literal">nix-build -o
+ <em class="replaceable"><code>symlink</code></em></code> allows the symlink to
+ the build result to be named something other than
+ <code class="literal">result</code>.</p></li><li class="listitem"><p>Platform support:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Support for 64-bit platforms, provided a <a class="link" href="http://bugzilla.sen.cwi.nl:8080/show_bug.cgi?id=606" target="_top">suitably
+ patched ATerm library</a> is used. Also, files larger than 2
+ GiB are now supported.</p></li><li class="listitem"><p>Added support for Cygwin (Windows,
+ <code class="literal">i686-cygwin</code>), Mac OS X on Intel
+ (<code class="literal">i686-darwin</code>) and Linux on PowerPC
+ (<code class="literal">powerpc-linux</code>).</p></li><li class="listitem"><p>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
+ <code class="literal">build-max-jobs</code> setting.</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>Garbage collector improvements:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>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
+ (<code class="filename">find-runtime-roots.pl</code>) is inherently
+ system-specific, but it should work on Linux and on all
+ platforms that have the <span class="command"><strong>lsof</strong></span>
+ utility.</p></li><li class="listitem"><p><code class="literal">nix-store --gc</code>
+ (a.k.a. <span class="command"><strong>nix-collect-garbage</strong></span>) prints out the
+ number of bytes freed on standard output. <code class="literal">nix-store
+ --gc --print-dead</code> shows how many bytes would be freed
+ by an actual garbage collection.</p></li><li class="listitem"><p><code class="literal">nix-collect-garbage -d</code>
+ removes all old generations of <span class="emphasis"><em>all</em></span> profiles
+ before calling the actual garbage collector (<code class="literal">nix-store
+ --gc</code>). This is an easy way to get rid of all old
+ packages in the Nix store.</p></li><li class="listitem"><p><span class="command"><strong>nix-store</strong></span> now has an
+ operation <code class="option">--delete</code> to delete specific paths
+ from the Nix store. It won’t delete reachable (non-garbage)
+ paths unless <code class="option">--ignore-liveness</code> is
+ specified.</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>Berkeley DB 4.4’s process registry feature is used
+ to recover from crashed Nix processes.</p></li><li class="listitem"><p>A performance issue has been fixed with the
+ <code class="literal">referer</code> table, which stores the inverse of the
+ <code class="literal">references</code> 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)
+ (<code class="literal">NIX-23</code>).</p></li><li class="listitem"><p>Nix now catches the <code class="literal">TERM</code> and
+ <code class="literal">HUP</code> signals in addition to the
+ <code class="literal">INT</code> signal. So you can now do a <code class="literal">killall
+ nix-store</code> without triggering a database
+ recovery.</p></li><li class="listitem"><p><span class="command"><strong>bsdiff</strong></span> updated to version
+ 4.3.</p></li><li class="listitem"><p>Substantial performance improvements in expression
+ evaluation and <code class="literal">nix-env -qa</code>, all thanks to <a class="link" href="http://valgrind.org/" target="_top">Valgrind</a>. Memory use has
+ been reduced by a factor 8 or so. Big speedup by memoisation of
+ path hashing.</p></li><li class="listitem"><p>Lots of bug fixes, notably:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Make sure that the garbage collector can run
+ successfully when the disk is full
+ (<code class="literal">NIX-18</code>).</p></li><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> now locks the profile
+ to prevent races between concurrent <span class="command"><strong>nix-env</strong></span>
+ operations on the same profile
+ (<code class="literal">NIX-7</code>).</p></li><li class="listitem"><p>Removed misleading messages from
+ <code class="literal">nix-env -i</code> (e.g., <code class="literal">installing
+ `foo'</code> followed by <code class="literal">uninstalling
+ `foo'</code>) (<code class="literal">NIX-17</code>).</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>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).</p></li><li class="listitem"><p>Header files are now installed so that external
+ programs can use the Nix libraries.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ch-relnotes-0.9.2"></a>C.28. Release 0.9.2 (2005-09-21)</h2></div></div></div><p>This bug fix release fixes two problems on Mac OS X:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If Nix was linked against statically linked versions
+ of the ATerm or Berkeley DB library, there would be dynamic link
+ errors at runtime.</p></li><li class="listitem"><p><span class="command"><strong>nix-pull</strong></span> and
+ <span class="command"><strong>nix-push</strong></span> intermittently failed due to race
+ conditions involving pipes and child processes with error messages
+ such as <code class="literal">open2: open(GLOB(0x180b2e4), &gt;&amp;=9) failed: Bad
+ file descriptor at /nix/bin/nix-pull line 77</code> (issue
+ <code class="literal">NIX-14</code>).</p></li></ul></div><p>
+
+</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ch-relnotes-0.9.1"></a>C.29. Release 0.9.1 (2005-09-20)</h2></div></div></div><p>This bug fix release addresses a problem with the ATerm library
+when the <code class="option">--with-aterm</code> flag in
+<span class="command"><strong>configure</strong></span> was <span class="emphasis"><em>not</em></span> used.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ch-relnotes-0.9"></a>C.30. Release 0.9 (2005-09-16)</h2></div></div></div><p>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
+
+</p><pre class="screen">
+$ nix-store --clear-substitutes</pre><p>
+
+first.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Unpacking of patch sequences is much faster now
+ since we no longer do redundant unpacking and repacking of
+ intermediate paths.</p></li><li class="listitem"><p>Nix now uses Berkeley DB 4.3.</p></li><li class="listitem"><p>The <code class="function">derivation</code> primitive is
+ lazier. Attributes of dependent derivations can mutually refer to
+ each other (as long as there are no data dependencies on the
+ <code class="varname">outPath</code> and <code class="varname">drvPath</code> attributes
+ computed by <code class="function">derivation</code>).</p><p>For example, the expression <code class="literal">derivation
+ attrs</code> now evaluates to (essentially)
+
+ </p><pre class="programlisting">
+attrs // {
+ type = "derivation";
+ outPath = derivation! attrs;
+ drvPath = derivation! attrs;
+}</pre><p>
+
+ where <code class="function">derivation!</code> is a primop that does the
+ actual derivation instantiation (i.e., it does what
+ <code class="function">derivation</code> used to do). The advantage is that
+ it allows commands such as <span class="command"><strong>nix-env -qa</strong></span> and
+ <span class="command"><strong>nix-env -i</strong></span> to be much faster since they no longer
+ need to instantiate all derivations, just the
+ <code class="varname">name</code> attribute.</p><p>Also, it allows derivations to cyclically reference each
+ other, for example,
+
+ </p><pre class="programlisting">
+webServer = derivation {
+ ...
+ hostName = "svn.cs.uu.nl";
+ services = [svnService];
+};
+
+svnService = derivation {
+ ...
+ hostName = webServer.hostName;
+};</pre><p>
+
+ Previously, this would yield a black hole (infinite recursion).</p></li><li class="listitem"><p><span class="command"><strong>nix-build</strong></span> now defaults to using
+ <code class="filename">./default.nix</code> if no Nix expression is
+ specified.</p></li><li class="listitem"><p><span class="command"><strong>nix-instantiate</strong></span>, when applied to
+ a Nix expression that evaluates to a function, will call the
+ function automatically if all its arguments have
+ defaults.</p></li><li class="listitem"><p>Nix now uses libtool to build dynamic libraries.
+ This reduces the size of executables.</p></li><li class="listitem"><p>A new list concatenation operator
+ <code class="literal">++</code>. For example, <code class="literal">[1 2 3] ++ [4 5
+ 6]</code> evaluates to <code class="literal">[1 2 3 4 5
+ 6]</code>.</p></li><li class="listitem"><p>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 <code class="literal">r3578</code>
+ and <code class="literal">r3580</code>.</p></li><li class="listitem"><p>Various bug fixes and performance
+ improvements.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ch-relnotes-0.8.1"></a>C.31. Release 0.8.1 (2005-04-13)</h2></div></div></div><p>This is a bug fix release.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Patch downloading was broken.</p></li><li class="listitem"><p>The garbage collector would not delete paths that
+ had references from invalid (but substitutable)
+ paths.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ch-relnotes-0.8"></a>C.32. Release 0.8 (2005-04-11)</h2></div></div></div><p>NOTE: the hashing scheme in Nix 0.8 changed (as detailed below).
+As a result, <span class="command"><strong>nix-pull</strong></span> 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.</p><p>If you get the error message
+
+</p><pre class="screen">
+you have an old-style manifest `/nix/var/nix/manifests/[...]'; please
+delete it</pre><p>
+
+you should delete previously downloaded manifests:
+
+</p><pre class="screen">
+$ rm /nix/var/nix/manifests/*</pre><p>
+
+If <span class="command"><strong>nix-channel</strong></span> gives the error message
+
+</p><pre class="screen">
+manifest `http://catamaran.labs.cs.uu.nl/dist/nix/channels/[channel]/MANIFEST'
+is too old (i.e., for Nix &lt;= 0.7)</pre><p>
+
+then you should unsubscribe from the offending channel
+(<span class="command"><strong>nix-channel --remove
+<em class="replaceable"><code>URL</code></em></strong></span>; leave out
+<code class="literal">/MANIFEST</code>), and subscribe to the same URL, with
+<code class="literal">channels</code> replaced by <code class="literal">channels-v3</code>
+(e.g., <a class="link" href="http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable" target="_top">http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable</a>).</p><p>Nix 0.8 has the following improvements:
+
+</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>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.,
+ <code class="filename">/nix/store/csw87wag8bqlqk7ipllbwypb14xainap-atk-1.9.0</code>).
+ (This is actually a 160 bit truncation of a SHA-256
+ hash.)</p></li><li class="listitem"><p>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.</p><p>For instance, given any store path, you can query its closure:
+
+ </p><pre class="screen">
+$ nix-store -qR $(which firefox)
+... lots of paths ...</pre><p>
+
+ Also, Nix now remembers for each store path the derivation that
+ built it (the “deriver”):
+
+ </p><pre class="screen">
+$ nix-store -qR $(which firefox)
+/nix/store/4b0jx7vq80l9aqcnkszxhymsf1ffa5jd-firefox-1.0.1.drv</pre><p>
+
+ So to see the build-time dependencies, you can do
+
+ </p><pre class="screen">
+$ nix-store -qR $(nix-store -qd $(which firefox))</pre><p>
+
+ or, in a nicer format:
+
+ </p><pre class="screen">
+$ nix-store -q --tree $(nix-store -qd $(which firefox))</pre><p>
+
+ </p><p>File system references are also stored in reverse. For
+ instance, you can query all paths that directly or indirectly use a
+ certain Glibc:
+
+ </p><pre class="screen">
+$ nix-store -q --referrers-closure \
+ /nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4</pre><p>
+
+ </p></li><li class="listitem"><p>The concept of fixed-output derivations has been
+ formalised. Previously, functions such as
+ <code class="function">fetchurl</code> 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 <code class="varname">outputHash</code> and
+ <code class="varname">outputHashAlgo</code> 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.)</p></li><li class="listitem"><p>One-click installation :-) It is now possible to
+ install any top-level component in Nixpkgs directly, through the web
+ — see, e.g., <a class="link" href="http://catamaran.labs.cs.uu.nl/dist/nixpkgs-0.8/" target="_top">http://catamaran.labs.cs.uu.nl/dist/nixpkgs-0.8/</a>.
+ All you have to do is associate
+ <code class="filename">/nix/bin/nix-install-package</code> with the MIME type
+ <code class="literal">application/nix-package</code> (or the extension
+ <code class="filename">.nixpkg</code>), 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.</p></li><li class="listitem"><p><span class="command"><strong>nix-store -r
+ <em class="replaceable"><code>PATHS</code></em></strong></span> 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.</p></li><li class="listitem"><p><span class="command"><strong>nix-channel</strong></span> has new operations
+ <code class="option">--list</code> and
+ <code class="option">--remove</code>.</p></li><li class="listitem"><p>New ways of installing components into user
+ environments:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Copy from another user environment:
+
+ </p><pre class="screen">
+$ nix-env -i --from-profile .../other-profile firefox</pre><p>
+
+ </p></li><li class="listitem"><p>Install a store derivation directly (bypassing the
+ Nix expression language entirely):
+
+ </p><pre class="screen">
+$ nix-env -i /nix/store/z58v41v21xd3...-aterm-2.3.1.drv</pre><p>
+
+ (This is used to implement <span class="command"><strong>nix-install-package</strong></span>,
+ which is therefore immune to evolution in the Nix expression
+ language.)</p></li><li class="listitem"><p>Install an already built store path directly:
+
+ </p><pre class="screen">
+$ nix-env -i /nix/store/hsyj5pbn0d9i...-aterm-2.3.1</pre><p>
+
+ </p></li><li class="listitem"><p>Install the result of a Nix expression specified
+ as a command-line argument:
+
+ </p><pre class="screen">
+$ nix-env -f .../i686-linux.nix -i -E 'x: x.firefoxWrapper'</pre><p>
+
+ The difference with the normal installation mode is that
+ <code class="option">-E</code> does not use the <code class="varname">name</code>
+ attributes of derivations. Therefore, this can be used to
+ disambiguate multiple derivations with the same
+ name.</p></li></ul></div></li><li class="listitem"><p>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: <span class="command"><strong>nix-store
+ --verify --check-contents</strong></span>.</p></li><li class="listitem"><p>Implemented a concurrent garbage collector. It is now
+ always safe to run the garbage collector, even if other Nix
+ operations are happening simultaneously.</p><p>However, there can still be GC races if you use
+ <span class="command"><strong>nix-instantiate</strong></span> and <span class="command"><strong>nix-store
+ --realise</strong></span> directly to build things. To prevent races,
+ use the <code class="option">--add-root</code> flag of those commands.</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>Likewise, the substitute mechanism now downloads
+ files in the right order, thus preserving the closure invariant at
+ all times.</p></li><li class="listitem"><p>The result of <span class="command"><strong>nix-build</strong></span> is now
+ registered as a root of the garbage collector. If the
+ <code class="filename">./result</code> link is deleted, the GC root
+ disappears automatically.</p></li><li class="listitem"><p>The behaviour of the garbage collector can be changed
+ globally by setting options in
+ <code class="filename">/nix/etc/nix/nix.conf</code>.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><code class="literal">gc-keep-derivations</code> specifies
+ whether deriver links should be followed when searching for live
+ paths.</p></li><li class="listitem"><p><code class="literal">gc-keep-outputs</code> specifies
+ whether outputs of derivations should be followed when searching
+ for live paths.</p></li><li class="listitem"><p><code class="literal">env-keep-derivations</code>
+ specifies whether user environments should store the paths of
+ derivations when they are added (thus keeping the derivations
+ alive).</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>New <span class="command"><strong>nix-env</strong></span> query flags
+ <code class="option">--drv-path</code> and
+ <code class="option">--out-path</code>.</p></li><li class="listitem"><p><span class="command"><strong>fetchurl</strong></span> allows SHA-1 and SHA-256
+ in addition to MD5. Just specify the attribute
+ <code class="varname">sha1</code> or <code class="varname">sha256</code> instead of
+ <code class="varname">md5</code>.</p></li><li class="listitem"><p>Manual updates.</p></li></ul></div><p>
+
+</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ch-relnotes-0.7"></a>C.33. Release 0.7 (2005-01-12)</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>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 <span class="emphasis"><em>sequence</em></span> of patches to an installed
+ component, Nix will use it. Patches are currently generated
+ automatically between Nixpkgs (pre-)releases.</p></li><li class="listitem"><p>Simplifications to the substitute
+ mechanism.</p></li><li class="listitem"><p>Nix-pull now stores downloaded manifests in
+ <code class="filename">/nix/var/nix/manifests</code>.</p></li><li class="listitem"><p>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.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ch-relnotes-0.6"></a>C.34. Release 0.6 (2004-11-14)</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Rewrite of the normalisation engine.
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Multiple builds can now be performed in parallel
+ (option <code class="option">-j</code>).</p></li><li class="listitem"><p>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.</p></li><li class="listitem"><p>Option <code class="option">--fallback</code> allows
+ recovery from broken substitutes.</p></li><li class="listitem"><p>Option <code class="option">--keep-going</code> causes
+ building of other (unaffected) derivations to continue if one
+ failed.</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>Improvements to the garbage collector (i.e., it
+ should actually work now).</p></li><li class="listitem"><p>Setuid Nix installations allow a Nix store to be
+ shared among multiple users.</p></li><li class="listitem"><p>Substitute registration is much faster
+ now.</p></li><li class="listitem"><p>A utility <span class="command"><strong>nix-build</strong></span> to build a
+ Nix expression and create a symlink to the result int the current
+ directory; useful for testing Nix derivations.</p></li><li class="listitem"><p>Manual updates.</p></li><li class="listitem"><p><span class="command"><strong>nix-env</strong></span> changes:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Derivations for other platforms are filtered out
+ (which can be overridden using
+ <code class="option">--system-filter</code>).</p></li><li class="listitem"><p><code class="option">--install</code> by default now
+ uninstall previous derivations with the same
+ name.</p></li><li class="listitem"><p><code class="option">--upgrade</code> allows upgrading to a
+ specific version.</p></li><li class="listitem"><p>New operation
+ <code class="option">--delete-generations</code> to remove profile
+ generations (necessary for effective garbage
+ collection).</p></li><li class="listitem"><p>Nicer output (sorted,
+ columnised).</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>More sensible verbosity levels all around (builder
+ output is now shown always, unless <code class="option">-Q</code> is
+ given).</p></li><li class="listitem"><p>Nix expression language changes:
+
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>New language construct: <code class="literal">with
+ <em class="replaceable"><code>E1</code></em>;
+ <em class="replaceable"><code>E2</code></em></code> brings all attributes
+ defined in the attribute set <em class="replaceable"><code>E1</code></em> in
+ scope in <em class="replaceable"><code>E2</code></em>.</p></li><li class="listitem"><p>Added a <code class="function">map</code>
+ function.</p></li><li class="listitem"><p>Various new operators (e.g., string
+ concatenation).</p></li></ul></div><p>
+
+ </p></li><li class="listitem"><p>Expression evaluation is much
+ faster.</p></li><li class="listitem"><p>An Emacs mode for editing Nix expressions (with
+ syntax highlighting and indentation) has been
+ added.</p></li><li class="listitem"><p>Many bug fixes.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ch-relnotes-0.5"></a>C.35. Release 0.5 and earlier</h2></div></div></div><p>Please refer to the Subversion commit log messages.</p></div></div></div></body></html> \ No newline at end of file
diff --git a/doc/manual/manual.is-valid b/doc/manual/manual.is-valid
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/doc/manual/manual.is-valid
diff --git a/doc/manual/manual.xmli b/doc/manual/manual.xmli
new file mode 100644
index 000000000..241eef2cc
--- /dev/null
+++ b/doc/manual/manual.xmli
@@ -0,0 +1,20139 @@
+<?xml version="1.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 3.0</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>
+ -->
+
+ <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" xml:base="introduction/introduction.xml">
+
+<title>Introduction</title>
+
+<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 &#x2014; they are built by functions
+that don&#x2019;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&#x2026;</literal> is a unique identifier for the
+package that captures all its dependencies (it&#x2019;s a cryptographic hash
+of the package&#x2019;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 &#x2014; it prevents the &#x201C;DLL hell&#x201D;. Because of the hashing
+scheme, different versions of a package end up in different paths in
+the Nix store, so they don&#x2019;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 &#x201C;destructively&#x201D; 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&#x2019;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&#x2019;t install packages in &#x201C;global&#x201D;
+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&#x2019;t search in per-packages
+directories such as
+<filename>/nix/store/5lbfaxb722zp&#x2026;-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&#x2026;</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&#x2019;s <envar>PATH</envar>. If a user installs a
+package that another user has already installed previously, the
+package won&#x2019;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 &#x2014; which would be bad because a
+program might well crash if it&#x2019;s started during that period.</para>
+
+<para>And since packages aren&#x2019;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&#x2026;
+
+<screen>
+$ nix-env --uninstall firefox
+</screen>
+
+the package isn&#x2019;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&#x2019;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 &#x201C;derivation&#x201D;):
+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&#x2019;s a functional language, it&#x2019;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&#x2019;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&#x2026;-firefox-33.1</literal> from source,
+Nix would first check if the file
+<uri>https://cache.nixos.org/b6gvzjyb2pg0&#x2026;.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&#x2019;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 '&lt;nixpkgs&gt;' -A pan
+</screen>
+
+<para>You&#x2019;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>
+<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 &lt;(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 &#x201C;newer&#x201D; 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>
+
+</part>
+ <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" xml:base="installation/installation.xml">
+
+<title>Installation</title>
+
+<partintro>
+<para>This section describes how to install and configure Nix for first-time use.</para>
+</partintro>
+
+<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>
+<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 &lt;(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 &lt;(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&#x2019;t already exist. If you don&#x2019;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 &lt;(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 &lt;(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 &lt;(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>
+<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>
+
+<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&#x2019;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>
+<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>
+<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 &#x2014; 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>
+
+</chapter>
+<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
+&#x201C;single-user mode&#x201D;, 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 &#x201C;multi-user mode&#x201D;. In
+this model, all users can perform package management operations &#x2014; for
+instance, every user can install software without requiring root
+privileges. Nix ensures that this is secure. For instance, it&#x2019;s not
+possible for one user to overwrite a package used by another user with
+a Trojan horse.</para>
+
+<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&#x2019;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&#x2019;t have to <command>su</command> to <systemitem class="username">root</systemitem> all the time.</para>
+
+</section>
+<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&#x2019;ll want to put that line somewhere in your system&#x2019;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&#x2019; 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>
+
+</chapter>
+<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 &lt;(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>
+
+<!-- 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>
+ <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" xml:base="installation/upgrading.xml">
+
+ <title>Upgrading Nix</title>
+
+ <para>
+ Multi-user Nix users on macOS can upgrade Nix by running:
+ <command>sudo -i sh -c 'nix-channel --update &amp;&amp;
+ nix-env -iA nixpkgs.nix &amp;&amp;
+ launchctl remove org.nixos.nix-daemon &amp;&amp;
+ 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>
+ <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" xml:base="packages/package-management.xml">
+
+<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 &#x201C;user&#x2019;s&#x201D; perspective of the Nix system &#x2014; people
+who want to <emphasis>create</emphasis> packages should consult
+<xref linkend="chap-writing-nix-expressions"/>.</para>
+</partintro>
+
+<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 &#x201C;views&#x201D;
+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 &#x2014;
+where &#x201C;active&#x201D; just means that it appears in a directory
+in the user&#x2019;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&#x2019;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 &#x201C;subscribed&#x201D; 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&#x2019;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
+&#x2026;</screen>
+
+The flag <option>-q</option> specifies a query operation, and
+<option>-a</option> means that you want to show the &#x201C;available&#x201D; (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&#x2019;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
+&#x2026;
+-PS bash-3.0
+--S binutils-2.15
+IPS bison-1.875d
+&#x2026;</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&#x2019;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
+&#x201C;newer&#x201D; 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&#x2019;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&#x2019;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>
+<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&#x2019;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&#x2019;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 &#x2014;
+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&#x2019;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&#x2019;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&#x2019;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&#x2019;t in itself solve the problem, of course; you
+wouldn&#x2019;t want to type
+<filename>/nix/store/0c1p5z4kda11...-user-env/bin/svn</filename>
+either. That&#x2019;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&#x2019;t interfere
+with each other if they don&#x2019;t want to. For example:
+
+<screen>
+$ ls -l /nix/var/nix/profiles/
+...
+lrwxrwxrwx 1 eelco ... default-42-link -&gt; /nix/store/0c1p5z4kda11...-user-env
+lrwxrwxrwx 1 eelco ... default-43-link -&gt; /nix/store/3aw2pdyx2jfc...-user-env
+lrwxrwxrwx 1 eelco ... default -&gt; 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&#x2019;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&#x2019;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&#x2019;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&#x2019;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>
+<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 &#x201C;deleted&#x201D; 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&#x2019;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&#x2019;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>
+
+<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>
+
+</chapter>
+<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&#x2019;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&#x2019;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 &#x201C;subscribe&#x201D; 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 &#x201C;unsubscribe&#x201D; 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&#x2019;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>
+<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>
+
+<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>
+<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&#x2019;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)) &gt; 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 &lt; 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>
+<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&#x2019;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&#x2019;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&#x2026;-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&#x2026;-firefox-34.0.5
+</screen>
+
+</para>
+
+<para>You can use SSH&#x2019;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>
+<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&#x2013;east-1</literal> by
+ default.
+ </para>
+
+ <para>
+ If your bucket is not in <literal>us&#x2013;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&amp;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&amp;scheme=https&amp;endpoint=minio.example.com' nixpkgs.hello</command></para>
+ </example>
+</section>
+</section>
+
+</chapter>
+
+</part>
+ <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" xml:base="expressions/writing-nix-expressions.xml">
+
+<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>
+
+<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>
+
+<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>
+<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>
+<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>
+<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 -&gt; /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>&#x2019;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&#x2019;t the case with, say, <command>make</command>).</para>
+
+</section>
+<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 &#x2014; 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 &#x201C;setup hooks&#x201D; 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>
+
+</chapter>
+<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>
+
+<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" &gt; $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>&lt;nixpkgs&gt;</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>
+<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, &#x2026;, 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 -&gt; db4 != null; <co xml:id="ex-subversion-nix-co-1"/>
+assert httpServer -&gt; httpd != null &amp;&amp; httpd.expat == expat; <co xml:id="ex-subversion-nix-co-2"/>
+assert sslSupport -&gt; openssl != null &amp;&amp; (httpServer -&gt; httpd.openssl == openssl); <co xml:id="ex-subversion-nix-co-3"/>
+assert pythonBindings -&gt; swig != null &amp;&amp; swig.pythonSupport;
+assert javaSwigBindings -&gt; swig != null &amp;&amp; swig.javaSupport;
+assert javahlBindings -&gt; 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>
+<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&#x2019;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>&lt;</literal> <replaceable>e2</replaceable>,
+ </entry>
+ <entry>none</entry>
+ <entry>Arithmetic comparison.</entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry>Less Than or Equal To</entry>
+ <entry>
+ <replaceable>e1</replaceable> <literal>&lt;=</literal> <replaceable>e2</replaceable>
+ </entry>
+ <entry>none</entry>
+ <entry>Arithmetic comparison.</entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry>Greater Than</entry>
+ <entry>
+ <replaceable>e1</replaceable> <literal>&gt;</literal> <replaceable>e2</replaceable>
+ </entry>
+ <entry>none</entry>
+ <entry>Arithmetic comparison.</entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry>Greater Than or Equal To</entry>
+ <entry>
+ <replaceable>e1</replaceable> <literal>&gt;=</literal> <replaceable>e2</replaceable>
+ </entry>
+ <entry>none</entry>
+ <entry>Arithmetic comparison.</entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry>Equality</entry>
+ <entry>
+ <replaceable>e1</replaceable> <literal>==</literal> <replaceable>e2</replaceable>
+ </entry>
+ <entry>none</entry>
+ <entry>Equality.</entry>
+ <entry>11</entry>
+ </row>
+ <row>
+ <entry>Inequality</entry>
+ <entry>
+ <replaceable>e1</replaceable> <literal>!=</literal> <replaceable>e2</replaceable>
+ </entry>
+ <entry>none</entry>
+ <entry>Inequality.</entry>
+ <entry>11</entry>
+ </row>
+ <row>
+ <entry>Logical AND</entry>
+ <entry><replaceable>e1</replaceable> <literal>&amp;&amp;</literal>
+ <replaceable>e2</replaceable></entry>
+ <entry>left</entry>
+ <entry>Logical AND.</entry>
+ <entry>12</entry>
+ </row>
+ <row>
+ <entry>Logical OR</entry>
+ <entry><replaceable>e1</replaceable> <literal>||</literal>
+ <replaceable>e2</replaceable></entry>
+ <entry>left</entry>
+ <entry>Logical OR.</entry>
+ <entry>13</entry>
+ </row>
+ <row>
+ <entry>Logical Implication</entry>
+ <entry><replaceable>e1</replaceable> <literal>-&gt;</literal>
+ <replaceable>e2</replaceable></entry>
+ <entry>none</entry>
+ <entry>Logical implication (equivalent to
+ <literal>!<replaceable>e1</replaceable> ||
+ <replaceable>e2</replaceable></literal>).</entry>
+ <entry>14</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+</section>
+<section 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&#x2019;t
+ need the header files and documentation at runtime, and it doesn&#x2019;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&#x2019;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>
+
+<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&#x2019;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&#x2019;t, the build fails. The hash is simply
+ computed over the contents of that file (so it&#x2019;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&#x2019;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>
+
+</section>
+<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&#x2019;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&#x2019;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 { &#x2026; }
+</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 { &#x2026; }
+</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 &#x2014; 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&#x2019;</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&#x2019; 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&#x2019; (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&#x2019;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&#x2019;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&#x2019;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&#x2019;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&#x2019;t exist or contains an incorrect Nix expression.
+ <function>import</function> implements Nix&#x2019;s module system: you
+ can put any Nix expression (such as a set or a function) in a
+ separate file, and use it from Nix expressions in other
+ files.</para>
+
+ <note><para>Unlike some languages, <function>import</function> is a regular
+ function in Nix. Paths using the angle bracket syntax (e.g., <function>
+ import</function> <replaceable>&lt;foo&gt;</replaceable>) are normal path
+ values (see <xref linkend="ssec-values"/>).</para></note>
+
+ <para>A Nix expression loaded by <function>import</function> must
+ not contain any <emphasis>free variables</emphasis> (identifiers
+ that are not defined in the Nix expression itself and are not
+ built-in). Therefore, it cannot refer to variables that are in
+ scope at the call site. For instance, if you have a calling
+ expression
+
+<programlisting>
+rec {
+ x = 123;
+ y = import ./foo.nix;
+}</programlisting>
+
+ then the following <filename>foo.nix</filename> will give an
+ error:
+
+<programlisting>
+x + 456</programlisting>
+
+ since <varname>x</varname> is not in scope in
+ <filename>foo.nix</filename>. If you want <varname>x</varname>
+ to be available in <filename>foo.nix</filename>, you should pass
+ it as a function argument:
+
+<programlisting>
+rec {
+ x = 123;
+ y = import ./foo.nix x;
+}</programlisting>
+
+ and
+
+<programlisting>
+x: x + 456</programlisting>
+
+ (The function argument doesn&#x2019;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&#x2019;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&#x2019;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
+ &#x201C;inline&#x201D;. 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&#x2019;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&#x2019;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 &#x201C;inline&#x201D; 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>
+
+
+</chapter>
+
+</part>
+ <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" xml:base="advanced-topics/advanced-topics.xml">
+
+<title>Advanced Topics</title>
+
+<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&#x2019;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&#x2019;t or don&#x2019;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 &lt;nixpkgs&gt; { system = "x86_64-darwin"; }; runCommand "foo" {} "uname &gt; $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 &#x201C;speed factor&#x201D;, 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&#x2019;s mandatory features appear in the
+ derivation&#x2019;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>
+<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&#x2019;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>
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="chap-diff-hook" version="5.0">
+
+<title>Verifying Build Reproducibility with <option linkend="conf-diff-hook">diff-hook</option></title>
+
+<subtitle>Check build reproducibility by running builds multiple times
+and comparing their results.</subtitle>
+
+<para>Specify a program with Nix's <xref linkend="conf-diff-hook"/> to
+compare build results when two builds produce different results. Note:
+this hook is only executed if the results are not the same, this hook
+is not used for determining if the results are the same.</para>
+
+<para>For purposes of demonstration, we'll use the following Nix file,
+<filename>deterministic.nix</filename> for testing:</para>
+
+<programlisting>
+let
+ inherit (import &lt;nixpkgs&gt; {}) runCommand;
+in {
+ stable = runCommand "stable" {} ''
+ touch $out
+ '';
+
+ unstable = runCommand "unstable" {} ''
+ echo $RANDOM &gt; $out
+ '';
+}
+</programlisting>
+
+<para>Additionally, <filename>nix.conf</filename> contains:
+
+<programlisting>
+diff-hook = /etc/nix/my-diff-hook
+run-diff-hook = true
+</programlisting>
+
+where <filename>/etc/nix/my-diff-hook</filename> is an executable
+file containing:
+
+<programlisting>
+#!/bin/sh
+exec &gt;&amp;2
+echo "For derivation $3:"
+/run/current-system/sw/bin/diff -r "$1" "$2"
+</programlisting>
+
+</para>
+
+<para>The diff hook is executed by the same user and group who ran the
+build. However, the diff hook does not have write access to the store
+path just built.</para>
+
+<section>
+ <title>
+ Spot-Checking Build Determinism
+ </title>
+
+ <para>
+ Verify a path which already exists in the Nix store by passing
+ <option>--check</option> to the build command.
+ </para>
+
+ <para>If the build passes and is deterministic, Nix will exit with a
+ status code of 0:</para>
+
+ <screen>
+$ nix-build ./deterministic.nix -A stable
+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
+&lt; 8108
+---
+&gt; 30204
+</screen>
+</para>
+
+ <para>Using <option>--check</option> with <option>--keep-failed</option>
+ will cause Nix to keep the second build's output in a special,
+ <literal>.check</literal> path:</para>
+
+ <screen>
+$ nix-build ./deterministic.nix -A unstable --check --keep-failed
+checking outputs of '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'...
+note: keeping build directory '/tmp/nix-build-unstable.drv-0'
+error: derivation '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv' may not be deterministic: output '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable' differs from '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check'
+</screen>
+
+ <para>In particular, notice the
+ <literal>/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check</literal>
+ output. Nix has copied the build results to that directory where you
+ can examine it.</para>
+
+ <note xml:id="check-dirs-are-unregistered">
+ <title><literal>.check</literal> paths are not registered store paths</title>
+
+ <para>Check paths are not protected against garbage collection,
+ and this path will be deleted on the next garbage collection.</para>
+
+ <para>The path is guaranteed to be alive for the duration of
+ <xref linkend="conf-diff-hook"/>'s execution, but may be deleted
+ any time after.</para>
+
+ <para>If the comparison is performed as part of automated tooling,
+ please use the diff-hook or author your tooling to handle the case
+ where the build was not deterministic and also a check path does
+ not exist.</para>
+ </note>
+
+ <para>
+ <option>--check</option> is only usable if the derivation has
+ been built on the system already. If the derivation has not been
+ built Nix will fail with the error:
+ <screen>
+error: some outputs of '/nix/store/hzi1h60z2qf0nb85iwnpvrai3j2w7rr6-unstable.drv' are not valid, so checking is not possible
+</screen>
+
+ Run the build without <option>--check</option>, and then try with
+ <option>--check</option> again.
+ </para>
+</section>
+
+<section>
+ <title>
+ Automatic and Optionally Enforced Determinism Verification
+ </title>
+
+ <para>
+ Automatically verify every build at build time by executing the
+ build multiple times.
+ </para>
+
+ <para>
+ Setting <xref linkend="conf-repeat"/> and
+ <xref linkend="conf-enforce-determinism"/> in your
+ <filename>nix.conf</filename> permits the automated verification
+ of every build Nix performs.
+ </para>
+
+ <para>
+ The following configuration will run each build three times, and
+ will require the build to be deterministic:
+
+ <programlisting>
+enforce-determinism = true
+repeat = 2
+</programlisting>
+ </para>
+
+ <para>
+ Setting <xref linkend="conf-enforce-determinism"/> to false as in
+ the following configuration will run the build multiple times,
+ execute the build hook, but will allow the build to succeed even
+ if it does not build reproducibly:
+
+ <programlisting>
+enforce-determinism = false
+repeat = 1
+</programlisting>
+ </para>
+
+ <para>
+ An example output of this configuration:
+ <screen>
+$ nix-build ./test.nix -A unstable
+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>
+<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 &lt;nixpkgs&gt; {}).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>
+
+</part>
+ <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" xml:base="command-ref/command-ref.xml">
+
+<title>Command Reference</title>
+
+<partintro>
+<para>This section lists commands and options that you can use when you
+work with Nix.</para>
+</partintro>
+
+<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>&#x201C;Errors only&#x201D;: only print messages
+ explaining why the Nix invocation failed.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>1</term>
+ <listitem><para>&#x201C;Informational&#x201D;: print
+ <emphasis>useful</emphasis> messages about what Nix is doing.
+ This is the default.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>2</term>
+ <listitem><para>&#x201C;Talkative&#x201D;: print more informational
+ messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>3</term>
+ <listitem><para>&#x201C;Chatty&#x201D;: print even more
+ informational messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>4</term>
+ <listitem><para>&#x201C;Debug&#x201D;: print debug
+ information.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>5</term>
+ <listitem><para>&#x201C;Vomit&#x201D;: 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>
+<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>&lt;<replaceable>path</replaceable>&gt;</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>&lt;nixpkgs/<replaceable>path</replaceable>&gt;</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 &#x201C;impure&#x201D; builds. Builders
+ sometimes &#x201C;canonicalise&#x201D; 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&#x2019;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&#x2019;re symlinking the Nix store so that you can
+ put it on another file system than the root file system, on Linux
+ you&#x2019;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>
+<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>
+
+<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">3.0</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname>nix-env</refname>
+ <refpurpose>manipulate or query Nix user environments</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+ <cmdsynopsis>
+ <command>nix-env</command>
+ <arg xmlns="http://docbook.org/ns/docbook"><option>--help</option></arg><arg xmlns="http://docbook.org/ns/docbook"><option>--version</option></arg><arg xmlns="http://docbook.org/ns/docbook" rep="repeat">
+ <group choice="req">
+ <arg choice="plain"><option>--verbose</option></arg>
+ <arg choice="plain"><option>-v</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <arg choice="plain"><option>--quiet</option></arg>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--log-format</option>
+ <replaceable>format</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="plain">
+ <arg choice="plain"><option>--no-build-output</option></arg>
+ <arg choice="plain"><option>-Q</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="req">
+ <arg choice="plain"><option>--max-jobs</option></arg>
+ <arg choice="plain"><option>-j</option></arg>
+ </group>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--cores</option>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--max-silent-time</option>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--timeout</option>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="plain">
+ <arg choice="plain"><option>--keep-going</option></arg>
+ <arg choice="plain"><option>-k</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="plain">
+ <arg choice="plain"><option>--keep-failed</option></arg>
+ <arg choice="plain"><option>-K</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook"><option>--fallback</option></arg><arg xmlns="http://docbook.org/ns/docbook"><option>--readonly-mode</option></arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>-I</option>
+ <replaceable>path</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--option</option>
+ <replaceable>name</replaceable>
+ <replaceable>value</replaceable>
+</arg><sbr xmlns="http://docbook.org/ns/docbook"/>
+ <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">
+ <varlistentry xmlns="http://docbook.org/ns/docbook"><term><option>--help</option></term>
+
+ <listitem><para>Prints out a summary of the command syntax and
+ exits.</para></listitem>
+
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><term><option>--version</option></term>
+
+ <listitem><para>Prints out the Nix version number on standard output
+ and exits.</para></listitem>
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><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>&#x201C;Errors only&#x201D;: only print messages
+ explaining why the Nix invocation failed.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>1</term>
+ <listitem><para>&#x201C;Informational&#x201D;: print
+ <emphasis>useful</emphasis> messages about what Nix is doing.
+ This is the default.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>2</term>
+ <listitem><para>&#x201C;Talkative&#x201D;: print more informational
+ messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>3</term>
+ <listitem><para>&#x201C;Chatty&#x201D;: print even more
+ informational messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>4</term>
+ <listitem><para>&#x201C;Debug&#x201D;: print debug
+ information.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>5</term>
+ <listitem><para>&#x201C;Vomit&#x201D;: print vast amounts of debug
+ information.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </listitem>
+
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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>
+
+</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>
+ <arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="req">
+ <arg choice="plain"><option>--prebuilt-only</option></arg>
+ <arg choice="plain"><option>-b</option></arg>
+ </group>
+ </arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="req">
+ <arg choice="plain"><option>--attr</option></arg>
+ <arg choice="plain"><option>-A</option></arg>
+ </group>
+ </arg><arg xmlns="http://docbook.org/ns/docbook"><option>--from-expression</option></arg><arg xmlns="http://docbook.org/ns/docbook"><option>-E</option></arg><arg xmlns="http://docbook.org/ns/docbook"><option>--from-profile</option> <replaceable>path</replaceable></arg>
+ <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 '&lt;nixpkgs&gt;' -iA hello --dry-run
+(dry run; not doing anything)
+installing &#x2018;hello-2.10&#x2019;
+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>
+ <arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="req">
+ <arg choice="plain"><option>--prebuilt-only</option></arg>
+ <arg choice="plain"><option>-b</option></arg>
+ </group>
+ </arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="req">
+ <arg choice="plain"><option>--attr</option></arg>
+ <arg choice="plain"><option>-A</option></arg>
+ </group>
+ </arg><arg xmlns="http://docbook.org/ns/docbook"><option>--from-expression</option></arg><arg xmlns="http://docbook.org/ns/docbook"><option>-E</option></arg><arg xmlns="http://docbook.org/ns/docbook"><option>--from-profile</option> <replaceable>path</replaceable></arg>
+ <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
+ &#x201C;upgrade&#x201D; 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 &#x201C;synchronisation&#x201D; between the installed and available
+ derivations.</para></listitem>
+
+ </varlistentry>
+
+ <varlistentry><term><option>--eq</option></term>
+
+ <listitem><para><emphasis>Only</emphasis> &#x201C;upgrade&#x201D; 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
+ &#x201C;upgrade&#x201D; 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 &lt; 2.3
+2.1 &lt; 2.3
+2.3 = 2.3
+2.5 &gt; 2.3
+3.1 &gt; 2.3
+2.3.1 &gt; 2.3
+2.3.1 &gt; 2.3a
+2.3pre1 &lt; 2.3
+2.3pre3 &lt; 2.3pre12
+2.3a &lt; 2.3c
+2.3pre1 &lt; 2.3c
+2.3pre1 &lt; 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&#x2019;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 &#x201C;disable&#x201D; 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&#x2019;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&#x2019;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>&lt;</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>&gt;</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>&#x2026;</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>&#x2026;</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>&#x2026;</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&#x2019;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 &lt; 1.0.7 <lineannotation>(a more recent version is available)</lineannotation>
+<replaceable>...</replaceable>
+</screen>
+
+</para>
+
+<para>To show all packages with &#x201C;<literal>zip</literal>&#x201D; in the name:
+
+<screen>
+$ nix-env -qa '.*zip.*'
+bzip2-1.0.6
+gzip-1.6
+zip-3.0
+<replaceable>&#x2026;</replaceable>
+</screen>
+
+</para>
+
+<para>To show all packages with &#x201C;<literal>firefox</literal>&#x201D; or
+&#x201C;<literal>chromium</literal>&#x201D; 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>&#x2026;</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 &#x201C;previous&#x201D; 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>
+
+ <varlistentry xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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>&lt;<replaceable>path</replaceable>&gt;</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>&lt;nixpkgs/<replaceable>path</replaceable>&gt;</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 xmlns="http://docbook.org/ns/docbook"><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 &#x201C;impure&#x201D; builds. Builders
+ sometimes &#x201C;canonicalise&#x201D; 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&#x2019;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&#x2019;re symlinking the Nix store so that you can
+ put it on another file system than the root file system, on Linux
+ you&#x2019;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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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>
+
+</refsection>
+
+
+</refentry>
+<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">3.0</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname>nix-build</refname>
+ <refpurpose>build a Nix expression</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+ <cmdsynopsis>
+ <command>nix-build</command>
+ <arg xmlns="http://docbook.org/ns/docbook"><option>--help</option></arg><arg xmlns="http://docbook.org/ns/docbook"><option>--version</option></arg><arg xmlns="http://docbook.org/ns/docbook" rep="repeat">
+ <group choice="req">
+ <arg choice="plain"><option>--verbose</option></arg>
+ <arg choice="plain"><option>-v</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <arg choice="plain"><option>--quiet</option></arg>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--log-format</option>
+ <replaceable>format</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="plain">
+ <arg choice="plain"><option>--no-build-output</option></arg>
+ <arg choice="plain"><option>-Q</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="req">
+ <arg choice="plain"><option>--max-jobs</option></arg>
+ <arg choice="plain"><option>-j</option></arg>
+ </group>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--cores</option>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--max-silent-time</option>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--timeout</option>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="plain">
+ <arg choice="plain"><option>--keep-going</option></arg>
+ <arg choice="plain"><option>-k</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="plain">
+ <arg choice="plain"><option>--keep-failed</option></arg>
+ <arg choice="plain"><option>-K</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook"><option>--fallback</option></arg><arg xmlns="http://docbook.org/ns/docbook"><option>--readonly-mode</option></arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>-I</option>
+ <replaceable>path</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--option</option>
+ <replaceable>name</replaceable>
+ <replaceable>value</replaceable>
+</arg><sbr xmlns="http://docbook.org/ns/docbook"/>
+ <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&#x2019;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">
+ <varlistentry xmlns="http://docbook.org/ns/docbook"><term><option>--help</option></term>
+
+ <listitem><para>Prints out a summary of the command syntax and
+ exits.</para></listitem>
+
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><term><option>--version</option></term>
+
+ <listitem><para>Prints out the Nix version number on standard output
+ and exits.</para></listitem>
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><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>&#x201C;Errors only&#x201D;: only print messages
+ explaining why the Nix invocation failed.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>1</term>
+ <listitem><para>&#x201C;Informational&#x201D;: print
+ <emphasis>useful</emphasis> messages about what Nix is doing.
+ This is the default.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>2</term>
+ <listitem><para>&#x201C;Talkative&#x201D;: print more informational
+ messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>3</term>
+ <listitem><para>&#x201C;Chatty&#x201D;: print even more
+ informational messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>4</term>
+ <listitem><para>&#x201C;Debug&#x201D;: print debug
+ information.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>5</term>
+ <listitem><para>&#x201C;Vomit&#x201D;: print vast amounts of debug
+ information.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </listitem>
+
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-build '&lt;nixpkgs&gt;' -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 -&gt; /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 '&lt;nixpkgs&gt;' -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&#x2019;s also possible to build a specific
+output:
+<screen>
+$ nix-build '&lt;nixpkgs&gt;' -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 &lt;nixpkgs&gt; { }; runCommand "foo" { } "echo bar &gt; $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>
+ <varlistentry xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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>&lt;<replaceable>path</replaceable>&gt;</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>&lt;nixpkgs/<replaceable>path</replaceable>&gt;</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 xmlns="http://docbook.org/ns/docbook"><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 &#x201C;impure&#x201D; builds. Builders
+ sometimes &#x201C;canonicalise&#x201D; 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&#x2019;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&#x2019;re symlinking the Nix store so that you can
+ put it on another file system than the root file system, on Linux
+ you&#x2019;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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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>
+
+</refsection>
+
+
+</refentry>
+<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">3.0</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
+ &#x201C;real&#x201D; 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>&#x2026;</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">
+ <varlistentry xmlns="http://docbook.org/ns/docbook"><term><option>--help</option></term>
+
+ <listitem><para>Prints out a summary of the command syntax and
+ exits.</para></listitem>
+
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><term><option>--version</option></term>
+
+ <listitem><para>Prints out the Nix version number on standard output
+ and exits.</para></listitem>
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><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>&#x201C;Errors only&#x201D;: only print messages
+ explaining why the Nix invocation failed.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>1</term>
+ <listitem><para>&#x201C;Informational&#x201D;: print
+ <emphasis>useful</emphasis> messages about what Nix is doing.
+ This is the default.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>2</term>
+ <listitem><para>&#x201C;Talkative&#x201D;: print more informational
+ messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>3</term>
+ <listitem><para>&#x201C;Chatty&#x201D;: print even more
+ informational messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>4</term>
+ <listitem><para>&#x201C;Debug&#x201D;: print debug
+ information.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>5</term>
+ <listitem><para>&#x201C;Vomit&#x201D;: print vast amounts of debug
+ information.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </listitem>
+
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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>
+
+</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 '&lt;nixpkgs&gt;' -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 '&lt;nixpkgs&gt;' -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 &lt;nixpkgs&gt; { }; 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
+&#x2026; -L/nix/store/j1zg5v&#x2026;-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9&#x2026;-libX11-1.6.1/lib &#x2026;
+</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 &#x201C;real&#x201D; 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-&gt;new(url =&gt; 'http://nixos.org/');
+
+while (my $token = $p-&gt;get_tag("a")) {
+ my $href = $token-&gt;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 &lt;nixpkgs&gt; {};
+
+runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
+</programlisting>
+
+</para>
+
+</refsection>
+
+
+<refsection condition="manpage"><title>Environment variables</title>
+
+<variablelist>
+ <varlistentry xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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>&lt;<replaceable>path</replaceable>&gt;</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>&lt;nixpkgs/<replaceable>path</replaceable>&gt;</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 xmlns="http://docbook.org/ns/docbook"><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 &#x201C;impure&#x201D; builds. Builders
+ sometimes &#x201C;canonicalise&#x201D; 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&#x2019;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&#x2019;re symlinking the Nix store so that you can
+ put it on another file system than the root file system, on Linux
+ you&#x2019;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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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>
+
+</refsection>
+
+
+</refentry>
+<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">3.0</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname>nix-store</refname>
+ <refpurpose>manipulate or query the Nix store</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+ <cmdsynopsis>
+ <command>nix-store</command>
+ <arg xmlns="http://docbook.org/ns/docbook"><option>--help</option></arg><arg xmlns="http://docbook.org/ns/docbook"><option>--version</option></arg><arg xmlns="http://docbook.org/ns/docbook" rep="repeat">
+ <group choice="req">
+ <arg choice="plain"><option>--verbose</option></arg>
+ <arg choice="plain"><option>-v</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <arg choice="plain"><option>--quiet</option></arg>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--log-format</option>
+ <replaceable>format</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="plain">
+ <arg choice="plain"><option>--no-build-output</option></arg>
+ <arg choice="plain"><option>-Q</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="req">
+ <arg choice="plain"><option>--max-jobs</option></arg>
+ <arg choice="plain"><option>-j</option></arg>
+ </group>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--cores</option>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--max-silent-time</option>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--timeout</option>
+ <replaceable>number</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="plain">
+ <arg choice="plain"><option>--keep-going</option></arg>
+ <arg choice="plain"><option>-k</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <group choice="plain">
+ <arg choice="plain"><option>--keep-failed</option></arg>
+ <arg choice="plain"><option>-K</option></arg>
+ </group>
+</arg><arg xmlns="http://docbook.org/ns/docbook"><option>--fallback</option></arg><arg xmlns="http://docbook.org/ns/docbook"><option>--readonly-mode</option></arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>-I</option>
+ <replaceable>path</replaceable>
+</arg><arg xmlns="http://docbook.org/ns/docbook">
+ <option>--option</option>
+ <replaceable>name</replaceable>
+ <replaceable>value</replaceable>
+</arg><sbr xmlns="http://docbook.org/ns/docbook"/>
+ <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... -&gt; /home/eelco/bla/result
+
+$ ls -l /home/eelco/bla/result
+lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -&gt; /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">
+ <varlistentry xmlns="http://docbook.org/ns/docbook"><term><option>--help</option></term>
+
+ <listitem><para>Prints out a summary of the command syntax and
+ exits.</para></listitem>
+
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><term><option>--version</option></term>
+
+ <listitem><para>Prints out the Nix version number on standard output
+ and exits.</para></listitem>
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><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>&#x201C;Errors only&#x201D;: only print messages
+ explaining why the Nix invocation failed.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>1</term>
+ <listitem><para>&#x201C;Informational&#x201D;: print
+ <emphasis>useful</emphasis> messages about what Nix is doing.
+ This is the default.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>2</term>
+ <listitem><para>&#x201C;Talkative&#x201D;: print more informational
+ messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>3</term>
+ <listitem><para>&#x201C;Chatty&#x201D;: print even more
+ informational messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>4</term>
+ <listitem><para>&#x201C;Debug&#x201D;: print debug
+ information.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>5</term>
+ <listitem><para>&#x201C;Vomit&#x201D;: print vast amounts of debug
+ information.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </listitem>
+
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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>
+
+</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 &#x201C;builds&#x201D;
+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&#x2019;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 &#x201C;valid&#x201D; 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 '&lt;nixpkgs&gt;' -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 &lt;&lt;EOF &gt;&gt;/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
+&#x201C;roots&#x201D;, 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 &#x201C;live&#x201D; store paths, which are all the store paths reachable
+ from the roots. Live paths should never be deleted, since that
+ would break consistency &#x2014; 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 &#x201C;dead&#x201D; 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&#x2019;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&amp;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> &#x2014; 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 &gt; 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&#x2019;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
+&#x201C;repair&#x201D; 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'...
+&#x2026;
+</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 &#x201C;equal&#x201D; paths always produce the same NAR archive. For instance,
+directory entries are always sorted so that the actual on-disk order
+doesn&#x2019;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&#x2019;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&#x2019;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>) &gt; out</screen>
+
+To import the whole closure again, run:
+
+<screen>
+$ nix-store --import &lt; 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&#x2019;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 '&lt;nixpkgs&gt;' -A firefox)
+<replaceable>&#x2026;</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&#x2019;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>
+ <varlistentry xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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>&lt;<replaceable>path</replaceable>&gt;</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>&lt;nixpkgs/<replaceable>path</replaceable>&gt;</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 xmlns="http://docbook.org/ns/docbook"><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 &#x201C;impure&#x201D; builds. Builders
+ sometimes &#x201C;canonicalise&#x201D; 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&#x2019;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&#x2019;re symlinking the Nix store so that you can
+ put it on another file system than the root file system, on Linux
+ you&#x2019;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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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>
+
+</refsection>
+
+
+</refentry>
+
+</chapter>
+<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>
+
+<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">3.0</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>&#x2026;]</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 &lt;nixpkgs&gt; {}).lib.version'
+"14.04.527.0e935f1"
+
+$ nix-channel --rollback
+switching from generation 483 to 482
+
+$ nix-instantiate --eval -E '(import &lt;nixpkgs&gt; {}).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&#x2019;s &#x201C;entry point&#x201D;.</para></listitem>
+
+ </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+</refentry>
+<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">3.0</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>
+<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">3.0</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&#x2019;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>
+<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">3.0</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>
+<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">3.0</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&#x2019;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&#x2019;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://&lt;(echo test)
+1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
+$ nix-hash --type sha256 --flat --base32 &lt;(echo test)
+1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
+</screen>
+</para>
+
+<para>Computing hashes:
+
+<screen>
+$ mkdir test
+$ echo "hello" &gt; 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>
+<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">3.0</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&#x2019;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">
+ <varlistentry xmlns="http://docbook.org/ns/docbook"><term><option>--help</option></term>
+
+ <listitem><para>Prints out a summary of the command syntax and
+ exits.</para></listitem>
+
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><term><option>--version</option></term>
+
+ <listitem><para>Prints out the Nix version number on standard output
+ and exits.</para></listitem>
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><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>&#x201C;Errors only&#x201D;: only print messages
+ explaining why the Nix invocation failed.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>1</term>
+ <listitem><para>&#x201C;Informational&#x201D;: print
+ <emphasis>useful</emphasis> messages about what Nix is doing.
+ This is the default.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>2</term>
+ <listitem><para>&#x201C;Talkative&#x201D;: print more informational
+ messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>3</term>
+ <listitem><para>&#x201C;Chatty&#x201D;: print even more
+ informational messages.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>4</term>
+ <listitem><para>&#x201C;Debug&#x201D;: print debug
+ information.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term>5</term>
+ <listitem><para>&#x201C;Vomit&#x201D;: print vast amounts of debug
+ information.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </listitem>
+
+</varlistentry><varlistentry xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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>
+
+</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 &lt;nixpkgs&gt; { }; hello'
+/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
+</screen>
+
+This is equivalent to:
+
+<screen>
+$ nix-instantiate '&lt;nixpkgs&gt;' -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&#x2019;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>
+ <varlistentry xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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>&lt;<replaceable>path</replaceable>&gt;</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>&lt;nixpkgs/<replaceable>path</replaceable>&gt;</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 xmlns="http://docbook.org/ns/docbook"><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 &#x201C;impure&#x201D; builds. Builders
+ sometimes &#x201C;canonicalise&#x201D; 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&#x2019;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&#x2019;re symlinking the Nix store so that you can
+ put it on another file system than the root file system, on Linux
+ you&#x2019;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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook" 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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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 xmlns="http://docbook.org/ns/docbook"><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>
+
+</refsection>
+
+
+</refentry>
+<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">3.0</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&#x2019;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>
+
+</chapter>
+<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>
+
+<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">3.0</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>&#x2019;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.
+ 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 hashed mirror
+ <literal>http://tarballs.example.com/</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.example.com/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
+ &#x201C;sticky&#x201D;: 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&#x2019;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 &#x201C;valid&#x201D; in Nix&#x2019;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&#x2019;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">&#x201C;build users&#x201D;
+ 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 &#x2018;lie&#x2019; 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., &#x2018;universal binaries&#x2019; 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 &#x201C;features&#x201D; 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>
+
+</chapter>
+
+</part>
+ <appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="part-glossary" xml:base="glossary/glossary.xml">
+
+<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 &#x201C;reachable&#x201D; from that store
+ path; that is, it&#x2019;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 &#x201C;active&#x201D; 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>
+ <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>
+ <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" xml:base="release-notes/release-notes.xml">
+
+<title>Nix Release Notes</title>
+
+<!--
+<partintro>
+<para>This section lists the release notes for each stable version of Nix.</para>
+</partintro>
+-->
+
+<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>
+<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 &lt;nix/fetchurl.nix&gt; {
+ url = https://nixos.org/releases/nix/nix-2.1.3/nix-2.1.3.tar.xz;
+ hash = "sha256-XSLa0FjVyADWWhFfkZ2iKTjFDda6mMXjoYMXLRSYQKQ=";
+};
+</programlisting>
+
+ instead of
+
+<programlisting>
+import &lt;nix/fetchurl.nix&gt; {
+ 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>
+<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 &lt;(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&#x17E;ar,
+Doug Beardsley,
+Eelco Dolstra,
+Erik Arvstedt,
+F&#xE9;lix Baylac-Jacqu&#xE9;,
+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>
+<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 &#x201C;copy from other stores&#x201D; 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&#x2026;</replaceable></literal></para>
+ </listitem>
+
+ <listitem>
+ <para>The &#x201C;nested&#x201D; 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 &lt;nixpkgs&gt; {}; 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 (&#x201C;porcelain&#x201D;)
+ 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&#x2019;t work on NixOS, or if it&#x2019;s installed
+ outside of the Nix store.)</para>
+ </listitem>
+
+ <listitem>
+ <para><command>nix verify</command> checks whether store paths
+ are unmodified and/or &#x201C;trusted&#x201D; (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 &#x201C;dev&#x201D; output of
+ <literal>libdrm</literal> in its closure &#x2014; 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 (&#x201C;plumbing&#x201D;) 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 &#x201C;physical&#x201D; location of
+ the Nix store
+ (e.g. <filename>/home/alice/nix/store</filename>) to differ
+ from its &#x201C;logical&#x201D; 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
+ &#x201C;ultimately trusted&#x201D;, but this bit is not propagated when
+ paths are copied between stores.</para>
+ </listitem>
+
+ <listitem>
+ <para>Content-addressable store paths no longer require
+ signatures &#x2014; 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&#x2019;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&#x2019;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&#x2019;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>&#x2019;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>&lt;nix/fetchurl.nix&gt;</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&#x2019;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&#x2019;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&#x2019;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&#xFC;nfst&#xFC;ck,
+Bj&#xF8;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&#x17E;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&#xF6;rg Thalheim,
+Jude Taylor,
+kballou,
+Keshav Kini,
+Kjetil Orbekk,
+Langston Barrett,
+Linus Heckemann,
+Ludovic Court&#xE8;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&#xFC;chen,
+Nikolay Amiantov,
+Ole J&#xF8;rgen Br&#xF8;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&#xED;r &#x10C;un&#xE1;t,
+Will Dietz,
+wmertens,
+Wout Mertens,
+zimbatm and
+Zoran Plesiv&#x10D;ak.
+</para>
+
+</section>
+<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&#x2019;s &#x201C;build user&#x201D; 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 &#x201C;allow all except the creation of setuid/setgid binaries&#x201D;
+profile when regular sandboxing is disabled. On other platforms, the
+&#x201C;build user&#x201D; mechanism is now disabled.</para>
+
+<para>Thanks go to Linus Heckemann for discovering and reporting this
+bug.</para>
+
+</section>
+<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&#x2019;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>&lt;nix/fetchurl.nix&gt;</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 &#x2018;/nix/store/l54i8wlw2265&#x2026;-zlib-1.2.8.drv&#x2019; may not
+be deterministic: output &#x2018;/nix/store/11a27shh6n2i&#x2026;-zlib-1.2.8&#x2019;
+differs from &#x2018;/nix/store/11a27shh6n2i&#x2026;-zlib-1.2.8-check&#x2019;
+
+$ diffoscope /nix/store/11a27shh6n2i&#x2026;-zlib-1.2.8 /nix/store/11a27shh6n2i&#x2026;-zlib-1.2.8-check
+&#x2026;
+&#x251C;&#x2500;&#x2500; lib/libz.a
+&#x2502; &#x251C;&#x2500;&#x2500; metadata
+&#x2502; &#x2502; @@ -1,15 +1,15 @@
+&#x2502; &#x2502; -rw-r--r-- 30001/30000 3096 Jan 12 15:20 2016 adler32.o
+&#x2026;
+&#x2502; &#x2502; +rw-r--r-- 30001/30000 3096 Jan 12 15:28 2016 adler32.o
+&#x2026;
+</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&#xF8;rn Forsman, Brian McKenna, Danny Wilson, davidak, Eelco Dolstra,
+Fabian Schmitthenner, FrankHB, Ilya Novoselov, janus, Jim Garrison, John
+Ericson, Jude Taylor, Ludovic Court&#xE8;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&#xED;r &#x10C;un&#xE1;t.</para>
+
+</section>
+<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&#x2019;</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&#x2019;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>&lt;nix/fetchurl.nix&gt;</literal> now
+ uses a <emphasis>builtin</emphasis> builder (i.e. it doesn&#x2019;t
+ require starting an external process; the download is performed by
+ Nix itself). This ensures that derivation paths don&#x2019;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&#xE8;s,
+Manolis Ragkousis, Nicolas B. Pierron and Shea Levy.</para>
+
+</section>
+<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) {}; &#x2026;
+</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&#x2019;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 &lt;- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/")
+ body &lt;- 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/&#x2026;-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/&#x2026;-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
+ &#x201C;generation&#x201D; 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>&lt;...&gt;</literal>
+ lookups now show position information.</para></listitem>
+
+ <listitem><para>Improved Boehm GC use: we disabled scanning for
+ interior pointers, which should reduce the &#x201C;<literal>Repeated
+ allocation of very large block</literal>&#x201D; 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&#x17E;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>
+<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 &#x2018;nix-store -l&#x2019; will now try to download it from the servers
+ listed in the &#x2018;log-servers&#x2019; 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 &#x201C;dependencies&#x201D; 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&#xE8;s, Marko Durkovic,
+Mikey Ariel, Paul Colomiets, Ricardo M. Correia, Ricky Elrod, Robert
+Helgesson, Rob Vermaas, Russell O'Connor, Shea Levy, Shell Turner,
+S&#xF6;nke Hahn, Steve Purcell, Vladim&#xED;r &#x10C;un&#xE1;t and Wout Mertens.</para>
+
+</section>
+<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 '&lt;nixpkgs&gt;' -A patchelf
+<replaceable>&#x2026;</replaceable>
+$ nix-build '&lt;nixpkgs&gt;' -A patchelf --check
+<replaceable>&#x2026;</replaceable>
+error: derivation `/nix/store/1ipvxs&#x2026;-patchelf-0.6' may not be deterministic:
+ hash mismatch in output `/nix/store/4pc1dm&#x2026;-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&#x2019;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&#x2019;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&#x2019;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&#x2019;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&#x2019;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 '&lt;nixos&gt;' -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 &#x201C;permanently failed&#x201D;. 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 '&lt;nixpkgs&gt;' -A libreoffice --argstr system x86_64-darwin
+error: the package &#x2018;libreoffice-4.0.5.2&#x2019; in &#x2018;.../applications/office/libreoffice/default.nix:263&#x2019;
+ is not supported on &#x2018;x86_64-darwin&#x2019;
+</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 &lt;(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&#x17E;ar,
+Eelco Dolstra, Ian-Woo Kim, Ludovic Court&#xE8;s, Maxim Ivanov, Petr
+Rockai, Ricardo M. Correia and Shea Levy.</para>
+
+</section>
+<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>
+<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 &#x201C;real&#x201D; 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&#x2019;s
+ <option>environment.systemPackages</option>. For instance, if you
+ have a specification <filename>my-packages.nix</filename> like this:
+
+<programlisting>
+with import &lt;nixpkgs&gt; {};
+[ 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 &#x2018;<literal>with</literal>&#x2019; 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 &#x201C;infinite recursion&#x201D; 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 &lt;
+ 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 &#x201C;Segmentation fault&#x201D;) 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&#x17E;ar, Eelco Dolstra,
+Florian Friesdorf, Gergely Risko, Ivan Kozik, Ludovic Court&#xE8;s and Shea
+Levy.</para>
+
+</section>
+<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&#xED;s Batlle i Rossell and Shea Levy.</para>
+
+</section>
+<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>
+<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>
+<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>
+<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 &#x201C;manifest&#x201D;-based method of getting
+ pre-built binaries is that you don&#x2019;t have to worry about your
+ manifest being in sync with the Nix expressions you&#x2019;re installing
+ from; i.e., you don&#x2019;t need to run <command>nix-pull</command> to
+ update your manifest. It&#x2019;s also more scalable because you don&#x2019;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 &#x201C;slave&#x201D; 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>
+<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 &lt;nix/fetchurl.nix&gt; { 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>
+<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&#x2019;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>&lt;nixpkgs/default.nix&gt;</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" = &#x2026;; "bla bla" = &#x2026;; }."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 &#x2014; 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>
+<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>
+<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>
+<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>
+<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&#x2019;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 (&gt; 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 &#x2014; 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>
+<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&#x2019;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&#x2019;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>&#x201C;<literal>...</literal>&#x201D; (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>) &gt; closure</literal> and
+ <literal>nix-store --import &lt;
+ 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>
+<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
+ &#x201C;intelligently&#x201D; 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&#x2019;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 &#x201C;disable&#x201D; 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&#x2019;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 &#x201C;quickly&#x201D;, i.e., don&#x2019;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 &#x2014; 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&#x2019;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 &#x201C;chroot&#x201D;. 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&#x2019;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>
+<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>
+<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&#x2019;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&#x2019;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 &#x2018;deep&#x2019;
+ 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&#x2019;t delete reachable (non-garbage)
+ paths unless <option>--ignore-liveness</option> is
+ specified.</para></listitem>
+
+ </itemizedlist>
+
+ </para></listitem>
+
+
+ <listitem><para>Berkeley DB 4.4&#x2019;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>
+<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), &gt;&amp;=9) failed: Bad
+ file descriptor at /nix/bin/nix-pull line 77</literal> (issue
+ <literal>NIX-14</literal>).</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+</section>
+<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>
+<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>
+<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>
+<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 &lt;= 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 &#x201C;closure store expressions&#x201D; is gone (and
+ so is the notion of &#x201C;successors&#x201D;); 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 &#x201C;deriver&#x201D;):
+
+ <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
+ &#x2014; 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 &#x201C;references&#x201D;
+ 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>
+<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 &#x201C;smart&#x201D;: 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>
+<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>
+<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>
+
+</appendix>
+
+<!--
+<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/src/command-ref/conf-file.md.tmp b/doc/manual/src/command-ref/conf-file.md.tmp
new file mode 100644
index 000000000..93d52069b
--- /dev/null
+++ b/doc/manual/src/command-ref/conf-file.md.tmp
@@ -0,0 +1,52 @@
+# 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`.
+
+ - If `NIX_CONFIG` is set, its contents is treated as the contents of
+ a configuration file.
+
+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`. Every configuration setting
+also has a corresponding command line flag, e.g. `--max-jobs 16`; for
+Boolean settings, there are two flags to enable or disable the setting
+(e.g. `--keep-failed` and `--no-keep-failed`).
+
+A configuration setting usually overrides any previous value. However,
+you can prefix the name of the setting by `extra-` to *append* to the
+previous value. For instance,
+
+ substituters = a b
+ extra-substituters = c d
+
+defines the `substituters` setting to be `a b c d`. This is also
+available as a command line flag (e.g. `--extra-substituters`).
+
+The following settings are currently available:
+
+EvalCommand::getEvalState()0
diff --git a/doc/manual/src/command-ref/nix.md b/doc/manual/src/command-ref/nix.md
new file mode 100644
index 000000000..acc7da3a6
--- /dev/null
+++ b/doc/manual/src/command-ref/nix.md
@@ -0,0 +1,3021 @@
+# Name
+
+`nix` - a tool for reproducible and declarative configuration management
+
+# Synopsis
+
+`nix` [*flags*...] *subcommand*
+
+# Flags
+
+ - `--debug`
+ enable debug output
+
+ - `--help`
+ show usage information
+
+ - `--help-config`
+ show configuration options
+
+ - `--log-format` *format*
+ format of log output; `raw`, `internal-json`, `bar` or `bar-with-logs`
+
+ - `--no-net`
+ disable substituters and consider all previously downloaded files up-to-date
+
+ - `--option` *name* *value*
+ set a Nix configuration option (overriding `nix.conf`)
+
+ - `--print-build-logs` / `L`
+ print full build logs on stderr
+
+ - `--quiet`
+ decrease verbosity level
+
+ - `--refresh`
+ consider all previously downloaded files out-of-date
+
+ - `--verbose` / `v`
+ increase verbosity level
+
+ - `--version`
+ show version information
+
+# Subcommand `nix add-to-store`
+
+## Name
+
+`nix add-to-store` - add a path to the Nix store
+
+## Synopsis
+
+`nix add-to-store` [*flags*...] *path*
+
+## Description
+
+
+Copy the file or directory *path* to the Nix store, and
+print the resulting store path on standard output.
+
+
+
+## Flags
+
+ - `--dry-run`
+ show what this command would do without doing it
+
+ - `--flat`
+ add flat file to the Nix store
+
+ - `--name` / `n` *name*
+ name component of the store path
+
+# Subcommand `nix build`
+
+## Name
+
+`nix build` - build a derivation or fetch a store path
+
+## Synopsis
+
+`nix build` [*flags*...] *installables*...
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--dry-run`
+ show what this command would do without doing it
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-link`
+ do not create a symlink to the build result
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--out-link` / `o` *path*
+ path of the symlink to the build result
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--profile` *path*
+ profile to update
+
+ - `--rebuild`
+ rebuild an already built package and compare the result to the existing store paths
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To build and run GNU Hello from NixOS 17.03:
+
+```console
+nix build -f channel:nixos-17.03 hello; ./result/bin/hello
+```
+
+To build the build.x86_64-linux attribute from release.nix:
+
+```console
+nix build -f release.nix build.x86_64-linux
+```
+
+To make a profile point at GNU Hello:
+
+```console
+nix build --profile /tmp/profile nixpkgs#hello
+```
+
+# Subcommand `nix bundle`
+
+## Name
+
+`nix bundle` - bundle an application so that it works outside of the Nix store
+
+## Synopsis
+
+`nix bundle` [*flags*...] *installable*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--bundler` *flake-url*
+ use custom bundler
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--out-link` / `o` *path*
+ path of the symlink to the build result
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To bundle Hello:
+
+```console
+nix bundle hello
+```
+
+# Subcommand `nix cat-nar`
+
+## Name
+
+`nix cat-nar` - print the contents of a file inside a NAR file on stdout
+
+## Synopsis
+
+`nix cat-nar` [*flags*...] *nar* *path*
+
+# Subcommand `nix cat-store`
+
+## Name
+
+`nix cat-store` - print the contents of a file in the Nix store on stdout
+
+## Synopsis
+
+`nix cat-store` [*flags*...] *path*
+
+# Subcommand `nix copy`
+
+## Name
+
+`nix copy` - copy paths between Nix stores
+
+## Synopsis
+
+`nix copy` [*flags*...] *installables*...
+
+## Flags
+
+ - `--all`
+ apply operation to the entire store
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--from` *store-uri*
+ URI of the source Nix store
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-check-sigs`
+ do not require that paths are signed by trusted keys
+
+ - `--no-recursive`
+ apply operation to specified paths only
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--substitute-on-destination` / `s`
+ whether to try substitutes on the destination store (only supported by SSH)
+
+ - `--to` *store-uri*
+ URI of the destination Nix store
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To copy Firefox from the local store to a binary cache in file:///tmp/cache:
+
+```console
+nix copy --to file:///tmp/cache $(type -p firefox)
+```
+
+To copy the entire current NixOS system closure to another machine via SSH:
+
+```console
+nix copy --to ssh://server /run/current-system
+```
+
+To copy a closure from another machine via SSH:
+
+```console
+nix copy --from ssh://server /nix/store/a6cnl93nk1wxnq84brbbwr6hxw9gp2w9-blender-2.79-rc2
+```
+
+To copy Hello to an S3 binary cache:
+
+```console
+nix copy --to s3://my-bucket?region=eu-west-1 nixpkgs#hello
+```
+
+To copy Hello to an S3-compatible binary cache:
+
+```console
+nix copy --to s3://my-bucket?region=eu-west-1&endpoint=example.com nixpkgs#hello
+```
+
+# Subcommand `nix copy-sigs`
+
+## Name
+
+`nix copy-sigs` - copy path signatures from substituters (like binary caches)
+
+## Synopsis
+
+`nix copy-sigs` [*flags*...] *installables*...
+
+## Flags
+
+ - `--all`
+ apply operation to the entire store
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--recursive` / `r`
+ apply operation to closure of the specified paths
+
+ - `--substituter` / `s` *store-uri*
+ use signatures from specified store
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+# Subcommand `nix describe-stores`
+
+## Name
+
+`nix describe-stores` - show registered store types and their available options
+
+## Synopsis
+
+`nix describe-stores` [*flags*...]
+
+## Flags
+
+ - `--json`
+ produce JSON output
+
+# Subcommand `nix develop`
+
+## Name
+
+`nix develop` - run a bash shell that provides the build environment of a derivation
+
+## Synopsis
+
+`nix develop` [*flags*...] *installable*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--build`
+ run the build phase
+
+ - `--check`
+ run the check phase
+
+ - `--command` / `c` *command* *args*
+ command and arguments to be executed instead of an interactive shell
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--configure`
+ run the configure phase
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--ignore-environment` / `i`
+ clear the entire environment (except those specified with --keep)
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--install`
+ run the install phase
+
+ - `--installcheck`
+ run the installcheck phase
+
+ - `--keep` / `k` *name*
+ keep specified environment variable
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--phase` *phase-name*
+ phase to run (e.g. `build` or `configure`)
+
+ - `--profile` *path*
+ profile to update
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--redirect` *installable* *outputs-dir*
+ redirect a store path to a mutable location
+
+ - `--unset` / `u` *name*
+ unset specified environment variable
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To get the build environment of GNU hello:
+
+```console
+nix develop nixpkgs#hello
+```
+
+To get the build environment of the default package of flake in the current directory:
+
+```console
+nix develop
+```
+
+To store the build environment in a profile:
+
+```console
+nix develop --profile /tmp/my-shell nixpkgs#hello
+```
+
+To use a build environment previously recorded in a profile:
+
+```console
+nix develop /tmp/my-shell
+```
+
+To replace all occurences of a store path with a writable directory:
+
+```console
+nix develop --redirect nixpkgs#glibc.dev ~/my-glibc/outputs/dev
+```
+
+# Subcommand `nix diff-closures`
+
+## Name
+
+`nix diff-closures` - show what packages and versions were added and removed between two closures
+
+## Synopsis
+
+`nix diff-closures` [*flags*...] *before* *after*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To show what got added and removed between two versions of the NixOS system profile:
+
+```console
+nix diff-closures /nix/var/nix/profiles/system-655-link /nix/var/nix/profiles/system-658-link
+```
+
+# Subcommand `nix doctor`
+
+## Name
+
+`nix doctor` - check your system for potential problems and print a PASS or FAIL for each check
+
+## Synopsis
+
+`nix doctor` [*flags*...]
+
+# Subcommand `nix dump-path`
+
+## Name
+
+`nix dump-path` - dump a store path to stdout (in NAR format)
+
+## Synopsis
+
+`nix dump-path` [*flags*...] *installables*...
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To get a NAR from the binary cache https://cache.nixos.org/:
+
+```console
+nix dump-path --store https://cache.nixos.org/ /nix/store/7crrmih8c52r8fbnqb933dxrsp44md93-glibc-2.25
+```
+
+# Subcommand `nix edit`
+
+## Name
+
+`nix edit` - open the Nix expression of a Nix package in $EDITOR
+
+## Synopsis
+
+`nix edit` [*flags*...] *installable*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To open the Nix expression of the GNU Hello package:
+
+```console
+nix edit nixpkgs#hello
+```
+
+# Subcommand `nix eval`
+
+## Name
+
+`nix eval` - evaluate a Nix expression
+
+## Synopsis
+
+`nix eval` [*flags*...] *installable*
+
+## Flags
+
+ - `--apply` *expr*
+ apply a function to each argument
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--json`
+ produce JSON output
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--raw`
+ print strings unquoted
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To evaluate a Nix expression given on the command line:
+
+```console
+nix eval --expr '1 + 2'
+```
+
+To evaluate a Nix expression from a file or URI:
+
+```console
+nix eval -f ./my-nixpkgs hello.name
+```
+
+To get the current version of Nixpkgs:
+
+```console
+nix eval --raw nixpkgs#lib.version
+```
+
+To print the store path of the Hello package:
+
+```console
+nix eval --raw nixpkgs#hello
+```
+
+To get a list of checks in the 'nix' flake:
+
+```console
+nix eval nix#checks.x86_64-linux --apply builtins.attrNames
+```
+
+# Subcommand `nix flake`
+
+## Name
+
+`nix flake` - manage Nix flakes
+
+## Synopsis
+
+`nix flake` [*flags*...] *subcommand*
+
+# Subcommand `nix flake archive`
+
+## Name
+
+`nix flake archive` - copy a flake and all its inputs to a store
+
+## Synopsis
+
+`nix flake archive` [*flags*...] *flake-url*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--dry-run`
+ show what this command would do without doing it
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--json`
+ produce JSON output
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--to` *store-uri*
+ URI of the destination Nix store
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To copy the dwarffs flake and its dependencies to a binary cache:
+
+```console
+nix flake archive --to file:///tmp/my-cache dwarffs
+```
+
+To fetch the dwarffs flake and its dependencies to the local Nix store:
+
+```console
+nix flake archive dwarffs
+```
+
+To print the store paths of the flake sources of NixOps without fetching them:
+
+```console
+nix flake archive --json --dry-run nixops
+```
+
+# Subcommand `nix flake check`
+
+## Name
+
+`nix flake check` - check whether the flake evaluates and run its tests
+
+## Synopsis
+
+`nix flake check` [*flags*...] *flake-url*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-build`
+ do not build checks
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+# Subcommand `nix flake clone`
+
+## Name
+
+`nix flake clone` - clone flake repository
+
+## Synopsis
+
+`nix flake clone` [*flags*...] *flake-url*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--dest` / `f` *path*
+ destination path
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+# Subcommand `nix flake info`
+
+## Name
+
+`nix flake info` - list info about a given flake
+
+## Synopsis
+
+`nix flake info` [*flags*...] *flake-url*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--json`
+ produce JSON output
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+# Subcommand `nix flake init`
+
+## Name
+
+`nix flake init` - create a flake in the current directory from a template
+
+## Synopsis
+
+`nix flake init` [*flags*...]
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--template` / `t` *template*
+ the template to use
+
+## Examples
+
+To create a flake using the default template:
+
+```console
+nix flake init
+```
+
+To see available templates:
+
+```console
+nix flake show templates
+```
+
+To create a flake from a specific template:
+
+```console
+nix flake init -t templates#nixos-container
+```
+
+# Subcommand `nix flake list-inputs`
+
+## Name
+
+`nix flake list-inputs` - list flake inputs
+
+## Synopsis
+
+`nix flake list-inputs` [*flags*...] *flake-url*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--json`
+ produce JSON output
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+# Subcommand `nix flake new`
+
+## Name
+
+`nix flake new` - create a flake in the specified directory from a template
+
+## Synopsis
+
+`nix flake new` [*flags*...] *dest-dir*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--template` / `t` *template*
+ the template to use
+
+# Subcommand `nix flake show`
+
+## Name
+
+`nix flake show` - show the outputs provided by a flake
+
+## Synopsis
+
+`nix flake show` [*flags*...] *flake-url*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--legacy`
+ show the contents of the 'legacyPackages' output
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+# Subcommand `nix flake update`
+
+## Name
+
+`nix flake update` - update flake lock file
+
+## Synopsis
+
+`nix flake update` [*flags*...] *flake-url*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+# Subcommand `nix hash-file`
+
+## Name
+
+`nix hash-file` - print cryptographic hash of a regular file
+
+## Synopsis
+
+`nix hash-file` [*flags*...] *paths*...
+
+## Flags
+
+ - `--base16`
+ print hash in base-16
+
+ - `--base32`
+ print hash in base-32 (Nix-specific)
+
+ - `--base64`
+ print hash in base-64
+
+ - `--sri`
+ print hash in SRI format
+
+ - `--type` *hash-algo*
+ hash algorithm ('md5', 'sha1', 'sha256', or 'sha512')
+
+# Subcommand `nix hash-path`
+
+## Name
+
+`nix hash-path` - print cryptographic hash of the NAR serialisation of a path
+
+## Synopsis
+
+`nix hash-path` [*flags*...] *paths*...
+
+## Flags
+
+ - `--base16`
+ print hash in base-16
+
+ - `--base32`
+ print hash in base-32 (Nix-specific)
+
+ - `--base64`
+ print hash in base-64
+
+ - `--sri`
+ print hash in SRI format
+
+ - `--type` *hash-algo*
+ hash algorithm ('md5', 'sha1', 'sha256', or 'sha512')
+
+# Subcommand `nix log`
+
+## Name
+
+`nix log` - show the build log of the specified packages or paths, if available
+
+## Synopsis
+
+`nix log` [*flags*...] *installable*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To get the build log of GNU Hello:
+
+```console
+nix log nixpkgs#hello
+```
+
+To get the build log of a specific path:
+
+```console
+nix log /nix/store/lmngj4wcm9rkv3w4dfhzhcyij3195hiq-thunderbird-52.2.1
+```
+
+To get a build log from a specific binary cache:
+
+```console
+nix log --store https://cache.nixos.org nixpkgs#hello
+```
+
+# Subcommand `nix ls-nar`
+
+## Name
+
+`nix ls-nar` - show information about a path inside a NAR file
+
+## Synopsis
+
+`nix ls-nar` [*flags*...] *nar* *path*
+
+## Flags
+
+ - `--directory` / `d`
+ show directories rather than their contents
+
+ - `--json`
+ produce JSON output
+
+ - `--long` / `l`
+ show more file information
+
+ - `--recursive` / `R`
+ list subdirectories recursively
+
+## Examples
+
+To list a specific file in a NAR:
+
+```console
+nix ls-nar -l hello.nar /bin/hello
+```
+
+# Subcommand `nix ls-store`
+
+## Name
+
+`nix ls-store` - show information about a path in the Nix store
+
+## Synopsis
+
+`nix ls-store` [*flags*...] *path*
+
+## Flags
+
+ - `--directory` / `d`
+ show directories rather than their contents
+
+ - `--json`
+ produce JSON output
+
+ - `--long` / `l`
+ show more file information
+
+ - `--recursive` / `R`
+ list subdirectories recursively
+
+## Examples
+
+To list the contents of a store path in a binary cache:
+
+```console
+nix ls-store --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10
+```
+
+# Subcommand `nix make-content-addressable`
+
+## Name
+
+`nix make-content-addressable` - rewrite a path or closure to content-addressable form
+
+## Synopsis
+
+`nix make-content-addressable` [*flags*...] *installables*...
+
+## Flags
+
+ - `--all`
+ apply operation to the entire store
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--json`
+ produce JSON output
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--recursive` / `r`
+ apply operation to closure of the specified paths
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To create a content-addressable representation of GNU Hello (but not its dependencies):
+
+```console
+nix make-content-addressable nixpkgs#hello
+```
+
+To compute a content-addressable representation of the current NixOS system closure:
+
+```console
+nix make-content-addressable -r /run/current-system
+```
+
+# Subcommand `nix optimise-store`
+
+## Name
+
+`nix optimise-store` - replace identical files in the store by hard links
+
+## Synopsis
+
+`nix optimise-store` [*flags*...]
+
+## Examples
+
+To optimise the Nix store:
+
+```console
+nix optimise-store
+```
+
+# Subcommand `nix path-info`
+
+## Name
+
+`nix path-info` - query information about store paths
+
+## Synopsis
+
+`nix path-info` [*flags*...] *installables*...
+
+## Flags
+
+ - `--all`
+ apply operation to the entire store
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--closure-size` / `S`
+ print sum size of the NAR dumps of the closure of each path
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--human-readable` / `h`
+ with -s and -S, print sizes like 1K 234M 5.67G etc.
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--json`
+ produce JSON output
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--recursive` / `r`
+ apply operation to closure of the specified paths
+
+ - `--sigs`
+ show signatures
+
+ - `--size` / `s`
+ print size of the NAR dump of each path
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To show the closure sizes of every path in the current NixOS system closure, sorted by size:
+
+```console
+nix path-info -rS /run/current-system | sort -nk2
+```
+
+To show a package's closure size and all its dependencies with human readable sizes:
+
+```console
+nix path-info -rsSh nixpkgs#rust
+```
+
+To check the existence of a path in a binary cache:
+
+```console
+nix path-info -r /nix/store/7qvk5c91...-geeqie-1.1 --store https://cache.nixos.org/
+```
+
+To print the 10 most recently added paths (using --json and the jq(1) command):
+
+```console
+nix path-info --json --all | jq -r 'sort_by(.registrationTime)[-11:-1][].path'
+```
+
+To show the size of the entire Nix store:
+
+```console
+nix path-info --json --all | jq 'map(.narSize) | add'
+```
+
+To show every path whose closure is bigger than 1 GB, sorted by closure size:
+
+```console
+nix path-info --json --all -S | jq 'map(select(.closureSize > 1e9)) | sort_by(.closureSize) | map([.path, .closureSize])'
+```
+
+# Subcommand `nix ping-store`
+
+## Name
+
+`nix ping-store` - test whether a store can be opened
+
+## Synopsis
+
+`nix ping-store` [*flags*...]
+
+## Examples
+
+To test whether connecting to a remote Nix store via SSH works:
+
+```console
+nix ping-store --store ssh://mac1
+```
+
+# Subcommand `nix print-dev-env`
+
+## Name
+
+`nix print-dev-env` - print shell code that can be sourced by bash to reproduce the build environment of a derivation
+
+## Synopsis
+
+`nix print-dev-env` [*flags*...] *installable*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--profile` *path*
+ profile to update
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--redirect` *installable* *outputs-dir*
+ redirect a store path to a mutable location
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To apply the build environment of GNU hello to the current shell:
+
+```console
+. <(nix print-dev-env nixpkgs#hello)
+```
+
+# Subcommand `nix profile`
+
+## Name
+
+`nix profile` - manage Nix profiles
+
+## Synopsis
+
+`nix profile` [*flags*...] *subcommand*
+
+# Subcommand `nix profile diff-closures`
+
+## Name
+
+`nix profile diff-closures` - show the closure difference between each generation of a profile
+
+## Synopsis
+
+`nix profile diff-closures` [*flags*...]
+
+## Flags
+
+ - `--profile` *path*
+ profile to update
+
+## Examples
+
+To show what changed between each generation of the NixOS system profile:
+
+```console
+nix profile diff-closure --profile /nix/var/nix/profiles/system
+```
+
+# Subcommand `nix profile info`
+
+## Name
+
+`nix profile info` - list installed packages
+
+## Synopsis
+
+`nix profile info` [*flags*...]
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--profile` *path*
+ profile to update
+
+## Examples
+
+To show what packages are installed in the default profile:
+
+```console
+nix profile info
+```
+
+# Subcommand `nix profile install`
+
+## Name
+
+`nix profile install` - install a package into a profile
+
+## Synopsis
+
+`nix profile install` [*flags*...] *installables*...
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--profile` *path*
+ profile to update
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To install a package from Nixpkgs:
+
+```console
+nix profile install nixpkgs#hello
+```
+
+To install a package from a specific branch of Nixpkgs:
+
+```console
+nix profile install nixpkgs/release-19.09#hello
+```
+
+To install a package from a specific revision of Nixpkgs:
+
+```console
+nix profile install nixpkgs/1028bb33859f8dfad7f98e1c8d185f3d1aaa7340#hello
+```
+
+# Subcommand `nix profile remove`
+
+## Name
+
+`nix profile remove` - remove packages from a profile
+
+## Synopsis
+
+`nix profile remove` [*flags*...] *elements*...
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--profile` *path*
+ profile to update
+
+## Examples
+
+To remove a package by attribute path:
+
+```console
+nix profile remove packages.x86_64-linux.hello
+```
+
+To remove all packages:
+
+```console
+nix profile remove '.*'
+```
+
+To remove a package by store path:
+
+```console
+nix profile remove /nix/store/rr3y0c6zyk7kjjl8y19s4lsrhn4aiq1z-hello-2.10
+```
+
+To remove a package by position:
+
+```console
+nix profile remove 3
+```
+
+# Subcommand `nix profile upgrade`
+
+## Name
+
+`nix profile upgrade` - upgrade packages using their most recent flake
+
+## Synopsis
+
+`nix profile upgrade` [*flags*...] *elements*...
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--profile` *path*
+ profile to update
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To upgrade all packages that were installed using a mutable flake reference:
+
+```console
+nix profile upgrade '.*'
+```
+
+To upgrade a specific package:
+
+```console
+nix profile upgrade packages.x86_64-linux.hello
+```
+
+# Subcommand `nix registry`
+
+## Name
+
+`nix registry` - manage the flake registry
+
+## Synopsis
+
+`nix registry` [*flags*...] *subcommand*
+
+# Subcommand `nix registry add`
+
+## Name
+
+`nix registry add` - add/replace flake in user flake registry
+
+## Synopsis
+
+`nix registry add` [*flags*...] *from-url* *to-url*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+# Subcommand `nix registry list`
+
+## Name
+
+`nix registry list` - list available Nix flakes
+
+## Synopsis
+
+`nix registry list` [*flags*...]
+
+# Subcommand `nix registry pin`
+
+## Name
+
+`nix registry pin` - pin a flake to its current version in user flake registry
+
+## Synopsis
+
+`nix registry pin` [*flags*...] *url*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+# Subcommand `nix registry remove`
+
+## Name
+
+`nix registry remove` - remove flake from user flake registry
+
+## Synopsis
+
+`nix registry remove` [*flags*...] *url*
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+# Subcommand `nix repl`
+
+## Name
+
+`nix repl` - start an interactive environment for evaluating Nix expressions
+
+## Synopsis
+
+`nix repl` [*flags*...] *files*...
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+## Examples
+
+Display all special commands within the REPL:
+
+```console
+nix repl
+nix-repl> :?
+```
+
+# Subcommand `nix run`
+
+## Name
+
+`nix run` - run a Nix application
+
+## Synopsis
+
+`nix run` [*flags*...] *installable* *args*...
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To run Blender:
+
+```console
+nix run blender-bin
+```
+
+To run vim from nixpkgs:
+
+```console
+nix run nixpkgs#vim
+```
+
+To run vim from nixpkgs with arguments:
+
+```console
+nix run nixpkgs#vim -- --help
+```
+
+# Subcommand `nix search`
+
+## Name
+
+`nix search` - query available packages
+
+## Synopsis
+
+`nix search` [*flags*...] *installable* *regex*...
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--json`
+ produce JSON output
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To show all packages in the flake in the current directory:
+
+```console
+nix search
+```
+
+To show packages in the 'nixpkgs' flake containing 'blender' in its name or description:
+
+```console
+nix search nixpkgs blender
+```
+
+To search for Firefox or Chromium:
+
+```console
+nix search nixpkgs 'firefox|chromium'
+```
+
+To search for packages containing 'git' and either 'frontend' or 'gui':
+
+```console
+nix search nixpkgs git 'frontend|gui'
+```
+
+# Subcommand `nix shell`
+
+## Name
+
+`nix shell` - run a shell in which the specified packages are available
+
+## Synopsis
+
+`nix shell` [*flags*...] *installables*...
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--command` / `c` *command* *args*
+ command and arguments to be executed; defaults to '$SHELL'
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--ignore-environment` / `i`
+ clear the entire environment (except those specified with --keep)
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--keep` / `k` *name*
+ keep specified environment variable
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--unset` / `u` *name*
+ unset specified environment variable
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To start a shell providing GNU Hello from NixOS 20.03:
+
+```console
+nix shell nixpkgs/nixos-20.03#hello
+```
+
+To start a shell providing youtube-dl from your 'nixpkgs' channel:
+
+```console
+nix shell nixpkgs#youtube-dl
+```
+
+To run GNU Hello:
+
+```console
+nix shell nixpkgs#hello -c hello --greeting 'Hi everybody!'
+```
+
+To run GNU Hello in a chroot store:
+
+```console
+nix shell --store ~/my-nix nixpkgs#hello -c hello
+```
+
+# Subcommand `nix show-config`
+
+## Name
+
+`nix show-config` - show the Nix configuration
+
+## Synopsis
+
+`nix show-config` [*flags*...]
+
+## Flags
+
+ - `--json`
+ produce JSON output
+
+# Subcommand `nix show-derivation`
+
+## Name
+
+`nix show-derivation` - show the contents of a store derivation
+
+## Synopsis
+
+`nix show-derivation` [*flags*...] *installables*...
+
+## Flags
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--recursive` / `r`
+ include the dependencies of the specified derivations
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To show the store derivation that results from evaluating the Hello package:
+
+```console
+nix show-derivation nixpkgs#hello
+```
+
+To show the full derivation graph (if available) that produced your NixOS system:
+
+```console
+nix show-derivation -r /run/current-system
+```
+
+# Subcommand `nix sign-paths`
+
+## Name
+
+`nix sign-paths` - sign the specified paths
+
+## Synopsis
+
+`nix sign-paths` [*flags*...] *installables*...
+
+## Flags
+
+ - `--all`
+ apply operation to the entire store
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--key-file` / `k` *file*
+ file containing the secret signing key
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--recursive` / `r`
+ apply operation to closure of the specified paths
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+# Subcommand `nix to-base16`
+
+## Name
+
+`nix to-base16` - convert a hash to base-16 representation
+
+## Synopsis
+
+`nix to-base16` [*flags*...] *strings*...
+
+## Flags
+
+ - `--type` *hash-algo*
+ hash algorithm ('md5', 'sha1', 'sha256', or 'sha512'). Optional as can also be gotten from SRI hash itself.
+
+# Subcommand `nix to-base32`
+
+## Name
+
+`nix to-base32` - convert a hash to base-32 representation
+
+## Synopsis
+
+`nix to-base32` [*flags*...] *strings*...
+
+## Flags
+
+ - `--type` *hash-algo*
+ hash algorithm ('md5', 'sha1', 'sha256', or 'sha512'). Optional as can also be gotten from SRI hash itself.
+
+# Subcommand `nix to-base64`
+
+## Name
+
+`nix to-base64` - convert a hash to base-64 representation
+
+## Synopsis
+
+`nix to-base64` [*flags*...] *strings*...
+
+## Flags
+
+ - `--type` *hash-algo*
+ hash algorithm ('md5', 'sha1', 'sha256', or 'sha512'). Optional as can also be gotten from SRI hash itself.
+
+# Subcommand `nix to-sri`
+
+## Name
+
+`nix to-sri` - convert a hash to SRI representation
+
+## Synopsis
+
+`nix to-sri` [*flags*...] *strings*...
+
+## Flags
+
+ - `--type` *hash-algo*
+ hash algorithm ('md5', 'sha1', 'sha256', or 'sha512'). Optional as can also be gotten from SRI hash itself.
+
+# Subcommand `nix upgrade-nix`
+
+## Name
+
+`nix upgrade-nix` - upgrade Nix to the latest stable version
+
+## Synopsis
+
+`nix upgrade-nix` [*flags*...]
+
+## Flags
+
+ - `--dry-run`
+ show what this command would do without doing it
+
+ - `--nix-store-paths-url` *url*
+ URL of the file that contains the store paths of the latest Nix release
+
+ - `--profile` / `p` *profile-dir*
+ the Nix profile to upgrade
+
+## Examples
+
+To upgrade Nix to the latest stable version:
+
+```console
+nix upgrade-nix
+```
+
+To upgrade Nix in a specific profile:
+
+```console
+nix upgrade-nix -p /nix/var/nix/profiles/per-user/alice/profile
+```
+
+# Subcommand `nix verify`
+
+## Name
+
+`nix verify` - verify the integrity of store paths
+
+## Synopsis
+
+`nix verify` [*flags*...] *installables*...
+
+## Flags
+
+ - `--all`
+ apply operation to the entire store
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-contents`
+ do not verify the contents of each store path
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-trust`
+ do not verify whether each store path is trusted
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--recursive` / `r`
+ apply operation to closure of the specified paths
+
+ - `--sigs-needed` / `n` *N*
+ require that each path has at least N valid signatures
+
+ - `--substituter` / `s` *store-uri*
+ use signatures from specified store
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To verify the entire Nix store:
+
+```console
+nix verify --all
+```
+
+To check whether each path in the closure of Firefox has at least 2 signatures:
+
+```console
+nix verify -r -n2 --no-contents $(type -p firefox)
+```
+
+# Subcommand `nix why-depends`
+
+## Name
+
+`nix why-depends` - show why a package has another package in its closure
+
+## Synopsis
+
+`nix why-depends` [*flags*...] *package* *dependency*
+
+## Flags
+
+ - `--all` / `a`
+ show all edges in the dependency graph leading from 'package' to 'dependency', rather than just a shortest path
+
+ - `--arg` *name* *expr*
+ argument to be passed to Nix functions
+
+ - `--argstr` *name* *string*
+ string-valued argument to be passed to Nix functions
+
+ - `--commit-lock-file`
+ commit changes to the lock file
+
+ - `--derivation`
+ operate on the store derivation rather than its outputs
+
+ - `--expr` *expr*
+ evaluate attributes from *expr*
+
+ - `--file` / `f` *file*
+ evaluate *file* rather than the default
+
+ - `--impure`
+ allow access to mutable paths and repositories
+
+ - `--include` / `I` *path*
+ add a path to the list of locations used to look up `<...>` file names
+
+ - `--inputs-from` *flake-url*
+ use the inputs of the specified flake as registry entries
+
+ - `--no-registries`
+ don't use flake registries
+
+ - `--no-update-lock-file`
+ do not allow any updates to the lock file
+
+ - `--no-write-lock-file`
+ do not write the newly generated lock file
+
+ - `--override-flake` *original-ref* *resolved-ref*
+ override a flake registry value
+
+ - `--override-input` *input-path* *flake-url*
+ override a specific flake input (e.g. `dwarffs/nixpkgs`)
+
+ - `--recreate-lock-file`
+ recreate lock file from scratch
+
+ - `--update-input` *input-path*
+ update a specific flake input
+
+## Examples
+
+To show one path through the dependency graph leading from Hello to Glibc:
+
+```console
+nix why-depends nixpkgs#hello nixpkgs#glibc
+```
+
+To show all files and paths in the dependency graph leading from Thunderbird to libX11:
+
+```console
+nix why-depends --all nixpkgs#thunderbird nixpkgs#xorg.libX11
+```
+
+To show why Glibc depends on itself:
+
+```console
+nix why-depends nixpkgs#glibc nixpkgs#glibc
+```
+
diff --git a/doc/manual/src/expressions/builtins.md.tmp b/doc/manual/src/expressions/builtins.md.tmp
new file mode 100644
index 000000000..95a73709e
--- /dev/null
+++ b/doc/manual/src/expressions/builtins.md.tmp
@@ -0,0 +1,16 @@
+# Built-in Functions
+
+This section lists the functions 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`.
+
+ - `derivation` *attrs*; `builtins.derivation` *attrs*\
+
+ `derivation` is described in [its own section](derivations.md).
+
+EvalCommand::getEvalState()0
diff --git a/doc/manual/version.txt b/doc/manual/version.txt
new file mode 100644
index 000000000..f398a2061
--- /dev/null
+++ b/doc/manual/version.txt
@@ -0,0 +1 @@
+3.0 \ No newline at end of file
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-23 13:59:11 +0000