diff options
| author | Ben Burdette <bburdette@gmail.com> | 2021-09-13 11:57:25 -0600 |
|---|---|---|
| committer | Ben Burdette <bburdette@gmail.com> | 2021-09-13 11:57:25 -0600 |
| commit | 176911102ce2c0be06bbfed9099f364d71c3c679 (patch) | |
| tree | e8b0c12410c5126d57313601ba73c0afdc5e8851 /doc/manual/manual.xmli | |
| parent | 310c689d317d1eb4bcf50cd11d84165fe2ffd512 (diff) | |
printEnvPosChain
Diffstat (limited to 'doc/manual/manual.xmli')
| -rw-r--r-- | doc/manual/manual.xmli | 20139 |
1 files changed, 20139 insertions, 0 deletions
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 — they are built by functions +that don’t have side-effects, and they never change after they have +been built. Nix stores packages in the <emphasis>Nix +store</emphasis>, usually the directory +<filename>/nix/store</filename>, where each package has its own unique +subdirectory such as + +<programlisting> +/nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/ +</programlisting> + +where <literal>b6gvzjyb2pg0…</literal> is a unique identifier for the +package that captures all its dependencies (it’s a cryptographic hash +of the package’s build dependency graph). This enables many powerful +features.</para> + + +<simplesect><title>Multiple versions</title> + +<para>You can have multiple versions or variants of a package +installed at the same time. This is especially important when +different applications have dependencies on different versions of the +same package — it prevents the “DLL hell”. Because of the hashing +scheme, different versions of a package end up in different paths in +the Nix store, so they don’t interfere with each other.</para> + +<para>An important consequence is that operations like upgrading or +uninstalling an application cannot break other applications, since +these operations never “destructively” update or delete files that are +used by other packages.</para> + +</simplesect> + + +<simplesect><title>Complete dependencies</title> + +<para>Nix helps you make sure that package dependency specifications +are complete. In general, when you’re making a package for a package +management system like RPM, you have to specify for each package what +its dependencies are, but there are no guarantees that this +specification is complete. If you forget a dependency, then the +package will build and work correctly on <emphasis>your</emphasis> +machine if you have the dependency installed, but not on the end +user's machine if it's not there.</para> + +<para>Since Nix on the other hand doesn’t install packages in “global” +locations like <filename>/usr/bin</filename> but in package-specific +directories, the risk of incomplete dependencies is greatly reduced. +This is because tools such as compilers don’t search in per-packages +directories such as +<filename>/nix/store/5lbfaxb722zp…-openssl-0.9.8d/include</filename>, +so if a package builds correctly on your system, this is because you +specified the dependency explicitly. This takes care of the build-time +dependencies.</para> + +<para>Once a package is built, runtime dependencies are found by +scanning binaries for the hash parts of Nix store paths (such as +<literal>r8vvq9kq…</literal>). This sounds risky, but it works +extremely well.</para> + +</simplesect> + + +<simplesect><title>Multi-user support</title> + +<para>Nix has multi-user support. This means that non-privileged +users can securely install software. Each user can have a different +<emphasis>profile</emphasis>, a set of packages in the Nix store that +appear in the user’s <envar>PATH</envar>. If a user installs a +package that another user has already installed previously, the +package won’t be built or downloaded a second time. At the same time, +it is not possible for one user to inject a Trojan horse into a +package that might be used by another user.</para> + +</simplesect> + + +<simplesect><title>Atomic upgrades and rollbacks</title> + +<para>Since package management operations never overwrite packages in +the Nix store but just add new versions in different paths, they are +<emphasis>atomic</emphasis>. So during a package upgrade, there is no +time window in which the package has some files from the old version +and some files from the new version — which would be bad because a +program might well crash if it’s started during that period.</para> + +<para>And since packages aren’t overwritten, the old versions are still +there after an upgrade. This means that you can <emphasis>roll +back</emphasis> to the old version:</para> + +<screen> +$ nix-env --upgrade <replaceable>some-packages</replaceable> +$ nix-env --rollback +</screen> + +</simplesect> + + +<simplesect><title>Garbage collection</title> + +<para>When you uninstall a package like this… + +<screen> +$ nix-env --uninstall firefox +</screen> + +the package isn’t deleted from the system right away (after all, you +might want to do a rollback, or it might be in the profiles of other +users). Instead, unused packages can be deleted safely by running the +<emphasis>garbage collector</emphasis>: + +<screen> +$ nix-collect-garbage +</screen> + +This deletes all packages that aren’t in use by any user profile or by +a currently running program.</para> + +</simplesect> + + +<simplesect><title>Functional package language</title> + +<para>Packages are built from <emphasis>Nix expressions</emphasis>, +which is a simple functional language. A Nix expression describes +everything that goes into a package build action (a “derivation”): +other packages, sources, the build script, environment variables for +the build script, etc. Nix tries very hard to ensure that Nix +expressions are <emphasis>deterministic</emphasis>: building a Nix +expression twice should yield the same result.</para> + +<para>Because it’s a functional language, it’s easy to support +building variants of a package: turn the Nix expression into a +function and call it any number of times with the appropriate +arguments. Due to the hashing scheme, variants don’t conflict with +each other in the Nix store.</para> + +</simplesect> + + +<simplesect><title>Transparent source/binary deployment</title> + +<para>Nix expressions generally describe how to build a package from +source, so an installation action like + +<screen> +$ nix-env --install firefox +</screen> + +<emphasis>could</emphasis> cause quite a bit of build activity, as not +only Firefox but also all its dependencies (all the way up to the C +library and the compiler) would have to built, at least if they are +not already in the Nix store. This is a <emphasis>source deployment +model</emphasis>. For most users, building from source is not very +pleasant as it takes far too long. However, Nix can automatically +skip building from source and instead use a <emphasis>binary +cache</emphasis>, a web server that provides pre-built binaries. For +instance, when asked to build +<literal>/nix/store/b6gvzjyb2pg0…-firefox-33.1</literal> from source, +Nix would first check if the file +<uri>https://cache.nixos.org/b6gvzjyb2pg0….narinfo</uri> exists, and +if so, fetch the pre-built binary referenced from there; otherwise, it +would fall back to building from source.</para> + +</simplesect> + + +<!-- +<simplesect><title>Binary patching</title> + +<para>In addition to downloading binaries automatically if they’re +available, Nix can download binary deltas that patch an existing +package in the Nix store into a new version. This speeds up +upgrades.</para> + +</simplesect> +--> + + +<simplesect><title>Nix Packages collection</title> + +<para>We provide a large set of Nix expressions containing hundreds of +existing Unix packages, the <emphasis>Nix Packages +collection</emphasis> (Nixpkgs).</para> + +</simplesect> + + +<simplesect><title>Managing build environments</title> + +<para>Nix is extremely useful for developers as it makes it easy to +automatically set up the build environment for a package. Given a +Nix expression that describes the dependencies of your package, the +command <command>nix-shell</command> will build or download those +dependencies if they’re not already in your Nix store, and then start +a Bash shell in which all necessary environment variables (such as +compiler search paths) are set.</para> + +<para>For example, the following command gets all dependencies of the +Pan newsreader, as described by <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix">its +Nix expression</link>:</para> + +<screen> +$ nix-shell '<nixpkgs>' -A pan +</screen> + +<para>You’re then dropped into a shell where you can edit, build and test +the package:</para> + +<screen> +[nix-shell]$ tar xf $src +[nix-shell]$ cd pan-* +[nix-shell]$ ./configure +[nix-shell]$ make +[nix-shell]$ ./pan/gui/pan +</screen> + +<!-- +<para>Since Nix packages are reproducible and have complete dependency +specifications, Nix makes an excellent basis for <a +href="[%root%]hydra">a continuous build system</a>.</para> +--> + +</simplesect> + + +<simplesect><title>Portability</title> + +<para>Nix runs on Linux and macOS.</para> + +</simplesect> + + +<simplesect><title>NixOS</title> + +<para>NixOS is a Linux distribution based on Nix. It uses Nix not +just for package management but also to manage the system +configuration (e.g., to build configuration files in +<filename>/etc</filename>). This means, among other things, that it +is easy to roll back the entire configuration of the system to an +earlier state. Also, users can install software without root +privileges. For more information and downloads, see the <link xlink:href="http://nixos.org/">NixOS homepage</link>.</para> + +</simplesect> + + +<simplesect><title>License</title> + +<para>Nix is released under the terms of the <link xlink:href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">GNU +LGPLv2.1 or (at your option) any later version</link>.</para> + +</simplesect> + + +</chapter> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="chap-quick-start"> + +<title>Quick Start</title> + +<para>This chapter is for impatient people who don't like reading +documentation. For more in-depth information you are kindly referred +to subsequent chapters.</para> + +<procedure> + +<step><para>Install single-user Nix by running the following: + +<screen> +$ bash <(curl -L https://nixos.org/nix/install) +</screen> + +This will install Nix in <filename>/nix</filename>. The install script +will create <filename>/nix</filename> using <command>sudo</command>, +so make sure you have sufficient rights. (For other installation +methods, see <xref linkend="chap-installation"/>.)</para></step> + +<step><para>See what installable packages are currently available +in the channel: + +<screen> +$ nix-env -qa +docbook-xml-4.3 +docbook-xml-4.5 +firefox-33.0.2 +hello-2.9 +libxslt-1.1.28 +<replaceable>...</replaceable></screen> + +</para></step> + +<step><para>Install some packages from the channel: + +<screen> +$ nix-env -i hello</screen> + +This should download pre-built packages; it should not build them +locally (if it does, something went wrong).</para></step> + +<step><para>Test that they work: + +<screen> +$ which hello +/home/eelco/.nix-profile/bin/hello +$ hello +Hello, world! +</screen> + +</para></step> + +<step><para>Uninstall a package: + +<screen> +$ nix-env -e hello</screen> + +</para></step> + +<step><para>You can also test a package without installing it: + +<screen> +$ nix-shell -p hello +</screen> + +This builds or downloads GNU Hello and its dependencies, then drops +you into a Bash shell where the <command>hello</command> command is +present, all without affecting your normal environment: + +<screen> +[nix-shell:~]$ hello +Hello, world! + +[nix-shell:~]$ exit + +$ hello +hello: command not found +</screen> + +</para></step> + +<step><para>To keep up-to-date with the channel, do: + +<screen> +$ nix-channel --update nixpkgs +$ nix-env -u '*'</screen> + +The latter command will upgrade each installed package for which there +is a “newer” version (as determined by comparing the version +numbers).</para></step> + +<step><para>If you're unhappy with the result of a +<command>nix-env</command> action (e.g., an upgraded package turned +out not to work properly), you can go back: + +<screen> +$ nix-env --rollback</screen> + +</para></step> + +<step><para>You should periodically run the Nix garbage collector +to get rid of unused packages, since uninstalls or upgrades don't +actually delete them: + +<screen> +$ nix-collect-garbage -d</screen> + +<!-- +The first command deletes old “generations” of your profile (making +rollbacks impossible, but also making the packages in those old +generations available for garbage collection), while the second +command actually deletes them.--> + +</para></step> + +</procedure> + +</chapter> + +</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 <(curl -L https://nixos.org/nix/install) +</screen> + +<para> + If you're using macOS 10.15 (Catalina) or newer, consult + <link linkend="sect-macos-installation">the macOS installation instructions</link> + before installing. +</para> + +<para> + As of Nix 2.1.0, the Nix installer will always default to creating a + single-user installation, however opting in to the multi-user + installation is highly recommended. + <!-- TODO: this explains *neither* why the default version is + single-user, nor why we'd recommend multi-user over the default. + True prospective users don't have much basis for evaluating this. + What's it to me? Who should pick which? Why? What if I pick wrong? + --> +</para> + +<section xml:id="sect-single-user-installation"> + <title>Single User Installation</title> + + <para> + To explicitly select a single-user installation on your system: + + <screen> + sh <(curl -L https://nixos.org/nix/install) --no-daemon +</screen> + </para> + +<para> +This will perform a single-user installation of Nix, meaning that +<filename>/nix</filename> is owned by the invoking user. You should +run this under your usual user account, <emphasis>not</emphasis> as +root. The script will invoke <command>sudo</command> to create +<filename>/nix</filename> if it doesn’t already exist. If you don’t +have <command>sudo</command>, you should manually create +<filename>/nix</filename> first as root, e.g.: + +<screen> +$ mkdir /nix +$ chown alice /nix +</screen> + +The install script will modify the first writable file from amongst +<filename>.bash_profile</filename>, <filename>.bash_login</filename> +and <filename>.profile</filename> to source +<filename>~/.nix-profile/etc/profile.d/nix.sh</filename>. You can set +the <envar>NIX_INSTALLER_NO_MODIFY_PROFILE</envar> environment +variable before executing the install script to disable this +behaviour. +</para> + + +<para>You can uninstall Nix simply by running: + +<screen> +$ rm -rf /nix +</screen> + +</para> +</section> + +<section xml:id="sect-multi-user-installation"> + <title>Multi User Installation</title> + <para> + The multi-user Nix installation creates system users, and a system + service for the Nix daemon. + </para> + + <itemizedlist> + <title>Supported Systems</title> + + <listitem> + <para>Linux running systemd, with SELinux disabled</para> + </listitem> + <listitem><para>macOS</para></listitem> + </itemizedlist> + + <para> + You can instruct the installer to perform a multi-user + installation on your system: + </para> + + <screen>sh <(curl -L https://nixos.org/nix/install) --daemon</screen> + + <para> + The multi-user installation of Nix will create build users between + the user IDs 30001 and 30032, and a group with the group ID 30000. + + You should run this under your usual user account, + <emphasis>not</emphasis> as root. The script will invoke + <command>sudo</command> as needed. + </para> + + <note><para> + If you need Nix to use a different group ID or user ID set, you + will have to download the tarball manually and <link linkend="sect-nix-install-binary-tarball">edit the install + script</link>. + </para></note> + + <para> + The installer will modify <filename>/etc/bashrc</filename>, and + <filename>/etc/zshrc</filename> if they exist. The installer will + first back up these files with a + <literal>.backup-before-nix</literal> extension. The installer + will also create <filename>/etc/profile.d/nix.sh</filename>. + </para> + + <para>You can uninstall Nix with the following commands: + +<screen> +sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels + +# If you are on Linux with systemd, you will need to run: +sudo systemctl stop nix-daemon.socket +sudo systemctl stop nix-daemon.service +sudo systemctl disable nix-daemon.socket +sudo systemctl disable nix-daemon.service +sudo systemctl daemon-reload + +# If you are on macOS, you will need to run: +sudo launchctl unload /Library/LaunchDaemons/org.nixos.nix-daemon.plist +sudo rm /Library/LaunchDaemons/org.nixos.nix-daemon.plist +</screen> + + There may also be references to Nix in + <filename>/etc/profile</filename>, + <filename>/etc/bashrc</filename>, and + <filename>/etc/zshrc</filename> which you may remove. + </para> + +</section> + +<section xml:id="sect-macos-installation"> + <title>macOS Installation</title> + + <para> + Starting with macOS 10.15 (Catalina), the root filesystem is read-only. + This means <filename>/nix</filename> can no longer live on your system + volume, and that you'll need a workaround to install Nix. + </para> + + <para> + The recommended approach, which creates an unencrypted APFS volume + for your Nix store and a "synthetic" empty directory to mount it + over at <filename>/nix</filename>, is least likely to impair Nix + or your system. + </para> + + <note><para> + With all separate-volume approaches, it's possible something on + your system (particularly daemons/services and restored apps) may + need access to your Nix store before the volume is mounted. Adding + additional encryption makes this more likely. + </para></note> + + <para> + If you're using a recent Mac with a + <link xlink:href="https://www.apple.com/euro/mac/shared/docs/Apple_T2_Security_Chip_Overview.pdf">T2 chip</link>, + your drive will still be encrypted at rest (in which case "unencrypted" + is a bit of a misnomer). To use this approach, just install Nix with: + </para> + + <screen>$ sh <(curl -L https://nixos.org/nix/install) --darwin-use-unencrypted-nix-store-volume</screen> + + <para> + If you don't like the sound of this, you'll want to weigh the + other approaches and tradeoffs detailed in this section. + </para> + + <note> + <title>Eventual solutions?</title> + <para> + All of the known workarounds have drawbacks, but we hope + better solutions will be available in the future. Some that + we have our eye on are: + </para> + <orderedlist> + <listitem> + <para> + A true firmlink would enable the Nix store to live on the + primary data volume without the build problems caused by + the symlink approach. End users cannot currently + create true firmlinks. + </para> + </listitem> + <listitem> + <para> + If the Nix store volume shared FileVault encryption + with the primary data volume (probably by using the same + volume group and role), FileVault encryption could be + easily supported by the installer without requiring + manual setup by each user. + </para> + </listitem> + </orderedlist> + </note> + + <section xml:id="sect-macos-installation-change-store-prefix"> + <title>Change the Nix store path prefix</title> + <para> + Changing the default prefix for the Nix store is a simple + approach which enables you to leave it on your root volume, + where it can take full advantage of FileVault encryption if + enabled. Unfortunately, this approach also opts your device out + of some benefits that are enabled by using the same prefix + across systems: + + <itemizedlist> + <listitem> + <para> + Your system won't be able to take advantage of the binary + cache (unless someone is able to stand up and support + duplicate caching infrastructure), which means you'll + spend more time waiting for builds. + </para> + </listitem> + <listitem> + <para> + It's harder to build and deploy packages to Linux systems. + </para> + </listitem> + <!-- TODO: may be more here --> + </itemizedlist> + + <!-- TODO: Yes, but how?! --> + + It would also possible (and often requested) to just apply this + change ecosystem-wide, but it's an intrusive process that has + side effects we want to avoid for now. + <!-- magnificent hand-wavy gesture --> + </para> + <para> + </para> + </section> + + <section xml:id="sect-macos-installation-encrypted-volume"> + <title>Use a separate encrypted volume</title> + <para> + If you like, you can also add encryption to the recommended + approach taken by the installer. You can do this by pre-creating + an encrypted volume before you run the installer--or you can + run the installer and encrypt the volume it creates later. + <!-- TODO: see later note about whether this needs both add-encryption and from-scratch directions --> + </para> + <para> + In either case, adding encryption to a second volume isn't quite + as simple as enabling FileVault for your boot volume. Before you + dive in, there are a few things to weigh: + </para> + <orderedlist> + <listitem> + <para> + The additional volume won't be encrypted with your existing + FileVault key, so you'll need another mechanism to decrypt + the volume. + </para> + </listitem> + <listitem> + <para> + You can store the password in Keychain to automatically + decrypt the volume on boot--but it'll have to wait on Keychain + and may not mount before your GUI apps restore. If any of + your launchd agents or apps depend on Nix-installed software + (for example, if you use a Nix-installed login shell), the + restore may fail or break. + </para> + <para> + On a case-by-case basis, you may be able to work around this + problem by using <command>wait4path</command> to block + execution until your executable is available. + </para> + <para> + It's also possible to decrypt and mount the volume earlier + with a login hook--but this mechanism appears to be + deprecated and its future is unclear. + </para> + </listitem> + <listitem> + <para> + You can hard-code the password in the clear, so that your + store volume can be decrypted before Keychain is available. + </para> + </listitem> + </orderedlist> + <para> + If you are comfortable navigating these tradeoffs, you can encrypt the volume with + something along the lines of: + <!-- TODO: + I don't know if this also needs from-scratch instructions? + can we just recommend use-the-installer-and-then-encrypt? + --> + </para> + <!-- + TODO: it looks like this option can be encryptVolume|encrypt|enableFileVault + + It may be more clear to use encryptVolume, here? FileVault seems + heavily associated with the boot-volume behavior; I worry + a little that it can mislead here, especially as it gets + copied around minus doc context...? + --> + <screen>alice$ diskutil apfs enableFileVault /nix -user disk</screen> + + <!-- TODO: and then go into detail on the mount/decrypt approaches? --> + </section> + + <section xml:id="sect-macos-installation-symlink"> + <!-- + Maybe a good razor is: if we'd hate having to support someone who + installed Nix this way, it shouldn't even be detailed? + --> + <title>Symlink the Nix store to a custom location</title> + <para> + Another simple approach is using <filename>/etc/synthetic.conf</filename> + to symlink the Nix store to the data volume. This option also + enables your store to share any configured FileVault encryption. + Unfortunately, builds that resolve the symlink may leak the + canonical path or even fail. + </para> + <para> + Because of these downsides, we can't recommend this approach. + </para> + <!-- Leaving out instructions for this one. --> + </section> + + <section xml:id="sect-macos-installation-recommended-notes"> + <title>Notes on the recommended approach</title> + <para> + This section goes into a little more detail on the recommended + approach. You don't need to understand it to run the installer, + but it can serve as a helpful reference if you run into trouble. + </para> + <orderedlist> + <listitem> + <para> + In order to compose user-writable locations into the new + read-only system root, Apple introduced a new concept called + <literal>firmlinks</literal>, which it describes as a + "bi-directional wormhole" between two filesystems. You can + see the current firmlinks in <filename>/usr/share/firmlinks</filename>. + Unfortunately, firmlinks aren't (currently?) user-configurable. + </para> + + <para> + For special cases like NFS mount points or package manager roots, + <link xlink:href="https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man5/synthetic.conf.5.html">synthetic.conf(5)</link> + supports limited user-controlled file-creation (of symlinks, + and synthetic empty directories) at <filename>/</filename>. + To create a synthetic empty directory for mounting at <filename>/nix</filename>, + add the following line to <filename>/etc/synthetic.conf</filename> + (create it if necessary): + </para> + + <screen>nix</screen> + </listitem> + + <listitem> + <para> + This configuration is applied at boot time, but you can use + <command>apfs.util</command> to trigger creation (not deletion) + of new entries without a reboot: + </para> + + <screen>alice$ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B</screen> + </listitem> + + <listitem> + <para> + Create the new APFS volume with diskutil: + </para> + + <screen>alice$ sudo diskutil apfs addVolume diskX APFS 'Nix Store' -mountpoint /nix</screen> + </listitem> + + <listitem> + <para> + Using <command>vifs</command>, add the new mount to + <filename>/etc/fstab</filename>. If it doesn't already have + other entries, it should look something like: + </para> + +<screen> +# +# Warning - this file should only be modified with vifs(8) +# +# Failure to do so is unsupported and may be destructive. +# +LABEL=Nix\040Store /nix apfs rw,nobrowse +</screen> + + <para> + The nobrowse setting will keep Spotlight from indexing this + volume, and keep it from showing up on your desktop. + </para> + </listitem> + </orderedlist> + </section> + +</section> + +<section xml:id="sect-nix-install-pinned-version-url"> + <title>Installing a pinned Nix version from a URL</title> + + <para> + NixOS.org hosts version-specific installation URLs for all Nix + versions since 1.11.16, at + <literal>https://releases.nixos.org/nix/nix-<replaceable>version</replaceable>/install</literal>. + </para> + + <para> + These install scripts can be used the same as the main + NixOS.org installation script: + + <screen> + sh <(curl -L https://nixos.org/nix/install) +</screen> + </para> + + <para> + In the same directory of the install script are sha256 sums, and + gpg signature files. + </para> +</section> + +<section xml:id="sect-nix-install-binary-tarball"> + <title>Installing from a binary tarball</title> + + <para> + You can also download a binary tarball that contains Nix and all + its dependencies. (This is what the install script at + <uri>https://nixos.org/nix/install</uri> does automatically.) You + should unpack it somewhere (e.g. in <filename>/tmp</filename>), + and then run the script named <command>install</command> inside + the binary tarball: + + +<screen> +alice$ cd /tmp +alice$ tar xfj nix-1.8-x86_64-darwin.tar.bz2 +alice$ cd nix-1.8-x86_64-darwin +alice$ ./install +</screen> + </para> + + <para> + If you need to edit the multi-user installation script to use + different group ID or a different user ID range, modify the + variables set in the file named + <filename>install-multi-user</filename>. + </para> +</section> +</chapter> +<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’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 — 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 +“single-user mode”, which is similar to what most other package +management tools do: there is a single user (typically <systemitem class="username">root</systemitem>) who performs all package +management operations. All other users can then use the installed +packages, but they cannot perform package management operations +themselves.</para> + +<para>Alternatively, you can configure Nix in “multi-user mode”. In +this model, all users can perform package management operations — for +instance, every user can install software without requiring root +privileges. Nix ensures that this is secure. For instance, it’s not +possible for one user to overwrite a package used by another user with +a Trojan horse.</para> + +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-single-user"> + +<title>Single-User Mode</title> + +<para>In single-user mode, all Nix operations that access the database +in <filename><replaceable>prefix</replaceable>/var/nix/db</filename> +or modify the Nix store in +<filename><replaceable>prefix</replaceable>/store</filename> must be +performed under the user ID that owns those directories. This is +typically <systemitem class="username">root</systemitem>. (If you +install from RPM packages, that’s in fact the default ownership.) +However, on single-user machines, it is often convenient to +<command>chown</command> those directories to your normal user account +so that you don’t have to <command>su</command> to <systemitem class="username">root</systemitem> all the time.</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-multi-user"> + +<title>Multi-User Mode</title> + +<para>To allow a Nix store to be shared safely among multiple users, +it is important that users are not able to run builders that modify +the Nix store or database in arbitrary ways, or that interfere with +builds started by other users. If they could do so, they could +install a Trojan horse in some package and compromise the accounts of +other users.</para> + +<para>To prevent this, the Nix store and database are owned by some +privileged user (usually <literal>root</literal>) and builders are +executed under special user accounts (usually named +<literal>nixbld1</literal>, <literal>nixbld2</literal>, etc.). When a +unprivileged user runs a Nix command, actions that operate on the Nix +store (such as builds) are forwarded to a <emphasis>Nix +daemon</emphasis> running under the owner of the Nix store/database +that performs the operation.</para> + +<note><para>Multi-user mode has one important limitation: only +<systemitem class="username">root</systemitem> and a set of trusted +users specified in <filename>nix.conf</filename> can specify arbitrary +binary caches. So while unprivileged users may install packages from +arbitrary Nix expressions, they may not get pre-built +binaries.</para></note> + + +<simplesect> + +<title>Setting up the build users</title> + +<para>The <emphasis>build users</emphasis> are the special UIDs under +which builds are performed. They should all be members of the +<emphasis>build users group</emphasis> <literal>nixbld</literal>. +This group should have no other members. The build users should not +be members of any other group. On Linux, you can create the group and +users as follows: + +<screen> +$ groupadd -r nixbld +$ for n in $(seq 1 10); do useradd -c "Nix build user $n" \ + -d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \ + nixbld$n; done +</screen> + +This creates 10 build users. There can never be more concurrent builds +than the number of build users, so you may want to increase this if +you expect to do many builds at the same time.</para> + +</simplesect> + + +<simplesect> + +<title>Running the daemon</title> + +<para>The <link linkend="sec-nix-daemon">Nix daemon</link> should be +started as follows (as <literal>root</literal>): + +<screen> +$ nix-daemon</screen> + +You’ll want to put that line somewhere in your system’s boot +scripts.</para> + +<para>To let unprivileged users use the daemon, they should set the +<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment +variable</link> to <literal>daemon</literal>. So you should put a +line like + +<programlisting> +export NIX_REMOTE=daemon</programlisting> + +into the users’ login scripts.</para> + +</simplesect> + + +<simplesect> + +<title>Restricting access</title> + +<para>To limit which users can perform Nix operations, you can use the +permissions on the directory +<filename>/nix/var/nix/daemon-socket</filename>. For instance, if you +want to restrict the use of Nix to the members of a group called +<literal>nix-users</literal>, do + +<screen> +$ chgrp nix-users /nix/var/nix/daemon-socket +$ chmod ug=rwx,o= /nix/var/nix/daemon-socket +</screen> + +This way, users who are not in the <literal>nix-users</literal> group +cannot connect to the Unix domain socket +<filename>/nix/var/nix/daemon-socket/socket</filename>, so they cannot +perform Nix operations.</para> + +</simplesect> + + +</section> + +</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 <(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 && + nix-env -iA nixpkgs.nix && + launchctl remove org.nixos.nix-daemon && + launchctl load /Library/LaunchDaemons/org.nixos.nix-daemon.plist'</command> + </para> + + + <para> + Single-user installations of Nix should run this: + <command>nix-channel --update; nix-env -iA nixpkgs.nix nixpkgs.cacert</command> + </para> + + <para> + Multi-user Nix users on Linux should run this with sudo: + <command>nix-channel --update; nix-env -iA nixpkgs.nix nixpkgs.cacert; systemctl daemon-reload; systemctl restart nix-daemon</command> + </para> +</chapter> + <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 “user’s” perspective of the Nix system — people +who want to <emphasis>create</emphasis> packages should consult +<xref linkend="chap-writing-nix-expressions"/>.</para> +</partintro> + +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-basic-package-mgmt"> + +<title>Basic Package Management</title> + +<para>The main command for package management is <link linkend="sec-nix-env"><command>nix-env</command></link>. You can use +it to install, upgrade, and erase packages, and to query what +packages are installed or are available for installation.</para> + +<para>In Nix, different users can have different “views” +on the set of installed applications. That is, there might be lots of +applications present on the system (possibly in many different +versions), but users can have a specific selection of those active — +where “active” just means that it appears in a directory +in the user’s <envar>PATH</envar>. Such a view on the set of +installed applications is called a <emphasis>user +environment</emphasis>, which is just a directory tree consisting of +symlinks to the files of the active applications. </para> + +<para>Components are installed from a set of <emphasis>Nix +expressions</emphasis> that tell Nix how to build those packages, +including, if necessary, their dependencies. There is a collection of +Nix expressions called the Nixpkgs package collection that contains +packages ranging from basic development stuff such as GCC and Glibc, +to end-user applications like Mozilla Firefox. (Nix is however not +tied to the Nixpkgs package collection; you could write your own Nix +expressions based on Nixpkgs, or completely new ones.)</para> + +<para>You can manually download the latest version of Nixpkgs from +<link xlink:href="http://nixos.org/nixpkgs/download.html"/>. However, +it’s much more convenient to use the Nixpkgs +<emphasis>channel</emphasis>, since it makes it easy to stay up to +date with new versions of Nixpkgs. (Channels are described in more +detail in <xref linkend="sec-channels"/>.) Nixpkgs is automatically +added to your list of “subscribed” channels when you install +Nix. If this is not the case for some reason, you can add it as +follows: + +<screen> +$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable +$ nix-channel --update +</screen> + +</para> + +<note><para>On NixOS, you’re automatically subscribed to a NixOS +channel corresponding to your NixOS major release +(e.g. <uri>http://nixos.org/channels/nixos-14.12</uri>). A NixOS +channel is identical to the Nixpkgs channel, except that it contains +only Linux binaries and is updated only if a set of regression tests +succeed.</para></note> + +<para>You can view the set of available packages in Nixpkgs: + +<screen> +$ nix-env -qa +aterm-2.2 +bash-3.0 +binutils-2.15 +bison-1.875d +blackdown-1.4.2 +bzip2-1.0.2 +…</screen> + +The flag <option>-q</option> specifies a query operation, and +<option>-a</option> means that you want to show the “available” (i.e., +installable) packages, as opposed to the installed packages. If you +downloaded Nixpkgs yourself, or if you checked it out from GitHub, +then you need to pass the path to your Nixpkgs tree using the +<option>-f</option> flag: + +<screen> +$ nix-env -qaf <replaceable>/path/to/nixpkgs</replaceable> +</screen> + +where <replaceable>/path/to/nixpkgs</replaceable> is where you’ve +unpacked or checked out Nixpkgs.</para> + +<para>You can select specific packages by name: + +<screen> +$ nix-env -qa firefox +firefox-34.0.5 +firefox-with-plugins-34.0.5 +</screen> + +and using regular expressions: + +<screen> +$ nix-env -qa 'firefox.*' +</screen> + +</para> + +<para>It is also possible to see the <emphasis>status</emphasis> of +available packages, i.e., whether they are installed into the user +environment and/or present in the system: + +<screen> +$ nix-env -qas +… +-PS bash-3.0 +--S binutils-2.15 +IPS bison-1.875d +…</screen> + +The first character (<literal>I</literal>) indicates whether the +package is installed in your current user environment. The second +(<literal>P</literal>) indicates whether it is present on your system +(in which case installing it into your user environment would be a +very quick operation). The last one (<literal>S</literal>) indicates +whether there is a so-called <emphasis>substitute</emphasis> for the +package, which is Nix’s mechanism for doing binary deployment. It +just means that Nix knows that it can fetch a pre-built package from +somewhere (typically a network server) instead of building it +locally.</para> + +<para>You can install a package using <literal>nix-env -i</literal>. +For instance, + +<screen> +$ nix-env -i subversion</screen> + +will install the package called <literal>subversion</literal> (which +is, of course, the <link xlink:href="http://subversion.tigris.org/">Subversion version +management system</link>).</para> + +<note><para>When you ask Nix to install a package, it will first try +to get it in pre-compiled form from a <emphasis>binary +cache</emphasis>. By default, Nix will use the binary cache +<uri>https://cache.nixos.org</uri>; it contains binaries for most +packages in Nixpkgs. Only if no binary is available in the binary +cache, Nix will build the package from source. So if <literal>nix-env +-i subversion</literal> results in Nix building stuff from source, +then either the package is not built for your platform by the Nixpkgs +build servers, or your version of Nixpkgs is too old or too new. For +instance, if you have a very recent checkout of Nixpkgs, then the +Nixpkgs build servers may not have had a chance to build everything +and upload the resulting binaries to +<uri>https://cache.nixos.org</uri>. The Nixpkgs channel is only +updated after all binaries have been uploaded to the cache, so if you +stick to the Nixpkgs channel (rather than using a Git checkout of the +Nixpkgs tree), you will get binaries for most packages.</para></note> + +<para>Naturally, packages can also be uninstalled: + +<screen> +$ nix-env -e subversion</screen> + +</para> + +<para>Upgrading to a new version is just as easy. If you have a new +release of Nix Packages, you can do: + +<screen> +$ nix-env -u subversion</screen> + +This will <emphasis>only</emphasis> upgrade Subversion if there is a +“newer” version in the new set of Nix expressions, as +defined by some pretty arbitrary rules regarding ordering of version +numbers (which generally do what you’d expect of them). To just +unconditionally replace Subversion with whatever version is in the Nix +expressions, use <parameter>-i</parameter> instead of +<parameter>-u</parameter>; <parameter>-i</parameter> will remove +whatever version is already installed.</para> + +<para>You can also upgrade all packages for which there are newer +versions: + +<screen> +$ nix-env -u</screen> + +</para> + +<para>Sometimes it’s useful to be able to ask what +<command>nix-env</command> would do, without actually doing it. For +instance, to find out what packages would be upgraded by +<literal>nix-env -u</literal>, you can do + +<screen> +$ nix-env -u --dry-run +(dry run; not doing anything) +upgrading `libxslt-1.1.0' to `libxslt-1.1.10' +upgrading `graphviz-1.10' to `graphviz-1.12' +upgrading `coreutils-5.0' to `coreutils-5.2.1'</screen> + +</para> + +</chapter> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-profiles"> + +<title>Profiles</title> + +<para>Profiles and user environments are Nix’s mechanism for +implementing the ability to allow different users to have different +configurations, and to do atomic upgrades and rollbacks. To +understand how they work, it’s useful to know a bit about how Nix +works. In Nix, packages are stored in unique locations in the +<emphasis>Nix store</emphasis> (typically, +<filename>/nix/store</filename>). For instance, a particular version +of the Subversion package might be stored in a directory +<filename>/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/</filename>, +while another version might be stored in +<filename>/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2</filename>. +The long strings prefixed to the directory names are cryptographic +hashes<footnote><para>160-bit truncations of SHA-256 hashes encoded in +a base-32 notation, to be precise.</para></footnote> of +<emphasis>all</emphasis> inputs involved in building the package — +sources, dependencies, compiler flags, and so on. So if two +packages differ in any way, they end up in different locations in +the file system, so they don’t interfere with each other. <xref linkend="fig-user-environments"/> shows a part of a typical Nix +store.</para> + +<figure xml:id="fig-user-environments"><title>User environments</title> + <mediaobject> + <imageobject> + <imagedata fileref="../figures/user-environments.png" format="PNG"/> + </imageobject> + </mediaobject> +</figure> + +<para>Of course, you wouldn’t want to type + +<screen> +$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn</screen> + +every time you want to run Subversion. Of course we could set up the +<envar>PATH</envar> environment variable to include the +<filename>bin</filename> directory of every package we want to use, +but this is not very convenient since changing <envar>PATH</envar> +doesn’t take effect for already existing processes. The solution Nix +uses is to create directory trees of symlinks to +<emphasis>activated</emphasis> packages. These are called +<emphasis>user environments</emphasis> and they are packages +themselves (though automatically generated by +<command>nix-env</command>), so they too reside in the Nix store. For +instance, in <xref linkend="fig-user-environments"/> the user +environment <filename>/nix/store/0c1p5z4kda11...-user-env</filename> +contains a symlink to just Subversion 1.1.2 (arrows in the figure +indicate symlinks). This would be what we would obtain if we had done + +<screen> +$ nix-env -i subversion</screen> + +on a set of Nix expressions that contained Subversion 1.1.2.</para> + +<para>This doesn’t in itself solve the problem, of course; you +wouldn’t want to type +<filename>/nix/store/0c1p5z4kda11...-user-env/bin/svn</filename> +either. That’s why there are symlinks outside of the store that point +to the user environments in the store; for instance, the symlinks +<filename>default-42-link</filename> and +<filename>default-43-link</filename> in the example. These are called +<emphasis>generations</emphasis> since every time you perform a +<command>nix-env</command> operation, a new user environment is +generated based on the current one. For instance, generation 43 was +created from generation 42 when we did + +<screen> +$ nix-env -i subversion firefox</screen> + +on a set of Nix expressions that contained Firefox and a new version +of Subversion.</para> + +<para>Generations are grouped together into +<emphasis>profiles</emphasis> so that different users don’t interfere +with each other if they don’t want to. For example: + +<screen> +$ ls -l /nix/var/nix/profiles/ +... +lrwxrwxrwx 1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env +lrwxrwxrwx 1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env +lrwxrwxrwx 1 eelco ... default -> default-43-link</screen> + +This shows a profile called <filename>default</filename>. The file +<filename>default</filename> itself is actually a symlink that points +to the current generation. When we do a <command>nix-env</command> +operation, a new user environment and generation link are created +based on the current one, and finally the <filename>default</filename> +symlink is made to point at the new generation. This last step is +atomic on Unix, which explains how we can do atomic upgrades. (Note +that the building/installing of new packages doesn’t interfere in +any way with old packages, since they are stored in different +locations in the Nix store.)</para> + +<para>If you find that you want to undo a <command>nix-env</command> +operation, you can just do + +<screen> +$ nix-env --rollback</screen> + +which will just make the current generation link point at the previous +link. E.g., <filename>default</filename> would be made to point at +<filename>default-42-link</filename>. You can also switch to a +specific generation: + +<screen> +$ nix-env --switch-generation 43</screen> + +which in this example would roll forward to generation 43 again. You +can also see all available generations: + +<screen> +$ nix-env --list-generations</screen></para> + +<para>You generally wouldn’t have +<filename>/nix/var/nix/profiles/<replaceable>some-profile</replaceable>/bin</filename> +in your <envar>PATH</envar>. Rather, there is a symlink +<filename>~/.nix-profile</filename> that points to your current +profile. This means that you should put +<filename>~/.nix-profile/bin</filename> in your <envar>PATH</envar> +(and indeed, that’s what the initialisation script +<filename>/nix/etc/profile.d/nix.sh</filename> does). This makes it +easier to switch to a different profile. You can do that using the +command <command>nix-env --switch-profile</command>: + +<screen> +$ nix-env --switch-profile /nix/var/nix/profiles/my-profile + +$ nix-env --switch-profile /nix/var/nix/profiles/default</screen> + +These commands switch to the <filename>my-profile</filename> and +default profile, respectively. If the profile doesn’t exist, it will +be created automatically. You should be careful about storing a +profile in another location than the <filename>profiles</filename> +directory, since otherwise it might not be used as a root of the +garbage collector (see <xref linkend="sec-garbage-collection"/>).</para> + +<para>All <command>nix-env</command> operations work on the profile +pointed to by <command>~/.nix-profile</command>, but you can override +this using the <option>--profile</option> option (abbreviation +<option>-p</option>): + +<screen> +$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion</screen> + +This will <emphasis>not</emphasis> change the +<command>~/.nix-profile</command> symlink.</para> + +</chapter> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-garbage-collection"> + +<title>Garbage Collection</title> + +<para><command>nix-env</command> operations such as upgrades +(<option>-u</option>) and uninstall (<option>-e</option>) never +actually delete packages from the system. All they do (as shown +above) is to create a new user environment that no longer contains +symlinks to the “deleted” packages.</para> + +<para>Of course, since disk space is not infinite, unused packages +should be removed at some point. You can do this by running the Nix +garbage collector. It will remove from the Nix store any package +not used (directly or indirectly) by any generation of any +profile.</para> + +<para>Note however that as long as old generations reference a +package, it will not be deleted. After all, we wouldn’t be able to +do a rollback otherwise. So in order for garbage collection to be +effective, you should also delete (some) old generations. Of course, +this should only be done if you are certain that you will not need to +roll back.</para> + +<para>To delete all old (non-current) generations of your current +profile: + +<screen> +$ nix-env --delete-generations old</screen> + +Instead of <literal>old</literal> you can also specify a list of +generations, e.g., + +<screen> +$ nix-env --delete-generations 10 11 14</screen> + +To delete all generations older than a specified number of days +(except the current generation), use the <literal>d</literal> +suffix. For example, + +<screen> +$ nix-env --delete-generations 14d</screen> + +deletes all generations older than two weeks.</para> + +<para>After removing appropriate old generations you can run the +garbage collector as follows: + +<screen> +$ nix-store --gc</screen> + +The behaviour of the gargage collector is affected by the +<literal>keep-derivations</literal> (default: true) and <literal>keep-outputs</literal> +(default: false) options in the Nix configuration file. The defaults will ensure +that all derivations that are build-time dependencies of garbage collector roots +will be kept and that all output paths that are runtime dependencies +will be kept as well. All other derivations or paths will be collected. +(This is usually what you want, but while you are developing +it may make sense to keep outputs to ensure that rebuild times are quick.) + +If you are feeling uncertain, you can also first view what files would +be deleted: + +<screen> +$ nix-store --gc --print-dead</screen> + +Likewise, the option <option>--print-live</option> will show the paths +that <emphasis>won’t</emphasis> be deleted.</para> + +<para>There is also a convenient little utility +<command>nix-collect-garbage</command>, which when invoked with the +<option>-d</option> (<option>--delete-old</option>) switch deletes all +old generations of all profiles in +<filename>/nix/var/nix/profiles</filename>. So + +<screen> +$ nix-collect-garbage -d</screen> + +is a quick and easy way to clean up your system.</para> + +<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’s not +very convenient to manually download the latest set of Nix expressions +for those packages and upgrade using <command>nix-env</command>. +Fortunately, there’s a better way: <emphasis>Nix +channels</emphasis>.</para> + +<para>A Nix channel is just a URL that points to a place that contains +a set of Nix expressions and a manifest. Using the command <link linkend="sec-nix-channel"><command>nix-channel</command></link> you +can automatically stay up to date with whatever is available at that +URL.</para> + +<para>To see the list of official NixOS channels, visit <link xlink:href="https://nixos.org/channels"/>.</para> + +<para>You can “subscribe” to a channel using +<command>nix-channel --add</command>, e.g., + +<screen> +$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable</screen> + +subscribes you to a channel that always contains that latest version +of the Nix Packages collection. (Subscribing really just means that +the URL is added to the file <filename>~/.nix-channels</filename>, +where it is read by subsequent calls to <command>nix-channel +--update</command>.) You can “unsubscribe” using <command>nix-channel +--remove</command>: + +<screen> +$ nix-channel --remove nixpkgs +</screen> +</para> + +<para>To obtain the latest Nix expressions available in a channel, do + +<screen> +$ nix-channel --update</screen> + +This downloads and unpacks the Nix expressions in every channel +(downloaded from <literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal>). +It also makes the union of each channel’s Nix expressions available by +default to <command>nix-env</command> operations (via the symlink +<filename>~/.nix-defexpr/channels</filename>). Consequently, you can +then say + +<screen> +$ nix-env -u</screen> + +to upgrade all packages in your profile to the latest versions +available in the subscribed channels.</para> + +</chapter> +<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’t copy store paths that are already +present on the target machine. For example, the following command +copies Firefox with all its dependencies: + +<screen> +$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)</screen> + +See <xref linkend="sec-nix-copy-closure"/> for details.</para> + +<para>With <command linkend="refsec-nix-store-export">nix-store +--export</command> and <command linkend="refsec-nix-store-import">nix-store --import</command> you can +write the closure of a store path (that is, the path and all its +dependencies) to a file, and then unpack that file into another Nix +store. For example, + +<screen> +$ nix-store --export $(nix-store -qR $(type -p firefox)) > firefox.closure</screen> + +writes the closure of Firefox to a file. You can then copy this file +to another machine and install the closure: + +<screen> +$ nix-store --import < firefox.closure</screen> + +Any store paths in the closure that are already present in the target +store are ignored. It is also possible to pipe the export into +another command, e.g. to copy and install a closure directly to/on +another machine: + +<screen> +$ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \ + ssh alice@itchy.example.org "bunzip2 | nix-store --import"</screen> + +However, <command>nix-copy-closure</command> is generally more +efficient because it only copies paths that are not already present in +the target Nix store.</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-ssh-substituter"> + +<title>Serving a Nix store via SSH</title> + +<para>You can tell Nix to automatically fetch needed binaries from a +remote Nix store via SSH. For example, the following installs Firefox, +automatically fetching any store paths in Firefox’s closure if they +are available on the server <literal>avalon</literal>: + +<screen> +$ nix-env -i firefox --substituters ssh://alice@avalon +</screen> + +This works similar to the binary cache substituter that Nix usually +uses, only using SSH instead of HTTP: if a store path +<literal>P</literal> is needed, Nix will first check if it’s available +in the Nix store on <literal>avalon</literal>. If not, it will fall +back to using the binary cache substituter, and then to building from +source.</para> + +<note><para>The SSH substituter currently does not allow you to enter +an SSH passphrase interactively. Therefore, you should use +<command>ssh-add</command> to load the decrypted private key into +<command>ssh-agent</command>.</para></note> + +<para>You can also copy the closure of some store path, without +installing it into your profile, e.g. + +<screen> +$ nix-store -r /nix/store/m85bxg…-firefox-34.0.5 --substituters ssh://alice@avalon +</screen> + +This is essentially equivalent to doing + +<screen> +$ nix-copy-closure --from alice@avalon /nix/store/m85bxg…-firefox-34.0.5 +</screen> + +</para> + +<para>You can use SSH’s <emphasis>forced command</emphasis> feature to +set up a restricted user account for SSH substituter access, allowing +read-only access to the local Nix store, but nothing more. For +example, add the following lines to <filename>sshd_config</filename> +to restrict the user <literal>nix-ssh</literal>: + +<programlisting> +Match User nix-ssh + AllowAgentForwarding no + AllowTcpForwarding no + PermitTTY no + PermitTunnel no + X11Forwarding no + ForceCommand nix-store --serve +Match All +</programlisting> + +On NixOS, you can accomplish the same by adding the following to your +<filename>configuration.nix</filename>: + +<programlisting> +nix.sshServe.enable = true; +nix.sshServe.keys = [ "ssh-dss AAAAB3NzaC1k... bob@example.org" ]; +</programlisting> + +where the latter line lists the public keys of users that are allowed +to connect.</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-s3-substituter"> + +<title>Serving a Nix store via AWS S3 or S3-compatible Service</title> + +<para>Nix has built-in support for storing and fetching store paths +from Amazon S3 and S3 compatible services. This uses the same +<emphasis>binary</emphasis> cache mechanism that Nix usually uses to +fetch prebuilt binaries from <uri>cache.nixos.org</uri>.</para> + +<para>The following options can be specified as URL parameters to +the S3 URL:</para> + +<variablelist> + <varlistentry><term><literal>profile</literal></term> + <listitem> + <para> + The name of the AWS configuration profile to use. By default + Nix will use the <literal>default</literal> profile. + </para> + </listitem> + </varlistentry> + + <varlistentry><term><literal>region</literal></term> + <listitem> + <para> + The region of the S3 bucket. <literal>us–east-1</literal> by + default. + </para> + + <para> + If your bucket is not in <literal>us–east-1</literal>, you + should always explicitly specify the region parameter. + </para> + </listitem> + </varlistentry> + + <varlistentry><term><literal>endpoint</literal></term> + <listitem> + <para> + The URL to your S3-compatible service, for when not using + Amazon S3. Do not specify this value if you're using Amazon + S3. + </para> + <note><para>This endpoint must support HTTPS and will use + path-based addressing instead of virtual host based + addressing.</para></note> + </listitem> + </varlistentry> + + <varlistentry><term><literal>scheme</literal></term> + <listitem> + <para> + The scheme used for S3 requests, <literal>https</literal> + (default) or <literal>http</literal>. This option allows you to + disable HTTPS for binary caches which don't support it. + </para> + <note><para>HTTPS should be used if the cache might contain + sensitive information.</para></note> + </listitem> + </varlistentry> +</variablelist> + +<para>In this example we will use the bucket named +<literal>example-nix-cache</literal>.</para> + +<section xml:id="ssec-s3-substituter-anonymous-reads"> + <title>Anonymous Reads to your S3-compatible binary cache</title> + + <para>If your binary cache is publicly accessible and does not + require authentication, the simplest and easiest way to use Nix with + your S3 compatible binary cache is to use the HTTP URL for that + cache.</para> + + <para>For AWS S3 the binary cache URL for example bucket will be + exactly <uri>https://example-nix-cache.s3.amazonaws.com</uri> or + <uri>s3://example-nix-cache</uri>. For S3 compatible binary caches, + consult that cache's documentation.</para> + + <para>Your bucket will need the following bucket policy:</para> + + <programlisting><![CDATA[ +{ + "Id": "DirectReads", + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "AllowDirectReads", + "Action": [ + "s3:GetObject", + "s3:GetBucketLocation" + ], + "Effect": "Allow", + "Resource": [ + "arn:aws:s3:::example-nix-cache", + "arn:aws:s3:::example-nix-cache/*" + ], + "Principal": "*" + } + ] +} +]]></programlisting> +</section> + +<section xml:id="ssec-s3-substituter-authenticated-reads"> + <title>Authenticated Reads to your S3 binary cache</title> + + <para>For AWS S3 the binary cache URL for example bucket will be + exactly <uri>s3://example-nix-cache</uri>.</para> + + <para>Nix will use the <link xlink:href="https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html">default + credential provider chain</link> for authenticating requests to + Amazon S3.</para> + + <para>Nix supports authenticated reads from Amazon S3 and S3 + compatible binary caches.</para> + + <para>Your bucket will need a bucket policy allowing the desired + users to perform the <literal>s3:GetObject</literal> and + <literal>s3:GetBucketLocation</literal> action on all objects in the + bucket. The anonymous policy in <xref linkend="ssec-s3-substituter-anonymous-reads"/> can be updated to + have a restricted <literal>Principal</literal> to support + this.</para> +</section> + + +<section xml:id="ssec-s3-substituter-authenticated-writes"> + <title>Authenticated Writes to your S3-compatible binary cache</title> + + <para>Nix support fully supports writing to Amazon S3 and S3 + compatible buckets. The binary cache URL for our example bucket will + be <uri>s3://example-nix-cache</uri>.</para> + + <para>Nix will use the <link xlink:href="https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html">default + credential provider chain</link> for authenticating requests to + Amazon S3.</para> + + <para>Your account will need the following IAM policy to + upload to the cache:</para> + + <programlisting><![CDATA[ +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "UploadToCache", + "Effect": "Allow", + "Action": [ + "s3:AbortMultipartUpload", + "s3:GetBucketLocation", + "s3:GetObject", + "s3:ListBucket", + "s3:ListBucketMultipartUploads", + "s3:ListMultipartUploadParts", + "s3:PutObject" + ], + "Resource": [ + "arn:aws:s3:::example-nix-cache", + "arn:aws:s3:::example-nix-cache/*" + ] + } + ] +} +]]></programlisting> + + + <example><title>Uploading with a specific credential profile for Amazon S3</title> + <para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&region=eu-west-2' nixpkgs.hello</command></para> + </example> + + <example><title>Uploading to an S3-Compatible Binary Cache</title> + <para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' nixpkgs.hello</command></para> + </example> +</section> +</section> + +</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 -> /nix/store/632d2b22514d...-hello-2.1.1 + +$ ./result/bin/hello +Hello, world!</screen> + +The <link linkend="opt-attr"><option>-A</option></link> option selects +the <literal>hello</literal> attribute. This is faster than using the +symbolic package name specified by the <literal>name</literal> +attribute (which also happens to be <literal>hello</literal>) and is +unambiguous (there can be multiple packages with the symbolic name +<literal>hello</literal>, but there can be only one attribute in a set +named <literal>hello</literal>).</para> + +<para><command>nix-build</command> registers the +<filename>./result</filename> symlink as a garbage collection root, so +unless and until you delete the <filename>./result</filename> symlink, +the output of the build will be safely kept on your system. You can +use <command>nix-build</command>’s <option linkend="opt-out-link">-o</option> switch to give the symlink another +name.</para> + +<para>Nix has transactional semantics. Once a build finishes +successfully, Nix makes a note of this in its database: it registers +that the path denoted by <envar>out</envar> is now +<quote>valid</quote>. If you try to build the derivation again, Nix +will see that the path is already valid and finish immediately. If a +build fails, either because it returns a non-zero exit code, because +Nix or the builder are killed, or because the machine crashes, then +the output paths will not be registered as valid. If you try to build +the derivation again, Nix will remove the output paths if they exist +(e.g., because the builder died half-way through <literal>make +install</literal>) and try again. Note that there is no +<quote>negative caching</quote>: Nix doesn't remember that a build +failed, and so a failed build can always be repeated. This is because +Nix cannot distinguish between permanent failures (e.g., a compiler +error due to a syntax error in the source) and transient failures +(e.g., a disk full condition).</para> + +<para>Nix also performs locking. If you run multiple Nix builds +simultaneously, and they try to build the same derivation, the first +Nix instance that gets there will perform the build, while the others +block (or perform other derivations if available) until the build +finishes: + +<screen> +$ nix-build -A hello +waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x'</screen> + +So it is always safe to run multiple instances of Nix in parallel +(which isn’t the case with, say, <command>make</command>).</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-generic-builder"> + +<title>Generic Builder Syntax</title> + +<para>Recall from <xref linkend="ex-hello-builder"/> that the builder +looked something like this: + +<programlisting> +PATH=$perl/bin:$PATH +tar xvfz $src +cd hello-* +./configure --prefix=$out +make +make install</programlisting> + +The builders for almost all Unix packages look like this — set up some +environment variables, unpack the sources, configure, build, and +install. For this reason the standard environment provides some Bash +functions that automate the build process. A builder using the +generic build facilities in shown in <xref linkend="ex-hello-builder2"/>.</para> + +<example xml:id="ex-hello-builder2"><title>Build script using the generic +build functions</title> +<programlisting> +buildInputs="$perl" <co xml:id="ex-hello-builder2-co-1"/> + +source $stdenv/setup <co xml:id="ex-hello-builder2-co-2"/> + +genericBuild <co xml:id="ex-hello-builder2-co-3"/></programlisting> +</example> + +<calloutlist> + + <callout arearefs="ex-hello-builder2-co-1"> + + <para>The <envar>buildInputs</envar> variable tells + <filename>setup</filename> to use the indicated packages as + <quote>inputs</quote>. This means that if a package provides a + <filename>bin</filename> subdirectory, it's added to + <envar>PATH</envar>; if it has a <filename>include</filename> + subdirectory, it's added to GCC's header search path; and so + on.<footnote><para>How does it work? <filename>setup</filename> + tries to source the file + <filename><replaceable>pkg</replaceable>/nix-support/setup-hook</filename> + of all dependencies. These “setup hooks” can then set up whatever + environment variables they want; for instance, the setup hook for + Perl sets the <envar>PERL5LIB</envar> environment variable to + contain the <filename>lib/site_perl</filename> directories of all + inputs.</para></footnote> + </para> + + </callout> + + <callout arearefs="ex-hello-builder2-co-2"> + + <para>The function <function>genericBuild</function> is defined in + the file <literal>$stdenv/setup</literal>.</para> + + </callout> + + <callout arearefs="ex-hello-builder2-co-3"> + + <para>The final step calls the shell function + <function>genericBuild</function>, which performs the steps that + were done explicitly in <xref linkend="ex-hello-builder"/>. The + generic builder is smart enough to figure out whether to unpack + the sources using <command>gzip</command>, + <command>bzip2</command>, etc. It can be customised in many ways; + see the Nixpkgs manual for details.</para> + + </callout> + +</calloutlist> + +<para>Discerning readers will note that the +<envar>buildInputs</envar> could just as well have been set in the Nix +expression, like this: + +<programlisting> + buildInputs = [ perl ];</programlisting> + +The <varname>perl</varname> attribute can then be removed, and the +builder becomes even shorter: + +<programlisting> +source $stdenv/setup +genericBuild</programlisting> + +In fact, <varname>mkDerivation</varname> provides a default builder +that looks exactly like that, so it is actually possible to omit the +builder for Hello entirely.</para> + +</section> + +</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" > $out/etc/foo.conf + ${if enableBar then "cp bar $out/bin" else ""} + ''; + <replaceable>...</replaceable> +} +</programlisting> + + </para> + + <para>Finally, as a convenience, <emphasis>URIs</emphasis> as + defined in appendix B of <link xlink:href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</link> + can be written <emphasis>as is</emphasis>, without quotes. For + instance, the string + <literal>"http://example.org/foo.tar.bz2"</literal> + can also be written as + <literal>http://example.org/foo.tar.bz2</literal>.</para> + + </listitem> + + <listitem><para>Numbers, which can be <emphasis>integers</emphasis> (like + <literal>123</literal>) or <emphasis>floating point</emphasis> (like + <literal>123.43</literal> or <literal>.27e13</literal>).</para> + + <para>Numbers are type-compatible: pure integer operations will always + return integers, whereas any operation involving at least one floating point + number will have a floating point number as a result.</para></listitem> + + <listitem><para><emphasis>Paths</emphasis>, e.g., + <filename>/bin/sh</filename> or <filename>./builder.sh</filename>. + A path must contain at least one slash to be recognised as such; for + instance, <filename>builder.sh</filename> is not a + path<footnote><para>It's parsed as an expression that selects the + attribute <varname>sh</varname> from the variable + <varname>builder</varname>.</para></footnote>. If the file name is + relative, i.e., if it does not begin with a slash, it is made + absolute at parse time relative to the directory of the Nix + expression that contained it. For instance, if a Nix expression in + <filename>/foo/bar/bla.nix</filename> refers to + <filename>../xyzzy/fnord.nix</filename>, the absolute path is + <filename>/foo/xyzzy/fnord.nix</filename>.</para> + + <para>If the first component of a path is a <literal>~</literal>, + it is interpreted as if the rest of the path were relative to the + user's home directory. e.g. <filename>~/foo</filename> would be + equivalent to <filename>/home/edolstra/foo</filename> for a user + whose home directory is <filename>/home/edolstra</filename>. + </para> + + <para>Paths can also be specified between angle brackets, e.g. + <literal><nixpkgs></literal>. This means that the directories + listed in the environment variable + <envar linkend="env-NIX_PATH">NIX_PATH</envar> will be searched + for the given file or directory name. + </para> + + </listitem> + + <listitem><para><emphasis>Booleans</emphasis> with values + <literal>true</literal> and + <literal>false</literal>.</para></listitem> + + <listitem><para>The null value, denoted as + <literal>null</literal>.</para></listitem> + +</itemizedlist> + +</para> + +</simplesect> + + +<simplesect><title>Lists</title> + +<para>Lists are formed by enclosing a whitespace-separated list of +values between square brackets. For example, + +<programlisting> +[ 123 ./foo.nix "abc" (f { x = y; }) ]</programlisting> + +defines a list of four elements, the last being the result of a call +to the function <varname>f</varname>. Note that function calls have +to be enclosed in parentheses. If they had been omitted, e.g., + +<programlisting> +[ 123 ./foo.nix "abc" f { x = y; } ]</programlisting> + +the result would be a list of five elements, the fourth one being a +function and the fifth being a set.</para> + +<para>Note that lists are only lazy in values, and they are strict in length. +</para> + +</simplesect> + + +<simplesect><title>Sets</title> + +<para>Sets are really the core of the language, since ultimately the +Nix language is all about creating derivations, which are really just +sets of attributes to be passed to build scripts.</para> + +<para>Sets are just a list of name/value pairs (called +<emphasis>attributes</emphasis>) enclosed in curly brackets, where +each value is an arbitrary expression terminated by a semicolon. For +example: + +<programlisting> +{ x = 123; + text = "Hello"; + y = f { bla = 456; }; +}</programlisting> + +This defines a set with attributes named <varname>x</varname>, +<varname>text</varname>, <varname>y</varname>. The order of the +attributes is irrelevant. An attribute name may only occur +once.</para> + +<para>Attributes can be selected from a set using the +<literal>.</literal> operator. For instance, + +<programlisting> +{ a = "Foo"; b = "Bar"; }.a</programlisting> + +evaluates to <literal>"Foo"</literal>. It is possible to provide a +default value in an attribute selection using the +<literal>or</literal> keyword. For example, + +<programlisting> +{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"</programlisting> + +will evaluate to <literal>"Xyzzy"</literal> because there is no +<varname>c</varname> attribute in the set.</para> + +<para>You can use arbitrary double-quoted strings as attribute +names: + +<programlisting> +{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}" +</programlisting> + +This will evaluate to <literal>123</literal> (Assuming +<literal>bar</literal> is antiquotable). In the case where an +attribute name is just a single antiquotation, the quotes can be +dropped: + +<programlisting> +{ foo = 123; }.${bar} or 456 </programlisting> + +This will evaluate to <literal>123</literal> if +<literal>bar</literal> evaluates to <literal>"foo"</literal> when +coerced to a string and <literal>456</literal> otherwise (again +assuming <literal>bar</literal> is antiquotable).</para> + +<para>In the special case where an attribute name inside of a set declaration +evaluates to <literal>null</literal> (which is normally an error, as +<literal>null</literal> is not antiquotable), that attribute is simply not +added to the set: + +<programlisting> +{ ${if foo then "bar" else null} = true; }</programlisting> + +This will evaluate to <literal>{}</literal> if <literal>foo</literal> +evaluates to <literal>false</literal>.</para> + +<para>A set that has a <literal>__functor</literal> attribute whose value +is callable (i.e. is itself a function or a set with a +<literal>__functor</literal> attribute whose value is callable) can be +applied as if it were a function, with the set itself passed in first +, e.g., + +<programlisting> +let add = { __functor = self: x: x + self.x; }; + inc = add // { x = 1; }; +in inc 1 +</programlisting> + +evaluates to <literal>2</literal>. This can be used to attach metadata to a +function without the caller needing to treat it specially, or to implement +a form of object-oriented programming, for example. + +</para> + +</simplesect> + + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-constructs"> + +<title>Language Constructs</title> + +<simplesect><title>Recursive sets</title> + +<para>Recursive sets are just normal sets, but the attributes can +refer to each other. For example, + +<programlisting> +rec { + x = y; + y = 123; +}.x +</programlisting> + +evaluates to <literal>123</literal>. Note that without +<literal>rec</literal> the binding <literal>x = y;</literal> would +refer to the variable <varname>y</varname> in the surrounding scope, +if one exists, and would be invalid if no such variable exists. That +is, in a normal (non-recursive) set, attributes are not added to the +lexical scope; in a recursive set, they are.</para> + +<para>Recursive sets of course introduce the danger of infinite +recursion. For example, + +<programlisting> +rec { + x = y; + y = x; +}.x</programlisting> + +does not terminate<footnote><para>Actually, Nix detects infinite +recursion in this case and aborts (<quote>infinite recursion +encountered</quote>).</para></footnote>.</para> + +</simplesect> + + +<simplesect xml:id="sect-let-expressions"><title>Let-expressions</title> + +<para>A let-expression allows you to define local variables for an +expression. For instance, + +<programlisting> +let + x = "foo"; + y = "bar"; +in x + y</programlisting> + +evaluates to <literal>"foobar"</literal>. + +</para> + +</simplesect> + + +<simplesect><title>Inheriting attributes</title> + +<para>When defining a set or in a let-expression it is often convenient to copy variables +from the surrounding lexical scope (e.g., when you want to propagate +attributes). This can be shortened using the +<literal>inherit</literal> keyword. For instance, + +<programlisting> +let x = 123; in +{ inherit x; + y = 456; +}</programlisting> + +is equivalent to + +<programlisting> +let x = 123; in +{ x = x; + y = 456; +}</programlisting> + +and both evaluate to <literal>{ x = 123; y = 456; }</literal>. (Note that +this works because <varname>x</varname> is added to the lexical scope +by the <literal>let</literal> construct.) It is also possible to +inherit attributes from another set. For instance, in this fragment +from <filename>all-packages.nix</filename>, + +<programlisting> + graphviz = (import ../tools/graphics/graphviz) { + inherit fetchurl stdenv libpng libjpeg expat x11 yacc; + inherit (xlibs) libXaw; + }; + + xlibs = { + libX11 = ...; + libXaw = ...; + ... + } + + libpng = ...; + libjpg = ...; + ...</programlisting> + +the set used in the function call to the function defined in +<filename>../tools/graphics/graphviz</filename> inherits a number of +variables from the surrounding scope (<varname>fetchurl</varname> +... <varname>yacc</varname>), but also inherits +<varname>libXaw</varname> (the X Athena Widgets) from the +<varname>xlibs</varname> (X11 client-side libraries) set.</para> + +<para> +Summarizing the fragment + +<programlisting> +... +inherit x y z; +inherit (src-set) a b c; +...</programlisting> + +is equivalent to + +<programlisting> +... +x = x; y = y; z = z; +a = src-set.a; b = src-set.b; c = src-set.c; +...</programlisting> + +when used while defining local variables in a let-expression or +while defining a set.</para> + +</simplesect> + + +<simplesect xml:id="ss-functions"><title>Functions</title> + +<para>Functions have the following form: + +<programlisting> +<replaceable>pattern</replaceable>: <replaceable>body</replaceable></programlisting> + +The pattern specifies what the argument of the function must look +like, and binds variables in the body to (parts of) the +argument. There are three kinds of patterns:</para> + +<itemizedlist> + + + <listitem><para>If a pattern is a single identifier, then the + function matches any argument. Example: + + <programlisting> +let negate = x: !x; + concat = x: y: x + y; +in if negate true then concat "foo" "bar" else ""</programlisting> + + Note that <function>concat</function> is a function that takes one + argument and returns a function that takes another argument. This + allows partial parameterisation (i.e., only filling some of the + arguments of a function); e.g., + + <programlisting> +map (concat "foo") [ "bar" "bla" "abc" ]</programlisting> + + evaluates to <literal>[ "foobar" "foobla" + "fooabc" ]</literal>.</para></listitem> + + + <listitem><para>A <emphasis>set pattern</emphasis> of the form + <literal>{ name1, name2, …, nameN }</literal> matches a set + containing the listed attributes, and binds the values of those + attributes to variables in the function body. For example, the + function + +<programlisting> +{ x, y, z }: z + y + x</programlisting> + + can only be called with a set containing exactly the attributes + <varname>x</varname>, <varname>y</varname> and + <varname>z</varname>. No other attributes are allowed. If you want + to allow additional arguments, you can use an ellipsis + (<literal>...</literal>): + +<programlisting> +{ x, y, z, ... }: z + y + x</programlisting> + + This works on any set that contains at least the three named + attributes.</para> + + <para>It is possible to provide <emphasis>default values</emphasis> + for attributes, in which case they are allowed to be missing. A + default value is specified by writing + <literal><replaceable>name</replaceable> ? + <replaceable>e</replaceable></literal>, where + <replaceable>e</replaceable> is an arbitrary expression. For example, + +<programlisting> +{ x, y ? "foo", z ? "bar" }: z + y + x</programlisting> + + specifies a function that only requires an attribute named + <varname>x</varname>, but optionally accepts <varname>y</varname> + and <varname>z</varname>.</para></listitem> + + + <listitem><para>An <literal>@</literal>-pattern provides a means of referring + to the whole value being matched: + +<programlisting> args@{ x, y, z, ... }: z + y + x + args.a</programlisting> + +but can also be written as: + +<programlisting> { x, y, z, ... } @ args: z + y + x + args.a</programlisting> + + Here <varname>args</varname> is bound to the entire argument, which + is further matched against the pattern <literal>{ x, y, z, + ... }</literal>. <literal>@</literal>-pattern makes mainly sense with an + ellipsis(<literal>...</literal>) as you can access attribute names as + <literal>a</literal>, using <literal>args.a</literal>, which was given as an + additional attribute to the function. + </para> + + <warning> + <para> + The <literal>args@</literal> expression is bound to the argument passed to the function which + means that attributes with defaults that aren't explicitly specified in the function call + won't cause an evaluation error, but won't exist in <literal>args</literal>. + </para> + <para> + For instance +<programlisting> +let + function = args@{ a ? 23, ... }: args; +in + function {} +</programlisting> + will evaluate to an empty attribute set. + </para> + </warning></listitem> + +</itemizedlist> + +<para>Note that functions do not have names. If you want to give them +a name, you can bind them to an attribute, e.g., + +<programlisting> +let concat = { x, y }: x + y; +in concat { x = "foo"; y = "bar"; }</programlisting> + +</para> + +</simplesect> + + +<simplesect><title>Conditionals</title> + +<para>Conditionals look like this: + +<programlisting> +if <replaceable>e1</replaceable> then <replaceable>e2</replaceable> else <replaceable>e3</replaceable></programlisting> + +where <replaceable>e1</replaceable> is an expression that should +evaluate to a Boolean value (<literal>true</literal> or +<literal>false</literal>).</para> + +</simplesect> + + +<simplesect><title>Assertions</title> + +<para>Assertions are generally used to check that certain requirements +on or between features and dependencies hold. They look like this: + +<programlisting> +assert <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting> + +where <replaceable>e1</replaceable> is an expression that should +evaluate to a Boolean value. If it evaluates to +<literal>true</literal>, <replaceable>e2</replaceable> is returned; +otherwise expression evaluation is aborted and a backtrace is printed.</para> + +<example xml:id="ex-subversion-nix"><title>Nix expression for Subversion</title> +<programlisting> +{ localServer ? false +, httpServer ? false +, sslSupport ? false +, pythonBindings ? false +, javaSwigBindings ? false +, javahlBindings ? false +, stdenv, fetchurl +, openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null +}: + +assert localServer -> db4 != null; <co xml:id="ex-subversion-nix-co-1"/> +assert httpServer -> httpd != null && httpd.expat == expat; <co xml:id="ex-subversion-nix-co-2"/> +assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); <co xml:id="ex-subversion-nix-co-3"/> +assert pythonBindings -> swig != null && swig.pythonSupport; +assert javaSwigBindings -> swig != null && swig.javaSupport; +assert javahlBindings -> j2sdk != null; + +stdenv.mkDerivation { + name = "subversion-1.1.1"; + ... + openssl = if sslSupport then openssl else null; <co xml:id="ex-subversion-nix-co-4"/> + ... +}</programlisting> +</example> + +<para><xref linkend="ex-subversion-nix"/> show how assertions are +used in the Nix expression for Subversion.</para> + +<calloutlist> + + <callout arearefs="ex-subversion-nix-co-1"> + <para>This assertion states that if Subversion is to have support + for local repositories, then Berkeley DB is needed. So if the + Subversion function is called with the + <varname>localServer</varname> argument set to + <literal>true</literal> but the <varname>db4</varname> argument + set to <literal>null</literal>, then the evaluation fails.</para> + </callout> + + <callout arearefs="ex-subversion-nix-co-2"> + <para>This is a more subtle condition: if Subversion is built with + Apache (<literal>httpServer</literal>) support, then the Expat + library (an XML library) used by Subversion should be same as the + one used by Apache. This is because in this configuration + Subversion code ends up being linked with Apache code, and if the + Expat libraries do not match, a build- or runtime link error or + incompatibility might occur.</para> + </callout> + + <callout arearefs="ex-subversion-nix-co-3"> + <para>This assertion says that in order for Subversion to have SSL + support (so that it can access <literal>https</literal> URLs), an + OpenSSL library must be passed. Additionally, it says that + <emphasis>if</emphasis> Apache support is enabled, then Apache's + OpenSSL should match Subversion's. (Note that if Apache support + is not enabled, we don't care about Apache's OpenSSL.)</para> + </callout> + + <callout arearefs="ex-subversion-nix-co-4"> + <para>The conditional here is not really related to assertions, + but is worth pointing out: it ensures that if SSL support is + disabled, then the Subversion derivation is not dependent on + OpenSSL, even if a non-<literal>null</literal> value was passed. + This prevents an unnecessary rebuild of Subversion if OpenSSL + changes.</para> + </callout> + +</calloutlist> + +</simplesect> + + + +<simplesect><title>With-expressions</title> + +<para>A <emphasis>with-expression</emphasis>, + +<programlisting> +with <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting> + +introduces the set <replaceable>e1</replaceable> into the lexical +scope of the expression <replaceable>e2</replaceable>. For instance, + +<programlisting> +let as = { x = "foo"; y = "bar"; }; +in with as; x + y</programlisting> + +evaluates to <literal>"foobar"</literal> since the +<literal>with</literal> adds the <varname>x</varname> and +<varname>y</varname> attributes of <varname>as</varname> to the +lexical scope in the expression <literal>x + y</literal>. The most +common use of <literal>with</literal> is in conjunction with the +<function>import</function> function. E.g., + +<programlisting> +with (import ./definitions.nix); ...</programlisting> + +makes all attributes defined in the file +<filename>definitions.nix</filename> available as if they were defined +locally in a <literal>let</literal>-expression.</para> + +<para>The bindings introduced by <literal>with</literal> do not shadow bindings +introduced by other means, e.g. + +<programlisting> +let a = 3; in with { a = 1; }; let a = 4; in with { a = 2; }; ...</programlisting> + +establishes the same scope as + +<programlisting> +let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...</programlisting> + +</para> + +</simplesect> + + +<simplesect><title>Comments</title> + +<para>Comments can be single-line, started with a <literal>#</literal> +character, or inline/multi-line, enclosed within <literal>/* +... */</literal>.</para> + +</simplesect> + + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-language-operators"> + +<title>Operators</title> + +<para><xref linkend="table-operators"/> lists the operators in the +Nix expression language, in order of precedence (from strongest to +weakest binding).</para> + +<table xml:id="table-operators"> + <title>Operators</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Name</entry> + <entry>Syntax</entry> + <entry>Associativity</entry> + <entry>Description</entry> + <entry>Precedence</entry> + </row> + </thead> + <tbody> + <row> + <entry>Select</entry> + <entry><replaceable>e</replaceable> <literal>.</literal> + <replaceable>attrpath</replaceable> + [ <literal>or</literal> <replaceable>def</replaceable> ] + </entry> + <entry>none</entry> + <entry>Select attribute denoted by the attribute path + <replaceable>attrpath</replaceable> from set + <replaceable>e</replaceable>. (An attribute path is a + dot-separated list of attribute names.) If the attribute + doesn’t exist, return <replaceable>def</replaceable> if + provided, otherwise abort evaluation.</entry> + <entry>1</entry> + </row> + <row> + <entry>Application</entry> + <entry><replaceable>e1</replaceable> <replaceable>e2</replaceable></entry> + <entry>left</entry> + <entry>Call function <replaceable>e1</replaceable> with + argument <replaceable>e2</replaceable>.</entry> + <entry>2</entry> + </row> + <row> + <entry>Arithmetic Negation</entry> + <entry><literal>-</literal> <replaceable>e</replaceable></entry> + <entry>none</entry> + <entry>Arithmetic negation.</entry> + <entry>3</entry> + </row> + <row> + <entry>Has Attribute</entry> + <entry><replaceable>e</replaceable> <literal>?</literal> + <replaceable>attrpath</replaceable></entry> + <entry>none</entry> + <entry>Test whether set <replaceable>e</replaceable> contains + the attribute denoted by <replaceable>attrpath</replaceable>; + return <literal>true</literal> or + <literal>false</literal>.</entry> + <entry>4</entry> + </row> + <row> + <entry>List Concatenation</entry> + <entry><replaceable>e1</replaceable> <literal>++</literal> <replaceable>e2</replaceable></entry> + <entry>right</entry> + <entry>List concatenation.</entry> + <entry>5</entry> + </row> + <row> + <entry>Multiplication</entry> + <entry> + <replaceable>e1</replaceable> <literal>*</literal> <replaceable>e2</replaceable>, + </entry> + <entry>left</entry> + <entry>Arithmetic multiplication.</entry> + <entry>6</entry> + </row> + <row> + <entry>Division</entry> + <entry> + <replaceable>e1</replaceable> <literal>/</literal> <replaceable>e2</replaceable> + </entry> + <entry>left</entry> + <entry>Arithmetic division.</entry> + <entry>6</entry> + </row> + <row> + <entry>Addition</entry> + <entry> + <replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable> + </entry> + <entry>left</entry> + <entry>Arithmetic addition.</entry> + <entry>7</entry> + </row> + <row> + <entry>Subtraction</entry> + <entry> + <replaceable>e1</replaceable> <literal>-</literal> <replaceable>e2</replaceable> + </entry> + <entry>left</entry> + <entry>Arithmetic subtraction.</entry> + <entry>7</entry> + </row> + <row> + <entry>String Concatenation</entry> + <entry> + <replaceable>string1</replaceable> <literal>+</literal> <replaceable>string2</replaceable> + </entry> + <entry>left</entry> + <entry>String concatenation.</entry> + <entry>7</entry> + </row> + <row> + <entry>Not</entry> + <entry><literal>!</literal> <replaceable>e</replaceable></entry> + <entry>none</entry> + <entry>Boolean negation.</entry> + <entry>8</entry> + </row> + <row> + <entry>Update</entry> + <entry><replaceable>e1</replaceable> <literal>//</literal> + <replaceable>e2</replaceable></entry> + <entry>right</entry> + <entry>Return a set consisting of the attributes in + <replaceable>e1</replaceable> and + <replaceable>e2</replaceable> (with the latter taking + precedence over the former in case of equally named + attributes).</entry> + <entry>9</entry> + </row> + <row> + <entry>Less Than</entry> + <entry> + <replaceable>e1</replaceable> <literal><</literal> <replaceable>e2</replaceable>, + </entry> + <entry>none</entry> + <entry>Arithmetic comparison.</entry> + <entry>10</entry> + </row> + <row> + <entry>Less Than or Equal To</entry> + <entry> + <replaceable>e1</replaceable> <literal><=</literal> <replaceable>e2</replaceable> + </entry> + <entry>none</entry> + <entry>Arithmetic comparison.</entry> + <entry>10</entry> + </row> + <row> + <entry>Greater Than</entry> + <entry> + <replaceable>e1</replaceable> <literal>></literal> <replaceable>e2</replaceable> + </entry> + <entry>none</entry> + <entry>Arithmetic comparison.</entry> + <entry>10</entry> + </row> + <row> + <entry>Greater Than or Equal To</entry> + <entry> + <replaceable>e1</replaceable> <literal>>=</literal> <replaceable>e2</replaceable> + </entry> + <entry>none</entry> + <entry>Arithmetic comparison.</entry> + <entry>10</entry> + </row> + <row> + <entry>Equality</entry> + <entry> + <replaceable>e1</replaceable> <literal>==</literal> <replaceable>e2</replaceable> + </entry> + <entry>none</entry> + <entry>Equality.</entry> + <entry>11</entry> + </row> + <row> + <entry>Inequality</entry> + <entry> + <replaceable>e1</replaceable> <literal>!=</literal> <replaceable>e2</replaceable> + </entry> + <entry>none</entry> + <entry>Inequality.</entry> + <entry>11</entry> + </row> + <row> + <entry>Logical AND</entry> + <entry><replaceable>e1</replaceable> <literal>&&</literal> + <replaceable>e2</replaceable></entry> + <entry>left</entry> + <entry>Logical AND.</entry> + <entry>12</entry> + </row> + <row> + <entry>Logical OR</entry> + <entry><replaceable>e1</replaceable> <literal>||</literal> + <replaceable>e2</replaceable></entry> + <entry>left</entry> + <entry>Logical OR.</entry> + <entry>13</entry> + </row> + <row> + <entry>Logical Implication</entry> + <entry><replaceable>e1</replaceable> <literal>-></literal> + <replaceable>e2</replaceable></entry> + <entry>none</entry> + <entry>Logical implication (equivalent to + <literal>!<replaceable>e1</replaceable> || + <replaceable>e2</replaceable></literal>).</entry> + <entry>14</entry> + </row> + </tbody> + </tgroup> +</table> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-derivation"> + +<title>Derivations</title> + +<para>The most important built-in function is +<function>derivation</function>, which is used to describe a single +derivation (a build action). It takes as input a set, the attributes +of which specify the inputs of the build.</para> + +<itemizedlist> + + <listitem xml:id="attr-system"><para>There must be an attribute named + <varname>system</varname> whose value must be a string specifying a + Nix platform identifier, such as <literal>"i686-linux"</literal> or + <literal>"x86_64-darwin"</literal><footnote><para>To figure out + your platform identifier, look at the line <quote>Checking for the + canonical Nix system name</quote> in the output of Nix's + <filename>configure</filename> script.</para></footnote> The build + can only be performed on a machine and operating system matching the + platform identifier. (Nix can automatically forward builds for + other platforms by forwarding them to other machines; see <xref linkend="chap-distributed-builds"/>.)</para></listitem> + + <listitem><para>There must be an attribute named + <varname>name</varname> whose value must be a string. This is used + as a symbolic name for the package by <command>nix-env</command>, + and it is appended to the output paths of the + derivation.</para></listitem> + + <listitem><para>There must be an attribute named + <varname>builder</varname> that identifies the program that is + executed to perform the build. It can be either a derivation or a + source (a local file reference, e.g., + <filename>./builder.sh</filename>).</para></listitem> + + <listitem><para>Every attribute is passed as an environment variable + to the builder. Attribute values are translated to environment + variables as follows: + + <itemizedlist> + + <listitem><para>Strings and numbers are just passed + verbatim.</para></listitem> + + <listitem><para>A <emphasis>path</emphasis> (e.g., + <filename>../foo/sources.tar</filename>) causes the referenced + file to be copied to the store; its location in the store is put + in the environment variable. The idea is that all sources + should reside in the Nix store, since all inputs to a derivation + should reside in the Nix store.</para></listitem> + + <listitem><para>A <emphasis>derivation</emphasis> causes that + derivation to be built prior to the present derivation; its + default output path is put in the environment + variable.</para></listitem> + + <listitem><para>Lists of the previous types are also allowed. + They are simply concatenated, separated by + spaces.</para></listitem> + + <listitem><para><literal>true</literal> is passed as the string + <literal>1</literal>, <literal>false</literal> and + <literal>null</literal> are passed as an empty string. + </para></listitem> + </itemizedlist> + + </para></listitem> + + <listitem><para>The optional attribute <varname>args</varname> + specifies command-line arguments to be passed to the builder. It + should be a list.</para></listitem> + + <listitem><para>The optional attribute <varname>outputs</varname> + specifies a list of symbolic outputs of the derivation. By default, + a derivation produces a single output path, denoted as + <literal>out</literal>. However, derivations can produce multiple + output paths. This is useful because it allows outputs to be + downloaded or garbage-collected separately. For instance, imagine a + library package that provides a dynamic library, header files, and + documentation. A program that links against the library doesn’t + need the header files and documentation at runtime, and it doesn’t + need the documentation at build time. Thus, the library package + could specify: +<programlisting> +outputs = [ "lib" "headers" "doc" ]; +</programlisting> + This will cause Nix to pass environment variables + <literal>lib</literal>, <literal>headers</literal> and + <literal>doc</literal> to the builder containing the intended store + paths of each output. The builder would typically do something like +<programlisting> +./configure --libdir=$lib/lib --includedir=$headers/include --docdir=$doc/share/doc +</programlisting> + for an Autoconf-style package. You can refer to each output of a + derivation by selecting it as an attribute, e.g. +<programlisting> +buildInputs = [ pkg.lib pkg.headers ]; +</programlisting> + The first element of <varname>outputs</varname> determines the + <emphasis>default output</emphasis>. Thus, you could also write +<programlisting> +buildInputs = [ pkg pkg.headers ]; +</programlisting> + since <literal>pkg</literal> is equivalent to + <literal>pkg.lib</literal>.</para></listitem> + +</itemizedlist> + +<para>The function <function>mkDerivation</function> in the Nixpkgs +standard environment is a wrapper around +<function>derivation</function> that adds a default value for +<varname>system</varname> and always uses Bash as the builder, to +which the supplied builder is passed as a command-line argument. See +the Nixpkgs manual for details.</para> + +<para>The builder is executed as follows: + +<itemizedlist> + + <listitem><para>A temporary directory is created under the directory + specified by <envar>TMPDIR</envar> (default + <filename>/tmp</filename>) where the build will take place. The + current directory is changed to this directory.</para></listitem> + + <listitem><para>The environment is cleared and set to the derivation + attributes, as specified above.</para></listitem> + + <listitem><para>In addition, the following variables are set: + + <itemizedlist> + + <listitem><para><envar>NIX_BUILD_TOP</envar> contains the path of + the temporary directory for this build.</para></listitem> + + <listitem><para>Also, <envar>TMPDIR</envar>, + <envar>TEMPDIR</envar>, <envar>TMP</envar>, <envar>TEMP</envar> + are set to point to the temporary directory. This is to prevent + the builder from accidentally writing temporary files anywhere + else. Doing so might cause interference by other + processes.</para></listitem> + + <listitem><para><envar>PATH</envar> is set to + <filename>/path-not-set</filename> to prevent shells from + initialising it to their built-in default value.</para></listitem> + + <listitem><para><envar>HOME</envar> is set to + <filename>/homeless-shelter</filename> to prevent programs from + using <filename>/etc/passwd</filename> or the like to find the + user's home directory, which could cause impurity. Usually, when + <envar>HOME</envar> is set, it is used as the location of the home + directory, even if it points to a non-existent + path.</para></listitem> + + <listitem><para><envar>NIX_STORE</envar> is set to the path of the + top-level Nix store directory (typically, + <filename>/nix/store</filename>).</para></listitem> + + <listitem><para>For each output declared in + <varname>outputs</varname>, the corresponding environment variable + is set to point to the intended path in the Nix store for that + output. Each output path is a concatenation of the cryptographic + hash of all build inputs, the <varname>name</varname> attribute + and the output name. (The output name is omitted if it’s + <literal>out</literal>.)</para></listitem> + + </itemizedlist> + + </para></listitem> + + <listitem><para>If an output path already exists, it is removed. + Also, locks are acquired to prevent multiple Nix instances from + performing the same build at the same time.</para></listitem> + + <listitem><para>A log of the combined standard output and error is + written to <filename>/nix/var/log/nix</filename>.</para></listitem> + + <listitem><para>The builder is executed with the arguments specified + by the attribute <varname>args</varname>. If it exits with exit + code 0, it is considered to have succeeded.</para></listitem> + + <listitem><para>The temporary directory is removed (unless the + <option>-K</option> option was specified).</para></listitem> + + <listitem><para>If the build was successful, Nix scans each output + path for references to input paths by looking for the hash parts of + the input paths. Since these are potential runtime dependencies, + Nix registers them as dependencies of the output + paths.</para></listitem> + + <listitem><para>After the build, Nix sets the last-modified + timestamp on all files in the build result to 1 (00:00:01 1/1/1970 + UTC), sets the group to the default group, and sets the mode of the + file to 0444 or 0555 (i.e., read-only, with execute permission + enabled if the file was originally executable). Note that possible + <literal>setuid</literal> and <literal>setgid</literal> bits are + cleared. Setuid and setgid programs are not currently supported by + Nix. This is because the Nix archives used in deployment have no + concept of ownership information, and because it makes the build + result dependent on the user performing the build.</para></listitem> + +</itemizedlist> + +</para> + +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-advanced-attributes"> + +<title>Advanced Attributes</title> + +<para>Derivations can declare some infrequently used optional +attributes.</para> + +<variablelist> + + <varlistentry xml:id="adv-attr-allowedReferences"><term><varname>allowedReferences</varname></term> + + <listitem><para>The optional attribute + <varname>allowedReferences</varname> specifies a list of legal + references (dependencies) of the output of the builder. For + example, + +<programlisting> +allowedReferences = []; +</programlisting> + + enforces that the output of a derivation cannot have any runtime + dependencies on its inputs. To allow an output to have a runtime + dependency on itself, use <literal>"out"</literal> as a list item. + This is used in NixOS to check that generated files such as + initial ramdisks for booting Linux don’t have accidental + dependencies on other paths in the Nix store.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="adv-attr-allowedRequisites"><term><varname>allowedRequisites</varname></term> + + <listitem><para>This attribute is similar to + <varname>allowedReferences</varname>, but it specifies the legal + requisites of the whole closure, so all the dependencies + recursively. For example, + +<programlisting> +allowedRequisites = [ foobar ]; +</programlisting> + + enforces that the output of a derivation cannot have any other + runtime dependency than <varname>foobar</varname>, and in addition + it enforces that <varname>foobar</varname> itself doesn't + introduce any other dependency itself.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="adv-attr-disallowedReferences"><term><varname>disallowedReferences</varname></term> + + <listitem><para>The optional attribute + <varname>disallowedReferences</varname> specifies a list of illegal + references (dependencies) of the output of the builder. For + example, + +<programlisting> +disallowedReferences = [ foo ]; +</programlisting> + + enforces that the output of a derivation cannot have a direct runtime + dependencies on the derivation <varname>foo</varname>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="adv-attr-disallowedRequisites"><term><varname>disallowedRequisites</varname></term> + + <listitem><para>This attribute is similar to + <varname>disallowedReferences</varname>, but it specifies illegal + requisites for the whole closure, so all the dependencies + recursively. For example, + +<programlisting> +disallowedRequisites = [ foobar ]; +</programlisting> + + enforces that the output of a derivation cannot have any + runtime dependency on <varname>foobar</varname> or any other derivation + depending recursively on <varname>foobar</varname>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="adv-attr-exportReferencesGraph"><term><varname>exportReferencesGraph</varname></term> + + <listitem><para>This attribute allows builders access to the + references graph of their inputs. The attribute is a list of + inputs in the Nix store whose references graph the builder needs + to know. The value of this attribute should be a list of pairs + <literal>[ <replaceable>name1</replaceable> + <replaceable>path1</replaceable> <replaceable>name2</replaceable> + <replaceable>path2</replaceable> <replaceable>...</replaceable> + ]</literal>. The references graph of each + <replaceable>pathN</replaceable> will be stored in a text file + <replaceable>nameN</replaceable> in the temporary build directory. + The text files have the format used by <command>nix-store + --register-validity</command> (with the deriver fields left + empty). For example, when the following derivation is built: + +<programlisting> +derivation { + ... + exportReferencesGraph = [ "libfoo-graph" libfoo ]; +}; +</programlisting> + + the references graph of <literal>libfoo</literal> is placed in the + file <filename>libfoo-graph</filename> in the temporary build + directory.</para> + + <para><varname>exportReferencesGraph</varname> is useful for + builders that want to do something with the closure of a store + path. Examples include the builders in NixOS that generate the + initial ramdisk for booting Linux (a <command>cpio</command> + archive containing the closure of the boot script) and the + ISO-9660 image for the installation CD (which is populated with a + Nix store containing the closure of a bootable NixOS + configuration).</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="adv-attr-impureEnvVars"><term><varname>impureEnvVars</varname></term> + + <listitem><para>This attribute allows you to specify a list of + environment variables that should be passed from the environment + of the calling user to the builder. Usually, the environment is + cleared completely when the builder is executed, but with this + attribute you can allow specific environment variables to be + passed unmodified. For example, <function>fetchurl</function> in + Nixpkgs has the line + +<programlisting> +impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ]; +</programlisting> + + to make it use the proxy server configuration specified by the + user in the environment variables <envar>http_proxy</envar> and + friends.</para> + + <para>This attribute is only allowed in <link linkend="fixed-output-drvs">fixed-output derivations</link>, where + impurities such as these are okay since (the hash of) the output + is known in advance. It is ignored for all other + derivations.</para> + + <warning><para><varname>impureEnvVars</varname> implementation takes + environment variables from the current builder process. When a daemon is + building its environmental variables are used. Without the daemon, the + environmental variables come from the environment of the + <command>nix-build</command>.</para></warning></listitem> + + </varlistentry> + + + <varlistentry xml:id="fixed-output-drvs"> + <term xml:id="adv-attr-outputHash"><varname>outputHash</varname></term> + <term xml:id="adv-attr-outputHashAlgo"><varname>outputHashAlgo</varname></term> + <term xml:id="adv-attr-outputHashMode"><varname>outputHashMode</varname></term> + + <listitem><para>These attributes declare that the derivation is a + so-called <emphasis>fixed-output derivation</emphasis>, which + means that a cryptographic hash of the output is already known in + advance. When the build of a fixed-output derivation finishes, + Nix computes the cryptographic hash of the output and compares it + to the hash declared with these attributes. If there is a + mismatch, the build fails.</para> + + <para>The rationale for fixed-output derivations is derivations + such as those produced by the <function>fetchurl</function> + function. This function downloads a file from a given URL. To + ensure that the downloaded file has not been modified, the caller + must also specify a cryptographic hash of the file. For example, + +<programlisting> +fetchurl { + url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz"; + sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; +} +</programlisting> + + It sometimes happens that the URL of the file changes, e.g., + because servers are reorganised or no longer available. We then + must update the call to <function>fetchurl</function>, e.g., + +<programlisting> +fetchurl { + url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; + sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; +} +</programlisting> + + If a <function>fetchurl</function> derivation was treated like a + normal derivation, the output paths of the derivation and + <emphasis>all derivations depending on it</emphasis> would change. + For instance, if we were to change the URL of the Glibc source + distribution in Nixpkgs (a package on which almost all other + packages depend) massive rebuilds would be needed. This is + unfortunate for a change which we know cannot have a real effect + as it propagates upwards through the dependency graph.</para> + + <para>For fixed-output derivations, on the other hand, the name of + the output path only depends on the <varname>outputHash*</varname> + and <varname>name</varname> attributes, while all other attributes + are ignored for the purpose of computing the output path. (The + <varname>name</varname> attribute is included because it is part + of the path.)</para> + + <para>As an example, here is the (simplified) Nix expression for + <varname>fetchurl</varname>: + +<programlisting> +{ stdenv, curl }: # The <command>curl</command> program is used for downloading. + +{ url, sha256 }: + +stdenv.mkDerivation { + name = baseNameOf (toString url); + builder = ./builder.sh; + buildInputs = [ curl ]; + + # This is a fixed-output derivation; the output must be a regular + # file with SHA256 hash <varname>sha256</varname>. + outputHashMode = "flat"; + outputHashAlgo = "sha256"; + outputHash = sha256; + + inherit url; +} +</programlisting> + + </para> + + <para>The <varname>outputHashAlgo</varname> attribute specifies + the hash algorithm used to compute the hash. It can currently be + <literal>"sha1"</literal>, <literal>"sha256"</literal> or + <literal>"sha512"</literal>.</para> + + <para>The <varname>outputHashMode</varname> attribute determines + how the hash is computed. It must be one of the following two + values: + + <variablelist> + + <varlistentry><term><literal>"flat"</literal></term> + + <listitem><para>The output must be a non-executable regular + file. If it isn’t, the build fails. The hash is simply + computed over the contents of that file (so it’s equal to what + Unix commands like <command>sha256sum</command> or + <command>sha1sum</command> produce).</para> + + <para>This is the default.</para></listitem> + + </varlistentry> + + <varlistentry><term><literal>"recursive"</literal></term> + + <listitem><para>The hash is computed over the NAR archive dump + of the output (i.e., the result of <link linkend="refsec-nix-store-dump"><command>nix-store + --dump</command></link>). In this case, the output can be + anything, including a directory tree.</para></listitem> + + </varlistentry> + + </variablelist> + + </para> + + <para>The <varname>outputHash</varname> attribute, finally, must + be a string containing the hash in either hexadecimal or base-32 + notation. (See the <link linkend="sec-nix-hash"><command>nix-hash</command> command</link> + for information about converting to and from base-32 + notation.)</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="adv-attr-passAsFile"><term><varname>passAsFile</varname></term> + + <listitem><para>A list of names of attributes that should be + passed via files rather than environment variables. For example, + if you have + + <programlisting> +passAsFile = ["big"]; +big = "a very long string"; + </programlisting> + + then when the builder runs, the environment variable + <envar>bigPath</envar> will contain the absolute path to a + temporary file containing <literal>a very long + string</literal>. That is, for any attribute + <replaceable>x</replaceable> listed in + <varname>passAsFile</varname>, Nix will pass an environment + variable <envar><replaceable>x</replaceable>Path</envar> holding + the path of the file containing the value of attribute + <replaceable>x</replaceable>. This is useful when you need to pass + large strings to a builder, since most operating systems impose a + limit on the size of the environment (typically, a few hundred + kilobyte).</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="adv-attr-preferLocalBuild"><term><varname>preferLocalBuild</varname></term> + + <listitem><para>If this attribute is set to + <literal>true</literal> and <link linkend="chap-distributed-builds">distributed building is + enabled</link>, then, if possible, the derivaton will be built + locally instead of forwarded to a remote machine. This is + appropriate for trivial builders where the cost of doing a + download or remote build would exceed the cost of building + locally.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="adv-attr-allowSubstitutes"><term><varname>allowSubstitutes</varname></term> + + <listitem> + <para>If this attribute is set to + <literal>false</literal>, then Nix will always build this + derivation; it will not try to substitute its outputs. This is + useful for very trivial derivations (such as + <function>writeText</function> in Nixpkgs) that are cheaper to + build than to substitute from a binary cache.</para> + + <note><para>You need to have a builder configured which satisfies + the derivation’s <literal>system</literal> attribute, since the + derivation cannot be substituted. Thus it is usually a good idea + to align <literal>system</literal> with + <literal>builtins.currentSystem</literal> when setting + <literal>allowSubstitutes</literal> to <literal>false</literal>. + For most trivial derivations this should be the case. + </para></note> + </listitem> + + </varlistentry> + + +</variablelist> + +</section> + +</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’t have the desired built-in + function.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-compareVersions"> + <term><function>builtins.compareVersions</function> + <replaceable>s1</replaceable> <replaceable>s2</replaceable></term> + + <listitem><para>Compare two strings representing versions and + return <literal>-1</literal> if version + <replaceable>s1</replaceable> is older than version + <replaceable>s2</replaceable>, <literal>0</literal> if they are + the same, and <literal>1</literal> if + <replaceable>s1</replaceable> is newer than + <replaceable>s2</replaceable>. The version comparison algorithm + is the same as the one used by <link linkend="ssec-version-comparisons"><command>nix-env + -u</command></link>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-concatLists"> + <term><function>builtins.concatLists</function> + <replaceable>lists</replaceable></term> + + <listitem><para>Concatenate a list of lists into a single + list.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="builtin-concatStringsSep"> + <term><function>builtins.concatStringsSep</function> + <replaceable>separator</replaceable> <replaceable>list</replaceable></term> + + <listitem><para>Concatenate a list of strings with a separator + between each element, e.g. <literal>concatStringsSep "/" + ["usr" "local" "bin"] == "usr/local/bin"</literal></para></listitem> + + </varlistentry> + + <varlistentry xml:id="builtin-currentSystem"> + <term><varname>builtins.currentSystem</varname></term> + + <listitem><para>The built-in value <varname>currentSystem</varname> + evaluates to the Nix platform identifier for the Nix installation + on which the expression is being evaluated, such as + <literal>"i686-linux"</literal> or + <literal>"x86_64-darwin"</literal>.</para></listitem> + + </varlistentry> + + + <!-- + <varlistentry><term><function>currentTime</function></term> + + <listitem><para>The built-in value <varname>currentTime</varname> + returns the current system time in seconds since 00:00:00 1/1/1970 + UTC. Due to the evaluation model of Nix expressions + (<emphasis>maximal laziness</emphasis>), it always yields the same + value within an execution of Nix.</para></listitem> + + </varlistentry> + --> + + + <!-- + <varlistentry><term><function>dependencyClosure</function></term> + + <listitem><para>TODO</para></listitem> + + </varlistentry> + --> + + + <varlistentry xml:id="builtin-deepSeq"> + <term><function>builtins.deepSeq</function> + <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> + + <listitem><para>This is like <literal>seq + <replaceable>e1</replaceable> + <replaceable>e2</replaceable></literal>, except that + <replaceable>e1</replaceable> is evaluated + <emphasis>deeply</emphasis>: if it’s a list or set, its elements + or attributes are also evaluated recursively.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-derivation"> + <term><function>derivation</function> + <replaceable>attrs</replaceable></term> + <term><function>builtins.derivation</function> + <replaceable>attrs</replaceable></term> + + <listitem><para><function>derivation</function> is described in + <xref linkend="ssec-derivation"/>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-dirOf"> + <term><function>dirOf</function> <replaceable>s</replaceable></term> + <term><function>builtins.dirOf</function> <replaceable>s</replaceable></term> + + <listitem><para>Return the directory part of the string + <replaceable>s</replaceable>, that is, everything before the final + slash in the string. This is similar to the GNU + <command>dirname</command> command.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-div"> + <term><function>builtins.div</function> + <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> + + <listitem><para>Return the quotient of the numbers + <replaceable>e1</replaceable> and + <replaceable>e2</replaceable>.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="builtin-elem"> + <term><function>builtins.elem</function> + <replaceable>x</replaceable> <replaceable>xs</replaceable></term> + + <listitem><para>Return <literal>true</literal> if a value equal to + <replaceable>x</replaceable> occurs in the list + <replaceable>xs</replaceable>, and <literal>false</literal> + otherwise.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-elemAt"> + <term><function>builtins.elemAt</function> + <replaceable>xs</replaceable> <replaceable>n</replaceable></term> + + <listitem><para>Return element <replaceable>n</replaceable> from + the list <replaceable>xs</replaceable>. Elements are counted + starting from 0. A fatal error occurs if the index is out of + bounds.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-fetchurl"> + <term><function>builtins.fetchurl</function> + <replaceable>url</replaceable></term> + + <listitem><para>Download the specified URL and return the path of + the downloaded file. This function is not available if <link linkend="conf-restrict-eval">restricted evaluation mode</link> is + enabled.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-fetchTarball"> + <term><function>fetchTarball</function> + <replaceable>url</replaceable></term> + <term><function>builtins.fetchTarball</function> + <replaceable>url</replaceable></term> + + <listitem><para>Download the specified URL, unpack it and return + the path of the unpacked tree. The file must be a tape archive + (<filename>.tar</filename>) compressed with + <literal>gzip</literal>, <literal>bzip2</literal> or + <literal>xz</literal>. The top-level path component of the files + in the tarball is removed, so it is best if the tarball contains a + single directory at top level. The typical use of the function is + to obtain external Nix expression dependencies, such as a + particular version of Nixpkgs, e.g. + +<programlisting> +with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz) {}; + +stdenv.mkDerivation { … } +</programlisting> + </para> + + <para>The fetched tarball is cached for a certain amount of time + (1 hour by default) in <filename>~/.cache/nix/tarballs/</filename>. + You can change the cache timeout either on the command line with + <option>--option tarball-ttl <replaceable>number of seconds</replaceable></option> or + in the Nix configuration file with this option: + <literal><xref linkend="conf-tarball-ttl"/> <replaceable>number of seconds to cache</replaceable></literal>. + </para> + + <para>Note that when obtaining the hash with <varname>nix-prefetch-url + </varname> the option <varname>--unpack</varname> is required. + </para> + + <para>This function can also verify the contents against a hash. + In that case, the function takes a set instead of a URL. The set + requires the attribute <varname>url</varname> and the attribute + <varname>sha256</varname>, e.g. + +<programlisting> +with import (fetchTarball { + url = "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz"; + sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2"; +}) {}; + +stdenv.mkDerivation { … } +</programlisting> + + </para> + + <para>This function is not available if <link linkend="conf-restrict-eval">restricted evaluation mode</link> is + enabled.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="builtin-fetchGit"> + <term> + <function>builtins.fetchGit</function> + <replaceable>args</replaceable> + </term> + + <listitem> + <para> + Fetch a path from git. <replaceable>args</replaceable> can be + a URL, in which case the HEAD of the repo at that URL is + fetched. Otherwise, it can be an attribute with the following + attributes (all except <varname>url</varname> optional): + </para> + + <variablelist> + <varlistentry> + <term>url</term> + <listitem> + <para> + The URL of the repo. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>name</term> + <listitem> + <para> + The name of the directory the repo should be exported to + in the store. Defaults to the basename of the URL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>rev</term> + <listitem> + <para> + The git revision to fetch. Defaults to the tip of + <varname>ref</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ref</term> + <listitem> + <para> + The git ref to look for the requested revision under. + This is often a branch or tag name. Defaults to + <literal>HEAD</literal>. + </para> + + <para> + By default, the <varname>ref</varname> value is prefixed + with <literal>refs/heads/</literal>. As of Nix 2.3.0 + Nix will not prefix <literal>refs/heads/</literal> if + <varname>ref</varname> starts with <literal>refs/</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>submodules</term> + <listitem> + <para> + A Boolean parameter that specifies whether submodules + should be checked out. Defaults to + <literal>false</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title>Fetching a private repository over SSH</title> + <programlisting>builtins.fetchGit { + url = "git@github.com:my-secret/repository.git"; + ref = "master"; + rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; +}</programlisting> + </example> + + <example> + <title>Fetching an arbitrary ref</title> + <programlisting>builtins.fetchGit { + url = "https://github.com/NixOS/nix.git"; + ref = "refs/heads/0.5-release"; +}</programlisting> + </example> + + <example> + <title>Fetching a repository's specific commit on an arbitrary branch</title> + <para> + If the revision you're looking for is in the default branch + of the git repository you don't strictly need to specify + the branch name in the <varname>ref</varname> attribute. + </para> + <para> + However, if the revision you're looking for is in a future + branch for the non-default branch you will need to specify + the the <varname>ref</varname> attribute as well. + </para> + <programlisting>builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; + ref = "1.11-maintenance"; +}</programlisting> + <note> + <para> + It is nice to always specify the branch which a revision + belongs to. Without the branch being specified, the + fetcher might fail if the default branch changes. + Additionally, it can be confusing to try a commit from a + non-default branch and see the fetch fail. If the branch + is specified the fault is much more obvious. + </para> + </note> + </example> + + <example> + <title>Fetching a repository's specific commit on the default branch</title> + <para> + If the revision you're looking for is in the default branch + of the git repository you may omit the + <varname>ref</varname> attribute. + </para> + <programlisting>builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; +}</programlisting> + </example> + + <example> + <title>Fetching a tag</title> + <programlisting>builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + ref = "refs/tags/1.9"; +}</programlisting> + </example> + + <example> + <title>Fetching the latest version of a remote branch</title> + <para> + <function>builtins.fetchGit</function> can behave impurely + fetch the latest version of a remote branch. + </para> + <note><para>Nix will refetch the branch in accordance to + <xref linkend="conf-tarball-ttl"/>.</para></note> + <note><para>This behavior is disabled in + <emphasis>Pure evaluation mode</emphasis>.</para></note> + <programlisting>builtins.fetchGit { + url = "ssh://git@github.com/nixos/nix.git"; + ref = "master"; +}</programlisting> + </example> + </listitem> + </varlistentry> + + + <varlistentry><term><function>builtins.filter</function> + <replaceable>f</replaceable> <replaceable>xs</replaceable></term> + + <listitem><para>Return a list consisting of the elements of + <replaceable>xs</replaceable> for which the function + <replaceable>f</replaceable> returns + <literal>true</literal>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-filterSource"> + <term><function>builtins.filterSource</function> + <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> + + <listitem> + + <para>This function allows you to copy sources into the Nix + store while filtering certain files. For instance, suppose that + you want to use the directory <filename>source-dir</filename> as + an input to a Nix expression, e.g. + +<programlisting> +stdenv.mkDerivation { + ... + src = ./source-dir; +} +</programlisting> + + However, if <filename>source-dir</filename> is a Subversion + working copy, then all those annoying <filename>.svn</filename> + subdirectories will also be copied to the store. Worse, the + contents of those directories may change a lot, causing lots of + spurious rebuilds. With <function>filterSource</function> you + can filter out the <filename>.svn</filename> directories: + +<programlisting> + src = builtins.filterSource + (path: type: type != "directory" || baseNameOf path != ".svn") + ./source-dir; +</programlisting> + + </para> + + <para>Thus, the first argument <replaceable>e1</replaceable> + must be a predicate function that is called for each regular + file, directory or symlink in the source tree + <replaceable>e2</replaceable>. If the function returns + <literal>true</literal>, the file is copied to the Nix store, + otherwise it is omitted. The function is called with two + arguments. The first is the full path of the file. The second + is a string that identifies the type of the file, which is + either <literal>"regular"</literal>, + <literal>"directory"</literal>, <literal>"symlink"</literal> or + <literal>"unknown"</literal> (for other kinds of files such as + device nodes or fifos — but note that those cannot be copied to + the Nix store, so if the predicate returns + <literal>true</literal> for them, the copy will fail). If you + exclude a directory, the entire corresponding subtree of + <replaceable>e2</replaceable> will be excluded.</para> + + </listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-foldl-prime"> + <term><function>builtins.foldl’</function> + <replaceable>op</replaceable> <replaceable>nul</replaceable> <replaceable>list</replaceable></term> + + <listitem><para>Reduce a list by applying a binary operator, from + left to right, e.g. <literal>foldl’ op nul [x0 x1 x2 ...] = op (op + (op nul x0) x1) x2) ...</literal>. The operator is applied + strictly, i.e., its arguments are evaluated first. For example, + <literal>foldl’ (x: y: x + y) 0 [1 2 3]</literal> evaluates to + 6.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-functionArgs"> + <term><function>builtins.functionArgs</function> + <replaceable>f</replaceable></term> + + <listitem><para> + Return a set containing the names of the formal arguments expected + by the function <replaceable>f</replaceable>. + The value of each attribute is a Boolean denoting whether the corresponding + argument has a default value. For instance, + <literal>functionArgs ({ x, y ? 123}: ...) = { x = false; y = true; }</literal>. + </para> + + <para>"Formal argument" here refers to the attributes pattern-matched by + the function. Plain lambdas are not included, e.g. + <literal>functionArgs (x: ...) = { }</literal>. + </para></listitem> + </varlistentry> + + + <varlistentry xml:id="builtin-fromJSON"> + <term><function>builtins.fromJSON</function> <replaceable>e</replaceable></term> + + <listitem><para>Convert a JSON string to a Nix + value. For example, + +<programlisting> +builtins.fromJSON ''{"x": [1, 2, 3], "y": null}'' +</programlisting> + + returns the value <literal>{ x = [ 1 2 3 ]; y = null; + }</literal>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-genList"> + <term><function>builtins.genList</function> + <replaceable>generator</replaceable> <replaceable>length</replaceable></term> + + <listitem><para>Generate list of size + <replaceable>length</replaceable>, with each element + <replaceable>i</replaceable> equal to the value returned by + <replaceable>generator</replaceable> <literal>i</literal>. For + example, + +<programlisting> +builtins.genList (x: x * x) 5 +</programlisting> + + returns the list <literal>[ 0 1 4 9 16 ]</literal>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-getAttr"> + <term><function>builtins.getAttr</function> + <replaceable>s</replaceable> <replaceable>set</replaceable></term> + + <listitem><para><function>getAttr</function> returns the attribute + named <replaceable>s</replaceable> from + <replaceable>set</replaceable>. Evaluation aborts if the + attribute doesn’t exist. This is a dynamic version of the + <literal>.</literal> operator, since <replaceable>s</replaceable> + is an expression rather than an identifier.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-getEnv"> + <term><function>builtins.getEnv</function> + <replaceable>s</replaceable></term> + + <listitem><para><function>getEnv</function> returns the value of + the environment variable <replaceable>s</replaceable>, or an empty + string if the variable doesn’t exist. This function should be + used with care, as it can introduce all sorts of nasty environment + dependencies in your Nix expression.</para> + + <para><function>getEnv</function> is used in Nix Packages to + locate the file <filename>~/.nixpkgs/config.nix</filename>, which + contains user-local settings for Nix Packages. (That is, it does + a <literal>getEnv "HOME"</literal> to locate the user’s home + directory.)</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-hasAttr"> + <term><function>builtins.hasAttr</function> + <replaceable>s</replaceable> <replaceable>set</replaceable></term> + + <listitem><para><function>hasAttr</function> returns + <literal>true</literal> if <replaceable>set</replaceable> has an + attribute named <replaceable>s</replaceable>, and + <literal>false</literal> otherwise. This is a dynamic version of + the <literal>?</literal> operator, since + <replaceable>s</replaceable> is an expression rather than an + identifier.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-hashString"> + <term><function>builtins.hashString</function> + <replaceable>type</replaceable> <replaceable>s</replaceable></term> + + <listitem><para>Return a base-16 representation of the + cryptographic hash of string <replaceable>s</replaceable>. The + hash algorithm specified by <replaceable>type</replaceable> must + be one of <literal>"md5"</literal>, <literal>"sha1"</literal>, + <literal>"sha256"</literal> or <literal>"sha512"</literal>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-hashFile"> + <term><function>builtins.hashFile</function> + <replaceable>type</replaceable> <replaceable>p</replaceable></term> + + <listitem><para>Return a base-16 representation of the + cryptographic hash of the file at path <replaceable>p</replaceable>. The + hash algorithm specified by <replaceable>type</replaceable> must + be one of <literal>"md5"</literal>, <literal>"sha1"</literal>, + <literal>"sha256"</literal> or <literal>"sha512"</literal>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-head"> + <term><function>builtins.head</function> + <replaceable>list</replaceable></term> + + <listitem><para>Return the first element of a list; abort + evaluation if the argument isn’t a list or is an empty list. You + can test whether a list is empty by comparing it with + <literal>[]</literal>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-import"> + <term><function>import</function> + <replaceable>path</replaceable></term> + <term><function>builtins.import</function> + <replaceable>path</replaceable></term> + + <listitem><para>Load, parse and return the Nix expression in the + file <replaceable>path</replaceable>. If <replaceable>path + </replaceable> is a directory, the file <filename>default.nix + </filename> in that directory is loaded. Evaluation aborts if the + file doesn’t exist or contains an incorrect Nix expression. + <function>import</function> implements Nix’s module system: you + can put any Nix expression (such as a set or a function) in a + separate file, and use it from Nix expressions in other + files.</para> + + <note><para>Unlike some languages, <function>import</function> is a regular + function in Nix. Paths using the angle bracket syntax (e.g., <function> + import</function> <replaceable><foo></replaceable>) are normal path + values (see <xref linkend="ssec-values"/>).</para></note> + + <para>A Nix expression loaded by <function>import</function> must + not contain any <emphasis>free variables</emphasis> (identifiers + that are not defined in the Nix expression itself and are not + built-in). Therefore, it cannot refer to variables that are in + scope at the call site. For instance, if you have a calling + expression + +<programlisting> +rec { + x = 123; + y = import ./foo.nix; +}</programlisting> + + then the following <filename>foo.nix</filename> will give an + error: + +<programlisting> +x + 456</programlisting> + + since <varname>x</varname> is not in scope in + <filename>foo.nix</filename>. If you want <varname>x</varname> + to be available in <filename>foo.nix</filename>, you should pass + it as a function argument: + +<programlisting> +rec { + x = 123; + y = import ./foo.nix x; +}</programlisting> + + and + +<programlisting> +x: x + 456</programlisting> + + (The function argument doesn’t have to be called + <varname>x</varname> in <filename>foo.nix</filename>; any name + would work.)</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-intersectAttrs"> + <term><function>builtins.intersectAttrs</function> + <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> + + <listitem><para>Return a set consisting of the attributes in the + set <replaceable>e2</replaceable> that also exist in the set + <replaceable>e1</replaceable>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-isAttrs"> + <term><function>builtins.isAttrs</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return <literal>true</literal> if + <replaceable>e</replaceable> evaluates to a set, and + <literal>false</literal> otherwise.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-isList"> + <term><function>builtins.isList</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return <literal>true</literal> if + <replaceable>e</replaceable> evaluates to a list, and + <literal>false</literal> otherwise.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-isFunction"><term><function>builtins.isFunction</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return <literal>true</literal> if + <replaceable>e</replaceable> evaluates to a function, and + <literal>false</literal> otherwise.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-isString"> + <term><function>builtins.isString</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return <literal>true</literal> if + <replaceable>e</replaceable> evaluates to a string, and + <literal>false</literal> otherwise.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-isInt"> + <term><function>builtins.isInt</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return <literal>true</literal> if + <replaceable>e</replaceable> evaluates to an int, and + <literal>false</literal> otherwise.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-isFloat"> + <term><function>builtins.isFloat</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return <literal>true</literal> if + <replaceable>e</replaceable> evaluates to a float, and + <literal>false</literal> otherwise.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-isBool"> + <term><function>builtins.isBool</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return <literal>true</literal> if + <replaceable>e</replaceable> evaluates to a bool, and + <literal>false</literal> otherwise.</para></listitem> + + </varlistentry> + + <varlistentry><term><function>builtins.isPath</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return <literal>true</literal> if + <replaceable>e</replaceable> evaluates to a path, and + <literal>false</literal> otherwise.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="builtin-isNull"> + <term><function>isNull</function> + <replaceable>e</replaceable></term> + <term><function>builtins.isNull</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return <literal>true</literal> if + <replaceable>e</replaceable> evaluates to <literal>null</literal>, + and <literal>false</literal> otherwise.</para> + + <warning><para>This function is <emphasis>deprecated</emphasis>; + just write <literal>e == null</literal> instead.</para></warning> + + </listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-length"> + <term><function>builtins.length</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return the length of the list + <replaceable>e</replaceable>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-lessThan"> + <term><function>builtins.lessThan</function> + <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> + + <listitem><para>Return <literal>true</literal> if the number + <replaceable>e1</replaceable> is less than the number + <replaceable>e2</replaceable>, and <literal>false</literal> + otherwise. Evaluation aborts if either + <replaceable>e1</replaceable> or <replaceable>e2</replaceable> + does not evaluate to a number.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-listToAttrs"> + <term><function>builtins.listToAttrs</function> + <replaceable>e</replaceable></term> + + <listitem><para>Construct a set from a list specifying the names + and values of each attribute. Each element of the list should be + a set consisting of a string-valued attribute + <varname>name</varname> specifying the name of the attribute, and + an attribute <varname>value</varname> specifying its value. + Example: + +<programlisting> +builtins.listToAttrs + [ { name = "foo"; value = 123; } + { name = "bar"; value = 456; } + ] +</programlisting> + + evaluates to + +<programlisting> +{ foo = 123; bar = 456; } +</programlisting> + + </para></listitem> + + </varlistentry> + + <varlistentry xml:id="builtin-map"> + <term><function>map</function> + <replaceable>f</replaceable> <replaceable>list</replaceable></term> + <term><function>builtins.map</function> + <replaceable>f</replaceable> <replaceable>list</replaceable></term> + + <listitem><para>Apply the function <replaceable>f</replaceable> to + each element in the list <replaceable>list</replaceable>. For + example, + +<programlisting> +map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting> + + evaluates to <literal>[ "foobar" "foobla" "fooabc" + ]</literal>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-match"> + <term><function>builtins.match</function> + <replaceable>regex</replaceable> <replaceable>str</replaceable></term> + + <listitem><para>Returns a list if the <link xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended + POSIX regular expression</link> <replaceable>regex</replaceable> + matches <replaceable>str</replaceable> precisely, otherwise returns + <literal>null</literal>. Each item in the list is a regex group. + +<programlisting> +builtins.match "ab" "abc" +</programlisting> + +Evaluates to <literal>null</literal>. + +<programlisting> +builtins.match "abc" "abc" +</programlisting> + +Evaluates to <literal>[ ]</literal>. + +<programlisting> +builtins.match "a(b)(c)" "abc" +</programlisting> + +Evaluates to <literal>[ "b" "c" ]</literal>. + +<programlisting> +builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO " +</programlisting> + +Evaluates to <literal>[ "foo" ]</literal>. + + </para></listitem> + </varlistentry> + + <varlistentry xml:id="builtin-mul"> + <term><function>builtins.mul</function> + <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> + + <listitem><para>Return the product of the numbers + <replaceable>e1</replaceable> and + <replaceable>e2</replaceable>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-parseDrvName"> + <term><function>builtins.parseDrvName</function> + <replaceable>s</replaceable></term> + + <listitem><para>Split the string <replaceable>s</replaceable> into + a package name and version. The package name is everything up to + but not including the first dash followed by a digit, and the + version is everything following that dash. The result is returned + in a set <literal>{ name, version }</literal>. Thus, + <literal>builtins.parseDrvName "nix-0.12pre12876"</literal> + returns <literal>{ name = "nix"; version = "0.12pre12876"; + }</literal>.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="builtin-path"> + <term> + <function>builtins.path</function> + <replaceable>args</replaceable> + </term> + + <listitem> + <para> + An enrichment of the built-in path type, based on the attributes + present in <replaceable>args</replaceable>. All are optional + except <varname>path</varname>: + </para> + + <variablelist> + <varlistentry> + <term>path</term> + <listitem> + <para>The underlying path.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>name</term> + <listitem> + <para> + The name of the path when added to the store. This can + used to reference paths that have nix-illegal characters + in their names, like <literal>@</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>filter</term> + <listitem> + <para> + A function of the type expected by + <link linkend="builtin-filterSource">builtins.filterSource</link>, + with the same semantics. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>recursive</term> + <listitem> + <para> + When <literal>false</literal>, when + <varname>path</varname> is added to the store it is with a + flat hash, rather than a hash of the NAR serialization of + the file. Thus, <varname>path</varname> must refer to a + regular file, not a directory. This allows similar + behavior to <literal>fetchurl</literal>. Defaults to + <literal>true</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>sha256</term> + <listitem> + <para> + When provided, this is the expected hash of the file at + the path. Evaluation will fail if the hash is incorrect, + and providing a hash allows + <literal>builtins.path</literal> to be used even when the + <literal>pure-eval</literal> nix config option is on. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry xml:id="builtin-pathExists"> + <term><function>builtins.pathExists</function> + <replaceable>path</replaceable></term> + + <listitem><para>Return <literal>true</literal> if the path + <replaceable>path</replaceable> exists at evaluation time, and + <literal>false</literal> otherwise.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="builtin-placeholder"> + <term><function>builtins.placeholder</function> + <replaceable>output</replaceable></term> + + <listitem><para>Return a placeholder string for the specified + <replaceable>output</replaceable> that will be substituted by the + corresponding output path at build time. Typical outputs would be + <literal>"out"</literal>, <literal>"bin"</literal> or + <literal>"dev"</literal>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="builtin-readDir"> + <term><function>builtins.readDir</function> + <replaceable>path</replaceable></term> + + <listitem><para>Return the contents of the directory + <replaceable>path</replaceable> as a set mapping directory entries + to the corresponding file type. For instance, if directory + <filename>A</filename> contains a regular file + <filename>B</filename> and another directory + <filename>C</filename>, then <literal>builtins.readDir + ./A</literal> will return the set + +<programlisting> +{ B = "regular"; C = "directory"; }</programlisting> + + The possible values for the file type are + <literal>"regular"</literal>, <literal>"directory"</literal>, + <literal>"symlink"</literal> and + <literal>"unknown"</literal>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-readFile"> + <term><function>builtins.readFile</function> + <replaceable>path</replaceable></term> + + <listitem><para>Return the contents of the file + <replaceable>path</replaceable> as a string.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-removeAttrs"> + <term><function>removeAttrs</function> + <replaceable>set</replaceable> <replaceable>list</replaceable></term> + <term><function>builtins.removeAttrs</function> + <replaceable>set</replaceable> <replaceable>list</replaceable></term> + + <listitem><para>Remove the attributes listed in + <replaceable>list</replaceable> from + <replaceable>set</replaceable>. The attributes don’t have to + exist in <replaceable>set</replaceable>. For instance, + +<programlisting> +removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</programlisting> + + evaluates to <literal>{ y = 2; }</literal>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-replaceStrings"> + <term><function>builtins.replaceStrings</function> + <replaceable>from</replaceable> <replaceable>to</replaceable> <replaceable>s</replaceable></term> + + <listitem><para>Given string <replaceable>s</replaceable>, replace + every occurrence of the strings in <replaceable>from</replaceable> + with the corresponding string in + <replaceable>to</replaceable>. For example, + +<programlisting> +builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar" +</programlisting> + + evaluates to <literal>"fabir"</literal>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-seq"> + <term><function>builtins.seq</function> + <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> + + <listitem><para>Evaluate <replaceable>e1</replaceable>, then + evaluate and return <replaceable>e2</replaceable>. This ensures + that a computation is strict in the value of + <replaceable>e1</replaceable>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-sort"> + <term><function>builtins.sort</function> + <replaceable>comparator</replaceable> <replaceable>list</replaceable></term> + + <listitem><para>Return <replaceable>list</replaceable> in sorted + order. It repeatedly calls the function + <replaceable>comparator</replaceable> with two elements. The + comparator should return <literal>true</literal> if the first + element is less than the second, and <literal>false</literal> + otherwise. For example, + +<programlisting> +builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ] +</programlisting> + + produces the list <literal>[ 42 77 147 249 483 526 + ]</literal>.</para> + + <para>This is a stable sort: it preserves the relative order of + elements deemed equal by the comparator.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-split"> + <term><function>builtins.split</function> + <replaceable>regex</replaceable> <replaceable>str</replaceable></term> + + <listitem><para>Returns a list composed of non matched strings interleaved + with the lists of the <link xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended + POSIX regular expression</link> <replaceable>regex</replaceable> matches + of <replaceable>str</replaceable>. Each item in the lists of matched + sequences is a regex group. + +<programlisting> +builtins.split "(a)b" "abc" +</programlisting> + +Evaluates to <literal>[ "" [ "a" ] "c" ]</literal>. + +<programlisting> +builtins.split "([ac])" "abc" +</programlisting> + +Evaluates to <literal>[ "" [ "a" ] "b" [ "c" ] "" ]</literal>. + +<programlisting> +builtins.split "(a)|(c)" "abc" +</programlisting> + +Evaluates to <literal>[ "" [ "a" null ] "b" [ null "c" ] "" ]</literal>. + +<programlisting> +builtins.split "([[:upper:]]+)" " FOO " +</programlisting> + +Evaluates to <literal>[ " " [ "FOO" ] " " ]</literal>. + + </para></listitem> + </varlistentry> + + + <varlistentry xml:id="builtin-splitVersion"> + <term><function>builtins.splitVersion</function> + <replaceable>s</replaceable></term> + + <listitem><para>Split a string representing a version into its + components, by the same version splitting logic underlying the + version comparison in <link linkend="ssec-version-comparisons"> + <command>nix-env -u</command></link>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-stringLength"> + <term><function>builtins.stringLength</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return the length of the string + <replaceable>e</replaceable>. If <replaceable>e</replaceable> is + not a string, evaluation is aborted.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-sub"> + <term><function>builtins.sub</function> + <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> + + <listitem><para>Return the difference between the numbers + <replaceable>e1</replaceable> and + <replaceable>e2</replaceable>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-substring"> + <term><function>builtins.substring</function> + <replaceable>start</replaceable> <replaceable>len</replaceable> + <replaceable>s</replaceable></term> + + <listitem><para>Return the substring of + <replaceable>s</replaceable> from character position + <replaceable>start</replaceable> (zero-based) up to but not + including <replaceable>start + len</replaceable>. If + <replaceable>start</replaceable> is greater than the length of the + string, an empty string is returned, and if <replaceable>start + + len</replaceable> lies beyond the end of the string, only the + substring up to the end of the string is returned. + <replaceable>start</replaceable> must be + non-negative. For example, + +<programlisting> +builtins.substring 0 3 "nixos" +</programlisting> + + evaluates to <literal>"nix"</literal>. + </para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-tail"> + <term><function>builtins.tail</function> + <replaceable>list</replaceable></term> + + <listitem><para>Return the second to last elements of a list; + abort evaluation if the argument isn’t a list or is an empty + list.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-throw"> + <term><function>throw</function> + <replaceable>s</replaceable></term> + <term><function>builtins.throw</function> + <replaceable>s</replaceable></term> + + <listitem><para>Throw an error message + <replaceable>s</replaceable>. This usually aborts Nix expression + evaluation, but in <command>nix-env -qa</command> and other + commands that try to evaluate a set of derivations to get + information about those derivations, a derivation that throws an + error is silently skipped (which is not the case for + <function>abort</function>).</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-toFile"> + <term><function>builtins.toFile</function> + <replaceable>name</replaceable> + <replaceable>s</replaceable></term> + + <listitem><para>Store the string <replaceable>s</replaceable> in a + file in the Nix store and return its path. The file has suffix + <replaceable>name</replaceable>. This file can be used as an + input to derivations. One application is to write builders + “inline”. For instance, the following Nix expression combines + <xref linkend="ex-hello-nix"/> and <xref linkend="ex-hello-builder"/> into one file: + +<programlisting> +{ stdenv, fetchurl, perl }: + +stdenv.mkDerivation { + name = "hello-2.1.1"; + + builder = builtins.toFile "builder.sh" " + source $stdenv/setup + + PATH=$perl/bin:$PATH + + tar xvfz $src + cd hello-* + ./configure --prefix=$out + make + make install + "; + + src = fetchurl { + url = "http://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; + sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; + }; + inherit perl; +}</programlisting> + + </para> + + <para>It is even possible for one file to refer to another, e.g., + +<programlisting> + builder = let + configFile = builtins.toFile "foo.conf" " + # This is some dummy configuration file. + <replaceable>...</replaceable> + "; + in builtins.toFile "builder.sh" " + source $stdenv/setup + <replaceable>...</replaceable> + cp ${configFile} $out/etc/foo.conf + ";</programlisting> + + Note that <literal>${configFile}</literal> is an antiquotation + (see <xref linkend="ssec-values"/>), so the result of the + expression <literal>configFile</literal> (i.e., a path like + <filename>/nix/store/m7p7jfny445k...-foo.conf</filename>) will be + spliced into the resulting string.</para> + + <para>It is however <emphasis>not</emphasis> allowed to have files + mutually referring to each other, like so: + +<programlisting> +let + foo = builtins.toFile "foo" "...${bar}..."; + bar = builtins.toFile "bar" "...${foo}..."; +in foo</programlisting> + + This is not allowed because it would cause a cyclic dependency in + the computation of the cryptographic hashes for + <varname>foo</varname> and <varname>bar</varname>.</para> + <para>It is also not possible to reference the result of a derivation. + If you are using Nixpkgs, the <literal>writeTextFile</literal> function is able to + do that.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-toJSON"> + <term><function>builtins.toJSON</function> <replaceable>e</replaceable></term> + + <listitem><para>Return a string containing a JSON representation + of <replaceable>e</replaceable>. Strings, integers, floats, booleans, + nulls and lists are mapped to their JSON equivalents. Sets + (except derivations) are represented as objects. Derivations are + translated to a JSON string containing the derivation’s output + path. Paths are copied to the store and represented as a JSON + string of the resulting store path.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-toPath"> + <term><function>builtins.toPath</function> <replaceable>s</replaceable></term> + + <listitem><para> DEPRECATED. Use <literal>/. + "/path"</literal> + to convert a string into an absolute path. For relative paths, + use <literal>./. + "/path"</literal>. + </para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-toString"> + <term><function>toString</function> <replaceable>e</replaceable></term> + <term><function>builtins.toString</function> <replaceable>e</replaceable></term> + + <listitem><para>Convert the expression + <replaceable>e</replaceable> to a string. + <replaceable>e</replaceable> can be:</para> + <itemizedlist> + <listitem><para>A string (in which case the string is returned unmodified).</para></listitem> + <listitem><para>A path (e.g., <literal>toString /foo/bar</literal> yields <literal>"/foo/bar"</literal>.</para></listitem> + <listitem><para>A set containing <literal>{ __toString = self: ...; }</literal>.</para></listitem> + <listitem><para>An integer.</para></listitem> + <listitem><para>A list, in which case the string representations of its elements are joined with spaces.</para></listitem> + <listitem><para>A Boolean (<literal>false</literal> yields <literal>""</literal>, <literal>true</literal> yields <literal>"1"</literal>).</para></listitem> + <listitem><para><literal>null</literal>, which yields the empty string.</para></listitem> + </itemizedlist> + </listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-toXML"> + <term><function>builtins.toXML</function> <replaceable>e</replaceable></term> + + <listitem><para>Return a string containing an XML representation + of <replaceable>e</replaceable>. The main application for + <function>toXML</function> is to communicate information with the + builder in a more structured format than plain environment + variables.</para> + + <!-- TODO: more formally describe the schema of the XML + representation --> + + <para><xref linkend="ex-toxml"/> shows an example where this is + the case. The builder is supposed to generate the configuration + file for a <link xlink:href="http://jetty.mortbay.org/">Jetty + servlet container</link>. A servlet container contains a number + of servlets (<filename>*.war</filename> files) each exported under + a specific URI prefix. So the servlet configuration is a list of + sets containing the <varname>path</varname> and + <varname>war</varname> of the servlet (<xref linkend="ex-toxml-co-servlets"/>). This kind of information is + difficult to communicate with the normal method of passing + information through an environment variable, which just + concatenates everything together into a string (which might just + work in this case, but wouldn’t work if fields are optional or + contain lists themselves). Instead the Nix expression is + converted to an XML representation with + <function>toXML</function>, which is unambiguous and can easily be + processed with the appropriate tools. For instance, in the + example an XSLT stylesheet (<xref linkend="ex-toxml-co-stylesheet"/>) is applied to it (<xref linkend="ex-toxml-co-apply"/>) to + generate the XML configuration file for the Jetty server. The XML + representation produced from <xref linkend="ex-toxml-co-servlets"/> by <function>toXML</function> is shown in <xref linkend="ex-toxml-result"/>.</para> + + <para>Note that <xref linkend="ex-toxml"/> uses the <function linkend="builtin-toFile">toFile</function> built-in to write the + builder and the stylesheet “inline” in the Nix expression. The + path of the stylesheet is spliced into the builder at + <literal>xsltproc ${stylesheet} + <replaceable>...</replaceable></literal>.</para> + + <example xml:id="ex-toxml"><title>Passing information to a builder + using <function>toXML</function></title> + +<programlisting><![CDATA[ +{ stdenv, fetchurl, libxslt, jira, uberwiki }: + +stdenv.mkDerivation (rec { + name = "web-server"; + + buildInputs = [ libxslt ]; + + builder = builtins.toFile "builder.sh" " + source $stdenv/setup + mkdir $out + echo "$servlets" | xsltproc ${stylesheet} - > $out/server-conf.xml]]> <co xml:id="ex-toxml-co-apply"/> <![CDATA[ + "; + + stylesheet = builtins.toFile "stylesheet.xsl"]]> <co xml:id="ex-toxml-co-stylesheet"/> <![CDATA[ + "<?xml version='1.0' encoding='UTF-8'?> + <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'> + <xsl:template match='/'> + <Configure> + <xsl:for-each select='/expr/list/attrs'> + <Call name='addWebApplication'> + <Arg><xsl:value-of select=\"attr[@name = 'path']/string/@value\" /></Arg> + <Arg><xsl:value-of select=\"attr[@name = 'war']/path/@value\" /></Arg> + </Call> + </xsl:for-each> + </Configure> + </xsl:template> + </xsl:stylesheet> + "; + + servlets = builtins.toXML []]> <co xml:id="ex-toxml-co-servlets"/> <![CDATA[ + { path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; } + { path = "/wiki"; war = uberwiki + "/uberwiki.war"; } + ]; +})]]></programlisting> + + </example> + + <example xml:id="ex-toxml-result"><title>XML representation produced by + <function>toXML</function></title> + +<programlisting><![CDATA[<?xml version='1.0' encoding='utf-8'?> +<expr> + <list> + <attrs> + <attr name="path"> + <string value="/bugtracker" /> + </attr> + <attr name="war"> + <path value="/nix/store/d1jh9pasa7k2...-jira/lib/atlassian-jira.war" /> + </attr> + </attrs> + <attrs> + <attr name="path"> + <string value="/wiki" /> + </attr> + <attr name="war"> + <path value="/nix/store/y6423b1yi4sx...-uberwiki/uberwiki.war" /> + </attr> + </attrs> + </list> +</expr>]]></programlisting> + + </example> + + </listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-trace"> + <term><function>builtins.trace</function> + <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> + + <listitem><para>Evaluate <replaceable>e1</replaceable> and print its + abstract syntax representation on standard error. Then return + <replaceable>e2</replaceable>. This function is useful for + debugging.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="builtin-tryEval"> + <term><function>builtins.tryEval</function> + <replaceable>e</replaceable></term> + + <listitem><para>Try to shallowly evaluate <replaceable>e</replaceable>. + Return a set containing the attributes <literal>success</literal> + (<literal>true</literal> if <replaceable>e</replaceable> evaluated + successfully, <literal>false</literal> if an error was thrown) and + <literal>value</literal>, equalling <replaceable>e</replaceable> + if successful and <literal>false</literal> otherwise. Note that this + doesn't evaluate <replaceable>e</replaceable> deeply, so + <literal>let e = { x = throw ""; }; in (builtins.tryEval e).success + </literal> will be <literal>true</literal>. Using <literal>builtins.deepSeq + </literal> one can get the expected result: <literal>let e = { x = throw ""; + }; in (builtins.tryEval (builtins.deepSeq e e)).success</literal> will be + <literal>false</literal>. + </para></listitem> + + </varlistentry> + + + <varlistentry xml:id="builtin-typeOf"> + <term><function>builtins.typeOf</function> + <replaceable>e</replaceable></term> + + <listitem><para>Return a string representing the type of the value + <replaceable>e</replaceable>, namely <literal>"int"</literal>, + <literal>"bool"</literal>, <literal>"string"</literal>, + <literal>"path"</literal>, <literal>"null"</literal>, + <literal>"set"</literal>, <literal>"list"</literal>, + <literal>"lambda"</literal> or + <literal>"float"</literal>.</para></listitem> + + </varlistentry> + + +</variablelist> + + +</section> + + +</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’s required that the +remote machine is accessible via SSH and that it has Nix +installed. You can test whether connecting to the remote Nix instance +works, e.g. + +<screen> +$ nix ping-store --store ssh://mac +</screen> + +will try to connect to the machine named <literal>mac</literal>. It is +possible to specify an SSH identity file as part of the remote store +URI, e.g. + +<screen> +$ nix ping-store --store ssh://mac?ssh-key=/home/alice/my-key +</screen> + +Since builds should be non-interactive, the key should not have a +passphrase. Alternatively, you can load identities ahead of time into +<command>ssh-agent</command> or <command>gpg-agent</command>.</para> + +<para>If you get the error + +<screen> +bash: nix-store: command not found +error: cannot connect to 'mac' +</screen> + +then you need to ensure that the <envar>PATH</envar> of +non-interactive login shells contains Nix.</para> + +<warning><para>If you are building via the Nix daemon, it is the Nix +daemon user account (that is, <literal>root</literal>) that should +have SSH access to the remote machine. If you can’t or don’t want to +configure <literal>root</literal> to be able to access to remote +machine, you can use a private Nix store instead by passing +e.g. <literal>--store ~/my-nix</literal>.</para></warning> + +<para>The list of remote machines can be specified on the command line +or in the Nix configuration file. The former is convenient for +testing. For example, the following command allows you to build a +derivation for <literal>x86_64-darwin</literal> on a Linux machine: + +<screen> +$ uname +Linux + +$ nix build \ + '(with import <nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \ + --builders 'ssh://mac x86_64-darwin' +[1/0/1 built, 0.0 MiB DL] building foo on ssh://mac + +$ cat ./result +Darwin +</screen> + +It is possible to specify multiple builders separated by a semicolon +or a newline, e.g. + +<screen> + --builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd' +</screen> +</para> + +<para>Each machine specification consists of the following elements, +separated by spaces. Only the first element is required. +To leave a field at its default, set it to <literal>-</literal>. + +<orderedlist> + + <listitem><para>The URI of the remote store in the format + <literal>ssh://[<replaceable>username</replaceable>@]<replaceable>hostname</replaceable></literal>, + e.g. <literal>ssh://nix@mac</literal> or + <literal>ssh://mac</literal>. For backward compatibility, + <literal>ssh://</literal> may be omitted. The hostname may be an + alias defined in your + <filename>~/.ssh/config</filename>.</para></listitem> + + <listitem><para>A comma-separated list of Nix platform type + identifiers, such as <literal>x86_64-darwin</literal>. It is + possible for a machine to support multiple platform types, e.g., + <literal>i686-linux,x86_64-linux</literal>. If omitted, this + defaults to the local platform type.</para></listitem> + + <listitem><para>The SSH identity file to be used to log in to the + remote machine. If omitted, SSH will use its regular + identities.</para></listitem> + + <listitem><para>The maximum number of builds that Nix will execute + in parallel on the machine. Typically this should be equal to the + number of CPU cores. For instance, the machine + <literal>itchy</literal> in the example will execute up to 8 builds + in parallel.</para></listitem> + + <listitem><para>The “speed factor”, indicating the relative speed of + the machine. If there are multiple machines of the right type, Nix + will prefer the fastest, taking load into account.</para></listitem> + + <listitem><para>A comma-separated list of <emphasis>supported + features</emphasis>. If a derivation has the + <varname>requiredSystemFeatures</varname> attribute, then Nix will + only perform the derivation on a machine that has the specified + features. For instance, the attribute + +<programlisting> +requiredSystemFeatures = [ "kvm" ]; +</programlisting> + + will cause the build to be performed on a machine that has the + <literal>kvm</literal> feature.</para></listitem> + + <listitem><para>A comma-separated list of <emphasis>mandatory + features</emphasis>. A machine will only be used to build a + derivation if all of the machine’s mandatory features appear in the + derivation’s <varname>requiredSystemFeatures</varname> + attribute..</para></listitem> + +</orderedlist> + +For example, the machine specification + +<programlisting> +nix@scratchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 1 kvm +nix@itchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 2 +nix@poochie.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 1 2 kvm benchmark +</programlisting> + +specifies several machines that can perform +<literal>i686-linux</literal> builds. However, +<literal>poochie</literal> will only do builds that have the attribute + +<programlisting> +requiredSystemFeatures = [ "benchmark" ]; +</programlisting> + +or + +<programlisting> +requiredSystemFeatures = [ "benchmark" "kvm" ]; +</programlisting> + +<literal>itchy</literal> cannot do builds that require +<literal>kvm</literal>, but <literal>scratchy</literal> does support +such builds. For regular builds, <literal>itchy</literal> will be +preferred over <literal>scratchy</literal> because it has a higher +speed factor.</para> + +<para>Remote builders can also be configured in +<filename>nix.conf</filename>, e.g. + +<programlisting> +builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd +</programlisting> + +Finally, remote builders can be configured in a separate configuration +file included in <option>builders</option> via the syntax +<literal>@<replaceable>file</replaceable></literal>. For example, + +<programlisting> +builders = @/etc/nix/machines +</programlisting> + +causes the list of machines in <filename>/etc/nix/machines</filename> +to be included. (This is the default.)</para> + +<para>If you want the builders to use caches, you likely want to set +the option <link linkend="conf-builders-use-substitutes"><literal>builders-use-substitutes</literal></link> +in your local <filename>nix.conf</filename>.</para> + +<para>To build only on remote builders and disable building on the local machine, +you can use the option <option>--max-jobs 0</option>.</para> + +</chapter> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="chap-tuning-cores-and-jobs"> + +<title>Tuning Cores and Jobs</title> + +<para>Nix has two relevant settings with regards to how your CPU cores +will be utilized: <xref linkend="conf-cores"/> and +<xref linkend="conf-max-jobs"/>. This chapter will talk about what +they are, how they interact, and their configuration trade-offs.</para> + +<variablelist> + <varlistentry> + <term><xref linkend="conf-max-jobs"/></term> + <listitem><para> + Dictates how many separate derivations will be built at the same + time. If you set this to zero, the local machine will do no + builds. Nix will still substitute from binary caches, and build + remotely if remote builders are configured. + </para></listitem> + </varlistentry> + <varlistentry> + <term><xref linkend="conf-cores"/></term> + <listitem><para> + Suggests how many cores each derivation should use. Similar to + <command>make -j</command>. + </para></listitem> + </varlistentry> +</variablelist> + +<para>The <xref linkend="conf-cores"/> setting determines the value of +<envar>NIX_BUILD_CORES</envar>. <envar>NIX_BUILD_CORES</envar> is equal +to <xref linkend="conf-cores"/>, unless <xref linkend="conf-cores"/> +equals <literal>0</literal>, in which case <envar>NIX_BUILD_CORES</envar> +will be the total number of cores in the system.</para> + +<para>The maximum number of consumed cores is a simple multiplication, +<xref linkend="conf-max-jobs"/> * <envar>NIX_BUILD_CORES</envar>.</para> + +<para>The balance on how to set these two independent variables depends +upon each builder's workload and hardware. Here are a few example +scenarios on a machine with 24 cores:</para> + +<table> + <caption>Balancing 24 Build Cores</caption> + <thead> + <tr> + <th><xref linkend="conf-max-jobs"/></th> + <th><xref linkend="conf-cores"/></th> + <th><envar>NIX_BUILD_CORES</envar></th> + <th>Maximum Processes</th> + <th>Result</th> + </tr> + </thead> + <tbody> + <tr> + <td>1</td> + <td>24</td> + <td>24</td> + <td>24</td> + <td> + One derivation will be built at a time, each one can use 24 + cores. Undersold if a job can’t use 24 cores. + </td> + </tr> + + <tr> + <td>4</td> + <td>6</td> + <td>6</td> + <td>24</td> + <td> + Four derivations will be built at once, each given access to + six cores. + </td> + </tr> + <tr> + <td>12</td> + <td>6</td> + <td>6</td> + <td>72</td> + <td> + 12 derivations will be built at once, each given access to six + cores. This configuration is over-sold. If all 12 derivations + being built simultaneously try to use all six cores, the + machine's performance will be degraded due to extensive context + switching between the 12 builds. + </td> + </tr> + <tr> + <td>24</td> + <td>1</td> + <td>1</td> + <td>24</td> + <td> + 24 derivations can build at the same time, each using a single + core. Never oversold, but derivations which require many cores + will be very slow to compile. + </td> + </tr> + <tr> + <td>24</td> + <td>0</td> + <td>24</td> + <td>576</td> + <td> + 24 derivations can build at the same time, each using all the + available cores of the machine. Very likely to be oversold, + and very likely to suffer context switches. + </td> + </tr> + </tbody> +</table> + +<para>It is up to the derivations' build script to respect +host's requested cores-per-build by following the value of the +<envar>NIX_BUILD_CORES</envar> environment variable.</para> + +</chapter> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="chap-diff-hook" version="5.0"> + +<title>Verifying Build Reproducibility with <option linkend="conf-diff-hook">diff-hook</option></title> + +<subtitle>Check build reproducibility by running builds multiple times +and comparing their results.</subtitle> + +<para>Specify a program with Nix's <xref linkend="conf-diff-hook"/> to +compare build results when two builds produce different results. Note: +this hook is only executed if the results are not the same, this hook +is not used for determining if the results are the same.</para> + +<para>For purposes of demonstration, we'll use the following Nix file, +<filename>deterministic.nix</filename> for testing:</para> + +<programlisting> +let + inherit (import <nixpkgs> {}) runCommand; +in { + stable = runCommand "stable" {} '' + touch $out + ''; + + unstable = runCommand "unstable" {} '' + echo $RANDOM > $out + ''; +} +</programlisting> + +<para>Additionally, <filename>nix.conf</filename> contains: + +<programlisting> +diff-hook = /etc/nix/my-diff-hook +run-diff-hook = true +</programlisting> + +where <filename>/etc/nix/my-diff-hook</filename> is an executable +file containing: + +<programlisting> +#!/bin/sh +exec >&2 +echo "For derivation $3:" +/run/current-system/sw/bin/diff -r "$1" "$2" +</programlisting> + +</para> + +<para>The diff hook is executed by the same user and group who ran the +build. However, the diff hook does not have write access to the store +path just built.</para> + +<section> + <title> + Spot-Checking Build Determinism + </title> + + <para> + Verify a path which already exists in the Nix store by passing + <option>--check</option> to the build command. + </para> + + <para>If the build passes and is deterministic, Nix will exit with a + status code of 0:</para> + + <screen> +$ nix-build ./deterministic.nix -A stable +this derivation will be built: + /nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv +building '/nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv'... +/nix/store/yyxlzw3vqaas7wfp04g0b1xg51f2czgq-stable + +$ nix-build ./deterministic.nix -A stable --check +checking outputs of '/nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv'... +/nix/store/yyxlzw3vqaas7wfp04g0b1xg51f2czgq-stable +</screen> + + <para>If the build is not deterministic, Nix will exit with a status + code of 1:</para> + + <screen> +$ nix-build ./deterministic.nix -A unstable +this derivation will be built: + /nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv +building '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'... +/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable + +$ nix-build ./deterministic.nix -A unstable --check +checking outputs of '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'... +error: derivation '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv' may not be deterministic: output '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable' differs +</screen> + +<para>In the Nix daemon's log, we will now see: +<screen> +For derivation /nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv: +1c1 +< 8108 +--- +> 30204 +</screen> +</para> + + <para>Using <option>--check</option> with <option>--keep-failed</option> + will cause Nix to keep the second build's output in a special, + <literal>.check</literal> path:</para> + + <screen> +$ nix-build ./deterministic.nix -A unstable --check --keep-failed +checking outputs of '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'... +note: keeping build directory '/tmp/nix-build-unstable.drv-0' +error: derivation '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv' may not be deterministic: output '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable' differs from '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check' +</screen> + + <para>In particular, notice the + <literal>/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check</literal> + output. Nix has copied the build results to that directory where you + can examine it.</para> + + <note xml:id="check-dirs-are-unregistered"> + <title><literal>.check</literal> paths are not registered store paths</title> + + <para>Check paths are not protected against garbage collection, + and this path will be deleted on the next garbage collection.</para> + + <para>The path is guaranteed to be alive for the duration of + <xref linkend="conf-diff-hook"/>'s execution, but may be deleted + any time after.</para> + + <para>If the comparison is performed as part of automated tooling, + please use the diff-hook or author your tooling to handle the case + where the build was not deterministic and also a check path does + not exist.</para> + </note> + + <para> + <option>--check</option> is only usable if the derivation has + been built on the system already. If the derivation has not been + built Nix will fail with the error: + <screen> +error: some outputs of '/nix/store/hzi1h60z2qf0nb85iwnpvrai3j2w7rr6-unstable.drv' are not valid, so checking is not possible +</screen> + + Run the build without <option>--check</option>, and then try with + <option>--check</option> again. + </para> +</section> + +<section> + <title> + Automatic and Optionally Enforced Determinism Verification + </title> + + <para> + Automatically verify every build at build time by executing the + build multiple times. + </para> + + <para> + Setting <xref linkend="conf-repeat"/> and + <xref linkend="conf-enforce-determinism"/> in your + <filename>nix.conf</filename> permits the automated verification + of every build Nix performs. + </para> + + <para> + The following configuration will run each build three times, and + will require the build to be deterministic: + + <programlisting> +enforce-determinism = true +repeat = 2 +</programlisting> + </para> + + <para> + Setting <xref linkend="conf-enforce-determinism"/> to false as in + the following configuration will run the build multiple times, + execute the build hook, but will allow the build to succeed even + if it does not build reproducibly: + + <programlisting> +enforce-determinism = false +repeat = 1 +</programlisting> + </para> + + <para> + An example output of this configuration: + <screen> +$ nix-build ./test.nix -A unstable +this derivation will be built: + /nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv +building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 1/2)... +building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 2/2)... +output '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable' of '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' differs from '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable.check' from previous round +/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable +</screen> + </para> +</section> +</chapter> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="chap-post-build-hook" version="5.0"> + +<title>Using the <option linkend="conf-post-build-hook">post-build-hook</option></title> +<subtitle>Uploading to an S3-compatible binary cache after each build</subtitle> + + +<section xml:id="chap-post-build-hook-caveats"> + <title>Implementation Caveats</title> + <para>Here we use the post-build hook to upload to a binary cache. + This is a simple and working example, but it is not suitable for all + use cases.</para> + + <para>The post build hook program runs after each executed build, + and blocks the build loop. The build loop exits if the hook program + fails.</para> + + <para>Concretely, this implementation will make Nix slow or unusable + when the internet is slow or unreliable.</para> + + <para>A more advanced implementation might pass the store paths to a + user-supplied daemon or queue for processing the store paths outside + of the build loop.</para> +</section> + +<section> + <title>Prerequisites</title> + + <para> + This tutorial assumes you have configured an S3-compatible binary cache + according to the instructions at + <xref linkend="ssec-s3-substituter-authenticated-writes"/>, and + that the <literal>root</literal> user's default AWS profile can + upload to the bucket. + </para> +</section> + +<section> + <title>Set up a Signing Key</title> + <para>Use <command>nix-store --generate-binary-cache-key</command> to + create our public and private signing keys. We will sign paths + with the private key, and distribute the public key for verifying + the authenticity of the paths.</para> + + <screen> +# nix-store --generate-binary-cache-key example-nix-cache-1 /etc/nix/key.private /etc/nix/key.public +# cat /etc/nix/key.public +example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM= +</screen> + +<para>Then, add the public key and the cache URL to your +<filename>nix.conf</filename>'s <xref linkend="conf-trusted-public-keys"/> +and <xref linkend="conf-substituters"/> like:</para> + +<programlisting> +substituters = https://cache.nixos.org/ s3://example-nix-cache +trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM= +</programlisting> + +<para>We will restart the Nix daemon in a later step.</para> +</section> + +<section> + <title>Implementing the build hook</title> + <para>Write the following script to + <filename>/etc/nix/upload-to-cache.sh</filename>: + </para> + + <programlisting> +#!/bin/sh + +set -eu +set -f # disable globbing +export IFS=' ' + +echo "Signing paths" $OUT_PATHS +nix sign-paths --key-file /etc/nix/key.private $OUT_PATHS +echo "Uploading paths" $OUT_PATHS +exec nix copy --to 's3://example-nix-cache' $OUT_PATHS +</programlisting> + + <note> + <title>Should <literal>$OUT_PATHS</literal> be quoted?</title> + <para> + The <literal>$OUT_PATHS</literal> variable is a space-separated + list of Nix store paths. In this case, we expect and want the + shell to perform word splitting to make each output path its + own argument to <command>nix sign-paths</command>. Nix guarantees + the paths will not contain any spaces, however a store path + might contain glob characters. The <command>set -f</command> + disables globbing in the shell. + </para> + </note> + <para> + Then make sure the hook program is executable by the <literal>root</literal> user: + <screen> +# chmod +x /etc/nix/upload-to-cache.sh +</screen></para> +</section> + +<section> + <title>Updating Nix Configuration</title> + + <para>Edit <filename>/etc/nix/nix.conf</filename> to run our hook, + by adding the following configuration snippet at the end:</para> + + <programlisting> +post-build-hook = /etc/nix/upload-to-cache.sh +</programlisting> + +<para>Then, restart the <command>nix-daemon</command>.</para> +</section> + +<section> + <title>Testing</title> + + <para>Build any derivation, for example:</para> + + <screen> +$ nix-build -E '(import <nixpkgs> {}).writeText "example" (builtins.toString builtins.currentTime)' +this derivation will be built: + /nix/store/s4pnfbkalzy5qz57qs6yybna8wylkig6-example.drv +building '/nix/store/s4pnfbkalzy5qz57qs6yybna8wylkig6-example.drv'... +running post-build-hook '/home/grahamc/projects/github.com/NixOS/nix/post-hook.sh'... +post-build-hook: Signing paths /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example +post-build-hook: Uploading paths /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example +/nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example +</screen> + + <para>Then delete the path from the store, and try substituting it from the binary cache:</para> + <screen> +$ rm ./result +$ nix-store --delete /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example +</screen> + +<para>Now, copy the path back from the cache:</para> +<screen> +$ nix-store --realise /nix/store/ibcyipq5gf91838ldx40mjsp0b8w9n18-example +copying path '/nix/store/m8bmqwrch6l3h8s0k3d673xpmipcdpsa-example from 's3://example-nix-cache'... +warning: you did not specify '--add-root'; the result might be removed by the garbage collector +/nix/store/m8bmqwrch6l3h8s0k3d673xpmipcdpsa-example +</screen> +</section> +<section> + <title>Conclusion</title> + <para> + We now have a Nix installation configured to automatically sign and + upload every local build to a remote binary cache. + </para> + + <para> + Before deploying this to production, be sure to consider the + implementation caveats in <xref linkend="chap-post-build-hook-caveats"/>. + </para> +</section> +</chapter> + +</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>“Errors only”: only print messages + explaining why the Nix invocation failed.</para></listitem> + </varlistentry> + + <varlistentry><term>1</term> + <listitem><para>“Informational”: print + <emphasis>useful</emphasis> messages about what Nix is doing. + This is the default.</para></listitem> + </varlistentry> + + <varlistentry><term>2</term> + <listitem><para>“Talkative”: print more informational + messages.</para></listitem> + </varlistentry> + + <varlistentry><term>3</term> + <listitem><para>“Chatty”: print even more + informational messages.</para></listitem> + </varlistentry> + + <varlistentry><term>4</term> + <listitem><para>“Debug”: print debug + information.</para></listitem> + </varlistentry> + + <varlistentry><term>5</term> + <listitem><para>“Vomit”: print vast amounts of debug + information.</para></listitem> + </varlistentry> + + </variablelist> + + </listitem> + +</varlistentry> + + +<varlistentry><term><option>--quiet</option></term> + + <listitem> + + <para>Decreases the level of verbosity of diagnostic messages + printed on standard error. This is the inverse option to + <option>-v</option> / <option>--verbose</option>. + </para> + + <para>This option may be specified repeatedly. See the previous + verbosity levels list.</para> + + </listitem> + +</varlistentry> + + +<varlistentry xml:id="opt-log-format"><term><option>--log-format</option> <replaceable>format</replaceable></term> + + <listitem> + + <para>This option can be used to change the output of the log format, with + <replaceable>format</replaceable> being one of:</para> + + <variablelist> + + <varlistentry><term>raw</term> + <listitem><para>This is the raw format, as outputted by nix-build.</para></listitem> + </varlistentry> + + <varlistentry><term>internal-json</term> + <listitem><para>Outputs the logs in a structured manner. NOTE: the json schema is not guarantees to be stable between releases.</para></listitem> + </varlistentry> + + <varlistentry><term>bar</term> + <listitem><para>Only display a progress bar during the builds.</para></listitem> + </varlistentry> + + <varlistentry><term>bar-with-logs</term> + <listitem><para>Display the raw logs, with the progress bar at the bottom.</para></listitem> + </varlistentry> + + </variablelist> + + </listitem> + +</varlistentry> + +<varlistentry><term><option>--no-build-output</option> / <option>-Q</option></term> + + <listitem><para>By default, output written by builders to standard + output and standard error is echoed to the Nix command's standard + error. This option suppresses this behaviour. Note that the + builder's standard output and error are always written to a log file + in + <filename><replaceable>prefix</replaceable>/nix/var/log/nix</filename>.</para></listitem> + +</varlistentry> + + +<varlistentry xml:id="opt-max-jobs"><term><option>--max-jobs</option> / <option>-j</option> +<replaceable>number</replaceable></term> + + <listitem> + + <para>Sets the maximum number of build jobs that Nix will + perform in parallel to the specified number. Specify + <literal>auto</literal> to use the number of CPUs in the system. + The default is specified by the <link linkend="conf-max-jobs"><literal>max-jobs</literal></link> + configuration setting, which itself defaults to + <literal>1</literal>. A higher value is useful on SMP systems or to + exploit I/O latency.</para> + + <para> Setting it to <literal>0</literal> disallows building on the local + machine, which is useful when you want builds to happen only on remote + builders.</para> + + </listitem> + +</varlistentry> + + +<varlistentry xml:id="opt-cores"><term><option>--cores</option></term> + + <listitem><para>Sets the value of the <envar>NIX_BUILD_CORES</envar> + environment variable in the invocation of builders. Builders can + use this variable at their discretion to control the maximum amount + of parallelism. For instance, in Nixpkgs, if the derivation + attribute <varname>enableParallelBuilding</varname> is set to + <literal>true</literal>, the builder passes the + <option>-j<replaceable>N</replaceable></option> flag to GNU Make. + It defaults to the value of the <link linkend="conf-cores"><literal>cores</literal></link> + configuration setting, if set, or <literal>1</literal> otherwise. + The value <literal>0</literal> means that the builder should use all + available CPU cores in the system.</para></listitem> + +</varlistentry> + + +<varlistentry xml:id="opt-max-silent-time"><term><option>--max-silent-time</option></term> + + <listitem><para>Sets the maximum number of seconds that a builder + can go without producing any data on standard output or standard + error. The default is specified by the <link linkend="conf-max-silent-time"><literal>max-silent-time</literal></link> + configuration setting. <literal>0</literal> means no + time-out.</para></listitem> + +</varlistentry> + +<varlistentry xml:id="opt-timeout"><term><option>--timeout</option></term> + + <listitem><para>Sets the maximum number of seconds that a builder + can run. The default is specified by the <link linkend="conf-timeout"><literal>timeout</literal></link> + configuration setting. <literal>0</literal> means no + timeout.</para></listitem> + +</varlistentry> + +<varlistentry><term><option>--keep-going</option> / <option>-k</option></term> + + <listitem><para>Keep going in case of failed builds, to the + greatest extent possible. That is, if building an input of some + derivation fails, Nix will still build the other inputs, but not the + derivation itself. Without this option, Nix stops if any build + fails (except for builds of substitutes), possibly killing builds in + progress (in case of parallel or distributed builds).</para></listitem> + +</varlistentry> + + +<varlistentry><term><option>--keep-failed</option> / <option>-K</option></term> + + <listitem><para>Specifies that in case of a build failure, the + temporary directory (usually in <filename>/tmp</filename>) in which + the build takes place should not be deleted. The path of the build + directory is printed as an informational message. + </para> + </listitem> +</varlistentry> + + +<varlistentry><term><option>--fallback</option></term> + + <listitem> + + <para>Whenever Nix attempts to build a derivation for which + substitutes are known for each output path, but realising the output + paths through the substitutes fails, fall back on building the + derivation.</para> + + <para>The most common scenario in which this is useful is when we + have registered substitutes in order to perform binary distribution + from, say, a network repository. If the repository is down, the + realisation of the derivation will fail. When this option is + specified, Nix will build the derivation instead. Thus, + installation from binaries falls back on installation from source. + This option is not the default since it is generally not desirable + for a transient failure in obtaining the substitutes to lead to a + full build from source (with the related consumption of + resources).</para> + + </listitem> + +</varlistentry> + +<varlistentry><term><option>--no-build-hook</option></term> + + <listitem> + + <para>Disables the build hook mechanism. This allows to ignore remote + builders if they are setup on the machine.</para> + + <para>It's useful in cases where the bandwidth between the client and the + remote builder is too low. In that case it can take more time to upload the + sources to the remote builder and fetch back the result than to do the + computation locally.</para> + + </listitem> + +</varlistentry> + + + +<varlistentry><term><option>--readonly-mode</option></term> + + <listitem><para>When this option is used, no attempt is made to open + the Nix database. Most Nix operations do need database access, so + those operations will fail.</para></listitem> + +</varlistentry> + + +<varlistentry><term><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term> + + <listitem><para>This option is accepted by + <command>nix-env</command>, <command>nix-instantiate</command>, + <command>nix-shell</command> and <command>nix-build</command>. + When evaluating Nix expressions, the expression evaluator will + automatically try to call functions that + it encounters. It can automatically call functions for which every + argument has a <link linkend="ss-functions">default value</link> + (e.g., <literal>{ <replaceable>argName</replaceable> ? + <replaceable>defaultValue</replaceable> }: + <replaceable>...</replaceable></literal>). With + <option>--arg</option>, you can also call functions that have + arguments without a default value (or override a default value). + That is, if the evaluator encounters a function with an argument + named <replaceable>name</replaceable>, it will call it with value + <replaceable>value</replaceable>.</para> + + <para>For instance, the top-level <literal>default.nix</literal> in + Nixpkgs is actually a function: + +<programlisting> +{ # The system (e.g., `i686-linux') for which to build the packages. + system ? builtins.currentSystem + <replaceable>...</replaceable> +}: <replaceable>...</replaceable></programlisting> + + So if you call this Nix expression (e.g., when you do + <literal>nix-env -i <replaceable>pkgname</replaceable></literal>), + the function will be called automatically using the value <link linkend="builtin-currentSystem"><literal>builtins.currentSystem</literal></link> + for the <literal>system</literal> argument. You can override this + using <option>--arg</option>, e.g., <literal>nix-env -i + <replaceable>pkgname</replaceable> --arg system + \"i686-freebsd\"</literal>. (Note that since the argument is a Nix + string literal, you have to escape the quotes.)</para></listitem> + +</varlistentry> + + +<varlistentry><term><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term> + + <listitem><para>This option is like <option>--arg</option>, only the + value is not a Nix expression but a string. So instead of + <literal>--arg system \"i686-linux\"</literal> (the outer quotes are + to keep the shell happy) you can say <literal>--argstr system + i686-linux</literal>.</para></listitem> + +</varlistentry> + + +<varlistentry xml:id="opt-attr"><term><option>--attr</option> / <option>-A</option> +<replaceable>attrPath</replaceable></term> + + <listitem><para>Select an attribute from the top-level Nix + expression being evaluated. (<command>nix-env</command>, + <command>nix-instantiate</command>, <command>nix-build</command> and + <command>nix-shell</command> only.) The <emphasis>attribute + path</emphasis> <replaceable>attrPath</replaceable> is a sequence of + attribute names separated by dots. For instance, given a top-level + Nix expression <replaceable>e</replaceable>, the attribute path + <literal>xorg.xorgserver</literal> would cause the expression + <literal><replaceable>e</replaceable>.xorg.xorgserver</literal> to + be used. See <link linkend="refsec-nix-env-install-examples"><command>nix-env + --install</command></link> for some concrete examples.</para> + + <para>In addition to attribute names, you can also specify array + indices. For instance, the attribute path + <literal>foo.3.bar</literal> selects the <literal>bar</literal> + attribute of the fourth element of the array in the + <literal>foo</literal> attribute of the top-level + expression.</para></listitem> + +</varlistentry> + + +<varlistentry><term><option>--expr</option> / <option>-E</option></term> + + <listitem><para>Interpret the command line arguments as a list of + Nix expressions to be parsed and evaluated, rather than as a list + of file names of Nix expressions. + (<command>nix-instantiate</command>, <command>nix-build</command> + and <command>nix-shell</command> only.)</para> + + <para>For <command>nix-shell</command>, this option is commonly used + to give you a shell in which you can build the packages returned + by the expression. If you want to get a shell which contain the + <emphasis>built</emphasis> packages ready for use, give your + expression to the <command>nix-shell -p</command> convenience flag + instead.</para></listitem> + +</varlistentry> + + +<varlistentry xml:id="opt-I"><term><option>-I</option> <replaceable>path</replaceable></term> + + <listitem><para>Add a path to the Nix expression search path. This + option may be given multiple times. See the <envar linkend="env-NIX_PATH">NIX_PATH</envar> environment variable for + information on the semantics of the Nix search path. Paths added + through <option>-I</option> take precedence over + <envar>NIX_PATH</envar>.</para></listitem> + +</varlistentry> + + +<varlistentry><term><option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term> + + <listitem><para>Set the Nix configuration option + <replaceable>name</replaceable> to <replaceable>value</replaceable>. + This overrides settings in the Nix configuration file (see + <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para></listitem> + +</varlistentry> + + +<varlistentry><term><option>--repair</option></term> + + <listitem><para>Fix corrupted or missing store paths by + redownloading or rebuilding them. Note that this is slow because it + requires computing a cryptographic hash of the contents of every + path in the closure of the build. Also note the warning under + <command>nix-store --repair-path</command>.</para></listitem> + +</varlistentry> + + +</variablelist> + + +</chapter> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-common-env"> + +<title>Common Environment Variables</title> + + +<para>Most Nix commands interpret the following environment variables:</para> + +<variablelist xml:id="env-common"> + +<varlistentry><term><envar>IN_NIX_SHELL</envar></term> + + <listitem><para>Indicator that tells if the current environment was set up by + <command>nix-shell</command>. Since Nix 2.0 the values are + <literal>"pure"</literal> and <literal>"impure"</literal></para></listitem> + +</varlistentry> + +<varlistentry xml:id="env-NIX_PATH"><term><envar>NIX_PATH</envar></term> + + <listitem> + + <para>A colon-separated list of directories used to look up Nix + expressions enclosed in angle brackets (i.e., + <literal><<replaceable>path</replaceable>></literal>). For + instance, the value + + <screen> +/home/eelco/Dev:/etc/nixos</screen> + + will cause Nix to look for paths relative to + <filename>/home/eelco/Dev</filename> and + <filename>/etc/nixos</filename>, in this order. It is also + possible to match paths against a prefix. For example, the value + + <screen> +nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen> + + will cause Nix to search for + <literal><nixpkgs/<replaceable>path</replaceable>></literal> in + <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename> + and + <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.</para> + + <para>If a path in the Nix search path starts with + <literal>http://</literal> or <literal>https://</literal>, it is + interpreted as the URL of a tarball that will be downloaded and + unpacked to a temporary location. The tarball must consist of a + single top-level directory. For example, setting + <envar>NIX_PATH</envar> to + + <screen> +nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz</screen> + + tells Nix to download the latest revision in the Nixpkgs/NixOS + 15.09 channel.</para> + + <para>A following shorthand can be used to refer to the official channels: + + <screen>nixpkgs=channel:nixos-15.09</screen> + </para> + + <para>The search path can be extended using the <option linkend="opt-I">-I</option> option, which takes precedence over + <envar>NIX_PATH</envar>.</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_IGNORE_SYMLINK_STORE</envar></term> + + <listitem> + + <para>Normally, the Nix store directory (typically + <filename>/nix/store</filename>) is not allowed to contain any + symlink components. This is to prevent “impure” builds. Builders + sometimes “canonicalise” paths by resolving all symlink components. + Thus, builds on different machines (with + <filename>/nix/store</filename> resolving to different locations) + could yield different results. This is generally not a problem, + except when builds are deployed to machines where + <filename>/nix/store</filename> resolves differently. If you are + sure that you’re not going to do that, you can set + <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para> + + <para>Note that if you’re symlinking the Nix store so that you can + put it on another file system than the root file system, on Linux + you’re better off using <literal>bind</literal> mount points, e.g., + + <screen> +$ mkdir /nix +$ mount -o bind /mnt/otherdisk/nix /nix</screen> + + Consult the <citerefentry><refentrytitle>mount</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> manual page for details.</para> + + </listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_STORE_DIR</envar></term> + + <listitem><para>Overrides the location of the Nix store (default + <filename><replaceable>prefix</replaceable>/store</filename>).</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_DATA_DIR</envar></term> + + <listitem><para>Overrides the location of the Nix static data + directory (default + <filename><replaceable>prefix</replaceable>/share</filename>).</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_LOG_DIR</envar></term> + + <listitem><para>Overrides the location of the Nix log directory + (default <filename><replaceable>prefix</replaceable>/var/log/nix</filename>).</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_STATE_DIR</envar></term> + + <listitem><para>Overrides the location of the Nix state directory + (default <filename><replaceable>prefix</replaceable>/var/nix</filename>).</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_CONF_DIR</envar></term> + + <listitem><para>Overrides the location of the system Nix configuration + directory (default + <filename><replaceable>prefix</replaceable>/etc/nix</filename>).</para></listitem> + +</varlistentry> + +<varlistentry><term><envar>NIX_USER_CONF_FILES</envar></term> + + <listitem><para>Overrides the location of the user Nix configuration files + to load from (defaults to the XDG spec locations). The variable is treated + as a list separated by the <literal>:</literal> token.</para></listitem> + +</varlistentry> + +<varlistentry><term><envar>TMPDIR</envar></term> + + <listitem><para>Use the specified directory to store temporary + files. In particular, this includes temporary build directories; + these can take up substantial amounts of disk space. The default is + <filename>/tmp</filename>.</para></listitem> + +</varlistentry> + + +<varlistentry xml:id="envar-remote"><term><envar>NIX_REMOTE</envar></term> + + <listitem><para>This variable should be set to + <literal>daemon</literal> if you want to use the Nix daemon to + execute Nix operations. This is necessary in <link linkend="ssec-multi-user">multi-user Nix installations</link>. + If the Nix daemon's Unix socket is at some non-standard path, + this variable should be set to <literal>unix://path/to/socket</literal>. + Otherwise, it should be left unset.</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_SHOW_STATS</envar></term> + + <listitem><para>If set to <literal>1</literal>, Nix will print some + evaluation statistics, such as the number of values + allocated.</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_COUNT_CALLS</envar></term> + + <listitem><para>If set to <literal>1</literal>, Nix will print how + often functions were called during Nix expression evaluation. This + is useful for profiling your Nix expressions.</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>GC_INITIAL_HEAP_SIZE</envar></term> + + <listitem><para>If Nix has been configured to use the Boehm garbage + collector, this variable sets the initial size of the heap in bytes. + It defaults to 384 MiB. Setting it to a low value reduces memory + consumption, but will increase runtime due to the overhead of + garbage collection.</para></listitem> + +</varlistentry> + + +</variablelist> + + +</chapter> +<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>“Errors only”: only print messages + explaining why the Nix invocation failed.</para></listitem> + </varlistentry> + + <varlistentry><term>1</term> + <listitem><para>“Informational”: print + <emphasis>useful</emphasis> messages about what Nix is doing. + This is the default.</para></listitem> + </varlistentry> + + <varlistentry><term>2</term> + <listitem><para>“Talkative”: print more informational + messages.</para></listitem> + </varlistentry> + + <varlistentry><term>3</term> + <listitem><para>“Chatty”: print even more + informational messages.</para></listitem> + </varlistentry> + + <varlistentry><term>4</term> + <listitem><para>“Debug”: print debug + information.</para></listitem> + </varlistentry> + + <varlistentry><term>5</term> + <listitem><para>“Vomit”: print vast amounts of debug + information.</para></listitem> + </varlistentry> + + </variablelist> + + </listitem> + +</varlistentry><varlistentry 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 '<nixpkgs>' -iA hello --dry-run +(dry run; not doing anything) +installing ‘hello-2.10’ +this path will be fetched (0.04 MiB download, 0.19 MiB unpacked): + /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10 + <replaceable>...</replaceable></screen> + +</para> + +<para>To install Firefox from the latest revision in the Nixpkgs/NixOS +14.12 channel: + +<screen> +$ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox +</screen> + +</para> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection xml:id="rsec-nix-env-upgrade"><title>Operation <option>--upgrade</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <group choice="req"> + <arg choice="plain"><option>--upgrade</option></arg> + <arg choice="plain"><option>-u</option></arg> + </group> + <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 + “upgrade” to derivations that have the same version. Version are + not a unique identification of a derivation, so there may be many + derivations that have the same version. This flag may be useful + to force “synchronisation” between the installed and available + derivations.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--eq</option></term> + + <listitem><para><emphasis>Only</emphasis> “upgrade” to derivations + that have the same version. This may not seem very useful, but it + actually is, e.g., when there is a new release of Nixpkgs and you + want to replace installed applications with the same versions + built against newer dependencies (to reduce the number of + dependencies floating around on your system).</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--always</option></term> + + <listitem><para>In addition to upgrading to newer versions, also + “upgrade” to derivations that have the same or a lower version. + I.e., derivations may actually be downgraded depending on what is + available in the active Nix expression.</para></listitem> + + </varlistentry> + +</variablelist> + +<para>For the other flags, see <option linkend="rsec-nix-env-install">--install</option>.</para> + +</refsection> + +<refsection><title>Examples</title> + +<screen> +$ nix-env --upgrade gcc +upgrading `gcc-3.3.1' to `gcc-3.4' + +$ nix-env -u gcc-3.3.2 --always <lineannotation>(switch to a specific version)</lineannotation> +upgrading `gcc-3.4' to `gcc-3.3.2' + +$ nix-env --upgrade pan +<lineannotation>(no upgrades available, so nothing happens)</lineannotation> + +$ nix-env -u <lineannotation>(try to upgrade everything)</lineannotation> +upgrading `hello-2.1.2' to `hello-2.1.3' +upgrading `mozilla-1.2' to `mozilla-1.4'</screen> + +</refsection> + +<refsection xml:id="ssec-version-comparisons"><title>Versions</title> + +<para>The upgrade operation determines whether a derivation +<varname>y</varname> is an upgrade of a derivation +<varname>x</varname> by looking at their respective +<literal>name</literal> attributes. The names (e.g., +<literal>gcc-3.3.1</literal> are split into two parts: the package +name (<literal>gcc</literal>), and the version +(<literal>3.3.1</literal>). The version part starts after the first +dash not followed by a letter. <varname>x</varname> is considered an +upgrade of <varname>y</varname> if their package names match, and the +version of <varname>y</varname> is higher that that of +<varname>x</varname>.</para> + +<para>The versions are compared by splitting them into contiguous +components of numbers and letters. E.g., <literal>3.3.1pre5</literal> +is split into <literal>[3, 3, 1, "pre", 5]</literal>. These lists are +then compared lexicographically (from left to right). Corresponding +components <varname>a</varname> and <varname>b</varname> are compared +as follows. If they are both numbers, integer comparison is used. If +<varname>a</varname> is an empty string and <varname>b</varname> is a +number, <varname>a</varname> is considered less than +<varname>b</varname>. The special string component +<literal>pre</literal> (for <emphasis>pre-release</emphasis>) is +considered to be less than other components. String components are +considered less than number components. Otherwise, they are compared +lexicographically (i.e., using case-sensitive string comparison).</para> + +<para>This is illustrated by the following examples: + +<screen> +1.0 < 2.3 +2.1 < 2.3 +2.3 = 2.3 +2.5 > 2.3 +3.1 > 2.3 +2.3.1 > 2.3 +2.3.1 > 2.3a +2.3pre1 < 2.3 +2.3pre3 < 2.3pre12 +2.3a < 2.3c +2.3pre1 < 2.3c +2.3pre1 < 2.3q</screen> + +</para> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection><title>Operation <option>--uninstall</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <group choice="req"> + <arg choice="plain"><option>--uninstall</option></arg> + <arg choice="plain"><option>-e</option></arg> + </group> + <arg choice="plain" rep="repeat"><replaceable>drvnames</replaceable></arg> +</cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The uninstall operation creates a new user environment, based on +the current generation of the active profile, from which the store +paths designated by the symbolic names +<replaceable>names</replaceable> are removed.</para> + +</refsection> + +<refsection><title>Examples</title> + +<screen> +$ nix-env --uninstall gcc +$ nix-env -e '.*' <lineannotation>(remove everything)</lineannotation></screen> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection xml:id="rsec-nix-env-set"><title>Operation <option>--set</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <arg choice="plain"><option>--set</option></arg> + <arg choice="plain"><replaceable>drvname</replaceable></arg> +</cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The <option>--set</option> operation modifies the current generation of a +profile so that it contains exactly the specified derivation, and nothing else. +</para> + +</refsection> + +<refsection><title>Examples</title> + +<para> +The following updates a profile such that its current generation will contain +just Firefox: + +<screen> +$ nix-env -p /nix/var/nix/profiles/browser --set firefox</screen> + +</para> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection xml:id="rsec-nix-env-set-flag"><title>Operation <option>--set-flag</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <arg choice="plain"><option>--set-flag</option></arg> + <arg choice="plain"><replaceable>name</replaceable></arg> + <arg choice="plain"><replaceable>value</replaceable></arg> + <arg choice="plain" rep="repeat"><replaceable>drvnames</replaceable></arg> +</cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The <option>--set-flag</option> operation allows meta attributes +of installed packages to be modified. There are several attributes +that can be usefully modified, because they affect the behaviour of +<command>nix-env</command> or the user environment build +script: + +<itemizedlist> + + <listitem><para><varname>priority</varname> can be changed to + resolve filename clashes. The user environment build script uses + the <varname>meta.priority</varname> attribute of derivations to + resolve filename collisions between packages. Lower priority values + denote a higher priority. For instance, the GCC wrapper package and + the Binutils package in Nixpkgs both have a file + <filename>bin/ld</filename>, so previously if you tried to install + both you would get a collision. Now, on the other hand, the GCC + wrapper declares a higher priority than Binutils, so the former’s + <filename>bin/ld</filename> is symlinked in the user + environment.</para></listitem> + + <listitem><para><varname>keep</varname> can be set to + <literal>true</literal> to prevent the package from being upgraded + or replaced. This is useful if you want to hang on to an older + version of a package.</para></listitem> + + <listitem><para><varname>active</varname> can be set to + <literal>false</literal> to “disable” the package. That is, no + symlinks will be generated to the files of the package, but it + remains part of the profile (so it won’t be garbage-collected). It + can be set back to <literal>true</literal> to re-enable the + package.</para></listitem> + +</itemizedlist> + +</para> + +</refsection> + +<refsection><title>Examples</title> + +<para>To prevent the currently installed Firefox from being upgraded: + +<screen> +$ nix-env --set-flag keep true firefox</screen> + +After this, <command>nix-env -u</command> will ignore Firefox.</para> + +<para>To disable the currently installed Firefox, then install a new +Firefox while the old remains part of the profile: + +<screen> +$ nix-env -q +firefox-2.0.0.9 <lineannotation>(the current one)</lineannotation> + +$ nix-env --preserve-installed -i firefox-2.0.0.11 +installing `firefox-2.0.0.11' +building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment' +collision between `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.11/bin/firefox' + and `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.9/bin/firefox'. +<lineannotation>(i.e., can’t have two active at the same time)</lineannotation> + +$ nix-env --set-flag active false firefox +setting flag on `firefox-2.0.0.9' + +$ nix-env --preserve-installed -i firefox-2.0.0.11 +installing `firefox-2.0.0.11' + +$ nix-env -q +firefox-2.0.0.11 <lineannotation>(the enabled one)</lineannotation> +firefox-2.0.0.9 <lineannotation>(the disabled one)</lineannotation></screen> + +</para> + +<para>To make files from <literal>binutils</literal> take precedence +over files from <literal>gcc</literal>: + +<screen> +$ nix-env --set-flag priority 5 binutils +$ nix-env --set-flag priority 10 gcc</screen> + +</para> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection><title>Operation <option>--query</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <group choice="req"> + <arg choice="plain"><option>--query</option></arg> + <arg choice="plain"><option>-q</option></arg> + </group> + <group choice="opt"> + <arg choice="plain"><option>--installed</option></arg> + <arg choice="plain"><option>--available</option></arg> + <arg choice="plain"><option>-a</option></arg> + </group> + + <sbr/> + + <arg> + <group choice="req"> + <arg choice="plain"><option>--status</option></arg> + <arg choice="plain"><option>-s</option></arg> + </group> + </arg> + <arg> + <group choice="req"> + <arg choice="plain"><option>--attr-path</option></arg> + <arg choice="plain"><option>-P</option></arg> + </group> + </arg> + <arg><option>--no-name</option></arg> + <arg> + <group choice="req"> + <arg choice="plain"><option>--compare-versions</option></arg> + <arg choice="plain"><option>-c</option></arg> + </group> + </arg> + <arg><option>--system</option></arg> + <arg><option>--drv-path</option></arg> + <arg><option>--out-path</option></arg> + <arg><option>--description</option></arg> + <arg><option>--meta</option></arg> + + <sbr/> + + <arg><option>--xml</option></arg> + <arg><option>--json</option></arg> + <arg> + <group choice="req"> + <arg choice="plain"><option>--prebuilt-only</option></arg> + <arg choice="plain"><option>-b</option></arg> + </group> + </arg> + + <arg> + <group choice="req"> + <arg choice="plain"><option>--attr</option></arg> + <arg choice="plain"><option>-A</option></arg> + </group> + <replaceable>attribute-path</replaceable> + </arg> + + <sbr/> + + <arg choice="plain" rep="repeat"><replaceable>names</replaceable></arg> +</cmdsynopsis> + +</refsection> + + +<refsection><title>Description</title> + +<para>The query operation displays information about either the store +paths that are installed in the current generation of the active +profile (<option>--installed</option>), or the derivations that are +available for installation in the active Nix expression +(<option>--available</option>). It only prints information about +derivations whose symbolic name matches one of +<replaceable>names</replaceable>.</para> + +<para>The derivations are sorted by their <literal>name</literal> +attributes.</para> + +</refsection> + + +<refsection><title>Source selection</title> + +<para>The following flags specify the set of things on which the query +operates.</para> + +<variablelist> + + <varlistentry><term><option>--installed</option></term> + + <listitem><para>The query operates on the store paths that are + installed in the current generation of the active profile. This + is the default.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--available</option></term> + <term><option>-a</option></term> + + <listitem><para>The query operates on the derivations that are + available in the active Nix expression.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + + +<refsection><title>Queries</title> + +<para>The following flags specify what information to display about +the selected derivations. Multiple flags may be specified, in which +case the information is shown in the order given here. Note that the +name of the derivation is shown unless <option>--no-name</option> is +specified.</para> + +<!-- TODO: fix the terminology here; i.e., derivations, store paths, +user environment elements, etc. --> + +<variablelist> + + <varlistentry><term><option>--xml</option></term> + + <listitem><para>Print the result in an XML representation suitable + for automatic processing by other tools. The root element is + called <literal>items</literal>, which contains a + <literal>item</literal> element for each available or installed + derivation. The fields discussed below are all stored in + attributes of the <literal>item</literal> + elements.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--json</option></term> + + <listitem><para>Print the result in a JSON representation suitable + for automatic processing by other tools.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--prebuilt-only</option> / <option>-b</option></term> + + <listitem><para>Show only derivations for which a substitute is + registered, i.e., there is a pre-built binary available that can + be downloaded in lieu of building the derivation. Thus, this + shows all packages that probably can be installed + quickly.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--status</option></term> + <term><option>-s</option></term> + + <listitem><para>Print the <emphasis>status</emphasis> of the + derivation. The status consists of three characters. The first + is <literal>I</literal> or <literal>-</literal>, indicating + whether the derivation is currently installed in the current + generation of the active profile. This is by definition the case + for <option>--installed</option>, but not for + <option>--available</option>. The second is <literal>P</literal> + or <literal>-</literal>, indicating whether the derivation is + present on the system. This indicates whether installation of an + available derivation will require the derivation to be built. The + third is <literal>S</literal> or <literal>-</literal>, indicating + whether a substitute is available for the + derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--attr-path</option></term> + <term><option>-P</option></term> + + <listitem><para>Print the <emphasis>attribute path</emphasis> of + the derivation, which can be used to unambiguously select it using + the <link linkend="opt-attr"><option>--attr</option> option</link> + available in commands that install derivations like + <literal>nix-env --install</literal>. This option only works + together with <option>--available</option></para></listitem> + + </varlistentry> + + <varlistentry><term><option>--no-name</option></term> + + <listitem><para>Suppress printing of the <literal>name</literal> + attribute of each derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--compare-versions</option> / + <option>-c</option></term> + + <listitem><para>Compare installed versions to available versions, + or vice versa (if <option>--available</option> is given). This is + useful for quickly seeing whether upgrades for installed + packages are available in a Nix expression. A column is added + with the following meaning: + + <variablelist> + + <varlistentry><term><literal><</literal> <replaceable>version</replaceable></term> + + <listitem><para>A newer version of the package is available + or installed.</para></listitem> + + </varlistentry> + + <varlistentry><term><literal>=</literal> <replaceable>version</replaceable></term> + + <listitem><para>At most the same version of the package is + available or installed.</para></listitem> + + </varlistentry> + + <varlistentry><term><literal>></literal> <replaceable>version</replaceable></term> + + <listitem><para>Only older versions of the package are + available or installed.</para></listitem> + + </varlistentry> + + <varlistentry><term><literal>- ?</literal></term> + + <listitem><para>No version of the package is available or + installed.</para></listitem> + + </varlistentry> + + </variablelist> + + </para></listitem> + + </varlistentry> + + <varlistentry><term><option>--system</option></term> + + <listitem><para>Print the <literal>system</literal> attribute of + the derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--drv-path</option></term> + + <listitem><para>Print the path of the store + derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--out-path</option></term> + + <listitem><para>Print the output path of the + derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--description</option></term> + + <listitem><para>Print a short (one-line) description of the + derivation, if available. The description is taken from the + <literal>meta.description</literal> attribute of the + derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--meta</option></term> + + <listitem><para>Print all of the meta-attributes of the + derivation. This option is only available with + <option>--xml</option> or <option>--json</option>.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + + +<refsection><title>Examples</title> + +<para>To show installed packages: + +<screen> +$ nix-env -q +bison-1.875c +docbook-xml-4.2 +firefox-1.0.4 +MPlayer-1.0pre7 +ORBit2-2.8.3 +<replaceable>…</replaceable> +</screen> + +</para> + +<para>To show available packages: + +<screen> +$ nix-env -qa +firefox-1.0.7 +GConf-2.4.0.1 +MPlayer-1.0pre7 +ORBit2-2.8.3 +<replaceable>…</replaceable> +</screen> + +</para> + +<para>To show the status of available packages: + +<screen> +$ nix-env -qas +-P- firefox-1.0.7 <lineannotation>(not installed but present)</lineannotation> +--S GConf-2.4.0.1 <lineannotation>(not present, but there is a substitute for fast installation)</lineannotation> +--S MPlayer-1.0pre3 <lineannotation>(i.e., this is not the installed MPlayer, even though the version is the same!)</lineannotation> +IP- ORBit2-2.8.3 <lineannotation>(installed and by definition present)</lineannotation> +<replaceable>…</replaceable> +</screen> + +</para> + +<para>To show available packages in the Nix expression <filename>foo.nix</filename>: + +<screen> +$ nix-env -f ./foo.nix -qa +foo-1.2.3 +</screen> + +</para> + +<para>To compare installed versions to what’s available: + +<screen> +$ nix-env -qc +<replaceable>...</replaceable> +acrobat-reader-7.0 - ? <lineannotation>(package is not available at all)</lineannotation> +autoconf-2.59 = 2.59 <lineannotation>(same version)</lineannotation> +firefox-1.0.4 < 1.0.7 <lineannotation>(a more recent version is available)</lineannotation> +<replaceable>...</replaceable> +</screen> + +</para> + +<para>To show all packages with “<literal>zip</literal>” in the name: + +<screen> +$ nix-env -qa '.*zip.*' +bzip2-1.0.6 +gzip-1.6 +zip-3.0 +<replaceable>…</replaceable> +</screen> + +</para> + +<para>To show all packages with “<literal>firefox</literal>” or +“<literal>chromium</literal>” in the name: + +<screen> +$ nix-env -qa '.*(firefox|chromium).*' +chromium-37.0.2062.94 +chromium-beta-38.0.2125.24 +firefox-32.0.3 +firefox-with-plugins-13.0.1 +<replaceable>…</replaceable> +</screen> + +</para> + +<para>To show all packages in the latest revision of the Nixpkgs +repository: + +<screen> +$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa +</screen> + +</para> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection><title>Operation <option>--switch-profile</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <group choice="req"> + <arg choice="plain"><option>--switch-profile</option></arg> + <arg choice="plain"><option>-S</option></arg> + </group> + <arg choice="req"><replaceable>path</replaceable></arg> +</cmdsynopsis> + +</refsection> + + +<refsection><title>Description</title> + +<para>This operation makes <replaceable>path</replaceable> the current +profile for the user. That is, the symlink +<filename>~/.nix-profile</filename> is made to point to +<replaceable>path</replaceable>.</para> + +</refsection> + +<refsection><title>Examples</title> + +<screen> +$ nix-env -S ~/my-profile</screen> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection><title>Operation <option>--list-generations</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <arg choice="plain"><option>--list-generations</option></arg> +</cmdsynopsis> + +</refsection> + + +<refsection><title>Description</title> + +<para>This operation print a list of all the currently existing +generations for the active profile. These may be switched to using +the <option>--switch-generation</option> operation. It also prints +the creation date of the generation, and indicates the current +generation.</para> + +</refsection> + + +<refsection><title>Examples</title> + +<screen> +$ nix-env --list-generations + 95 2004-02-06 11:48:24 + 96 2004-02-06 11:49:01 + 97 2004-02-06 16:22:45 + 98 2004-02-06 16:24:33 (current)</screen> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection><title>Operation <option>--delete-generations</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <arg choice="plain"><option>--delete-generations</option></arg> + <arg choice="plain" rep="repeat"><replaceable>generations</replaceable></arg> +</cmdsynopsis> + +</refsection> + + +<refsection><title>Description</title> + +<para>This operation deletes the specified generations of the current +profile. The generations can be a list of generation numbers, the +special value <literal>old</literal> to delete all non-current +generations, a value such as <literal>30d</literal> to delete all +generations older than the specified number of days (except for the +generation that was active at that point in time), or a value such as +<literal>+5</literal> to keep the last <literal>5</literal> generations +ignoring any newer than current, e.g., if <literal>30</literal> is the current +generation <literal>+5</literal> will delete generation <literal>25</literal> +and all older generations. +Periodically deleting old generations is important to make garbage collection +effective.</para> + +</refsection> + +<refsection><title>Examples</title> + +<screen> +$ nix-env --delete-generations 3 4 8 + +$ nix-env --delete-generations +5 + +$ nix-env --delete-generations 30d + +$ nix-env -p other_profile --delete-generations old</screen> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection><title>Operation <option>--switch-generation</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <group choice="req"> + <arg choice="plain"><option>--switch-generation</option></arg> + <arg choice="plain"><option>-G</option></arg> + </group> + <arg choice="req"><replaceable>generation</replaceable></arg> +</cmdsynopsis> + +</refsection> + + +<refsection><title>Description</title> + +<para>This operation makes generation number +<replaceable>generation</replaceable> the current generation of the +active profile. That is, if the +<filename><replaceable>profile</replaceable></filename> is the path to +the active profile, then the symlink +<filename><replaceable>profile</replaceable></filename> is made to +point to +<filename><replaceable>profile</replaceable>-<replaceable>generation</replaceable>-link</filename>, +which is in turn a symlink to the actual user environment in the Nix +store.</para> + +<para>Switching will fail if the specified generation does not exist.</para> + +</refsection> + + +<refsection><title>Examples</title> + +<screen> +$ nix-env -G 42 +switching from generation 50 to 42</screen> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection><title>Operation <option>--rollback</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <arg choice="plain"><option>--rollback</option></arg> +</cmdsynopsis> + +</refsection> + +<refsection><title>Description</title> + +<para>This operation switches to the “previous” generation of the +active profile, that is, the highest numbered generation lower than +the current generation, if it exists. It is just a convenience +wrapper around <option>--list-generations</option> and +<option>--switch-generation</option>.</para> + +</refsection> + + +<refsection><title>Examples</title> + +<screen> +$ nix-env --rollback +switching from generation 92 to 91 + +$ nix-env --rollback +error: no generation older than the current (91) exists</screen> + +</refsection> + +</refsection> + + +<refsection condition="manpage"><title>Environment variables</title> + +<variablelist> + + <varlistentry><term><envar>NIX_PROFILE</envar></term> + + <listitem><para>Location of the Nix profile. Defaults to the + target of the symlink <filename>~/.nix-profile</filename>, if it + exists, or <filename>/nix/var/nix/profiles/default</filename> + otherwise.</para></listitem> + + </varlistentry> + + <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><<replaceable>path</replaceable>></literal>). For + instance, the value + + <screen> +/home/eelco/Dev:/etc/nixos</screen> + + will cause Nix to look for paths relative to + <filename>/home/eelco/Dev</filename> and + <filename>/etc/nixos</filename>, in this order. It is also + possible to match paths against a prefix. For example, the value + + <screen> +nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen> + + will cause Nix to search for + <literal><nixpkgs/<replaceable>path</replaceable>></literal> in + <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename> + and + <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.</para> + + <para>If a path in the Nix search path starts with + <literal>http://</literal> or <literal>https://</literal>, it is + interpreted as the URL of a tarball that will be downloaded and + unpacked to a temporary location. The tarball must consist of a + single top-level directory. For example, setting + <envar>NIX_PATH</envar> to + + <screen> +nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz</screen> + + tells Nix to download the latest revision in the Nixpkgs/NixOS + 15.09 channel.</para> + + <para>A following shorthand can be used to refer to the official channels: + + <screen>nixpkgs=channel:nixos-15.09</screen> + </para> + + <para>The search path can be extended using the <option linkend="opt-I">-I</option> option, which takes precedence over + <envar>NIX_PATH</envar>.</para></listitem> + +</varlistentry><varlistentry 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 “impure” builds. Builders + sometimes “canonicalise” paths by resolving all symlink components. + Thus, builds on different machines (with + <filename>/nix/store</filename> resolving to different locations) + could yield different results. This is generally not a problem, + except when builds are deployed to machines where + <filename>/nix/store</filename> resolves differently. If you are + sure that you’re not going to do that, you can set + <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para> + + <para>Note that if you’re symlinking the Nix store so that you can + put it on another file system than the root file system, on Linux + you’re better off using <literal>bind</literal> mount points, e.g., + + <screen> +$ mkdir /nix +$ mount -o bind /mnt/otherdisk/nix /nix</screen> + + Consult the <citerefentry><refentrytitle>mount</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> manual page for details.</para> + + </listitem> + +</varlistentry><varlistentry 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’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>“Errors only”: only print messages + explaining why the Nix invocation failed.</para></listitem> + </varlistentry> + + <varlistentry><term>1</term> + <listitem><para>“Informational”: print + <emphasis>useful</emphasis> messages about what Nix is doing. + This is the default.</para></listitem> + </varlistentry> + + <varlistentry><term>2</term> + <listitem><para>“Talkative”: print more informational + messages.</para></listitem> + </varlistentry> + + <varlistentry><term>3</term> + <listitem><para>“Chatty”: print even more + informational messages.</para></listitem> + </varlistentry> + + <varlistentry><term>4</term> + <listitem><para>“Debug”: print debug + information.</para></listitem> + </varlistentry> + + <varlistentry><term>5</term> + <listitem><para>“Vomit”: print vast amounts of debug + information.</para></listitem> + </varlistentry> + + </variablelist> + + </listitem> + +</varlistentry><varlistentry 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 '<nixpkgs>' -A firefox +store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv +/nix/store/d18hyl92g30l...-firefox-1.5.0.7 + +$ ls -l result +lrwxrwxrwx <replaceable>...</replaceable> result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7 + +$ ls ./result/bin/ +firefox firefox-config</screen> + +<para>If a derivation has multiple outputs, +<command>nix-build</command> will build the default (first) output. +You can also build all outputs: +<screen> +$ nix-build '<nixpkgs>' -A openssl.all +</screen> +This will create a symlink for each output named +<filename>result-<replaceable>outputname</replaceable></filename>. +The suffix is omitted if the output name is <literal>out</literal>. +So if <literal>openssl</literal> has outputs <literal>out</literal>, +<literal>bin</literal> and <literal>man</literal>, +<command>nix-build</command> will create symlinks +<literal>result</literal>, <literal>result-bin</literal> and +<literal>result-man</literal>. It’s also possible to build a specific +output: +<screen> +$ nix-build '<nixpkgs>' -A openssl.man +</screen> +This will create a symlink <literal>result-man</literal>.</para> + +<para>Build a Nix expression given on the command line: + +<screen> +$ nix-build -E 'with import <nixpkgs> { }; runCommand "foo" { } "echo bar > $out"' +$ cat ./result +bar +</screen> + +</para> + +<para>Build the GNU Hello package from the latest revision of the +master branch of Nixpkgs: + +<screen> +$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello +</screen> + +</para> + +</refsection> + + +<refsection condition="manpage"><title>Environment variables</title> + +<variablelist> + <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><<replaceable>path</replaceable>></literal>). For + instance, the value + + <screen> +/home/eelco/Dev:/etc/nixos</screen> + + will cause Nix to look for paths relative to + <filename>/home/eelco/Dev</filename> and + <filename>/etc/nixos</filename>, in this order. It is also + possible to match paths against a prefix. For example, the value + + <screen> +nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen> + + will cause Nix to search for + <literal><nixpkgs/<replaceable>path</replaceable>></literal> in + <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename> + and + <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.</para> + + <para>If a path in the Nix search path starts with + <literal>http://</literal> or <literal>https://</literal>, it is + interpreted as the URL of a tarball that will be downloaded and + unpacked to a temporary location. The tarball must consist of a + single top-level directory. For example, setting + <envar>NIX_PATH</envar> to + + <screen> +nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz</screen> + + tells Nix to download the latest revision in the Nixpkgs/NixOS + 15.09 channel.</para> + + <para>A following shorthand can be used to refer to the official channels: + + <screen>nixpkgs=channel:nixos-15.09</screen> + </para> + + <para>The search path can be extended using the <option linkend="opt-I">-I</option> option, which takes precedence over + <envar>NIX_PATH</envar>.</para></listitem> + +</varlistentry><varlistentry 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 “impure” builds. Builders + sometimes “canonicalise” paths by resolving all symlink components. + Thus, builds on different machines (with + <filename>/nix/store</filename> resolving to different locations) + could yield different results. This is generally not a problem, + except when builds are deployed to machines where + <filename>/nix/store</filename> resolves differently. If you are + sure that you’re not going to do that, you can set + <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para> + + <para>Note that if you’re symlinking the Nix store so that you can + put it on another file system than the root file system, on Linux + you’re better off using <literal>bind</literal> mount points, e.g., + + <screen> +$ mkdir /nix +$ mount -o bind /mnt/otherdisk/nix /nix</screen> + + Consult the <citerefentry><refentrytitle>mount</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> manual page for details.</para> + + </listitem> + +</varlistentry><varlistentry 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 + “real” Nix build. A few variables, in particular + <envar>HOME</envar>, <envar>USER</envar> and + <envar>DISPLAY</envar>, are retained. Note that + <filename>~/.bashrc</filename> and (depending on your Bash + installation) <filename>/etc/bashrc</filename> are still sourced, + so any variables set there will affect the interactive + shell.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--packages</option> / <option>-p</option> <replaceable>packages</replaceable>…</term> + + <listitem><para>Set up an environment in which the specified + packages are present. The command line arguments are interpreted + as attribute names inside the Nix Packages collection. Thus, + <literal>nix-shell -p libjpeg openjdk</literal> will start a shell + in which the packages denoted by the attribute names + <varname>libjpeg</varname> and <varname>openjdk</varname> are + present.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>-i</option> <replaceable>interpreter</replaceable></term> + + <listitem><para>The chained script interpreter to be invoked by + <command>nix-shell</command>. Only applicable in + <literal>#!</literal>-scripts (described <link linkend="ssec-nix-shell-shebang">below</link>).</para> + + </listitem></varlistentry> + + <varlistentry><term><option>--keep</option> <replaceable>name</replaceable></term> + + <listitem><para>When a <option>--pure</option> shell is started, + keep the listed environment variables.</para></listitem> + + </varlistentry> + +</variablelist> + +<para>The following common options are supported:</para> + +<variablelist condition="manpage"> + <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>“Errors only”: only print messages + explaining why the Nix invocation failed.</para></listitem> + </varlistentry> + + <varlistentry><term>1</term> + <listitem><para>“Informational”: print + <emphasis>useful</emphasis> messages about what Nix is doing. + This is the default.</para></listitem> + </varlistentry> + + <varlistentry><term>2</term> + <listitem><para>“Talkative”: print more informational + messages.</para></listitem> + </varlistentry> + + <varlistentry><term>3</term> + <listitem><para>“Chatty”: print even more + informational messages.</para></listitem> + </varlistentry> + + <varlistentry><term>4</term> + <listitem><para>“Debug”: print debug + information.</para></listitem> + </varlistentry> + + <varlistentry><term>5</term> + <listitem><para>“Vomit”: print vast amounts of debug + information.</para></listitem> + </varlistentry> + + </variablelist> + + </listitem> + +</varlistentry><varlistentry 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 '<nixpkgs>' -A pan +[nix-shell]$ unpackPhase +[nix-shell]$ cd pan-* +[nix-shell]$ configurePhase +[nix-shell]$ buildPhase +[nix-shell]$ ./pan/gui/pan +</screen> + +To clear the environment first, and do some additional automatic +initialisation of the interactive shell: + +<screen> +$ nix-shell '<nixpkgs>' -A pan --pure \ + --command 'export NIX_DEBUG=1; export NIX_CORES=8; return' +</screen> + +Nix expressions can also be given on the command line using the +<command>-E</command> and <command>-p</command> flags. +For instance, the following starts a shell containing the packages +<literal>sqlite</literal> and <literal>libX11</literal>: + +<screen> +$ nix-shell -E 'with import <nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""' +</screen> + +A shorter way to do the same is: + +<screen> +$ nix-shell -p sqlite xorg.libX11 +[nix-shell]$ echo $NIX_LDFLAGS +… -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib … +</screen> + +Note that <command>-p</command> accepts multiple full nix expressions that +are valid in the <literal>buildInputs = [ ... ]</literal> shown above, +not only package names. So the following is also legal: + +<screen> +$ nix-shell -p sqlite 'git.override { withManual = false; }' +</screen> + +The <command>-p</command> flag looks up Nixpkgs in the Nix search +path. You can override it by passing <option>-I</option> or setting +<envar>NIX_PATH</envar>. For example, the following gives you a shell +containing the Pan package from a specific revision of Nixpkgs: + +<screen> +$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz + +[nix-shell:~]$ pan --version +Pan 0.139 +</screen> + +</para> + +</refsection> + + +<refsection xml:id="ssec-nix-shell-shebang"><title>Use as a <literal>#!</literal>-interpreter</title> + +<para>You can use <command>nix-shell</command> as a script interpreter +to allow scripts written in arbitrary languages to obtain their own +dependencies via Nix. This is done by starting the script with the +following lines: + +<programlisting> +#! /usr/bin/env nix-shell +#! nix-shell -i <replaceable>real-interpreter</replaceable> -p <replaceable>packages</replaceable> +</programlisting> + +where <replaceable>real-interpreter</replaceable> is the “real” script +interpreter that will be invoked by <command>nix-shell</command> after +it has obtained the dependencies and initialised the environment, and +<replaceable>packages</replaceable> are the attribute names of the +dependencies in Nixpkgs.</para> + +<para>The lines starting with <literal>#! nix-shell</literal> specify +<command>nix-shell</command> options (see above). Note that you cannot +write <literal>#! /usr/bin/env nix-shell -i ...</literal> because +many operating systems only allow one argument in +<literal>#!</literal> lines.</para> + +<para>For example, here is a Python script that depends on Python and +the <literal>prettytable</literal> package: + +<programlisting> +#! /usr/bin/env nix-shell +#! nix-shell -i python -p python pythonPackages.prettytable + +import prettytable + +# Print a simple table. +t = prettytable.PrettyTable(["N", "N^2"]) +for n in range(1, 10): t.add_row([n, n * n]) +print t +</programlisting> + +</para> + +<para>Similarly, the following is a Perl script that specifies that it +requires Perl and the <literal>HTML::TokeParser::Simple</literal> and +<literal>LWP</literal> packages: + +<programlisting> +#! /usr/bin/env nix-shell +#! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP + +use HTML::TokeParser::Simple; + +# Fetch nixos.org and print all hrefs. +my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/'); + +while (my $token = $p->get_tag("a")) { + my $href = $token->get_attr("href"); + print "$href\n" if $href; +} +</programlisting> + +</para> + +<para>Sometimes you need to pass a simple Nix expression to customize +a package like Terraform: + +<programlisting><![CDATA[ +#! /usr/bin/env nix-shell +#! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])" + +terraform apply +]]></programlisting> + +<note><para>You must use double quotes (<literal>"</literal>) when +passing a simple Nix expression in a nix-shell shebang.</para></note> +</para> + +<para>Finally, using the merging of multiple nix-shell shebangs the +following Haskell script uses a specific branch of Nixpkgs/NixOS (the +18.03 stable branch): + +<programlisting><![CDATA[ +#! /usr/bin/env nix-shell +#! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.HTTP ps.tagsoup])" +#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-18.03.tar.gz + +import Network.HTTP +import Text.HTML.TagSoup + +-- Fetch nixos.org and print all hrefs. +main = do + resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/") + body <- getResponseBody resp + let tags = filter (isTagOpenName "a") $ parseTags body + let tags' = map (fromAttrib "href") tags + mapM_ putStrLn $ filter (/= "") tags' +]]></programlisting> + +If you want to be even more precise, you can specify a specific +revision of Nixpkgs: + +<programlisting> +#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz +</programlisting> + +</para> + +<para>The examples above all used <option>-p</option> to get +dependencies from Nixpkgs. You can also use a Nix expression to build +your own dependencies. For example, the Python example could have been +written as: + +<programlisting> +#! /usr/bin/env nix-shell +#! nix-shell deps.nix -i python +</programlisting> + +where the file <filename>deps.nix</filename> in the same directory +as the <literal>#!</literal>-script contains: + +<programlisting> +with import <nixpkgs> {}; + +runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } "" +</programlisting> + +</para> + +</refsection> + + +<refsection condition="manpage"><title>Environment variables</title> + +<variablelist> + <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><<replaceable>path</replaceable>></literal>). For + instance, the value + + <screen> +/home/eelco/Dev:/etc/nixos</screen> + + will cause Nix to look for paths relative to + <filename>/home/eelco/Dev</filename> and + <filename>/etc/nixos</filename>, in this order. It is also + possible to match paths against a prefix. For example, the value + + <screen> +nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen> + + will cause Nix to search for + <literal><nixpkgs/<replaceable>path</replaceable>></literal> in + <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename> + and + <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.</para> + + <para>If a path in the Nix search path starts with + <literal>http://</literal> or <literal>https://</literal>, it is + interpreted as the URL of a tarball that will be downloaded and + unpacked to a temporary location. The tarball must consist of a + single top-level directory. For example, setting + <envar>NIX_PATH</envar> to + + <screen> +nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz</screen> + + tells Nix to download the latest revision in the Nixpkgs/NixOS + 15.09 channel.</para> + + <para>A following shorthand can be used to refer to the official channels: + + <screen>nixpkgs=channel:nixos-15.09</screen> + </para> + + <para>The search path can be extended using the <option linkend="opt-I">-I</option> option, which takes precedence over + <envar>NIX_PATH</envar>.</para></listitem> + +</varlistentry><varlistentry 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 “impure” builds. Builders + sometimes “canonicalise” paths by resolving all symlink components. + Thus, builds on different machines (with + <filename>/nix/store</filename> resolving to different locations) + could yield different results. This is generally not a problem, + except when builds are deployed to machines where + <filename>/nix/store</filename> resolves differently. If you are + sure that you’re not going to do that, you can set + <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para> + + <para>Note that if you’re symlinking the Nix store so that you can + put it on another file system than the root file system, on Linux + you’re better off using <literal>bind</literal> mount points, e.g., + + <screen> +$ mkdir /nix +$ mount -o bind /mnt/otherdisk/nix /nix</screen> + + Consult the <citerefentry><refentrytitle>mount</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> manual page for details.</para> + + </listitem> + +</varlistentry><varlistentry 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... -> /home/eelco/bla/result + +$ ls -l /home/eelco/bla/result +lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10</screen> + + Thus, when <filename>/home/eelco/bla/result</filename> is removed, + the GC root in the <filename>auto</filename> directory becomes a + dangling symlink and will be ignored by the collector.</para> + + <warning><para>Note that it is not possible to move or rename + indirect GC roots, since the symlink in the + <filename>auto</filename> directory will still point to the old + location.</para></warning> + + </listitem> + + </varlistentry> + +</variablelist> + +<variablelist condition="manpage"> + <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>“Errors only”: only print messages + explaining why the Nix invocation failed.</para></listitem> + </varlistentry> + + <varlistentry><term>1</term> + <listitem><para>“Informational”: print + <emphasis>useful</emphasis> messages about what Nix is doing. + This is the default.</para></listitem> + </varlistentry> + + <varlistentry><term>2</term> + <listitem><para>“Talkative”: print more informational + messages.</para></listitem> + </varlistentry> + + <varlistentry><term>3</term> + <listitem><para>“Chatty”: print even more + informational messages.</para></listitem> + </varlistentry> + + <varlistentry><term>4</term> + <listitem><para>“Debug”: print debug + information.</para></listitem> + </varlistentry> + + <varlistentry><term>5</term> + <listitem><para>“Vomit”: print vast amounts of debug + information.</para></listitem> + </varlistentry> + + </variablelist> + + </listitem> + +</varlistentry><varlistentry 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 “builds” +the specified store paths. Realisation is a somewhat overloaded term: + +<itemizedlist> + + <listitem><para>If the store path is a + <emphasis>derivation</emphasis>, realisation ensures that the output + paths of the derivation are <link linkend="gloss-validity">valid</link> (i.e., the output path and its + closure exist in the file system). This can be done in several + ways. First, it is possible that the outputs are already valid, in + which case we are done immediately. Otherwise, there may be <link linkend="gloss-substitute">substitutes</link> that produce the + outputs (e.g., by downloading them). Finally, the outputs can be + produced by performing the build action described by the + derivation.</para></listitem> + + <listitem><para>If the store path is not a derivation, realisation + ensures that the specified path is valid (i.e., it and its closure + exist in the file system). If the path is already valid, we are + done immediately. Otherwise, the path and any missing paths in its + closure may be produced through substitutes. If there are no + (successful) subsitutes, realisation fails.</para></listitem> + +</itemizedlist> + +</para> + +<para>The output path of each derivation is printed on standard +output. (For non-derivations argument, the argument itself is +printed.)</para> + +<para>The following flags are available:</para> + +<variablelist> + + <varlistentry><term><option>--dry-run</option></term> + + <listitem><para>Print on standard error a description of what + packages would be built or downloaded, without actually performing + the operation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--ignore-unknown</option></term> + + <listitem><para>If a non-derivation path does not have a + substitute, then silently ignore it.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--check</option></term> + + <listitem><para>This option allows you to check whether a + derivation is deterministic. It rebuilds the specified derivation + and checks whether the result is bitwise-identical with the + existing outputs, printing an error if that’s not the case. The + outputs of the specified derivation must already exist. When used + with <option>-K</option>, if an output path is not identical to + the corresponding output from the previous build, the new output + path is left in + <filename>/nix/store/<replaceable>name</replaceable>.check.</filename></para> + + <para>See also the <option>build-repeat</option> configuration + option, which repeats a derivation a number of times and prevents + its outputs from being registered as “valid” in the Nix store + unless they are identical.</para></listitem> + + </varlistentry> + +</variablelist> + +<para>Special exit codes:</para> + +<variablelist> + + <varlistentry><term><literal>100</literal></term> + <listitem><para>Generic build failure, the builder process + returned with a non-zero exit code.</para></listitem> + </varlistentry> + + <varlistentry><term><literal>101</literal></term> + <listitem><para>Build timeout, the build was aborted because it + did not complete within the specified <link linkend="conf-timeout"><literal>timeout</literal></link>. + </para></listitem> + </varlistentry> + + <varlistentry><term><literal>102</literal></term> + <listitem><para>Hash mismatch, the build output was rejected + because it does not match the specified <link linkend="fixed-output-drvs"><varname>outputHash</varname></link>. + </para></listitem> + </varlistentry> + + <varlistentry><term><literal>104</literal></term> + <listitem><para>Not deterministic, the build succeeded in check + mode but the resulting output is not binary reproducable.</para> + </listitem> + </varlistentry> + +</variablelist> + +<para>With the <option>--keep-going</option> flag it's possible for +multiple failures to occur, in this case the 1xx status codes are or combined +using binary or. <screen> +1100100 + ^^^^ + |||`- timeout + ||`-- output hash mismatch + |`--- build failure + `---- not deterministic +</screen></para> + +</refsection> + + +<refsection><title>Examples</title> + +<para>This operation is typically used to build store derivations +produced by <link linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>: + +<screen> +$ nix-store -r $(nix-instantiate ./test.nix) +/nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1</screen> + +This is essentially what <link linkend="sec-nix-build"><command>nix-build</command></link> does.</para> + +<para>To test whether a previously-built derivation is deterministic: + +<screen> +$ nix-build '<nixpkgs>' -A hello --check -K +</screen> + +</para> + +</refsection> + + +</refsection> + + + +<!--######################################################################--> + +<refsection xml:id="rsec-nix-store-serve"><title>Operation <option>--serve</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--serve</option></arg> + <arg><option>--write</option></arg> +</cmdsynopsis> + +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--serve</option> provides access to +the Nix store over stdin and stdout, and is intended to be used +as a means of providing Nix store access to a restricted ssh user. +</para> + +<para>The following flags are available:</para> + +<variablelist> + + <varlistentry><term><option>--write</option></term> + + <listitem><para>Allow the connected client to request the realization + of derivations. In effect, this can be used to make the host act + as a remote builder.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + + +<refsection><title>Examples</title> + +<para>To turn a host into a build server, the +<filename>authorized_keys</filename> file can be used to provide build +access to a given SSH public key: + +<screen> +$ cat <<EOF >>/root/.ssh/authorized_keys +command="nice -n20 nix-store --serve --write" ssh-rsa AAAAB3NzaC1yc2EAAAA... +EOF +</screen> + +</para> + +</refsection> + + +</refsection> + + + +<!--######################################################################--> + +<refsection xml:id="rsec-nix-store-gc"><title>Operation <option>--gc</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--gc</option></arg> + <group> + <arg choice="plain"><option>--print-roots</option></arg> + <arg choice="plain"><option>--print-live</option></arg> + <arg choice="plain"><option>--print-dead</option></arg> + </group> + <arg><option>--max-freed</option> <replaceable>bytes</replaceable></arg> +</cmdsynopsis> + +</refsection> + +<refsection><title>Description</title> + +<para>Without additional flags, the operation <option>--gc</option> +performs a garbage collection on the Nix store. That is, all paths in +the Nix store not reachable via file system references from a set of +“roots”, are deleted.</para> + +<para>The following suboperations may be specified:</para> + +<variablelist> + + <varlistentry><term><option>--print-roots</option></term> + + <listitem><para>This operation prints on standard output the set + of roots used by the garbage collector. What constitutes a root + is described in <xref linkend="ssec-gc-roots"/>.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--print-live</option></term> + + <listitem><para>This operation prints on standard output the set + of “live” store paths, which are all the store paths reachable + from the roots. Live paths should never be deleted, since that + would break consistency — it would become possible that + applications are installed that reference things that are no + longer present in the store.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--print-dead</option></term> + + <listitem><para>This operation prints out on standard output the + set of “dead” store paths, which is just the opposite of the set + of live paths: any path in the store that is not live (with + respect to the roots) is dead.</para></listitem> + + </varlistentry> + +</variablelist> + +<para>By default, all unreachable paths are deleted. The following +options control what gets deleted and in what order: + +<variablelist> + + <varlistentry><term><option>--max-freed</option> <replaceable>bytes</replaceable></term> + + <listitem><para>Keep deleting paths until at least + <replaceable>bytes</replaceable> bytes have been deleted, then + stop. The argument <replaceable>bytes</replaceable> can be + followed by the multiplicative suffix <literal>K</literal>, + <literal>M</literal>, <literal>G</literal> or + <literal>T</literal>, denoting KiB, MiB, GiB or TiB + units.</para></listitem> + + </varlistentry> + +</variablelist> + +</para> + +<para>The behaviour of the collector is also influenced by the <link linkend="conf-keep-outputs"><literal>keep-outputs</literal></link> +and <link linkend="conf-keep-derivations"><literal>keep-derivations</literal></link> +variables in the Nix configuration file.</para> + +<para>By default, the collector prints the total number of freed bytes +when it finishes (or when it is interrupted). With +<option>--print-dead</option>, it prints the number of bytes that would +be freed.</para> + +</refsection> + + +<refsection><title>Examples</title> + +<para>To delete all unreachable paths, just do: + +<screen> +$ nix-store --gc +deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv' +<replaceable>...</replaceable> +8825586 bytes freed (8.42 MiB)</screen> + +</para> + +<para>To delete at least 100 MiBs of unreachable paths: + +<screen> +$ nix-store --gc --max-freed $((100 * 1024 * 1024))</screen> + +</para> + +</refsection> + + +</refsection> + + + +<!--######################################################################--> + +<refsection><title>Operation <option>--delete</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--delete</option></arg> + <arg><option>--ignore-liveness</option></arg> + <arg choice="plain" rep="repeat"><replaceable>paths</replaceable></arg> +</cmdsynopsis> + +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--delete</option> deletes the store paths +<replaceable>paths</replaceable> from the Nix store, but only if it is +safe to do so; that is, when the path is not reachable from a root of +the garbage collector. This means that you can only delete paths that +would also be deleted by <literal>nix-store --gc</literal>. Thus, +<literal>--delete</literal> is a more targeted version of +<literal>--gc</literal>.</para> + +<para>With the option <option>--ignore-liveness</option>, reachability +from the roots is ignored. However, the path still won’t be deleted +if there are other paths in the store that refer to it (i.e., depend +on it).</para> + +</refsection> + +<refsection><title>Example</title> + +<screen> +$ nix-store --delete /nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4 +0 bytes freed (0.00 MiB) +error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4' since it is still alive</screen> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection xml:id="refsec-nix-store-query"><title>Operation <option>--query</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-store</command> + <group choice="req"> + <arg choice="plain"><option>--query</option></arg> + <arg choice="plain"><option>-q</option></arg> + </group> + <group choice="req"> + <arg choice="plain"><option>--outputs</option></arg> + <arg choice="plain"><option>--requisites</option></arg> + <arg choice="plain"><option>-R</option></arg> + <arg choice="plain"><option>--references</option></arg> + <arg choice="plain"><option>--referrers</option></arg> + <arg choice="plain"><option>--referrers-closure</option></arg> + <arg choice="plain"><option>--deriver</option></arg> + <arg choice="plain"><option>-d</option></arg> + <arg choice="plain"><option>--graph</option></arg> + <arg choice="plain"><option>--tree</option></arg> + <arg choice="plain"><option>--binding</option> <replaceable>name</replaceable></arg> + <arg choice="plain"><option>-b</option> <replaceable>name</replaceable></arg> + <arg choice="plain"><option>--hash</option></arg> + <arg choice="plain"><option>--size</option></arg> + <arg choice="plain"><option>--roots</option></arg> + </group> + <arg><option>--use-output</option></arg> + <arg><option>-u</option></arg> + <arg><option>--force-realise</option></arg> + <arg><option>-f</option></arg> + <arg choice="plain" rep="repeat"><replaceable>paths</replaceable></arg> +</cmdsynopsis> + +</refsection> + + +<refsection><title>Description</title> + +<para>The operation <option>--query</option> displays various bits of +information about the store paths . The queries are described below. At +most one query can be specified. The default query is +<option>--outputs</option>.</para> + +<para>The paths <replaceable>paths</replaceable> may also be symlinks +from outside of the Nix store, to the Nix store. In that case, the +query is applied to the target of the symlink.</para> + + +</refsection> + + +<refsection><title>Common query options</title> + +<variablelist> + + <varlistentry><term><option>--use-output</option></term> + <term><option>-u</option></term> + + <listitem><para>For each argument to the query that is a store + derivation, apply the query to the output path of the derivation + instead.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--force-realise</option></term> + <term><option>-f</option></term> + + <listitem><para>Realise each argument to the query first (see + <link linkend="rsec-nix-store-realise"><command>nix-store + --realise</command></link>).</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + + +<refsection xml:id="nixref-queries"><title>Queries</title> + +<variablelist> + + <varlistentry><term><option>--outputs</option></term> + + <listitem><para>Prints out the <link linkend="gloss-output-path">output paths</link> of the store + derivations <replaceable>paths</replaceable>. These are the paths + that will be produced when the derivation is + built.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--requisites</option></term> + <term><option>-R</option></term> + + <listitem><para>Prints out the <link linkend="gloss-closure">closure</link> of the store path + <replaceable>paths</replaceable>.</para> + + <para>This query has one option:</para> + + <variablelist> + + <varlistentry><term><option>--include-outputs</option></term> + + <listitem><para>Also include the output path of store + derivations, and their closures.</para></listitem> + + </varlistentry> + + </variablelist> + + <para>This query can be used to implement various kinds of + deployment. A <emphasis>source deployment</emphasis> is obtained + by distributing the closure of a store derivation. A + <emphasis>binary deployment</emphasis> is obtained by distributing + the closure of an output path. A <emphasis>cache + deployment</emphasis> (combined source/binary deployment, + including binaries of build-time-only dependencies) is obtained by + distributing the closure of a store derivation and specifying the + option <option>--include-outputs</option>.</para> + + </listitem> + + </varlistentry> + + <varlistentry><term><option>--references</option></term> + + <listitem><para>Prints the set of <link linkend="gloss-reference">references</link> of the store paths + <replaceable>paths</replaceable>, that is, their immediate + dependencies. (For <emphasis>all</emphasis> dependencies, use + <option>--requisites</option>.)</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--referrers</option></term> + + <listitem><para>Prints the set of <emphasis>referrers</emphasis> of + the store paths <replaceable>paths</replaceable>, that is, the + store paths currently existing in the Nix store that refer to one + of <replaceable>paths</replaceable>. Note that contrary to the + references, the set of referrers is not constant; it can change as + store paths are added or removed.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--referrers-closure</option></term> + + <listitem><para>Prints the closure of the set of store paths + <replaceable>paths</replaceable> under the referrers relation; that + is, all store paths that directly or indirectly refer to one of + <replaceable>paths</replaceable>. These are all the path currently + in the Nix store that are dependent on + <replaceable>paths</replaceable>.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--deriver</option></term> + <term><option>-d</option></term> + + <listitem><para>Prints the <link linkend="gloss-deriver">deriver</link> of the store paths + <replaceable>paths</replaceable>. If the path has no deriver + (e.g., if it is a source file), or if the deriver is not known + (e.g., in the case of a binary-only deployment), the string + <literal>unknown-deriver</literal> is printed.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--graph</option></term> + + <listitem><para>Prints the references graph of the store paths + <replaceable>paths</replaceable> in the format of the + <command>dot</command> tool of AT&T's <link xlink:href="http://www.graphviz.org/">Graphviz package</link>. + This can be used to visualise dependency graphs. To obtain a + build-time dependency graph, apply this to a store derivation. To + obtain a runtime dependency graph, apply it to an output + path.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--tree</option></term> + + <listitem><para>Prints the references graph of the store paths + <replaceable>paths</replaceable> as a nested ASCII tree. + References are ordered by descending closure size; this tends to + flatten the tree, making it more readable. The query only + recurses into a store path when it is first encountered; this + prevents a blowup of the tree representation of the + graph.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--graphml</option></term> + + <listitem><para>Prints the references graph of the store paths + <replaceable>paths</replaceable> in the <link xlink:href="http://graphml.graphdrawing.org/">GraphML</link> file format. + This can be used to visualise dependency graphs. To obtain a + build-time dependency graph, apply this to a store derivation. To + obtain a runtime dependency graph, apply it to an output + path.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--binding</option> <replaceable>name</replaceable></term> + <term><option>-b</option> <replaceable>name</replaceable></term> + + <listitem><para>Prints the value of the attribute + <replaceable>name</replaceable> (i.e., environment variable) of + the store derivations <replaceable>paths</replaceable>. It is an + error for a derivation to not have the specified + attribute.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--hash</option></term> + + <listitem><para>Prints the SHA-256 hash of the contents of the + store paths <replaceable>paths</replaceable> (that is, the hash of + the output of <command>nix-store --dump</command> on the given + paths). Since the hash is stored in the Nix database, this is a + fast operation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--size</option></term> + + <listitem><para>Prints the size in bytes of the contents of the + store paths <replaceable>paths</replaceable> — to be precise, the + size of the output of <command>nix-store --dump</command> on the + given paths. Note that the actual disk space required by the + store paths may be higher, especially on filesystems with large + cluster sizes.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--roots</option></term> + + <listitem><para>Prints the garbage collector roots that point, + directly or indirectly, at the store paths + <replaceable>paths</replaceable>.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + + +<refsection><title>Examples</title> + +<para>Print the closure (runtime dependencies) of the +<command>svn</command> program in the current user environment: + +<screen> +$ nix-store -qR $(which svn) +/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4 +/nix/store/9lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4 +<replaceable>...</replaceable></screen> + +</para> + +<para>Print the build-time dependencies of <command>svn</command>: + +<screen> +$ nix-store -qR $(nix-store -qd $(which svn)) +/nix/store/02iizgn86m42q905rddvg4ja975bk2i4-grep-2.5.1.tar.bz2.drv +/nix/store/07a2bzxmzwz5hp58nf03pahrv2ygwgs3-gcc-wrapper.sh +/nix/store/0ma7c9wsbaxahwwl04gbw3fcd806ski4-glibc-2.3.4.drv +<replaceable>... lots of other paths ...</replaceable></screen> + +The difference with the previous example is that we ask the closure of +the derivation (<option>-qd</option>), not the closure of the output +path that contains <command>svn</command>.</para> + +<para>Show the build-time dependencies as a tree: + +<screen> +$ nix-store -q --tree $(nix-store -qd $(which svn)) +/nix/store/7i5082kfb6yjbqdbiwdhhza0am2xvh6c-subversion-1.1.4.drv ++---/nix/store/d8afh10z72n8l1cr5w42366abiblgn54-builder.sh ++---/nix/store/fmzxmpjx2lh849ph0l36snfj9zdibw67-bash-3.0.drv +| +---/nix/store/570hmhmx3v57605cqg9yfvvyh0nnb8k8-bash +| +---/nix/store/p3srsbd8dx44v2pg6nbnszab5mcwx03v-builder.sh +<replaceable>...</replaceable></screen> + +</para> + +<para>Show all paths that depend on the same OpenSSL library as +<command>svn</command>: + +<screen> +$ nix-store -q --referrers $(nix-store -q --binding openssl $(nix-store -qd $(which svn))) +/nix/store/23ny9l9wixx21632y2wi4p585qhva1q8-sylpheed-1.0.0 +/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4 +/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3 +/nix/store/l51240xqsgg8a7yrbqdx1rfzyv6l26fx-lynx-2.8.5</screen> + +</para> + +<para>Show all paths that directly or indirectly depend on the Glibc +(C library) used by <command>svn</command>: + +<screen> +$ nix-store -q --referrers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}') +/nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2 +/nix/store/15l3yi0d45prm7a82pcrknxdh6nzmxza-gawk-3.1.4 +<replaceable>...</replaceable></screen> + +Note that <command>ldd</command> is a command that prints out the +dynamic libraries used by an ELF executable.</para> + +<para>Make a picture of the runtime dependency graph of the current +user environment: + +<screen> +$ nix-store -q --graph ~/.nix-profile | dot -Tps > graph.ps +$ gv graph.ps</screen> + +</para> + +<para>Show every garbage collector root that points to a store path +that depends on <command>svn</command>: + +<screen> +$ nix-store -q --roots $(which svn) +/nix/var/nix/profiles/default-81-link +/nix/var/nix/profiles/default-82-link +/nix/var/nix/profiles/per-user/eelco/profile-97-link +</screen> + +</para> + +</refsection> + + +</refsection> + + + +<!--######################################################################--> + +<!-- +<refsection xml:id="rsec-nix-store-reg-val"><title>Operation <option>-XXX-register-validity</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-store</command> + <arg choice='plain'><option>-XXX-register-validity</option></arg> +</cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>TODO</para> + +</refsection> + +</refsection> +--> + + + +<!--######################################################################--> + +<refsection><title>Operation <option>--add</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--add</option></arg> + <arg choice="plain" rep="repeat"><replaceable>paths</replaceable></arg> +</cmdsynopsis> + +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--add</option> adds the specified paths to +the Nix store. It prints the resulting paths in the Nix store on +standard output.</para> + +</refsection> + +<refsection><title>Example</title> + +<screen> +$ nix-store --add ./foo.c +/nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c</screen> + +</refsection> + +</refsection> + +<!--######################################################################--> + +<refsection><title>Operation <option>--add-fixed</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-store</command> + <arg><option>--recursive</option></arg> + <arg choice="plain"><option>--add-fixed</option></arg> + <arg choice="plain"><replaceable>algorithm</replaceable></arg> + <arg choice="plain" rep="repeat"><replaceable>paths</replaceable></arg> +</cmdsynopsis> + +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--add-fixed</option> adds the specified paths to +the Nix store. Unlike <option>--add</option> paths are registered using the +specified hashing algorithm, resulting in the same output path as a fixed-output +derivation. This can be used for sources that are not available from a public +url or broke since the download expression was written. +</para> + +<para>This operation has the following options: + +<variablelist> + + <varlistentry><term><option>--recursive</option></term> + + <listitem><para> + Use recursive instead of flat hashing mode, used when adding directories + to the store. + </para></listitem> + + </varlistentry> + +</variablelist> + +</para> + +</refsection> + +<refsection><title>Example</title> + +<screen> +$ nix-store --add-fixed sha256 ./hello-2.10.tar.gz +/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz</screen> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection xml:id="refsec-nix-store-verify"><title>Operation <option>--verify</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--verify</option></arg> + <arg><option>--check-contents</option></arg> + <arg><option>--repair</option></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--verify</option> verifies the internal +consistency of the Nix database, and the consistency between the Nix +database and the Nix store. Any inconsistencies encountered are +automatically repaired. Inconsistencies are generally the result of +the Nix store or database being modified by non-Nix tools, or of bugs +in Nix itself.</para> + +<para>This operation has the following options: + +<variablelist> + + <varlistentry><term><option>--check-contents</option></term> + + <listitem><para>Checks that the contents of every valid store path + has not been altered by computing a SHA-256 hash of the contents + and comparing it with the hash stored in the Nix database at build + time. Paths that have been modified are printed out. For large + stores, <option>--check-contents</option> is obviously quite + slow.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--repair</option></term> + + <listitem><para>If any valid path is missing from the store, or + (if <option>--check-contents</option> is given) the contents of a + valid path has been modified, then try to repair the path by + redownloading it. See <command>nix-store --repair-path</command> + for details.</para></listitem> + + </varlistentry> + +</variablelist> + +</para> + +</refsection> + + +</refsection> + + +<!--######################################################################--> + +<refsection><title>Operation <option>--verify-path</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--verify-path</option></arg> + <arg choice="plain" rep="repeat"><replaceable>paths</replaceable></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--verify-path</option> compares the +contents of the given store paths to their cryptographic hashes stored +in Nix’s database. For every changed path, it prints a warning +message. The exit status is 0 if no path has changed, and 1 +otherwise.</para> + +</refsection> + +<refsection><title>Example</title> + +<para>To verify the integrity of the <command>svn</command> command and all its dependencies: + +<screen> +$ nix-store --verify-path $(nix-store -qR $(which svn)) +</screen> + +</para> + +</refsection> + +</refsection> + + +<!--######################################################################--> + +<refsection><title>Operation <option>--repair-path</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--repair-path</option></arg> + <arg choice="plain" rep="repeat"><replaceable>paths</replaceable></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--repair-path</option> attempts to +“repair” the specified paths by redownloading them using the available +substituters. If no substitutes are available, then repair is not +possible.</para> + +<warning><para>During repair, there is a very small time window during +which the old path (if it exists) is moved out of the way and replaced +with the new path. If repair is interrupted in between, then the +system may be left in a broken state (e.g., if the path contains a +critical system component like the GNU C Library).</para></warning> + +</refsection> + +<refsection><title>Example</title> + +<screen> +$ nix-store --verify-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13 +path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified! + expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588', + got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4' + +$ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13 +fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'... +… +</screen> + +</refsection> + +</refsection> + + +<!--######################################################################--> + +<refsection xml:id="refsec-nix-store-dump"><title>Operation <option>--dump</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--dump</option></arg> + <arg choice="plain"><replaceable>path</replaceable></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--dump</option> produces a NAR (Nix +ARchive) file containing the contents of the file system tree rooted +at <replaceable>path</replaceable>. The archive is written to +standard output.</para> + +<para>A NAR archive is like a TAR or Zip archive, but it contains only +the information that Nix considers important. For instance, +timestamps are elided because all files in the Nix store have their +timestamp set to 0 anyway. Likewise, all permissions are left out +except for the execute bit, because all files in the Nix store have +444 or 555 permission.</para> + +<para>Also, a NAR archive is <emphasis>canonical</emphasis>, meaning +that “equal” paths always produce the same NAR archive. For instance, +directory entries are always sorted so that the actual on-disk order +doesn’t influence the result. This means that the cryptographic hash +of a NAR dump of a path is usable as a fingerprint of the contents of +the path. Indeed, the hashes of store paths stored in Nix’s database +(see <link linkend="refsec-nix-store-query"><literal>nix-store -q +--hash</literal></link>) are SHA-256 hashes of the NAR dump of each +store path.</para> + +<para>NAR archives support filenames of unlimited length and 64-bit +file sizes. They can contain regular files, directories, and symbolic +links, but not other types of files (such as device nodes).</para> + +<para>A Nix archive can be unpacked using <literal>nix-store +--restore</literal>.</para> + +</refsection> + + +</refsection> + + +<!--######################################################################--> + +<refsection><title>Operation <option>--restore</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--restore</option></arg> + <arg choice="plain"><replaceable>path</replaceable></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--restore</option> unpacks a NAR archive +to <replaceable>path</replaceable>, which must not already exist. The +archive is read from standard input.</para> + +</refsection> + + +</refsection> + + +<!--######################################################################--> + +<refsection xml:id="refsec-nix-store-export"><title>Operation <option>--export</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--export</option></arg> + <arg choice="plain" rep="repeat"><replaceable>paths</replaceable></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--export</option> writes a serialisation +of the specified store paths to standard output in a format that can +be imported into another Nix store with <command linkend="refsec-nix-store-import">nix-store --import</command>. This +is like <command linkend="refsec-nix-store-dump">nix-store +--dump</command>, except that the NAR archive produced by that command +doesn’t contain the necessary meta-information to allow it to be +imported into another Nix store (namely, the set of references of the +path).</para> + +<para>This command does not produce a <emphasis>closure</emphasis> of +the specified paths, so if a store path references other store paths +that are missing in the target Nix store, the import will fail. To +copy a whole closure, do something like: + +<screen> +$ nix-store --export $(nix-store -qR <replaceable>paths</replaceable>) > out</screen> + +To import the whole closure again, run: + +<screen> +$ nix-store --import < out</screen> + +</para> + +</refsection> + + +</refsection> + + +<!--######################################################################--> + +<refsection xml:id="refsec-nix-store-import"><title>Operation <option>--import</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--import</option></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--import</option> reads a serialisation of +a set of store paths produced by <command linkend="refsec-nix-store-export">nix-store --export</command> from +standard input and adds those store paths to the Nix store. Paths +that already exist in the Nix store are ignored. If a path refers to +another path that doesn’t exist in the Nix store, the import +fails.</para> + +</refsection> + + +</refsection> + + +<!--######################################################################--> + +<refsection><title>Operation <option>--optimise</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--optimise</option></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--optimise</option> reduces Nix store disk +space usage by finding identical files in the store and hard-linking +them to each other. It typically reduces the size of the store by +something like 25-35%. Only regular files and symlinks are +hard-linked in this manner. Files are considered identical when they +have the same NAR archive serialisation: that is, regular files must +have the same contents and permission (executable or non-executable), +and symlinks must have the same contents.</para> + +<para>After completion, or when the command is interrupted, a report +on the achieved savings is printed on standard error.</para> + +<para>Use <option>-vv</option> or <option>-vvv</option> to get some +progress indication.</para> + +</refsection> + +<refsection><title>Example</title> + +<screen> +$ nix-store --optimise +hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1' +<replaceable>...</replaceable> +541838819 bytes (516.74 MiB) freed by hard-linking 54143 files; +there are 114486 files with equal contents out of 215894 files in total +</screen> + +</refsection> + + +</refsection> + + +<!--######################################################################--> + +<refsection><title>Operation <option>--read-log</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <group choice="req"> + <arg choice="plain"><option>--read-log</option></arg> + <arg choice="plain"><option>-l</option></arg> + </group> + <arg choice="plain" rep="repeat"><replaceable>paths</replaceable></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--read-log</option> prints the build log +of the specified store paths on standard output. The build log is +whatever the builder of a derivation wrote to standard output and +standard error. If a store path is not a derivation, the deriver of +the store path is used.</para> + +<para>Build logs are kept in +<filename>/nix/var/log/nix/drvs</filename>. However, there is no +guarantee that a build log is available for any particular store path. +For instance, if the path was downloaded as a pre-built binary through +a substitute, then the log is unavailable.</para> + +</refsection> + +<refsection><title>Example</title> + +<screen> +$ nix-store -l $(which ktorrent) +building /nix/store/dhc73pvzpnzxhdgpimsd9sw39di66ph1-ktorrent-2.2.1 +unpacking sources +unpacking source archive /nix/store/p8n1jpqs27mgkjw07pb5269717nzf5f8-ktorrent-2.2.1.tar.gz +ktorrent-2.2.1/ +ktorrent-2.2.1/NEWS +<replaceable>...</replaceable> +</screen> + +</refsection> + + +</refsection> + + +<!--######################################################################--> + +<refsection><title>Operation <option>--dump-db</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--dump-db</option></arg> + <arg rep="repeat"><replaceable>paths</replaceable></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--dump-db</option> writes a dump of the +Nix database to standard output. It can be loaded into an empty Nix +store using <option>--load-db</option>. This is useful for making +backups and when migrating to different database schemas.</para> + +<para>By default, <option>--dump-db</option> will dump the entire Nix +database. When one or more store paths is passed, only the subset of +the Nix database for those store paths is dumped. As with +<option>--export</option>, the user is responsible for passing all the +store paths for a closure. See <option>--export</option> for an +example.</para> + +</refsection> + +</refsection> + + +<!--######################################################################--> + +<refsection><title>Operation <option>--load-db</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--load-db</option></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--load-db</option> reads a dump of the Nix +database created by <option>--dump-db</option> from standard input and +loads it into the Nix database.</para> + +</refsection> + +</refsection> + + +<!--######################################################################--> + +<refsection><title>Operation <option>--print-env</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"><option>--print-env</option></arg> + <arg choice="plain"><replaceable>drvpath</replaceable></arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The operation <option>--print-env</option> prints out the +environment of a derivation in a format that can be evaluated by a +shell. The command line arguments of the builder are placed in the +variable <envar>_args</envar>.</para> + +</refsection> + +<refsection><title>Example</title> + +<screen> +$ nix-store --print-env $(nix-instantiate '<nixpkgs>' -A firefox) +<replaceable>…</replaceable> +export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2' +export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv' +export system; system='x86_64-linux' +export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-builder.sh' +</screen> + +</refsection> + +</refsection> + + +<!--######################################################################--> + +<refsection xml:id="rsec-nix-store-generate-binary-cache-key"><title>Operation <option>--generate-binary-cache-key</option></title> + +<refsection> + <title>Synopsis</title> + <cmdsynopsis> + <command>nix-store</command> + <arg choice="plain"> + <option>--generate-binary-cache-key</option> + <option>key-name</option> + <option>secret-key-file</option> + <option>public-key-file</option> + </arg> + </cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>This command generates an <link xlink:href="http://ed25519.cr.yp.to/">Ed25519 key pair</link> that can +be used to create a signed binary cache. It takes three mandatory +parameters: + +<orderedlist> + + <listitem><para>A key name, such as + <literal>cache.example.org-1</literal>, that is used to look up keys + on the client when it verifies signatures. It can be anything, but + it’s suggested to use the host name of your cache + (e.g. <literal>cache.example.org</literal>) with a suffix denoting + the number of the key (to be incremented every time you need to + revoke a key).</para></listitem> + + <listitem><para>The file name where the secret key is to be + stored.</para></listitem> + + <listitem><para>The file name where the public key is to be + stored.</para></listitem> + +</orderedlist> + +</para> + +</refsection> + +</refsection> + + +<!--######################################################################--> + +<refsection condition="manpage"><title>Environment variables</title> + +<variablelist> + <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><<replaceable>path</replaceable>></literal>). For + instance, the value + + <screen> +/home/eelco/Dev:/etc/nixos</screen> + + will cause Nix to look for paths relative to + <filename>/home/eelco/Dev</filename> and + <filename>/etc/nixos</filename>, in this order. It is also + possible to match paths against a prefix. For example, the value + + <screen> +nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen> + + will cause Nix to search for + <literal><nixpkgs/<replaceable>path</replaceable>></literal> in + <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename> + and + <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.</para> + + <para>If a path in the Nix search path starts with + <literal>http://</literal> or <literal>https://</literal>, it is + interpreted as the URL of a tarball that will be downloaded and + unpacked to a temporary location. The tarball must consist of a + single top-level directory. For example, setting + <envar>NIX_PATH</envar> to + + <screen> +nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz</screen> + + tells Nix to download the latest revision in the Nixpkgs/NixOS + 15.09 channel.</para> + + <para>A following shorthand can be used to refer to the official channels: + + <screen>nixpkgs=channel:nixos-15.09</screen> + </para> + + <para>The search path can be extended using the <option linkend="opt-I">-I</option> option, which takes precedence over + <envar>NIX_PATH</envar>.</para></listitem> + +</varlistentry><varlistentry 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 “impure” builds. Builders + sometimes “canonicalise” paths by resolving all symlink components. + Thus, builds on different machines (with + <filename>/nix/store</filename> resolving to different locations) + could yield different results. This is generally not a problem, + except when builds are deployed to machines where + <filename>/nix/store</filename> resolves differently. If you are + sure that you’re not going to do that, you can set + <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para> + + <para>Note that if you’re symlinking the Nix store so that you can + put it on another file system than the root file system, on Linux + you’re better off using <literal>bind</literal> mount points, e.g., + + <screen> +$ mkdir /nix +$ mount -o bind /mnt/otherdisk/nix /nix</screen> + + Consult the <citerefentry><refentrytitle>mount</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> manual page for details.</para> + + </listitem> + +</varlistentry><varlistentry 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>…]</term> + + <listitem><para>Downloads the Nix expressions of all subscribed + channels (or only those included in + <replaceable>names</replaceable> if specified) and makes them the + default for <command>nix-env</command> operations (by symlinking + them from the directory + <filename>~/.nix-defexpr</filename>).</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--rollback</option> [<replaceable>generation</replaceable>]</term> + + <listitem><para>Reverts the previous call to <command>nix-channel + --update</command>. Optionally, you can specify a specific channel + generation number to restore.</para></listitem> + + </varlistentry> + +</variablelist> + +</para> + +<para>Note that <option>--add</option> does not automatically perform +an update.</para> + +<para>The list of subscribed channels is stored in +<filename>~/.nix-channels</filename>.</para> + +</refsection> + +<refsection><title>Examples</title> + +<para>To subscribe to the Nixpkgs channel and install the GNU Hello package:</para> + +<screen> +$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable +$ nix-channel --update +$ nix-env -iA nixpkgs.hello</screen> + +<para>You can revert channel updates using <option>--rollback</option>:</para> + +<screen> +$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' +"14.04.527.0e935f1" + +$ nix-channel --rollback +switching from generation 483 to 482 + +$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' +"14.04.526.dbadfad" +</screen> + +</refsection> + +<refsection><title>Files</title> + +<variablelist> + + <varlistentry><term><filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename></term> + + <listitem><para><command>nix-channel</command> uses a + <command>nix-env</command> profile to keep track of previous + versions of the subscribed channels. Every time you run + <command>nix-channel --update</command>, a new channel generation + (that is, a symlink to the channel Nix expressions in the Nix store) + is created. This enables <command>nix-channel --rollback</command> + to revert to previous versions.</para></listitem> + + </varlistentry> + + <varlistentry><term><filename>~/.nix-defexpr/channels</filename></term> + + <listitem><para>This is a symlink to + <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename>. It + ensures that <command>nix-env</command> can find your channels. In + a multi-user installation, you may also have + <filename>~/.nix-defexpr/channels_root</filename>, which links to + the channels of the root user.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + +<refsection><title>Channel format</title> + +<para>A channel URL should point to a directory containing the +following files:</para> + +<variablelist> + + <varlistentry><term><filename>nixexprs.tar.xz</filename></term> + + <listitem><para>A tarball containing Nix expressions and files + referenced by them (such as build scripts and patches). At the + top level, the tarball should contain a single directory. That + directory must contain a file <filename>default.nix</filename> + that serves as the channel’s “entry point”.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + +</refentry> +<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’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’t hash anything, but convert the base-32 hash + representation <replaceable>hash</replaceable> to + hexadecimal.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--to-base32</option></term> + + <listitem><para>Don’t hash anything, but convert the hexadecimal + hash representation <replaceable>hash</replaceable> to + base-32.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + + +<refsection><title>Examples</title> + +<para>Computing the same hash as <command>nix-prefetch-url</command>: +<screen> +$ nix-prefetch-url file://<(echo test) +1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj +$ nix-hash --type sha256 --flat --base32 <(echo test) +1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj +</screen> +</para> + +<para>Computing hashes: + +<screen> +$ mkdir test +$ echo "hello" > test/world + +$ nix-hash test/ <lineannotation>(MD5 hash; default)</lineannotation> +8179d3caeff1869b5ba1744e5a245c04 + +$ nix-store --dump test/ | md5sum <lineannotation>(for comparison)</lineannotation> +8179d3caeff1869b5ba1744e5a245c04 - + +$ nix-hash --type sha1 test/ +e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 + +$ nix-hash --type sha1 --base32 test/ +nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 + +$ nix-hash --type sha256 --flat test/ +error: reading file `test/': Is a directory + +$ nix-hash --type sha256 --flat test/world +5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03</screen> + +</para> + +<para>Converting between hexadecimal and base-32: + +<screen> +$ nix-hash --type sha1 --to-base32 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 +nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 + +$ nix-hash --type sha1 --to-base16 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 +e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6</screen> + +</para> + +</refsection> + + +</refentry> +<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’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>“Errors only”: only print messages + explaining why the Nix invocation failed.</para></listitem> + </varlistentry> + + <varlistentry><term>1</term> + <listitem><para>“Informational”: print + <emphasis>useful</emphasis> messages about what Nix is doing. + This is the default.</para></listitem> + </varlistentry> + + <varlistentry><term>2</term> + <listitem><para>“Talkative”: print more informational + messages.</para></listitem> + </varlistentry> + + <varlistentry><term>3</term> + <listitem><para>“Chatty”: print even more + informational messages.</para></listitem> + </varlistentry> + + <varlistentry><term>4</term> + <listitem><para>“Debug”: print debug + information.</para></listitem> + </varlistentry> + + <varlistentry><term>5</term> + <listitem><para>“Vomit”: print vast amounts of debug + information.</para></listitem> + </varlistentry> + + </variablelist> + + </listitem> + +</varlistentry><varlistentry 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 <nixpkgs> { }; hello' +/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv +</screen> + +This is equivalent to: + +<screen> +$ nix-instantiate '<nixpkgs>' -A hello +</screen> + +</para> + +<para>Parsing and evaluating Nix expressions: + +<screen> +$ nix-instantiate --parse -E '1 + 2' +1 + 2 + +$ nix-instantiate --eval -E '1 + 2' +3 + +$ nix-instantiate --eval --xml -E '1 + 2' +<![CDATA[<?xml version='1.0' encoding='utf-8'?> +<expr> + <int value="3" /> +</expr>]]></screen> + +</para> + +<para>The difference between non-strict and strict evaluation: + +<screen> +$ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }' +<replaceable>...</replaceable><![CDATA[ + <attr name="x"> + <string value="foo" /> + </attr> + <attr name="y"> + <unevaluated /> + </attr>]]> +<replaceable>...</replaceable></screen> + +Note that <varname>y</varname> is left unevaluated (the XML +representation doesn’t attempt to show non-normal forms). + +<screen> +$ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }' +<replaceable>...</replaceable><![CDATA[ + <attr name="x"> + <string value="foo" /> + </attr> + <attr name="y"> + <string value="foo" /> + </attr>]]> +<replaceable>...</replaceable></screen> + +</para> + +</refsection> + + +<refsection condition="manpage"><title>Environment variables</title> + +<variablelist> + <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><<replaceable>path</replaceable>></literal>). For + instance, the value + + <screen> +/home/eelco/Dev:/etc/nixos</screen> + + will cause Nix to look for paths relative to + <filename>/home/eelco/Dev</filename> and + <filename>/etc/nixos</filename>, in this order. It is also + possible to match paths against a prefix. For example, the value + + <screen> +nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen> + + will cause Nix to search for + <literal><nixpkgs/<replaceable>path</replaceable>></literal> in + <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename> + and + <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.</para> + + <para>If a path in the Nix search path starts with + <literal>http://</literal> or <literal>https://</literal>, it is + interpreted as the URL of a tarball that will be downloaded and + unpacked to a temporary location. The tarball must consist of a + single top-level directory. For example, setting + <envar>NIX_PATH</envar> to + + <screen> +nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz</screen> + + tells Nix to download the latest revision in the Nixpkgs/NixOS + 15.09 channel.</para> + + <para>A following shorthand can be used to refer to the official channels: + + <screen>nixpkgs=channel:nixos-15.09</screen> + </para> + + <para>The search path can be extended using the <option linkend="opt-I">-I</option> option, which takes precedence over + <envar>NIX_PATH</envar>.</para></listitem> + +</varlistentry><varlistentry 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 “impure” builds. Builders + sometimes “canonicalise” paths by resolving all symlink components. + Thus, builds on different machines (with + <filename>/nix/store</filename> resolving to different locations) + could yield different results. This is generally not a problem, + except when builds are deployed to machines where + <filename>/nix/store</filename> resolves differently. If you are + sure that you’re not going to do that, you can set + <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para> + + <para>Note that if you’re symlinking the Nix store so that you can + put it on another file system than the root file system, on Linux + you’re better off using <literal>bind</literal> mount points, e.g., + + <screen> +$ mkdir /nix +$ mount -o bind /mnt/otherdisk/nix /nix</screen> + + Consult the <citerefentry><refentrytitle>mount</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> manual page for details.</para> + + </listitem> + +</varlistentry><varlistentry 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’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>’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 + “sticky”: it applies to any user environment created while this + option was enabled, while <literal>keep-derivations</literal> + only applies at the moment the garbage collector is + run.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="conf-keep-outputs"><term><literal>keep-outputs</literal></term> + + <listitem><para>If <literal>true</literal>, the garbage collector + will keep the outputs of non-garbage derivations. If + <literal>false</literal> (default), outputs will be deleted unless + they are GC roots themselves (or reachable from other roots).</para> + + <para>In general, outputs must be registered as roots separately. + However, even if the output of a derivation is registered as a + root, the collector will still delete store paths that are used + only at build time (e.g., the C compiler, or source tarballs + downloaded from the network). To prevent it from doing so, set + this option to <literal>true</literal>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-max-build-log-size"><term><literal>max-build-log-size</literal></term> + + <listitem> + + <para>This option defines the maximum number of bytes that a + builder can write to its stdout/stderr. If the builder exceeds + this limit, it’s killed. A value of <literal>0</literal> (the + default) means that there is no limit.</para> + + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-max-free"><term><literal>max-free</literal></term> + + <listitem><para>When a garbage collection is triggered by the + <literal>min-free</literal> option, it stops as soon as + <literal>max-free</literal> bytes are available. The default is + infinity (i.e. delete all garbage).</para></listitem> + + </varlistentry> + + <varlistentry xml:id="conf-max-jobs"><term><literal>max-jobs</literal></term> + + <listitem><para>This option defines the maximum number of jobs + that Nix will try to build in parallel. The default is + <literal>1</literal>. The special value <literal>auto</literal> + causes Nix to use the number of CPUs in your system. <literal>0</literal> + is useful when using remote builders to prevent any local builds (except for + <literal>preferLocalBuild</literal> derivation attribute which executes locally + regardless). It can be + overridden using the <option linkend="opt-max-jobs">--max-jobs</option> (<option>-j</option>) + command line switch.</para> + + <para>See also <xref linkend="chap-tuning-cores-and-jobs"/>.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="conf-max-silent-time"><term><literal>max-silent-time</literal></term> + + <listitem> + + <para>This option defines the maximum number of seconds that a + builder can go without producing any data on standard output or + standard error. This is useful (for instance in an automated + build system) to catch builds that are stuck in an infinite + loop, or to catch remote builds that are hanging due to network + problems. It can be overridden using the <option linkend="opt-max-silent-time">--max-silent-time</option> command + line switch.</para> + + <para>The value <literal>0</literal> means that there is no + timeout. This is also the default.</para> + + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-min-free"><term><literal>min-free</literal></term> + + <listitem> + <para>When free disk space in <filename>/nix/store</filename> + drops below <literal>min-free</literal> during a build, Nix + performs a garbage-collection until <literal>max-free</literal> + bytes are available or there is no more garbage. A value of + <literal>0</literal> (the default) disables this feature.</para> + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-narinfo-cache-negative-ttl"><term><literal>narinfo-cache-negative-ttl</literal></term> + + <listitem> + + <para>The TTL in seconds for negative lookups. If a store path is + queried from a substituter but was not found, there will be a + negative lookup cached in the local disk cache database for the + specified duration.</para> + + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-narinfo-cache-positive-ttl"><term><literal>narinfo-cache-positive-ttl</literal></term> + + <listitem> + + <para>The TTL in seconds for positive lookups. If a store path is + queried from a substituter, the result of the query will be cached + in the local disk cache database including some of the NAR + metadata. The default TTL is a month, setting a shorter TTL for + positive lookups can be useful for binary caches that have + frequent garbage collection, in which case having a more frequent + cache invalidation would prevent trying to pull the path again and + failing with a hash mismatch if the build isn't reproducible. + </para> + + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-netrc-file"><term><literal>netrc-file</literal></term> + + <listitem><para>If set to an absolute path to a <filename>netrc</filename> + file, Nix will use the HTTP authentication credentials in this file when + trying to download from a remote host through HTTP or HTTPS. Defaults to + <filename>$NIX_CONF_DIR/netrc</filename>.</para> + + <para>The <filename>netrc</filename> file consists of a list of + accounts in the following format: + +<screen> +machine <replaceable>my-machine</replaceable> +login <replaceable>my-username</replaceable> +password <replaceable>my-password</replaceable> +</screen> + + For the exact syntax, see <link xlink:href="https://ec.haxx.se/usingcurl-netrc.html">the + <literal>curl</literal> documentation.</link></para> + + <note><para>This must be an absolute path, and <literal>~</literal> + is not resolved. For example, <filename>~/.netrc</filename> won't + resolve to your home directory's <filename>.netrc</filename>.</para></note> + </listitem> + + </varlistentry> + + + <varlistentry xml:id="conf-plugin-files"> + <term><literal>plugin-files</literal></term> + <listitem> + <para> + A list of plugin files to be loaded by Nix. Each of these + files will be dlopened by Nix, allowing them to affect + execution through static initialization. In particular, these + plugins may construct static instances of RegisterPrimOp to + add new primops or constants to the expression language, + RegisterStoreImplementation to add new store implementations, + RegisterCommand to add new subcommands to the + <literal>nix</literal> command, and RegisterSetting to add new + nix config settings. See the constructors for those types for + more details. + </para> + <para> + Since these files are loaded into the same address space as + Nix itself, they must be DSOs compatible with the instance of + Nix running at the time (i.e. compiled against the same + headers, not linked to any incompatible libraries). They + should not be linked to any Nix libs directly, as those will + be available already at load time. + </para> + <para> + If an entry in the list is a directory, all files in the + directory are loaded as plugins (non-recursively). + </para> + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-pre-build-hook"><term><literal>pre-build-hook</literal></term> + + <listitem> + + + <para>If set, the path to a program that can set extra + derivation-specific settings for this system. This is used for settings + that can't be captured by the derivation model itself and are too variable + between different versions of the same system to be hard-coded into nix. + </para> + + <para>The hook is passed the derivation path and, if sandboxes are enabled, + the sandbox directory. It can then modify the sandbox and send a series of + commands to modify various settings to stdout. The currently recognized + commands are:</para> + + <variablelist> + <varlistentry xml:id="extra-sandbox-paths"> + <term><literal>extra-sandbox-paths</literal></term> + + <listitem> + + <para>Pass a list of files and directories to be included in the + sandbox for this build. One entry per line, terminated by an empty + line. Entries have the same format as + <literal>sandbox-paths</literal>.</para> + + </listitem> + + </varlistentry> + </variablelist> + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-post-build-hook"> + <term><literal>post-build-hook</literal></term> + <listitem> + <para>Optional. The path to a program to execute after each build.</para> + + <para>This option is only settable in the global + <filename>nix.conf</filename>, or on the command line by trusted + users.</para> + + <para>When using the nix-daemon, the daemon executes the hook as + <literal>root</literal>. If the nix-daemon is not involved, the + hook runs as the user executing the nix-build.</para> + + <itemizedlist> + <listitem><para>The hook executes after an evaluation-time build.</para></listitem> + <listitem><para>The hook does not execute on substituted paths.</para></listitem> + <listitem><para>The hook's output always goes to the user's terminal.</para></listitem> + <listitem><para>If the hook fails, the build succeeds but no further builds execute.</para></listitem> + <listitem><para>The hook executes synchronously, and blocks other builds from progressing while it runs.</para></listitem> + </itemizedlist> + + <para>The program executes with no arguments. The program's environment + contains the following environment variables:</para> + + <variablelist> + <varlistentry> + <term><envar>DRV_PATH</envar></term> + <listitem> + <para>The derivation for the built paths.</para> + <para>Example: + <literal>/nix/store/5nihn1a7pa8b25l9zafqaqibznlvvp3f-bash-4.4-p23.drv</literal> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>OUT_PATHS</envar></term> + <listitem> + <para>Output paths of the built derivation, separated by a space character.</para> + <para>Example: + <literal>/nix/store/zf5lbh336mnzf1nlswdn11g4n2m8zh3g-bash-4.4-p23-dev + /nix/store/rjxwxwv1fpn9wa2x5ssk5phzwlcv4mna-bash-4.4-p23-doc + /nix/store/6bqvbzjkcp9695dq0dpl5y43nvy37pq1-bash-4.4-p23-info + /nix/store/r7fng3kk3vlpdlh2idnrbn37vh4imlj2-bash-4.4-p23-man + /nix/store/xfghy8ixrhz3kyy6p724iv3cxji088dx-bash-4.4-p23</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para>See <xref linkend="chap-post-build-hook"/> for an example + implementation.</para> + + </listitem> + </varlistentry> + + <varlistentry xml:id="conf-repeat"><term><literal>repeat</literal></term> + + <listitem><para>How many times to repeat builds to check whether + they are deterministic. The default value is 0. If the value is + non-zero, every build is repeated the specified number of + times. If the contents of any of the runs differs from the + previous ones and <xref linkend="conf-enforce-determinism"/> is + true, the build is rejected and the resulting store paths are not + registered as “valid” in Nix’s database.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-require-sigs"><term><literal>require-sigs</literal></term> + + <listitem><para>If set to <literal>true</literal> (the default), + any non-content-addressed path added or copied to the Nix store + (e.g. when substituting from a binary cache) must have a valid + signature, that is, be signed using one of the keys listed in + <option>trusted-public-keys</option> or + <option>secret-key-files</option>. Set to <literal>false</literal> + to disable signature checking.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="conf-restrict-eval"><term><literal>restrict-eval</literal></term> + + <listitem> + + <para>If set to <literal>true</literal>, the Nix evaluator will + not allow access to any files outside of the Nix search path (as + set via the <envar>NIX_PATH</envar> environment variable or the + <option>-I</option> option), or to URIs outside of + <option>allowed-uri</option>. The default is + <literal>false</literal>.</para> + + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-run-diff-hook"><term><literal>run-diff-hook</literal></term> + <listitem> + <para> + If true, enable the execution of <xref linkend="conf-diff-hook"/>. + </para> + + <para> + When using the Nix daemon, <literal>run-diff-hook</literal> must + be set in the <filename>nix.conf</filename> configuration file, + and cannot be passed at the command line. + </para> + </listitem> + </varlistentry> + + <varlistentry xml:id="conf-sandbox"><term><literal>sandbox</literal></term> + + <listitem><para>If set to <literal>true</literal>, builds will be + performed in a <emphasis>sandboxed environment</emphasis>, i.e., + they’re isolated from the normal file system hierarchy and will + only see their dependencies in the Nix store, the temporary build + directory, private versions of <filename>/proc</filename>, + <filename>/dev</filename>, <filename>/dev/shm</filename> and + <filename>/dev/pts</filename> (on Linux), and the paths configured with the + <link linkend="conf-sandbox-paths"><literal>sandbox-paths</literal> + option</link>. This is useful to prevent undeclared dependencies + on files in directories such as <filename>/usr/bin</filename>. In + addition, on Linux, builds run in private PID, mount, network, IPC + and UTS namespaces to isolate them from other processes in the + system (except that fixed-output derivations do not run in private + network namespace to ensure they can access the network).</para> + + <para>Currently, sandboxing only work on Linux and macOS. The use + of a sandbox requires that Nix is run as root (so you should use + the <link linkend="conf-build-users-group">“build users” + feature</link> to perform the actual builds under different users + than root).</para> + + <para>If this option is set to <literal>relaxed</literal>, then + fixed-output derivations and derivations that have the + <varname>__noChroot</varname> attribute set to + <literal>true</literal> do not run in sandboxes.</para> + + <para>The default is <literal>true</literal> on Linux and + <literal>false</literal> on all other platforms.</para> + + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-sandbox-dev-shm-size"><term><literal>sandbox-dev-shm-size</literal></term> + + <listitem><para>This option determines the maximum size of the + <literal>tmpfs</literal> filesystem mounted on + <filename>/dev/shm</filename> in Linux sandboxes. For the format, + see the description of the <option>size</option> option of + <literal>tmpfs</literal> in + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The + default is <literal>50%</literal>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="conf-sandbox-paths"> + <term><literal>sandbox-paths</literal></term> + + <listitem><para>A list of paths bind-mounted into Nix sandbox + environments. You can use the syntax + <literal><replaceable>target</replaceable>=<replaceable>source</replaceable></literal> + to mount a path in a different location in the sandbox; for + instance, <literal>/bin=/nix-bin</literal> will mount the path + <literal>/nix-bin</literal> as <literal>/bin</literal> inside the + sandbox. If <replaceable>source</replaceable> is followed by + <literal>?</literal>, then it is not an error if + <replaceable>source</replaceable> does not exist; for example, + <literal>/dev/nvidiactl?</literal> specifies that + <filename>/dev/nvidiactl</filename> will only be mounted in the + sandbox if it exists in the host filesystem.</para> + + <para>Depending on how Nix was built, the default value for this option + may be empty or provide <filename>/bin/sh</filename> as a + bind-mount of <command>bash</command>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="conf-secret-key-files"><term><literal>secret-key-files</literal></term> + + <listitem><para>A whitespace-separated list of files containing + secret (private) keys. These are used to sign locally-built + paths. They can be generated using <command>nix-store + --generate-binary-cache-key</command>. The corresponding public + key can be distributed to other users, who can add it to + <option>trusted-public-keys</option> in their + <filename>nix.conf</filename>.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="conf-show-trace"><term><literal>show-trace</literal></term> + + <listitem><para>Causes Nix to print out a stack trace in case of Nix + expression evaluation errors.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="conf-substitute"><term><literal>substitute</literal></term> + + <listitem><para>If set to <literal>true</literal> (default), Nix + will use binary substitutes if available. This option can be + disabled to force building from source.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="conf-stalled-download-timeout"><term><literal>stalled-download-timeout</literal></term> + <listitem> + <para>The timeout (in seconds) for receiving data from servers + during download. Nix cancels idle downloads after this timeout's + duration.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="conf-substituters"><term><literal>substituters</literal></term> + + <listitem><para>A list of URLs of substituters, separated by + whitespace. The default is + <literal>https://cache.nixos.org</literal>.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="conf-system"><term><literal>system</literal></term> + + <listitem><para>This option specifies the canonical Nix system + name of the current installation, such as + <literal>i686-linux</literal> or + <literal>x86_64-darwin</literal>. Nix can only build derivations + whose <literal>system</literal> attribute equals the value + specified here. In general, it never makes sense to modify this + value from its default, since you can use it to ‘lie’ about the + platform you are building on (e.g., perform a Mac OS build on a + Linux machine; the result would obviously be wrong). It only + makes sense if the Nix binaries can run on multiple platforms, + e.g., ‘universal binaries’ that run on <literal>x86_64-linux</literal> and + <literal>i686-linux</literal>.</para> + + <para>It defaults to the canonical Nix system name detected by + <filename>configure</filename> at build time.</para></listitem> + + </varlistentry> + + + <varlistentry xml:id="conf-system-features"><term><literal>system-features</literal></term> + + <listitem><para>A set of system “features” supported by this + machine, e.g. <literal>kvm</literal>. Derivations can express a + dependency on such features through the derivation attribute + <varname>requiredSystemFeatures</varname>. For example, the + attribute + +<programlisting> +requiredSystemFeatures = [ "kvm" ]; +</programlisting> + + ensures that the derivation can only be built on a machine with + the <literal>kvm</literal> feature.</para> + + <para>This setting by default includes <literal>kvm</literal> if + <filename>/dev/kvm</filename> is accessible, and the + pseudo-features <literal>nixos-test</literal>, + <literal>benchmark</literal> and <literal>big-parallel</literal> + that are used in Nixpkgs to route builds to specific + machines.</para> + + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-tarball-ttl"><term><literal>tarball-ttl</literal></term> + + <listitem> + <para>Default: <literal>3600</literal> seconds.</para> + + <para>The number of seconds a downloaded tarball is considered + fresh. If the cached tarball is stale, Nix will check whether + it is still up to date using the ETag header. Nix will download + a new version if the ETag header is unsupported, or the + cached ETag doesn't match. + </para> + + <para>Setting the TTL to <literal>0</literal> forces Nix to always + check if the tarball is up to date.</para> + + <para>Nix caches tarballs in + <filename>$XDG_CACHE_HOME/nix/tarballs</filename>.</para> + + <para>Files fetched via <envar>NIX_PATH</envar>, + <function>fetchGit</function>, <function>fetchMercurial</function>, + <function>fetchTarball</function>, and <function>fetchurl</function> + respect this TTL. + </para> + </listitem> + </varlistentry> + + <varlistentry xml:id="conf-timeout"><term><literal>timeout</literal></term> + + <listitem> + + <para>This option defines the maximum number of seconds that a + builder can run. This is useful (for instance in an automated + build system) to catch builds that are stuck in an infinite loop + but keep writing to their standard output or standard error. It + can be overridden using the <option linkend="opt-timeout">--timeout</option> command line + switch.</para> + + <para>The value <literal>0</literal> means that there is no + timeout. This is also the default.</para> + + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-trace-function-calls"><term><literal>trace-function-calls</literal></term> + + <listitem> + + <para>Default: <literal>false</literal>.</para> + + <para>If set to <literal>true</literal>, the Nix evaluator will + trace every function call. Nix will print a log message at the + "vomit" level for every function entrance and function exit.</para> + + <informalexample><screen> +function-trace entered undefined position at 1565795816999559622 +function-trace exited undefined position at 1565795816999581277 +function-trace entered /nix/store/.../example.nix:226:41 at 1565795253249935150 +function-trace exited /nix/store/.../example.nix:226:41 at 1565795253249941684 +</screen></informalexample> + + <para>The <literal>undefined position</literal> means the function + call is a builtin.</para> + + <para>Use the <literal>contrib/stack-collapse.py</literal> script + distributed with the Nix source code to convert the trace logs + in to a format suitable for <command>flamegraph.pl</command>.</para> + + </listitem> + + </varlistentry> + + <varlistentry xml:id="conf-trusted-public-keys"><term><literal>trusted-public-keys</literal></term> + + <listitem><para>A whitespace-separated list of public keys. When + paths are copied from another Nix store (such as a binary cache), + they must be signed with one of these keys. For example: + <literal>cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= + hydra.nixos.org-1:CNHJZBh9K4tP3EKF6FkkgeVYsS3ohTl+oS0Qa8bezVs=</literal>.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="conf-trusted-substituters"><term><literal>trusted-substituters</literal></term> + + <listitem><para>A list of URLs of substituters, separated by + whitespace. These are not used by default, but can be enabled by + users of the Nix daemon by specifying <literal>--option + substituters <replaceable>urls</replaceable></literal> on the + command line. Unprivileged users are only allowed to pass a + subset of the URLs listed in <literal>substituters</literal> and + <literal>trusted-substituters</literal>.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="conf-trusted-users"><term><literal>trusted-users</literal></term> + + <listitem> + + <para>A list of names of users (separated by whitespace) that + have additional rights when connecting to the Nix daemon, such + as the ability to specify additional binary caches, or to import + unsigned NARs. You can also specify groups by prefixing them + with <literal>@</literal>; for instance, + <literal>@wheel</literal> means all users in the + <literal>wheel</literal> group. The default is + <literal>root</literal>.</para> + + <warning><para>Adding a user to <option>trusted-users</option> + is essentially equivalent to giving that user root access to the + system. For example, the user can set + <option>sandbox-paths</option> and thereby obtain read access to + directories that are otherwise inacessible to + them.</para></warning> + + </listitem> + + </varlistentry> + +</variablelist> +</para> + +<refsection> + <title>Deprecated Settings</title> + +<para> + +<variablelist> + + <varlistentry xml:id="conf-binary-caches"> + <term><literal>binary-caches</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>binary-caches</literal> is now an alias to + <xref linkend="conf-substituters"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-binary-cache-public-keys"> + <term><literal>binary-cache-public-keys</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>binary-cache-public-keys</literal> is now an alias to + <xref linkend="conf-trusted-public-keys"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-compress-log"> + <term><literal>build-compress-log</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-compress-log</literal> is now an alias to + <xref linkend="conf-compress-build-log"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-cores"> + <term><literal>build-cores</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-cores</literal> is now an alias to + <xref linkend="conf-cores"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-extra-chroot-dirs"> + <term><literal>build-extra-chroot-dirs</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-extra-chroot-dirs</literal> is now an alias to + <xref linkend="conf-extra-sandbox-paths"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-extra-sandbox-paths"> + <term><literal>build-extra-sandbox-paths</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-extra-sandbox-paths</literal> is now an alias to + <xref linkend="conf-extra-sandbox-paths"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-fallback"> + <term><literal>build-fallback</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-fallback</literal> is now an alias to + <xref linkend="conf-fallback"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-max-jobs"> + <term><literal>build-max-jobs</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-max-jobs</literal> is now an alias to + <xref linkend="conf-max-jobs"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-max-log-size"> + <term><literal>build-max-log-size</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-max-log-size</literal> is now an alias to + <xref linkend="conf-max-build-log-size"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-max-silent-time"> + <term><literal>build-max-silent-time</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-max-silent-time</literal> is now an alias to + <xref linkend="conf-max-silent-time"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-repeat"> + <term><literal>build-repeat</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-repeat</literal> is now an alias to + <xref linkend="conf-repeat"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-timeout"> + <term><literal>build-timeout</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-timeout</literal> is now an alias to + <xref linkend="conf-timeout"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-use-chroot"> + <term><literal>build-use-chroot</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-use-chroot</literal> is now an alias to + <xref linkend="conf-sandbox"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-use-sandbox"> + <term><literal>build-use-sandbox</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-use-sandbox</literal> is now an alias to + <xref linkend="conf-sandbox"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-build-use-substitutes"> + <term><literal>build-use-substitutes</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>build-use-substitutes</literal> is now an alias to + <xref linkend="conf-substitute"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-gc-keep-derivations"> + <term><literal>gc-keep-derivations</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>gc-keep-derivations</literal> is now an alias to + <xref linkend="conf-keep-derivations"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-gc-keep-outputs"> + <term><literal>gc-keep-outputs</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>gc-keep-outputs</literal> is now an alias to + <xref linkend="conf-keep-outputs"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-env-keep-derivations"> + <term><literal>env-keep-derivations</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>env-keep-derivations</literal> is now an alias to + <xref linkend="conf-keep-env-derivations"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-extra-binary-caches"> + <term><literal>extra-binary-caches</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>extra-binary-caches</literal> is now an alias to + <xref linkend="conf-extra-substituters"/>.</para></listitem> + </varlistentry> + + <varlistentry xml:id="conf-trusted-binary-caches"> + <term><literal>trusted-binary-caches</literal></term> + + <listitem><para><emphasis>Deprecated:</emphasis> + <literal>trusted-binary-caches</literal> is now an alias to + <xref linkend="conf-trusted-substituters"/>.</para></listitem> + </varlistentry> +</variablelist> +</para> +</refsection> + +</refsection> + +</refentry> + +</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 “reachable” from that store + path; that is, it’s the closure of the path under the <link linkend="gloss-reference">references</link> relation. For a package, the + closure of its derivation is equivalent to the build-time + dependencies, while the closure of its output path is equivalent to its + runtime dependencies. For correct deployment it is necessary to deploy whole + closures, since otherwise at runtime files could be missing. The command + <command>nix-store -qR</command> prints out closures of store paths. + </para> + <para>As an example, if the store object at path <varname>P</varname> contains + a reference to path <varname>Q</varname>, then <varname>Q</varname> is + in the closure of <varname>P</varname>. Further, if <varname>Q</varname> + references <varname>R</varname> then <varname>R</varname> is also in + the closure of <varname>P</varname>. + </para></glossdef> + +</glossentry> + + +<glossentry xml:id="gloss-output-path"><glossterm>output path</glossterm> + + <glossdef><para>A store path produced by a derivation.</para></glossdef> + +</glossentry> + + +<glossentry xml:id="gloss-deriver"><glossterm>deriver</glossterm> + + <glossdef><para>The deriver of an <link linkend="gloss-output-path">output path</link> is the store + derivation that built it.</para></glossdef> + +</glossentry> + + +<glossentry xml:id="gloss-validity"><glossterm>validity</glossterm> + + <glossdef><para>A store path is considered + <emphasis>valid</emphasis> if it exists in the file system, is + listed in the Nix database as being valid, and if all paths in its + closure are also valid.</para></glossdef> + +</glossentry> + + +<glossentry xml:id="gloss-user-env"><glossterm>user environment</glossterm> + + <glossdef><para>An automatically generated store object that + consists of a set of symlinks to “active” applications, i.e., other + store paths. These are generated automatically by <link linkend="sec-nix-env"><command>nix-env</command></link>. See <xref linkend="sec-profiles"/>.</para> + + </glossdef> + +</glossentry> + + +<glossentry xml:id="gloss-profile"><glossterm>profile</glossterm> + + <glossdef><para>A symlink to the current <link linkend="gloss-user-env">user environment</link> of a user, e.g., + <filename>/nix/var/nix/profiles/default</filename>.</para></glossdef> + +</glossentry> + + +<glossentry xml:id="gloss-nar"><glossterm>NAR</glossterm> + + <glossdef><para>A <emphasis>N</emphasis>ix + <emphasis>AR</emphasis>chive. This is a serialisation of a path in + the Nix store. It can contain regular files, directories and + symbolic links. NARs are generated and unpacked using + <command>nix-store --dump</command> and <command>nix-store + --restore</command>.</para></glossdef> + +</glossentry> + + + +</glosslist> + + +</appendix> + <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 <nix/fetchurl.nix> { + url = https://nixos.org/releases/nix/nix-2.1.3/nix-2.1.3.tar.xz; + hash = "sha256-XSLa0FjVyADWWhFfkZ2iKTjFDda6mMXjoYMXLRSYQKQ="; +}; +</programlisting> + + instead of + +<programlisting> +import <nix/fetchurl.nix> { + url = https://nixos.org/releases/nix/nix-2.1.3/nix-2.1.3.tar.xz; + sha256 = "5d22dad058d5c800d65a115f919da22938c50dd6ba98c5e3a183172d149840a4"; +}; +</programlisting> + + </para> + + <para>In fixed-output derivations, the + <varname>outputHashAlgo</varname> attribute is no longer mandatory + if <varname>outputHash</varname> specifies the hash.</para> + + <para><command>nix hash-file</command> and <command>nix + hash-path</command> now print hashes in SRI format by + default. They also use SHA-256 by default instead of SHA-512 + because that's what we use most of the time in Nixpkgs.</para> + </listitem> + + <listitem> + <para>Integers are now 64 bits on all platforms.</para> + </listitem> + + <listitem> + <para>The evaluator now prints profiling statistics (enabled via + the <envar>NIX_SHOW_STATS</envar> and + <envar>NIX_COUNT_CALLS</envar> environment variables) in JSON + format.</para> + </listitem> + + <listitem> + <para>The option <option>--xml</option> in <command>nix-store + --query</command> has been removed. Instead, there now is an + option <option>--graphml</option> to output the dependency graph + in GraphML format.</para> + </listitem> + + <listitem> + <para>All <filename>nix-*</filename> commands are now symlinks to + <filename>nix</filename>. This saves a bit of disk space.</para> + </listitem> + + <listitem> + <para><command>nix repl</command> now uses + <literal>libeditline</literal> or + <literal>libreadline</literal>.</para> + </listitem> + +</itemizedlist> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-2.1"> + +<title>Release 2.1 (2018-09-02)</title> + +<para>This is primarily a bug fix release. It also reduces memory +consumption in certain situations. In addition, it has the following +new features:</para> + +<itemizedlist> + + <listitem> + <para>The Nix installer will no longer default to the Multi-User + installation for macOS. You can still <link linkend="sect-multi-user-installation">instruct the installer to + run in multi-user mode</link>. + </para> + </listitem> + + <listitem> + <para>The Nix installer now supports performing a Multi-User + installation for Linux computers which are running systemd. You + can <link linkend="sect-multi-user-installation">select a Multi-User installation</link> by passing the + <option>--daemon</option> flag to the installer: <command>sh <(curl + https://nixos.org/nix/install) --daemon</command>. + </para> + + <para>The multi-user installer cannot handle systems with SELinux. + If your system has SELinux enabled, you can <link linkend="sect-single-user-installation">force the installer to run + in single-user mode</link>.</para> + </listitem> + + <listitem> + <para>New builtin functions: + <literal>builtins.bitAnd</literal>, + <literal>builtins.bitOr</literal>, + <literal>builtins.bitXor</literal>, + <literal>builtins.fromTOML</literal>, + <literal>builtins.concatMap</literal>, + <literal>builtins.mapAttrs</literal>. + </para> + </listitem> + + <listitem> + <para>The S3 binary cache store now supports uploading NARs larger + than 5 GiB.</para> + </listitem> + + <listitem> + <para>The S3 binary cache store now supports uploading to + S3-compatible services with the <literal>endpoint</literal> + option.</para> + </listitem> + + <listitem> + <para>The flag <option>--fallback</option> is no longer required + to recover from disappeared NARs in binary caches.</para> + </listitem> + + <listitem> + <para><command>nix-daemon</command> now respects + <option>--store</option>.</para> + </listitem> + + <listitem> + <para><command>nix run</command> now respects + <varname>nix-support/propagated-user-env-packages</varname>.</para> + </listitem> + +</itemizedlist> + +<para>This release has contributions from + +Adrien Devresse, +Aleksandr Pashkov, +Alexandre Esteves, +Amine Chikhaoui, +Andrew Dunham, +Asad Saeeduddin, +aszlig, +Ben Challenor, +Ben Gamari, +Benjamin Hipple, +Bogdan Seniuc, +Corey O'Connor, +Daiderd Jordan, +Daniel Peebles, +Daniel Poelzleithner, +Danylo Hlynskyi, +Dmitry Kalinkin, +Domen Kožar, +Doug Beardsley, +Eelco Dolstra, +Erik Arvstedt, +Félix Baylac-Jacqué, +Gleb Peregud, +Graham Christensen, +Guillaume Maudoux, +Ivan Kozik, +John Arnold, +Justin Humm, +Linus Heckemann, +Lorenzo Manacorda, +Matthew Justin Bauer, +Matthew O'Gorman, +Maximilian Bosch, +Michael Bishop, +Michael Fiano, +Michael Mercier, +Michael Raskin, +Michael Weiss, +Nicolas Dudebout, +Peter Simons, +Ryan Trinkle, +Samuel Dionne-Riel, +Sean Seefried, +Shea Levy, +Symphorien Gibol, +Tim Engler, +Tim Sears, +Tuomas Tynkkynen, +volth, +Will Dietz, +Yorick van Pelt and +zimbatm. +</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-2.0"> + +<title>Release 2.0 (2018-02-22)</title> + +<para>The following incompatible changes have been made:</para> + +<itemizedlist> + + <listitem> + <para>The manifest-based substituter mechanism + (<command>download-using-manifests</command>) has been <link xlink:href="https://github.com/NixOS/nix/commit/867967265b80946dfe1db72d40324b4f9af988ed">removed</link>. It + has been superseded by the binary cache substituter mechanism + since several years. As a result, the following programs have been + removed: + + <itemizedlist> + <listitem><para><command>nix-pull</command></para></listitem> + <listitem><para><command>nix-generate-patches</command></para></listitem> + <listitem><para><command>bsdiff</command></para></listitem> + <listitem><para><command>bspatch</command></para></listitem> + </itemizedlist> + </para> + </listitem> + + <listitem> + <para>The “copy from other stores” substituter mechanism + (<command>copy-from-other-stores</command> and the + <envar>NIX_OTHER_STORES</envar> environment variable) has been + removed. It was primarily used by the NixOS installer to copy + available paths from the installation medium. The replacement is + to use a chroot store as a substituter + (e.g. <literal>--substituters /mnt</literal>), or to build into a + chroot store (e.g. <literal>--store /mnt --substituters /</literal>).</para> + </listitem> + + <listitem> + <para>The command <command>nix-push</command> has been removed as + part of the effort to eliminate Nix's dependency on Perl. You can + use <command>nix copy</command> instead, e.g. <literal>nix copy + --to file:///tmp/my-binary-cache <replaceable>paths…</replaceable></literal></para> + </listitem> + + <listitem> + <para>The “nested” log output feature (<option>--log-type + pretty</option>) has been removed. As a result, + <command>nix-log2xml</command> was also removed.</para> + </listitem> + + <listitem> + <para>OpenSSL-based signing has been <link xlink:href="https://github.com/NixOS/nix/commit/f435f8247553656774dd1b2c88e9de5d59cab203">removed</link>. This + feature was never well-supported. A better alternative is provided + by the <option>secret-key-files</option> and + <option>trusted-public-keys</option> options.</para> + </listitem> + + <listitem> + <para>Failed build caching has been <link xlink:href="https://github.com/NixOS/nix/commit/8cffec84859cec8b610a2a22ab0c4d462a9351ff">removed</link>. This + feature was introduced to support the Hydra continuous build + system, but Hydra no longer uses it.</para> + </listitem> + + <listitem> + <para><filename>nix-mode.el</filename> has been removed from + Nix. It is now <link xlink:href="https://github.com/NixOS/nix-mode">a separate + repository</link> and can be installed through the MELPA package + repository.</para> + </listitem> + +</itemizedlist> + +<para>This release has the following new features:</para> + +<itemizedlist> + + <listitem> + <para>It introduces a new command named <command>nix</command>, + which is intended to eventually replace all + <command>nix-*</command> commands with a more consistent and + better designed user interface. It currently provides replacements + for some (but not all) of the functionality provided by + <command>nix-store</command>, <command>nix-build</command>, + <command>nix-shell -p</command>, <command>nix-env -qa</command>, + <command>nix-instantiate --eval</command>, + <command>nix-push</command> and + <command>nix-copy-closure</command>. It has the following major + features:</para> + + <itemizedlist> + + <listitem> + <para>Unlike the legacy commands, it has a consistent way to + refer to packages and package-like arguments (like store + paths). For example, the following commands all copy the GNU + Hello package to a remote machine: + + <screen>nix copy --to ssh://machine nixpkgs.hello</screen> + <screen>nix copy --to ssh://machine /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10</screen> + <screen>nix copy --to ssh://machine '(with import <nixpkgs> {}; hello)'</screen> + + By contrast, <command>nix-copy-closure</command> only accepted + store paths as arguments.</para> + </listitem> + + <listitem> + <para>It is self-documenting: <option>--help</option> shows + all available command-line arguments. If + <option>--help</option> is given after a subcommand, it shows + examples for that subcommand. <command>nix + --help-config</command> shows all configuration + options.</para> + </listitem> + + <listitem> + <para>It is much less verbose. By default, it displays a + single-line progress indicator that shows how many packages + are left to be built or downloaded, and (if there are running + builds) the most recent line of builder output. If a build + fails, it shows the last few lines of builder output. The full + build log can be retrieved using <command>nix + log</command>.</para> + </listitem> + + <listitem> + <para>It <link xlink:href="https://github.com/NixOS/nix/commit/b8283773bd64d7da6859ed520ee19867742a03ba">provides</link> + all <filename>nix.conf</filename> configuration options as + command line flags. For example, instead of <literal>--option + http-connections 100</literal> you can write + <literal>--http-connections 100</literal>. Boolean options can + be written as + <literal>--<replaceable>foo</replaceable></literal> or + <literal>--no-<replaceable>foo</replaceable></literal> + (e.g. <option>--no-auto-optimise-store</option>).</para> + </listitem> + + <listitem> + <para>Many subcommands have a <option>--json</option> flag to + write results to stdout in JSON format.</para> + </listitem> + + </itemizedlist> + + <warning><para>Please note that the <command>nix</command> command + is a work in progress and the interface is subject to + change.</para></warning> + + <para>It provides the following high-level (“porcelain”) + subcommands:</para> + + <itemizedlist> + + <listitem> + <para><command>nix build</command> is a replacement for + <command>nix-build</command>.</para> + </listitem> + + <listitem> + <para><command>nix run</command> executes a command in an + environment in which the specified packages are available. It + is (roughly) a replacement for <command>nix-shell + -p</command>. Unlike that command, it does not execute the + command in a shell, and has a flag (<command>-c</command>) + that specifies the unquoted command line to be + executed.</para> + + <para>It is particularly useful in conjunction with chroot + stores, allowing Linux users who do not have permission to + install Nix in <command>/nix/store</command> to still use + binary substitutes that assume + <command>/nix/store</command>. For example, + + <screen>nix run --store ~/my-nix nixpkgs.hello -c hello --greeting 'Hi everybody!'</screen> + + downloads (or if not substitutes are available, builds) the + GNU Hello package into + <filename>~/my-nix/nix/store</filename>, then runs + <command>hello</command> in a mount namespace where + <filename>~/my-nix/nix/store</filename> is mounted onto + <command>/nix/store</command>.</para> + </listitem> + + <listitem> + <para><command>nix search</command> replaces <command>nix-env + -qa</command>. It searches the available packages for + occurrences of a search string in the attribute name, package + name or description. Unlike <command>nix-env -qa</command>, it + has a cache to speed up subsequent searches.</para> + </listitem> + + <listitem> + <para><command>nix copy</command> copies paths between + arbitrary Nix stores, generalising + <command>nix-copy-closure</command> and + <command>nix-push</command>.</para> + </listitem> + + <listitem> + <para><command>nix repl</command> replaces the external + program <command>nix-repl</command>. It provides an + interactive environment for evaluating and building Nix + expressions. Note that it uses <literal>linenoise-ng</literal> + instead of GNU Readline.</para> + </listitem> + + <listitem> + <para><command>nix upgrade-nix</command> upgrades Nix to the + latest stable version. This requires that Nix is installed in + a profile. (Thus it won’t work on NixOS, or if it’s installed + outside of the Nix store.)</para> + </listitem> + + <listitem> + <para><command>nix verify</command> checks whether store paths + are unmodified and/or “trusted” (see below). It replaces + <command>nix-store --verify</command> and <command>nix-store + --verify-path</command>.</para> + </listitem> + + <listitem> + <para><command>nix log</command> shows the build log of a + package or path. If the build log is not available locally, it + will try to obtain it from the configured substituters (such + as <uri>cache.nixos.org</uri>, which now provides build + logs).</para> + </listitem> + + <listitem> + <para><command>nix edit</command> opens the source code of a + package in your editor.</para> + </listitem> + + <listitem> + <para><command>nix eval</command> replaces + <command>nix-instantiate --eval</command>.</para> + </listitem> + + <listitem> + <para><command xlink:href="https://github.com/NixOS/nix/commit/d41c5eb13f4f3a37d80dbc6d3888644170c3b44a">nix + why-depends</command> shows why one store path has another in + its closure. This is primarily useful to finding the causes of + closure bloat. For example, + + <screen>nix why-depends nixpkgs.vlc nixpkgs.libdrm.dev</screen> + + shows a chain of files and fragments of file contents that + cause the VLC package to have the “dev” output of + <literal>libdrm</literal> in its closure — an undesirable + situation.</para> + </listitem> + + <listitem> + <para><command>nix path-info</command> shows information about + store paths, replacing <command>nix-store -q</command>. A + useful feature is the option <option>--closure-size</option> + (<option>-S</option>). For example, the following command show + the closure sizes of every path in the current NixOS system + closure, sorted by size: + + <screen>nix path-info -rS /run/current-system | sort -nk2</screen> + + </para> + </listitem> + + <listitem> + <para><command>nix optimise-store</command> replaces + <command>nix-store --optimise</command>. The main difference + is that it has a progress indicator.</para> + </listitem> + + </itemizedlist> + + <para>A number of low-level (“plumbing”) commands are also + available:</para> + + <itemizedlist> + + <listitem> + <para><command>nix ls-store</command> and <command>nix + ls-nar</command> list the contents of a store path or NAR + file. The former is primarily useful in conjunction with + remote stores, e.g. + + <screen>nix ls-store --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10</screen> + + lists the contents of path in a binary cache.</para> + </listitem> + + <listitem> + <para><command>nix cat-store</command> and <command>nix + cat-nar</command> allow extracting a file from a store path or + NAR file.</para> + </listitem> + + <listitem> + <para><command>nix dump-path</command> writes the contents of + a store path to stdout in NAR format. This replaces + <command>nix-store --dump</command>.</para> + </listitem> + + <listitem> + <para><command xlink:href="https://github.com/NixOS/nix/commit/e8d6ee7c1b90a2fe6d824f1a875acc56799ae6e2">nix + show-derivation</command> displays a store derivation in JSON + format. This is an alternative to + <command>pp-aterm</command>.</para> + </listitem> + + <listitem> + <para><command xlink:href="https://github.com/NixOS/nix/commit/970366266b8df712f5f9cedb45af183ef5a8357f">nix + add-to-store</command> replaces <command>nix-store + --add</command>.</para> + </listitem> + + <listitem> + <para><command>nix sign-paths</command> signs store + paths.</para> + </listitem> + + <listitem> + <para><command>nix copy-sigs</command> copies signatures from + one store to another.</para> + </listitem> + + <listitem> + <para><command>nix show-config</command> shows all + configuration options and their current values.</para> + </listitem> + + </itemizedlist> + + </listitem> + + <listitem> + <para>The store abstraction that Nix has had for a long time to + support store access via the Nix daemon has been extended + significantly. In particular, substituters (which used to be + external programs such as + <command>download-from-binary-cache</command>) are now subclasses + of the abstract <classname>Store</classname> class. This allows + many Nix commands to operate on such store types. For example, + <command>nix path-info</command> shows information about paths in + your local Nix store, while <command>nix path-info --store + https://cache.nixos.org/</command> shows information about paths + in the specified binary cache. Similarly, + <command>nix-copy-closure</command>, <command>nix-push</command> + and substitution are all instances of the general notion of + copying paths between different kinds of Nix stores.</para> + + <para>Stores are specified using an URI-like syntax, + e.g. <uri>https://cache.nixos.org/</uri> or + <uri>ssh://machine</uri>. The following store types are supported: + + <itemizedlist> + + <listitem> + + <para><classname>LocalStore</classname> (stori URI + <literal>local</literal> or an absolute path) and the misnamed + <classname>RemoteStore</classname> (<literal>daemon</literal>) + provide access to a local Nix store, the latter via the Nix + daemon. You can use <literal>auto</literal> or the empty + string to auto-select a local or daemon store depending on + whether you have write permission to the Nix store. It is no + longer necessary to set the <envar>NIX_REMOTE</envar> + environment variable to use the Nix daemon.</para> + + <para>As noted above, <classname>LocalStore</classname> now + supports chroot builds, allowing the “physical” location of + the Nix store + (e.g. <filename>/home/alice/nix/store</filename>) to differ + from its “logical” location (typically + <filename>/nix/store</filename>). This allows non-root users + to use Nix while still getting the benefits from prebuilt + binaries from <uri>cache.nixos.org</uri>.</para> + + </listitem> + + <listitem> + + <para><classname>BinaryCacheStore</classname> is the abstract + superclass of all binary cache stores. It supports writing + build logs and NAR content listings in JSON format.</para> + + </listitem> + + <listitem> + + <para><classname>HttpBinaryCacheStore</classname> + (<literal>http://</literal>, <literal>https://</literal>) + supports binary caches via HTTP or HTTPS. If the server + supports <literal>PUT</literal> requests, it supports + uploading store paths via commands such as <command>nix + copy</command>.</para> + + </listitem> + + <listitem> + + <para><classname>LocalBinaryCacheStore</classname> + (<literal>file://</literal>) supports binary caches in the + local filesystem.</para> + + </listitem> + + <listitem> + + <para><classname>S3BinaryCacheStore</classname> + (<literal>s3://</literal>) supports binary caches stored in + Amazon S3, if enabled at compile time.</para> + + </listitem> + + <listitem> + + <para><classname>LegacySSHStore</classname> (<literal>ssh://</literal>) + is used to implement remote builds and + <command>nix-copy-closure</command>.</para> + + </listitem> + + <listitem> + + <para><classname>SSHStore</classname> + (<literal>ssh-ng://</literal>) supports arbitrary Nix + operations on a remote machine via the same protocol used by + <command>nix-daemon</command>.</para> + + </listitem> + + </itemizedlist> + + </para> + + </listitem> + + <listitem> + + <para>Security has been improved in various ways: + + <itemizedlist> + + <listitem> + <para>Nix now stores signatures for local store + paths. When paths are copied between stores (e.g., copied from + a binary cache to a local store), signatures are + propagated.</para> + + <para>Locally-built paths are signed automatically using the + secret keys specified by the <option>secret-key-files</option> + store option. Secret/public key pairs can be generated using + <command>nix-store + --generate-binary-cache-key</command>.</para> + + <para>In addition, locally-built store paths are marked as + “ultimately trusted”, but this bit is not propagated when + paths are copied between stores.</para> + </listitem> + + <listitem> + <para>Content-addressable store paths no longer require + signatures — they can be imported into a store by unprivileged + users even if they lack signatures.</para> + </listitem> + + <listitem> + <para>The command <command>nix verify</command> checks whether + the specified paths are trusted, i.e., have a certain number + of trusted signatures, are ultimately trusted, or are + content-addressed.</para> + </listitem> + + <listitem> + <para>Substitutions from binary caches <link xlink:href="https://github.com/NixOS/nix/commit/ecbc3fedd3d5bdc5a0e1a0a51b29062f2874ac8b">now</link> + require signatures by default. This was already the case on + NixOS.</para> + </listitem> + + <listitem> + <para>In Linux sandbox builds, we <link xlink:href="https://github.com/NixOS/nix/commit/eba840c8a13b465ace90172ff76a0db2899ab11b">now</link> + use <filename>/build</filename> instead of + <filename>/tmp</filename> as the temporary build + directory. This fixes potential security problems when a build + accidentally stores its <envar>TMPDIR</envar> in some + security-sensitive place, such as an RPATH.</para> + </listitem> + + </itemizedlist> + + </para> + + </listitem> + + <listitem> + <para><emphasis>Pure evaluation mode</emphasis>. With the + <literal>--pure-eval</literal> flag, Nix enables a variant of the existing + restricted evaluation mode that forbids access to anything that could cause + different evaluations of the same command line arguments to produce a + different result. This includes builtin functions such as + <function>builtins.getEnv</function>, but more importantly, + <emphasis>all</emphasis> filesystem or network access unless a content hash + or commit hash is specified. For example, calls to + <function>builtins.fetchGit</function> are only allowed if a + <varname>rev</varname> attribute is specified.</para> + + <para>The goal of this feature is to enable true reproducibility + and traceability of builds (including NixOS system configurations) + at the evaluation level. For example, in the future, + <command>nixos-rebuild</command> might build configurations from a + Nix expression in a Git repository in pure mode. That expression + might fetch other repositories such as Nixpkgs via + <function>builtins.fetchGit</function>. The commit hash of the + top-level repository then uniquely identifies a running system, + and, in conjunction with that repository, allows it to be + reproduced or modified.</para> + + </listitem> + + <listitem> + <para>There are several new features to support binary + reproducibility (i.e. to help ensure that multiple builds of the + same derivation produce exactly the same output). When + <option>enforce-determinism</option> is set to + <literal>false</literal>, it’s <link xlink:href="https://github.com/NixOS/nix/commit/8bdf83f936adae6f2c907a6d2541e80d4120f051">no + longer</link> a fatal error if build rounds produce different + output. Also, a hook named <option>diff-hook</option> is <link xlink:href="https://github.com/NixOS/nix/commit/9a313469a4bdea2d1e8df24d16289dc2a172a169">provided</link> + to allow you to run tools such as <command>diffoscope</command> + when build rounds produce different output.</para> + </listitem> + + <listitem> + <para>Configuring remote builds is a lot easier now. Provided you + are not using the Nix daemon, you can now just specify a remote + build machine on the command line, e.g. <literal>--option builders + 'ssh://my-mac x86_64-darwin'</literal>. The environment variable + <envar>NIX_BUILD_HOOK</envar> has been removed and is no longer + needed. The environment variable <envar>NIX_REMOTE_SYSTEMS</envar> + is still supported for compatibility, but it is also possible to + specify builders in <command>nix.conf</command> by setting the + option <literal>builders = + @<replaceable>path</replaceable></literal>.</para> + </listitem> + + <listitem> + <para>If a fixed-output derivation produces a result with an + incorrect hash, the output path is moved to the location + corresponding to the actual hash and registered as valid. Thus, a + subsequent build of the fixed-output derivation with the correct + hash is unnecessary.</para> + </listitem> + + <listitem> + <para><command>nix-shell</command> <link xlink:href="https://github.com/NixOS/nix/commit/ea59f39326c8e9dc42dfed4bcbf597fbce58797c">now</link> + sets the <varname>IN_NIX_SHELL</varname> environment variable + during evaluation and in the shell itself. This can be used to + perform different actions depending on whether you’re in a Nix + shell or in a regular build. Nixpkgs provides + <varname>lib.inNixShell</varname> to check this variable during + evaluation.</para> + </listitem> + + <listitem> + <para><envar>NIX_PATH</envar> is now lazy, so URIs in the path are + only downloaded if they are needed for evaluation.</para> + </listitem> + + <listitem> + <para>You can now use + <uri>channel:<replaceable>channel-name</replaceable></uri> as a + short-hand for + <uri>https://nixos.org/channels/<replaceable>channel-name</replaceable>/nixexprs.tar.xz</uri>. For + example, <literal>nix-build channel:nixos-15.09 -A hello</literal> + will build the GNU Hello package from the + <literal>nixos-15.09</literal> channel. In the future, this may + use Git to fetch updates more efficiently.</para> + </listitem> + + <listitem> + <para>When <option>--no-build-output</option> is given, the last + 10 lines of the build log will be shown if a build + fails.</para> + </listitem> + + <listitem> + <para>Networking has been improved: + + <itemizedlist> + + <listitem> + <para>HTTP/2 is now supported. This makes binary cache lookups + <link xlink:href="https://github.com/NixOS/nix/commit/90ad02bf626b885a5dd8967894e2eafc953bdf92">much + more efficient</link>.</para> + </listitem> + + <listitem> + <para>We now retry downloads on many HTTP errors, making + binary caches substituters more resilient to temporary + failures.</para> + </listitem> + + <listitem> + <para>HTTP credentials can now be configured via the standard + <filename>netrc</filename> mechanism.</para> + </listitem> + + <listitem> + <para>If S3 support is enabled at compile time, + <uri>s3://</uri> URIs are <link xlink:href="https://github.com/NixOS/nix/commit/9ff9c3f2f80ba4108e9c945bbfda2c64735f987b">supported</link> + in all places where Nix allows URIs.</para> + </listitem> + + <listitem> + <para>Brotli compression is now supported. In particular, + <uri>cache.nixos.org</uri> build logs are now compressed using + Brotli.</para> + </listitem> + + </itemizedlist> + + </para> + + </listitem> + + <listitem> + <para><command>nix-env</command> <link xlink:href="https://github.com/NixOS/nix/commit/b0cb11722626e906a73f10dd9a0c9eea29faf43a">now</link> + ignores packages with bad derivation names (in particular those + starting with a digit or containing a dot).</para> + </listitem> + + <listitem> + <para>Many configuration options have been renamed, either because + they were unnecessarily verbose + (e.g. <option>build-use-sandbox</option> is now just + <option>sandbox</option>) or to reflect generalised behaviour + (e.g. <option>binary-caches</option> is now + <option>substituters</option> because it allows arbitrary store + URIs). The old names are still supported for compatibility.</para> + </listitem> + + <listitem> + <para>The <option>max-jobs</option> option can <link xlink:href="https://github.com/NixOS/nix/commit/7251d048fa812d2551b7003bc9f13a8f5d4c95a5">now</link> + be set to <literal>auto</literal> to use the number of CPUs in the + system.</para> + </listitem> + + <listitem> + <para>Hashes can <link xlink:href="https://github.com/NixOS/nix/commit/c0015e87af70f539f24d2aa2bc224a9d8b84276b">now</link> + be specified in base-64 format, in addition to base-16 and the + non-standard base-32.</para> + </listitem> + + <listitem> + <para><command>nix-shell</command> now uses + <varname>bashInteractive</varname> from Nixpkgs, rather than the + <command>bash</command> command that happens to be in the caller’s + <envar>PATH</envar>. This is especially important on macOS where + the <command>bash</command> provided by the system is seriously + outdated and cannot execute <literal>stdenv</literal>’s setup + script.</para> + </listitem> + + <listitem> + <para>Nix can now automatically trigger a garbage collection if + free disk space drops below a certain level during a build. This + is configured using the <option>min-free</option> and + <option>max-free</option> options.</para> + </listitem> + + <listitem> + <para><command>nix-store -q --roots</command> and + <command>nix-store --gc --print-roots</command> now show temporary + and in-memory roots.</para> + </listitem> + + <listitem> + <para> + Nix can now be extended with plugins. See the documentation of + the <option>plugin-files</option> option for more details. + </para> + </listitem> + +</itemizedlist> + +<para>The Nix language has the following new features: + +<itemizedlist> + + <listitem> + <para>It supports floating point numbers. They are based on the + C++ <literal>float</literal> type and are supported by the + existing numerical operators. Export and import to and from JSON + and XML works, too.</para> + </listitem> + + <listitem> + <para>Derivation attributes can now reference the outputs of the + derivation using the <function>placeholder</function> builtin + function. For example, the attribute + +<programlisting> +configureFlags = "--prefix=${placeholder "out"} --includedir=${placeholder "dev"}"; +</programlisting> + + will cause the <envar>configureFlags</envar> environment variable + to contain the actual store paths corresponding to the + <literal>out</literal> and <literal>dev</literal> outputs.</para> + </listitem> + +</itemizedlist> + +</para> + +<para>The following builtin functions are new or extended: + +<itemizedlist> + + <listitem> + <para><function xlink:href="https://github.com/NixOS/nix/commit/38539b943a060d9cdfc24d6e5d997c0885b8aa2f">builtins.fetchGit</function> + allows Git repositories to be fetched at evaluation time. Thus it + differs from the <function>fetchgit</function> function in + Nixpkgs, which fetches at build time and cannot be used to fetch + Nix expressions during evaluation. A typical use case is to import + external NixOS modules from your configuration, e.g. + + <programlisting>imports = [ (builtins.fetchGit https://github.com/edolstra/dwarffs + "/module.nix") ];</programlisting> + + </para> + </listitem> + + <listitem> + <para>Similarly, <function>builtins.fetchMercurial</function> + allows you to fetch Mercurial repositories.</para> + </listitem> + + <listitem> + <para><function>builtins.path</function> generalises + <function>builtins.filterSource</function> and path literals + (e.g. <literal>./foo</literal>). It allows specifying a store path + name that differs from the source path name + (e.g. <literal>builtins.path { path = ./foo; name = "bar"; + }</literal>) and also supports filtering out unwanted + files.</para> + </listitem> + + <listitem> + <para><function>builtins.fetchurl</function> and + <function>builtins.fetchTarball</function> now support + <varname>sha256</varname> and <varname>name</varname> + attributes.</para> + </listitem> + + <listitem> + <para><function xlink:href="https://github.com/NixOS/nix/commit/b8867a0239b1930a16f9ef3f7f3e864b01416dff">builtins.split</function> + splits a string using a POSIX extended regular expression as the + separator.</para> + </listitem> + + <listitem> + <para><function xlink:href="https://github.com/NixOS/nix/commit/26d92017d3b36cff940dcb7d1611c42232edb81a">builtins.partition</function> + partitions the elements of a list into two lists, depending on a + Boolean predicate.</para> + </listitem> + + <listitem> + <para><literal><nix/fetchurl.nix></literal> now uses the + content-addressable tarball cache at + <uri>http://tarballs.nixos.org/</uri>, just like + <function>fetchurl</function> in + Nixpkgs. (f2682e6e18a76ecbfb8a12c17e3a0ca15c084197)</para> + </listitem> + + <listitem> + <para>In restricted and pure evaluation mode, builtin functions + that download from the network (such as + <function>fetchGit</function>) are permitted to fetch underneath a + list of URI prefixes specified in the option + <option>allowed-uris</option>.</para> + </listitem> + +</itemizedlist> + +</para> + +<para>The Nix build environment has the following changes: + +<itemizedlist> + + <listitem> + <para>Values such as Booleans, integers, (nested) lists and + attribute sets can <link xlink:href="https://github.com/NixOS/nix/commit/6de33a9c675b187437a2e1abbcb290981a89ecb1">now</link> + be passed to builders in a non-lossy way. If the special attribute + <varname>__structuredAttrs</varname> is set to + <literal>true</literal>, the other derivation attributes are + serialised in JSON format and made available to the builder via + the file <envar>.attrs.json</envar> in the builder’s temporary + directory. This obviates the need for + <varname>passAsFile</varname> since JSON files have no size + restrictions, unlike process environments.</para> + + <para><link xlink:href="https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699">As + a convenience to Bash builders</link>, Nix writes a script named + <envar>.attrs.sh</envar> to the builder’s directory that + initialises shell variables corresponding to all attributes that + are representable in Bash. This includes non-nested (associative) + arrays. For example, the attribute <literal>hardening.format = + true</literal> ends up as the Bash associative array element + <literal>${hardening[format]}</literal>.</para> + </listitem> + + <listitem> + <para>Builders can <link xlink:href="https://github.com/NixOS/nix/commit/88e6bb76de5564b3217be9688677d1c89101b2a3">now</link> + communicate what build phase they are in by writing messages to + the file descriptor specified in <envar>NIX_LOG_FD</envar>. The + current phase is shown by the <command>nix</command> progress + indicator. + </para> + </listitem> + + <listitem> + <para>In Linux sandbox builds, we <link xlink:href="https://github.com/NixOS/nix/commit/a2d92bb20e82a0957067ede60e91fab256948b41">now</link> + provide a default <filename>/bin/sh</filename> (namely + <filename>ash</filename> from BusyBox).</para> + </listitem> + + <listitem> + <para>In structured attribute mode, + <varname>exportReferencesGraph</varname> <link xlink:href="https://github.com/NixOS/nix/commit/c2b0d8749f7e77afc1c4b3e8dd36b7ee9720af4a">exports</link> + extended information about closures in JSON format. In particular, + it includes the sizes and hashes of paths. This is primarily + useful for NixOS image builders.</para> + </listitem> + + <listitem> + <para>Builds are <link xlink:href="https://github.com/NixOS/nix/commit/21948deed99a3295e4d5666e027a6ca42dc00b40">now</link> + killed as soon as Nix receives EOF on the builder’s stdout or + stderr. This fixes a bug that allowed builds to hang Nix + indefinitely, regardless of + timeouts.</para> + </listitem> + + <listitem> + <para>The <option>sandbox-paths</option> configuration + option can now specify optional paths by appending a + <literal>?</literal>, e.g. <literal>/dev/nvidiactl?</literal> will + bind-mount <varname>/dev/nvidiactl</varname> only if it + exists.</para> + </listitem> + + <listitem> + <para>On Linux, builds are now executed in a user + namespace with UID 1000 and GID 100.</para> + </listitem> + +</itemizedlist> + +</para> + +<para>A number of significant internal changes were made: + +<itemizedlist> + + <listitem> + <para>Nix no longer depends on Perl and all Perl components have + been rewritten in C++ or removed. The Perl bindings that used to + be part of Nix have been moved to a separate package, + <literal>nix-perl</literal>.</para> + </listitem> + + <listitem> + <para>All <classname>Store</classname> classes are now + thread-safe. <classname>RemoteStore</classname> supports multiple + concurrent connections to the daemon. This is primarily useful in + multi-threaded programs such as + <command>hydra-queue-runner</command>.</para> + </listitem> + +</itemizedlist> + +</para> + +<para>This release has contributions from + +Adrien Devresse, +Alexander Ried, +Alex Cruice, +Alexey Shmalko, +AmineChikhaoui, +Andy Wingo, +Aneesh Agrawal, +Anthony Cowley, +Armijn Hemel, +aszlig, +Ben Gamari, +Benjamin Hipple, +Benjamin Staffin, +Benno Fünfstück, +Bjørn Forsman, +Brian McKenna, +Charles Strahan, +Chase Adams, +Chris Martin, +Christian Theune, +Chris Warburton, +Daiderd Jordan, +Dan Connolly, +Daniel Peebles, +Dan Peebles, +davidak, +David McFarland, +Dmitry Kalinkin, +Domen Kožar, +Eelco Dolstra, +Emery Hemingway, +Eric Litak, +Eric Wolf, +Fabian Schmitthenner, +Frederik Rietdijk, +Gabriel Gonzalez, +Giorgio Gallo, +Graham Christensen, +Guillaume Maudoux, +Harmen, +Iavael, +James Broadhead, +James Earl Douglas, +Janus Troelsen, +Jeremy Shaw, +Joachim Schiele, +Joe Hermaszewski, +Joel Moberg, +Johannes 'fish' Ziemke, +Jörg Thalheim, +Jude Taylor, +kballou, +Keshav Kini, +Kjetil Orbekk, +Langston Barrett, +Linus Heckemann, +Ludovic Courtès, +Manav Rathi, +Marc Scholten, +Markus Hauck, +Matt Audesse, +Matthew Bauer, +Matthias Beyer, +Matthieu Coudron, +N1X, +Nathan Zadoks, +Neil Mayhew, +Nicolas B. Pierron, +Niklas Hambüchen, +Nikolay Amiantov, +Ole Jørgen Brønner, +Orivej Desh, +Peter Simons, +Peter Stuart, +Pyry Jahkola, +regnat, +Renzo Carbonara, +Rhys, +Robert Vollmert, +Scott Olson, +Scott R. Parish, +Sergei Trofimovich, +Shea Levy, +Sheena Artrip, +Spencer Baugh, +Stefan Junker, +Susan Potter, +Thomas Tuegel, +Timothy Allen, +Tristan Hume, +Tuomas Tynkkynen, +tv, +Tyson Whitehead, +Vladimír Čunát, +Will Dietz, +wmertens, +Wout Mertens, +zimbatm and +Zoran Plesivčak. +</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-1.11.10"> + +<title>Release 1.11.10 (2017-06-12)</title> + +<para>This release fixes a security bug in Nix’s “build user” build +isolation mechanism. Previously, Nix builders had the ability to +create setuid binaries owned by a <literal>nixbld</literal> +user. Such a binary could then be used by an attacker to assume a +<literal>nixbld</literal> identity and interfere with subsequent +builds running under the same UID.</para> + +<para>To prevent this issue, Nix now disallows builders to create +setuid and setgid binaries. On Linux, this is done using a seccomp BPF +filter. Note that this imposes a small performance penalty (e.g. 1% +when building GNU Hello). Using seccomp, we now also prevent the +creation of extended attributes and POSIX ACLs since these cannot be +represented in the NAR format and (in the case of POSIX ACLs) allow +bypassing regular Nix store permissions. On macOS, the restriction is +implemented using the existing sandbox mechanism, which now uses a +minimal “allow all except the creation of setuid/setgid binaries” +profile when regular sandboxing is disabled. On other platforms, the +“build user” mechanism is now disabled.</para> + +<para>Thanks go to Linus Heckemann for discovering and reporting this +bug.</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-1.11"> + +<title>Release 1.11 (2016-01-19)</title> + +<para>This is primarily a bug fix release. It also has a number of new +features:</para> + +<itemizedlist> + + <listitem> + <para><command>nix-prefetch-url</command> can now download URLs + specified in a Nix expression. For example, + +<screen> +$ nix-prefetch-url -A hello.src +</screen> + + will prefetch the file specified by the + <function>fetchurl</function> call in the attribute + <literal>hello.src</literal> from the Nix expression in the + current directory, and print the cryptographic hash of the + resulting file on stdout. This differs from <literal>nix-build -A + hello.src</literal> in that it doesn't verify the hash, and is + thus useful when you’re updating a Nix expression.</para> + + <para>You can also prefetch the result of functions that unpack a + tarball, such as <function>fetchFromGitHub</function>. For example: + +<screen> +$ nix-prefetch-url --unpack https://github.com/NixOS/patchelf/archive/0.8.tar.gz +</screen> + + or from a Nix expression: + +<screen> +$ nix-prefetch-url -A nix-repl.src +</screen> + + </para> + + </listitem> + + <listitem> + <para>The builtin function + <function><nix/fetchurl.nix></function> now supports + downloading and unpacking NARs. This removes the need to have + multiple downloads in the Nixpkgs stdenv bootstrap process (like a + separate busybox binary for Linux, or curl/mkdir/sh/bzip2 for + Darwin). Now all those files can be combined into a single NAR, + optionally compressed using <command>xz</command>.</para> + </listitem> + + <listitem> + <para>Nix now supports SHA-512 hashes for verifying fixed-output + derivations, and in <function>builtins.hashString</function>.</para> + </listitem> + + <listitem> + <para> + The new flag <option>--option build-repeat + <replaceable>N</replaceable></option> will cause every build to + be executed <replaceable>N</replaceable>+1 times. If the build + output differs between any round, the build is rejected, and the + output paths are not registered as valid. This is primarily + useful to verify build determinism. (We already had a + <option>--check</option> option to repeat a previously succeeded + build. However, with <option>--check</option>, non-deterministic + builds are registered in the DB. Preventing that is useful for + Hydra to ensure that non-deterministic builds don't end up + getting published to the binary cache.) + </para> + </listitem> + + <listitem> + <para> + The options <option>--check</option> and <option>--option + build-repeat <replaceable>N</replaceable></option>, if they + detect a difference between two runs of the same derivation and + <option>-K</option> is given, will make the output of the other + run available under + <filename><replaceable>store-path</replaceable>-check</filename>. This + makes it easier to investigate the non-determinism using tools + like <command>diffoscope</command>, e.g., + +<screen> +$ nix-build pkgs/stdenv/linux -A stage1.pkgs.zlib --check -K +error: derivation ‘/nix/store/l54i8wlw2265…-zlib-1.2.8.drv’ may not +be deterministic: output ‘/nix/store/11a27shh6n2i…-zlib-1.2.8’ +differs from ‘/nix/store/11a27shh6n2i…-zlib-1.2.8-check’ + +$ diffoscope /nix/store/11a27shh6n2i…-zlib-1.2.8 /nix/store/11a27shh6n2i…-zlib-1.2.8-check +… +├── lib/libz.a +│ ├── metadata +│ │ @@ -1,15 +1,15 @@ +│ │ -rw-r--r-- 30001/30000 3096 Jan 12 15:20 2016 adler32.o +… +│ │ +rw-r--r-- 30001/30000 3096 Jan 12 15:28 2016 adler32.o +… +</screen> + + </para></listitem> + + <listitem> + <para>Improved FreeBSD support.</para> + </listitem> + + <listitem> + <para><command>nix-env -qa --xml --meta</command> now prints + license information.</para> + </listitem> + + <listitem> + <para>The maximum number of parallel TCP connections that the + binary cache substituter will use has been decreased from 150 to + 25. This should prevent upsetting some broken NAT routers, and + also improves performance.</para> + </listitem> + + <listitem> + <para>All "chroot"-containing strings got renamed to "sandbox". + In particular, some Nix options got renamed, but the old names + are still accepted as lower-priority aliases. + </para> + </listitem> + +</itemizedlist> + +<para>This release has contributions from Anders Claesson, Anthony +Cowley, Bjørn Forsman, Brian McKenna, Danny Wilson, davidak, Eelco Dolstra, +Fabian Schmitthenner, FrankHB, Ilya Novoselov, janus, Jim Garrison, John +Ericson, Jude Taylor, Ludovic Courtès, Manuel Jacob, Mathnerd314, +Pascal Wittmann, Peter Simons, Philip Potter, Preston Bennes, Rommel +M. Martinez, Sander van der Burg, Shea Levy, Tim Cuthbertson, Tuomas +Tynkkynen, Utku Demir and Vladimír Čunát.</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-1.10"> + +<title>Release 1.10 (2015-09-03)</title> + +<para>This is primarily a bug fix release. It also has a number of new +features:</para> + +<itemizedlist> + + <listitem> + <para>A number of builtin functions have been added to reduce + Nixpkgs/NixOS evaluation time and memory consumption: + <function>all</function>, + <function>any</function>, + <function>concatStringsSep</function>, + <function>foldl’</function>, + <function>genList</function>, + <function>replaceStrings</function>, + <function>sort</function>. + </para> + </listitem> + + <listitem> + <para>The garbage collector is more robust when the disk is full.</para> + </listitem> + + <listitem> + <para>Nix supports a new API for building derivations that doesn’t + require a <literal>.drv</literal> file to be present on disk; it + only requires an in-memory representation of the derivation. This + is used by the Hydra continuous build system to make remote builds + more efficient.</para> + </listitem> + + <listitem> + <para>The function <literal><nix/fetchurl.nix></literal> now + uses a <emphasis>builtin</emphasis> builder (i.e. it doesn’t + require starting an external process; the download is performed by + Nix itself). This ensures that derivation paths don’t change when + Nix is upgraded, and obviates the need for ugly hacks to support + chroot execution.</para> + </listitem> + + <listitem> + <para><option>--version -v</option> now prints some configuration + information, in particular what compile-time optional features are + enabled, and the paths of various directories.</para> + </listitem> + + <listitem> + <para>Build users have their supplementary groups set correctly.</para> + </listitem> + +</itemizedlist> + +<para>This release has contributions from Eelco Dolstra, Guillaume +Maudoux, Iwan Aucamp, Jaka Hudoklin, Kirill Elagin, Ludovic Courtès, +Manolis Ragkousis, Nicolas B. Pierron and Shea Levy.</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-1.9"> + +<title>Release 1.9 (2015-06-12)</title> + +<para>In addition to the usual bug fixes, this release has the +following new features:</para> + +<itemizedlist> + + <listitem> + <para>Signed binary cache support. You can enable signature + checking by adding the following to <filename>nix.conf</filename>: + +<programlisting> +signed-binary-caches = * +binary-cache-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= +</programlisting> + + This will prevent Nix from downloading any binary from the cache + that is not signed by one of the keys listed in + <option>binary-cache-public-keys</option>.</para> + + <para>Signature checking is only supported if you built Nix with + the <literal>libsodium</literal> package.</para> + + <para>Note that while Nix has had experimental support for signed + binary caches since version 1.7, this release changes the + signature format in a backwards-incompatible way.</para> + + </listitem> + + <listitem> + + <para>Automatic downloading of Nix expression tarballs. In various + places, you can now specify the URL of a tarball containing Nix + expressions (such as Nixpkgs), which will be downloaded and + unpacked automatically. For example:</para> + + <itemizedlist> + + <listitem><para>In <command>nix-env</command>: + +<screen> +$ nix-env -f https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox +</screen> + + This installs Firefox from the latest tested and built revision + of the NixOS 14.12 channel.</para></listitem> + + <listitem><para>In <command>nix-build</command> and + <command>nix-shell</command>: + +<screen> +$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello +</screen> + + This builds GNU Hello from the latest revision of the Nixpkgs + master branch.</para></listitem> + + <listitem><para>In the Nix search path (as specified via + <envar>NIX_PATH</envar> or <option>-I</option>). For example, to + start a shell containing the Pan package from a specific version + of Nixpkgs: + +<screen> +$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz +</screen> + + </para></listitem> + + <listitem><para>In <command>nixos-rebuild</command> (on NixOS): + +<screen> +$ nixos-rebuild test -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-unstable.tar.gz +</screen> + + </para></listitem> + + <listitem><para>In Nix expressions, via the new builtin function <function>fetchTarball</function>: + +<programlisting> +with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {}; … +</programlisting> + + (This is not allowed in restricted mode.)</para></listitem> + + </itemizedlist> + + </listitem> + + <listitem> + + <para><command>nix-shell</command> improvements:</para> + + <itemizedlist> + + <listitem><para><command>nix-shell</command> now has a flag + <option>--run</option> to execute a command in the + <command>nix-shell</command> environment, + e.g. <literal>nix-shell --run make</literal>. This is like + the existing <option>--command</option> flag, except that it + uses a non-interactive shell (ensuring that hitting Ctrl-C won’t + drop you into the child shell).</para></listitem> + + <listitem><para><command>nix-shell</command> can now be used as + a <literal>#!</literal>-interpreter. This allows you to write + scripts that dynamically fetch their own dependencies. For + example, here is a Haskell script that, when invoked, first + downloads GHC and the Haskell packages on which it depends: + +<programlisting> +#! /usr/bin/env nix-shell +#! nix-shell -i runghc -p haskellPackages.ghc haskellPackages.HTTP + +import Network.HTTP + +main = do + resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/") + body <- getResponseBody resp + print (take 100 body) +</programlisting> + + Of course, the dependencies are cached in the Nix store, so the + second invocation of this script will be much + faster.</para></listitem> + + </itemizedlist> + + </listitem> + + <listitem> + + <para>Chroot improvements:</para> + + <itemizedlist> + + <listitem><para>Chroot builds are now supported on Mac OS X + (using its sandbox mechanism).</para></listitem> + + <listitem><para>If chroots are enabled, they are now used for + all derivations, including fixed-output derivations (such as + <function>fetchurl</function>). The latter do have network + access, but can no longer access the host filesystem. If you + need the old behaviour, you can set the option + <option>build-use-chroot</option> to + <literal>relaxed</literal>.</para></listitem> + + <listitem><para>On Linux, if chroots are enabled, builds are + performed in a private PID namespace once again. (This + functionality was lost in Nix 1.8.)</para></listitem> + + <listitem><para>Store paths listed in + <option>build-chroot-dirs</option> are now automatically + expanded to their closure. For instance, if you want + <filename>/nix/store/…-bash/bin/sh</filename> mounted in your + chroot as <filename>/bin/sh</filename>, you only need to say + <literal>build-chroot-dirs = + /bin/sh=/nix/store/…-bash/bin/sh</literal>; it is no longer + necessary to specify the dependencies of Bash.</para></listitem> + + </itemizedlist> + + </listitem> + + <listitem><para>The new derivation attribute + <varname>passAsFile</varname> allows you to specify that the + contents of derivation attributes should be passed via files rather + than environment variables. This is useful if you need to pass very + long strings that exceed the size limit of the environment. The + Nixpkgs function <function>writeTextFile</function> uses + this.</para></listitem> + + <listitem><para>You can now use <literal>~</literal> in Nix file + names to refer to your home directory, e.g. <literal>import + ~/.nixpkgs/config.nix</literal>.</para></listitem> + + <listitem><para>Nix has a new option <option>restrict-eval</option> + that allows limiting what paths the Nix evaluator has access to. By + passing <literal>--option restrict-eval true</literal> to Nix, the + evaluator will throw an exception if an attempt is made to access + any file outside of the Nix search path. This is primarily intended + for Hydra to ensure that a Hydra jobset only refers to its declared + inputs (and is therefore reproducible).</para></listitem> + + <listitem><para><command>nix-env</command> now only creates a new + “generation” symlink in <filename>/nix/var/nix/profiles</filename> + if something actually changed.</para></listitem> + + <listitem><para>The environment variable <envar>NIX_PAGER</envar> + can now be set to override <envar>PAGER</envar>. You can set it to + <literal>cat</literal> to disable paging for Nix commands + only.</para></listitem> + + <listitem><para>Failing <literal><...></literal> + lookups now show position information.</para></listitem> + + <listitem><para>Improved Boehm GC use: we disabled scanning for + interior pointers, which should reduce the “<literal>Repeated + allocation of very large block</literal>” warnings and associated + retention of memory.</para></listitem> + +</itemizedlist> + +<para>This release has contributions from aszlig, Benjamin Staffin, +Charles Strahan, Christian Theune, Daniel Hahler, Danylo Hlynskyi +Daniel Peebles, Dan Peebles, Domen Kožar, Eelco Dolstra, Harald van +Dijk, Hoang Xuan Phu, Jaka Hudoklin, Jeff Ramnani, j-keck, Linquize, +Luca Bruno, Michael Merickel, Oliver Dunkl, Rob Vermaas, Rok Garbas, +Shea Levy, Tobias Geerinckx-Rice and William A. Kennington III.</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-1.8"> + +<title>Release 1.8 (2014-12-14)</title> + +<itemizedlist> + + <listitem><para>Breaking change: to address a race condition, the + remote build hook mechanism now uses <command>nix-store + --serve</command> on the remote machine. This requires build slaves + to be updated to Nix 1.8.</para></listitem> + + <listitem><para>Nix now uses HTTPS instead of HTTP to access the + default binary cache, + <literal>cache.nixos.org</literal>.</para></listitem> + + <listitem><para><command>nix-env</command> selectors are now regular + expressions. For instance, you can do + +<screen> +$ nix-env -qa '.*zip.*' +</screen> + + to query all packages with a name containing + <literal>zip</literal>.</para></listitem> + + <listitem><para><command>nix-store --read-log</command> can now + fetch remote build logs. If a build log is not available locally, + then ‘nix-store -l’ will now try to download it from the servers + listed in the ‘log-servers’ option in nix.conf. For instance, if you + have the configuration option + +<programlisting> +log-servers = http://hydra.nixos.org/log +</programlisting> + +then it will try to get logs from +<literal>http://hydra.nixos.org/log/<replaceable>base name of the +store path</replaceable></literal>. This allows you to do things like: + +<screen> +$ nix-store -l $(which xterm) +</screen> + + and get a log even if <command>xterm</command> wasn't built + locally.</para></listitem> + + <listitem><para>New builtin functions: + <function>attrValues</function>, <function>deepSeq</function>, + <function>fromJSON</function>, <function>readDir</function>, + <function>seq</function>.</para></listitem> + + <listitem><para><command>nix-instantiate --eval</command> now has a + <option>--json</option> flag to print the resulting value in JSON + format.</para></listitem> + + <listitem><para><command>nix-copy-closure</command> now uses + <command>nix-store --serve</command> on the remote side to send or + receive closures. This fixes a race condition between + <command>nix-copy-closure</command> and the garbage + collector.</para></listitem> + + <listitem><para>Derivations can specify the new special attribute + <varname>allowedRequisites</varname>, which has a similar meaning to + <varname>allowedReferences</varname>. But instead of only enforcing + to explicitly specify the immediate references, it requires the + derivation to specify all the dependencies recursively (hence the + name, requisites) that are used by the resulting + output.</para></listitem> + + <listitem><para>On Mac OS X, Nix now handles case collisions when + importing closures from case-sensitive file systems. This is mostly + useful for running NixOps on Mac OS X.</para></listitem> + + <listitem><para>The Nix daemon has new configuration options + <option>allowed-users</option> (specifying the users and groups that + are allowed to connect to the daemon) and + <option>trusted-users</option> (specifying the users and groups that + can perform privileged operations like specifying untrusted binary + caches).</para></listitem> + + <listitem><para>The configuration option + <option>build-cores</option> now defaults to the number of available + CPU cores.</para></listitem> + + <listitem><para>Build users are now used by default when Nix is + invoked as root. This prevents builds from accidentally running as + root.</para></listitem> + + <listitem><para>Nix now includes systemd units and Upstart + jobs.</para></listitem> + + <listitem><para>Speed improvements to <command>nix-store + --optimise</command>.</para></listitem> + + <listitem><para>Language change: the <literal>==</literal> operator + now ignores string contexts (the “dependencies” of a + string).</para></listitem> + + <listitem><para>Nix now filters out Nix-specific ANSI escape + sequences on standard error. They are supposed to be invisible, but + some terminals show them anyway.</para></listitem> + + <listitem><para>Various commands now automatically pipe their output + into the pager as specified by the <envar>PAGER</envar> environment + variable.</para></listitem> + + <listitem><para>Several improvements to reduce memory consumption in + the evaluator.</para></listitem> + +</itemizedlist> + +<para>This release has contributions from Adam Szkoda, Aristid +Breitkreuz, Bob van der Linden, Charles Strahan, darealshinji, Eelco +Dolstra, Gergely Risko, Joel Taylor, Ludovic Courtès, Marko Durkovic, +Mikey Ariel, Paul Colomiets, Ricardo M. Correia, Ricky Elrod, Robert +Helgesson, Rob Vermaas, Russell O'Connor, Shea Levy, Shell Turner, +Sönke Hahn, Steve Purcell, Vladimír Čunát and Wout Mertens.</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-1.7"> + +<title>Release 1.7 (2014-04-11)</title> + +<para>In addition to the usual bug fixes, this release has the +following new features:</para> + +<itemizedlist> + + <listitem> + <para>Antiquotation is now allowed inside of quoted attribute + names (e.g. <literal>set."${foo}"</literal>). In the case where + the attribute name is just a single antiquotation, the quotes can + be dropped (e.g. the above example can be written + <literal>set.${foo}</literal>). If an attribute name inside of a + set declaration evaluates to <literal>null</literal> (e.g. + <literal>{ ${null} = false; }</literal>), then that attribute is + not added to the set.</para> + </listitem> + + <listitem> + <para>Experimental support for cryptographically signed binary + caches. See <link xlink:href="https://github.com/NixOS/nix/commit/0fdf4da0e979f992db75cc17376e455ddc5a96d8">the + commit for details</link>.</para> + </listitem> + + <listitem> + <para>An experimental new substituter, + <command>download-via-ssh</command>, that fetches binaries from + remote machines via SSH. Specifying the flags <literal>--option + use-ssh-substituter true --option ssh-substituter-hosts + <replaceable>user@hostname</replaceable></literal> will cause Nix + to download binaries from the specified machine, if it has + them.</para> + </listitem> + + <listitem> + <para><command>nix-store -r</command> and + <command>nix-build</command> have a new flag, + <option>--check</option>, that builds a previously built + derivation again, and prints an error message if the output is not + exactly the same. This helps to verify whether a derivation is + truly deterministic. For example: + +<screen> +$ nix-build '<nixpkgs>' -A patchelf +<replaceable>…</replaceable> +$ nix-build '<nixpkgs>' -A patchelf --check +<replaceable>…</replaceable> +error: derivation `/nix/store/1ipvxs…-patchelf-0.6' may not be deterministic: + hash mismatch in output `/nix/store/4pc1dm…-patchelf-0.6.drv' +</screen> + + </para> + + </listitem> + + <listitem> + <para>The <command>nix-instantiate</command> flags + <option>--eval-only</option> and <option>--parse-only</option> + have been renamed to <option>--eval</option> and + <option>--parse</option>, respectively.</para> + </listitem> + + <listitem> + <para><command>nix-instantiate</command>, + <command>nix-build</command> and <command>nix-shell</command> now + have a flag <option>--expr</option> (or <option>-E</option>) that + allows you to specify the expression to be evaluated as a command + line argument. For instance, <literal>nix-instantiate --eval -E + '1 + 2'</literal> will print <literal>3</literal>.</para> + </listitem> + + <listitem> + <para><command>nix-shell</command> improvements:</para> + + <itemizedlist> + + <listitem> + <para>It has a new flag, <option>--packages</option> (or + <option>-p</option>), that sets up a build environment + containing the specified packages from Nixpkgs. For example, + the command + +<screen> +$ nix-shell -p sqlite xorg.libX11 hello +</screen> + + will start a shell in which the given packages are + present.</para> + </listitem> + + <listitem> + <para>It now uses <filename>shell.nix</filename> as the + default expression, falling back to + <filename>default.nix</filename> if the former doesn’t + exist. This makes it convenient to have a + <filename>shell.nix</filename> in your project to set up a + nice development environment.</para> + </listitem> + + <listitem> + <para>It evaluates the derivation attribute + <varname>shellHook</varname>, if set. Since + <literal>stdenv</literal> does not normally execute this hook, + it allows you to do <command>nix-shell</command>-specific + setup.</para> + </listitem> + + <listitem> + <para>It preserves the user’s timezone setting.</para> + </listitem> + + </itemizedlist> + + </listitem> + + <listitem> + <para>In chroots, Nix now sets up a <filename>/dev</filename> + containing only a minimal set of devices (such as + <filename>/dev/null</filename>). Note that it only does this if + you <emphasis>don’t</emphasis> have <filename>/dev</filename> + listed in your <option>build-chroot-dirs</option> setting; + otherwise, it will bind-mount the <literal>/dev</literal> from + outside the chroot.</para> + + <para>Similarly, if you don’t have <filename>/dev/pts</filename> listed + in <option>build-chroot-dirs</option>, Nix will mount a private + <literal>devpts</literal> filesystem on the chroot’s + <filename>/dev/pts</filename>.</para> + + </listitem> + + <listitem> + <para>New built-in function: <function>builtins.toJSON</function>, + which returns a JSON representation of a value.</para> + </listitem> + + <listitem> + <para><command>nix-env -q</command> has a new flag + <option>--json</option> to print a JSON representation of the + installed or available packages.</para> + </listitem> + + <listitem> + <para><command>nix-env</command> now supports meta attributes with + more complex values, such as attribute sets.</para> + </listitem> + + <listitem> + <para>The <option>-A</option> flag now allows attribute names with + dots in them, e.g. + +<screen> +$ nix-instantiate --eval '<nixos>' -A 'config.systemd.units."nscd.service".text' +</screen> + + </para> + </listitem> + + <listitem> + <para>The <option>--max-freed</option> option to + <command>nix-store --gc</command> now accepts a unit + specifier. For example, <literal>nix-store --gc --max-freed + 1G</literal> will free up to 1 gigabyte of disk space.</para> + </listitem> + + <listitem> + <para><command>nix-collect-garbage</command> has a new flag + <option>--delete-older-than</option> + <replaceable>N</replaceable><literal>d</literal>, which deletes + all user environment generations older than + <replaceable>N</replaceable> days. Likewise, <command>nix-env + --delete-generations</command> accepts a + <replaceable>N</replaceable><literal>d</literal> age limit.</para> + </listitem> + + <listitem> + <para>Nix now heuristically detects whether a build failure was + due to a disk-full condition. In that case, the build is not + flagged as “permanently failed”. This is mostly useful for Hydra, + which needs to distinguish between permanent and transient build + failures.</para> + </listitem> + + <listitem> + <para>There is a new symbol <literal>__curPos</literal> that + expands to an attribute set containing its file name and line and + column numbers, e.g. <literal>{ file = "foo.nix"; line = 10; + column = 5; }</literal>. There also is a new builtin function, + <varname>unsafeGetAttrPos</varname>, that returns the position of + an attribute. This is used by Nixpkgs to provide location + information in error messages, e.g. + +<screen> +$ nix-build '<nixpkgs>' -A libreoffice --argstr system x86_64-darwin +error: the package ‘libreoffice-4.0.5.2’ in ‘.../applications/office/libreoffice/default.nix:263’ + is not supported on ‘x86_64-darwin’ +</screen> + + </para> + </listitem> + + <listitem> + <para>The garbage collector is now more concurrent with other Nix + processes because it releases certain locks earlier.</para> + </listitem> + + <listitem> + <para>The binary tarball installer has been improved. You can now + install Nix by running: + +<screen> +$ bash <(curl https://nixos.org/nix/install) +</screen> + + </para> + </listitem> + + <listitem> + <para>More evaluation errors include position information. For + instance, selecting a missing attribute will print something like + +<screen> +error: attribute `nixUnstabl' missing, at /etc/nixos/configurations/misc/eelco/mandark.nix:216:15 +</screen> + + </para> + </listitem> + + <listitem> + <para>The command <command>nix-setuid-helper</command> is + gone.</para> + </listitem> + + <listitem> + <para>Nix no longer uses Automake, but instead has a + non-recursive, GNU Make-based build system.</para> + </listitem> + + <listitem> + <para>All installed libraries now have the prefix + <literal>libnix</literal>. In particular, this gets rid of + <literal>libutil</literal>, which could clash with libraries with + the same name from other packages.</para> + </listitem> + + <listitem> + <para>Nix now requires a compiler that supports C++11.</para> + </listitem> + +</itemizedlist> + +<para>This release has contributions from Danny Wilson, Domen Kožar, +Eelco Dolstra, Ian-Woo Kim, Ludovic Courtès, Maxim Ivanov, Petr +Rockai, Ricardo M. Correia and Shea Levy.</para> + +</section> +<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 “real” Nix build. + </para> + </listitem> + + <listitem> + <para><command>nix-shell</command> now sets the shell prompt + (<envar>PS1</envar>) to ensure that Nix shells are distinguishable + from your regular shells.</para> + </listitem> + + <listitem> + <para><command>nix-env</command> no longer requires a + <literal>*</literal> argument to match all packages, so + <literal>nix-env -qa</literal> is equivalent to <literal>nix-env + -qa '*'</literal>.</para> + </listitem> + + <listitem> + <para><command>nix-env -i</command> has a new flag + <option>--remove-all</option> (<option>-r</option>) to remove all + previous packages from the profile. This makes it easier to do + declarative package management similar to NixOS’s + <option>environment.systemPackages</option>. For instance, if you + have a specification <filename>my-packages.nix</filename> like this: + +<programlisting> +with import <nixpkgs> {}; +[ thunderbird + geeqie + ... +] +</programlisting> + + then after any change to this file, you can run: + +<screen> +$ nix-env -f my-packages.nix -ir +</screen> + + to update your profile to match the specification.</para> + </listitem> + + <listitem> + <para>The ‘<literal>with</literal>’ language construct is now more + lazy. It only evaluates its argument if a variable might actually + refer to an attribute in the argument. For instance, this now + works: + +<programlisting> +let + pkgs = with pkgs; { foo = "old"; bar = foo; } // overrides; + overrides = { foo = "new"; }; +in pkgs.bar +</programlisting> + + This evaluates to <literal>"new"</literal>, while previously it + gave an “infinite recursion” error.</para> + </listitem> + + <listitem> + <para>Nix now has proper integer arithmetic operators. For + instance, you can write <literal>x + y</literal> instead of + <literal>builtins.add x y</literal>, or <literal>x < + y</literal> instead of <literal>builtins.lessThan x y</literal>. + The comparison operators also work on strings.</para> + </listitem> + + <listitem> + <para>On 64-bit systems, Nix integers are now 64 bits rather than + 32 bits.</para> + </listitem> + + <listitem> + <para>When using the Nix daemon, the <command>nix-daemon</command> + worker process now runs on the same CPU as the client, on systems + that support setting CPU affinity. This gives a significant speedup + on some systems.</para> + </listitem> + + <listitem> + <para>If a stack overflow occurs in the Nix evaluator, you now get + a proper error message (rather than “Segmentation fault”) on some + systems.</para> + </listitem> + + <listitem> + <para>In addition to directories, you can now bind-mount regular + files in chroots through the (now misnamed) option + <option>build-chroot-dirs</option>.</para> + </listitem> + +</itemizedlist> + +<para>This release has contributions from Domen Kožar, Eelco Dolstra, +Florian Friesdorf, Gergely Risko, Ivan Kozik, Ludovic Courtès and Shea +Levy.</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-1.5.2"> + +<title>Release 1.5.2 (2013-05-13)</title> + +<para>This is primarily a bug fix release. It has contributions from +Eelco Dolstra, Lluís Batlle i Rossell and Shea Levy.</para> + +</section> +<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 “manifest”-based method of getting + pre-built binaries is that you don’t have to worry about your + manifest being in sync with the Nix expressions you’re installing + from; i.e., you don’t need to run <command>nix-pull</command> to + update your manifest. It’s also more scalable because you don’t + need to redownload a giant manifest file every time. + </para> + + <para>A Nix channel can provide a binary cache URL that will be + used automatically if you subscribe to that channel. If you use + the Nixpkgs or NixOS channels + (<uri>http://nixos.org/channels</uri>) you automatically get the + cache <uri>http://cache.nixos.org</uri>.</para> + + <para>Binary caches are created using <command>nix-push</command>. + For details on the operation and format of binary caches, see the + <command>nix-push</command> manpage. More details are provided in + <link xlink:href="https://nixos.org/nix-dev/2012-September/009826.html">this + nix-dev posting</link>.</para> + </listitem> + + <listitem> + <para>Multiple output support should now be usable. A derivation + can declare that it wants to produce multiple store paths by + saying something like +<programlisting> +outputs = [ "lib" "headers" "doc" ]; +</programlisting> + This will cause Nix to pass the intended store path of each output + to the builder through the environment variables + <literal>lib</literal>, <literal>headers</literal> and + <literal>doc</literal>. Other packages can refer to a specific + output by referring to + <literal><replaceable>pkg</replaceable>.<replaceable>output</replaceable></literal>, + e.g. +<programlisting> +buildInputs = [ pkg.lib pkg.headers ]; +</programlisting> + If you install a package with multiple outputs using + <command>nix-env</command>, each output path will be symlinked + into the user environment.</para> + </listitem> + + <listitem> + <para>Dashes are now valid as part of identifiers and attribute + names.</para> + </listitem> + + <listitem> + <para>The new operation <command>nix-store --repair-path</command> + allows corrupted or missing store paths to be repaired by + redownloading them. <command>nix-store --verify --check-contents + --repair</command> will scan and repair all paths in the Nix + store. Similarly, <command>nix-env</command>, + <command>nix-build</command>, <command>nix-instantiate</command> + and <command>nix-store --realise</command> have a + <option>--repair</option> flag to detect and fix bad paths by + rebuilding or redownloading them.</para> + </listitem> + + <listitem> + <para>Nix no longer sets the immutable bit on files in the Nix + store. Instead, the recommended way to guard the Nix store + against accidental modification on Linux is to make it a read-only + bind mount, like this: + +<screen> +$ mount --bind /nix/store /nix/store +$ mount -o remount,ro,bind /nix/store +</screen> + + Nix will automatically make <filename>/nix/store</filename> + writable as needed (using a private mount namespace) to allow + modifications.</para> + </listitem> + + <listitem> + <para>Store optimisation (replacing identical files in the store + with hard links) can now be done automatically every time a path + is added to the store. This is enabled by setting the + configuration option <literal>auto-optimise-store</literal> to + <literal>true</literal> (disabled by default).</para> + </listitem> + + <listitem> + <para>Nix now supports <command>xz</command> compression for NARs + in addition to <command>bzip2</command>. It compresses about 30% + better on typical archives and decompresses about twice as + fast.</para> + </listitem> + + <listitem> + <para>Basic Nix expression evaluation profiling: setting the + environment variable <envar>NIX_COUNT_CALLS</envar> to + <literal>1</literal> will cause Nix to print how many times each + primop or function was executed.</para> + </listitem> + + <listitem> + <para>New primops: <varname>concatLists</varname>, + <varname>elem</varname>, <varname>elemAt</varname> and + <varname>filter</varname>.</para> + </listitem> + + <listitem> + <para>The command <command>nix-copy-closure</command> has a new + flag <option>--use-substitutes</option> (<option>-s</option>) to + download missing paths on the target machine using the substitute + mechanism.</para> + </listitem> + + <listitem> + <para>The command <command>nix-worker</command> has been renamed + to <command>nix-daemon</command>. Support for running the Nix + worker in “slave” mode has been removed.</para> + </listitem> + + <listitem> + <para>The <option>--help</option> flag of every Nix command now + invokes <command>man</command>.</para> + </listitem> + + <listitem> + <para>Chroot builds are now supported on systemd machines.</para> + </listitem> + +</itemizedlist> + +<para>This release has contributions from Eelco Dolstra, Florian +Friesdorf, Mats Erik Andersson and Shea Levy.</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-1.1"> + +<title>Release 1.1 (2012-07-18)</title> + +<para>This release has the following improvements:</para> + +<itemizedlist> + + <listitem> + <para>On Linux, when doing a chroot build, Nix now uses various + namespace features provided by the Linux kernel to improve + build isolation. Namely: + <itemizedlist> + <listitem><para>The private network namespace ensures that + builders cannot talk to the outside world (or vice versa): each + build only sees a private loopback interface. This also means + that two concurrent builds can listen on the same port (e.g. as + part of a test) without conflicting with each + other.</para></listitem> + <listitem><para>The PID namespace causes each build to start as + PID 1. Processes outside of the chroot are not visible to those + on the inside. On the other hand, processes inside the chroot + <emphasis>are</emphasis> visible from the outside (though with + different PIDs).</para></listitem> + <listitem><para>The IPC namespace prevents the builder from + communicating with outside processes using SysV IPC mechanisms + (shared memory, message queues, semaphores). It also ensures + that all IPC objects are destroyed when the builder + exits.</para></listitem> + <listitem><para>The UTS namespace ensures that builders see a + hostname of <literal>localhost</literal> rather than the actual + hostname.</para></listitem> + <listitem><para>The private mount namespace was already used by + Nix to ensure that the bind-mounts used to set up the chroot are + cleaned up automatically.</para></listitem> + </itemizedlist> + </para> + </listitem> + + <listitem> + <para>Build logs are now compressed using + <command>bzip2</command>. The command <command>nix-store + -l</command> decompresses them on the fly. This can be disabled + by setting the option <literal>build-compress-log</literal> to + <literal>false</literal>.</para> + </listitem> + + <listitem> + <para>The creation of build logs in + <filename>/nix/var/log/nix/drvs</filename> can be disabled by + setting the new option <literal>build-keep-log</literal> to + <literal>false</literal>. This is useful, for instance, for Hydra + build machines.</para> + </listitem> + + <listitem> + <para>Nix now reserves some space in + <filename>/nix/var/nix/db/reserved</filename> to ensure that the + garbage collector can run successfully if the disk is full. This + is necessary because SQLite transactions fail if the disk is + full.</para> + </listitem> + + <listitem> + <para>Added a basic <function>fetchurl</function> function. This + is not intended to replace the <function>fetchurl</function> in + Nixpkgs, but is useful for bootstrapping; e.g., it will allow us + to get rid of the bootstrap binaries in the Nixpkgs source tree + and download them instead. You can use it by doing + <literal>import <nix/fetchurl.nix> { url = + <replaceable>url</replaceable>; sha256 = + "<replaceable>hash</replaceable>"; }</literal>. (Shea Levy)</para> + </listitem> + + <listitem> + <para>Improved RPM spec file. (Michel Alexandre Salim)</para> + </listitem> + + <listitem> + <para>Support for on-demand socket-based activation in the Nix + daemon with <command>systemd</command>.</para> + </listitem> + + <listitem> + <para>Added a manpage for + <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + + <listitem> + <para>When using the Nix daemon, the <option>-s</option> flag in + <command>nix-env -qa</command> is now much faster.</para> + </listitem> + +</itemizedlist> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-1.0"> + +<title>Release 1.0 (2012-05-11)</title> + +<para>There have been numerous improvements and bug fixes since the +previous release. Here are the most significant:</para> + +<itemizedlist> + + <listitem> + <para>Nix can now optionally use the Boehm garbage collector. + This significantly reduces the Nix evaluator’s memory footprint, + especially when evaluating large NixOS system configurations. It + can be enabled using the <option>--enable-gc</option> configure + option.</para> + </listitem> + + <listitem> + <para>Nix now uses SQLite for its database. This is faster and + more flexible than the old <emphasis>ad hoc</emphasis> format. + SQLite is also used to cache the manifests in + <filename>/nix/var/nix/manifests</filename>, resulting in a + significant speedup.</para> + </listitem> + + <listitem> + <para>Nix now has an search path for expressions. The search path + is set using the environment variable <envar>NIX_PATH</envar> and + the <option>-I</option> command line option. In Nix expressions, + paths between angle brackets are used to specify files that must + be looked up in the search path. For instance, the expression + <literal><nixpkgs/default.nix></literal> looks for a file + <filename>nixpkgs/default.nix</filename> relative to every element + in the search path.</para> + </listitem> + + <listitem> + <para>The new command <command>nix-build --run-env</command> + builds all dependencies of a derivation, then starts a shell in an + environment containing all variables from the derivation. This is + useful for reproducing the environment of a derivation for + development.</para> + </listitem> + + <listitem> + <para>The new command <command>nix-store --verify-path</command> + verifies that the contents of a store path have not + changed.</para> + </listitem> + + <listitem> + <para>The new command <command>nix-store --print-env</command> + prints out the environment of a derivation in a format that can be + evaluated by a shell.</para> + </listitem> + + <listitem> + <para>Attribute names can now be arbitrary strings. For instance, + you can write <literal>{ "foo-1.2" = …; "bla bla" = …; }."bla + bla"</literal>.</para> + </listitem> + + <listitem> + <para>Attribute selection can now provide a default value using + the <literal>or</literal> operator. For instance, the expression + <literal>x.y.z or e</literal> evaluates to the attribute + <literal>x.y.z</literal> if it exists, and <literal>e</literal> + otherwise.</para> + </listitem> + + <listitem> + <para>The right-hand side of the <literal>?</literal> operator can + now be an attribute path, e.g., <literal>attrs ? + a.b.c</literal>.</para> + </listitem> + + <listitem> + <para>On Linux, Nix will now make files in the Nix store immutable + on filesystems that support it. This prevents accidental + modification of files in the store by the root user.</para> + </listitem> + + <listitem> + <para>Nix has preliminary support for derivations with multiple + outputs. This is useful because it allows parts of a package to + be deployed and garbage-collected separately. For instance, + development parts of a package such as header files or static + libraries would typically not be part of the closure of an + application, resulting in reduced disk usage and installation + time.</para> + </listitem> + + <listitem> + <para>The Nix store garbage collector is faster and holds the + global lock for a shorter amount of time.</para> + </listitem> + + <listitem> + <para>The option <option>--timeout</option> (corresponding to the + configuration setting <literal>build-timeout</literal>) allows you + to set an absolute timeout on builds — if a build runs for more than + the given number of seconds, it is terminated. This is useful for + recovering automatically from builds that are stuck in an infinite + loop but keep producing output, and for which + <literal>--max-silent-time</literal> is ineffective.</para> + </listitem> + + <listitem> + <para>Nix development has moved to GitHub (<link xlink:href="https://github.com/NixOS/nix"/>).</para> + </listitem> + +</itemizedlist> + +</section> +<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’t known in + advance.)</para> + </listitem> + + <listitem> + <para>Support <literal>i686-linux</literal> builds directly on + <literal>x86_64-linux</literal> Nix installations. This is + implemented using the <function>personality()</function> syscall, + which causes <command>uname</command> to return + <literal>i686</literal> in child processes.</para> + </listitem> + + <listitem> + <para>Various improvements to the <literal>chroot</literal> + support. Building in a <literal>chroot</literal> works quite well + now.</para> + </listitem> + + <listitem> + <para>Nix no longer blocks if it tries to build a path and another + process is already building the same path. Instead it tries to + build another buildable path first. This improves + parallelism.</para> + </listitem> + + <listitem> + <para>Support for large (> 4 GiB) files in NAR archives.</para> + </listitem> + + <listitem> + <para>Various (performance) improvements to the remote build + mechanism.</para> + </listitem> + + <listitem> + <para>New primops: <varname>builtins.addErrorContext</varname> (to + add a string to stack traces — useful for debugging), + <varname>builtins.isBool</varname>, + <varname>builtins.isString</varname>, + <varname>builtins.isInt</varname>, + <varname>builtins.intersectAttrs</varname>.</para> + </listitem> + + <listitem> + <para>OpenSolaris support (Sander van der Burg).</para> + </listitem> + + <listitem> + <para>Stack traces are no longer displayed unless the + <option>--show-trace</option> option is used.</para> + </listitem> + + <listitem> + <para>The scoping rules for <literal>inherit + (<replaceable>e</replaceable>) ...</literal> in recursive + attribute sets have changed. The expression + <replaceable>e</replaceable> can now refer to the attributes + defined in the containing set.</para> + </listitem> + +</itemizedlist> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-0.12"> + +<title>Release 0.12 (2008-11-20)</title> + +<itemizedlist> + + <listitem> + <para>Nix no longer uses Berkeley DB to store Nix store metadata. + The principal advantages of the new storage scheme are: it works + properly over decent implementations of NFS (allowing Nix stores + to be shared between multiple machines); no recovery is needed + when a Nix process crashes; no write access is needed for + read-only operations; no more running out of Berkeley DB locks on + certain operations.</para> + + <para>You still need to compile Nix with Berkeley DB support if + you want Nix to automatically convert your old Nix store to the + new schema. If you don’t need this, you can build Nix with the + <filename>configure</filename> option + <option>--disable-old-db-compat</option>.</para> + + <para>After the automatic conversion to the new schema, you can + delete the old Berkeley DB files: + + <screen> +$ cd /nix/var/nix/db +$ rm __db* log.* derivers references referrers reserved validpaths DB_CONFIG</screen> + + The new metadata is stored in the directories + <filename>/nix/var/nix/db/info</filename> and + <filename>/nix/var/nix/db/referrer</filename>. Though the + metadata is stored in human-readable plain-text files, they are + not intended to be human-editable, as Nix is rather strict about + the format.</para> + + <para>The new storage schema may or may not require less disk + space than the Berkeley DB environment, mostly depending on the + cluster size of your file system. With 1 KiB clusters (which + seems to be the <literal>ext3</literal> default nowadays) it + usually takes up much less space.</para> + </listitem> + + <listitem><para>There is a new substituter that copies paths + directly from other (remote) Nix stores mounted somewhere in the + filesystem. For instance, you can speed up an installation by + mounting some remote Nix store that already has the packages in + question via NFS or <literal>sshfs</literal>. The environment + variable <envar>NIX_OTHER_STORES</envar> specifies the locations of + the remote Nix directories, + e.g. <literal>/mnt/remote-fs/nix</literal>.</para></listitem> + + <listitem><para>New <command>nix-store</command> operations + <option>--dump-db</option> and <option>--load-db</option> to dump + and reload the Nix database.</para></listitem> + + <listitem><para>The garbage collector has a number of new options to + allow only some of the garbage to be deleted. The option + <option>--max-freed <replaceable>N</replaceable></option> tells the + collector to stop after at least <replaceable>N</replaceable> bytes + have been deleted. The option <option>--max-links + <replaceable>N</replaceable></option> tells it to stop after the + link count on <filename>/nix/store</filename> has dropped below + <replaceable>N</replaceable>. This is useful for very large Nix + stores on filesystems with a 32000 subdirectories limit (like + <literal>ext3</literal>). The option <option>--use-atime</option> + causes store paths to be deleted in order of ascending last access + time. This allows non-recently used stuff to be deleted. The + option <option>--max-atime <replaceable>time</replaceable></option> + specifies an upper limit to the last accessed time of paths that may + be deleted. For instance, + + <screen> + $ nix-store --gc -v --max-atime $(date +%s -d "2 months ago")</screen> + + deletes everything that hasn’t been accessed in two months.</para></listitem> + + <listitem><para><command>nix-env</command> now uses optimistic + profile locking when performing an operation like installing or + upgrading, instead of setting an exclusive lock on the profile. + This allows multiple <command>nix-env -i / -u / -e</command> + operations on the same profile in parallel. If a + <command>nix-env</command> operation sees at the end that the profile + was changed in the meantime by another process, it will just + restart. This is generally cheap because the build results are + still in the Nix store.</para></listitem> + + <listitem><para>The option <option>--dry-run</option> is now + supported by <command>nix-store -r</command> and + <command>nix-build</command>.</para></listitem> + + <listitem><para>The information previously shown by + <option>--dry-run</option> (i.e., which derivations will be built + and which paths will be substituted) is now always shown by + <command>nix-env</command>, <command>nix-store -r</command> and + <command>nix-build</command>. The total download size of + substitutable paths is now also shown. For instance, a build will + show something like + + <screen> +the following derivations will be built: + /nix/store/129sbxnk5n466zg6r1qmq1xjv9zymyy7-activate-configuration.sh.drv + /nix/store/7mzy971rdm8l566ch8hgxaf89x7lr7ik-upstart-jobs.drv + ... +the following paths will be downloaded/copied (30.02 MiB): + /nix/store/4m8pvgy2dcjgppf5b4cj5l6wyshjhalj-samba-3.2.4 + /nix/store/7h1kwcj29ip8vk26rhmx6bfjraxp0g4l-libunwind-0.98.6 + ...</screen> + + </para></listitem> + + <listitem><para>Language features: + + <itemizedlist> + + <listitem><para>@-patterns as in Haskell. For instance, in a + function definition + + <programlisting>f = args @ {x, y, z}: <replaceable>...</replaceable>;</programlisting> + + <varname>args</varname> refers to the argument as a whole, which + is further pattern-matched against the attribute set pattern + <literal>{x, y, z}</literal>.</para></listitem> + + <listitem><para>“<literal>...</literal>” (ellipsis) patterns. + An attribute set pattern can now say <literal>...</literal> at + the end of the attribute name list to specify that the function + takes <emphasis>at least</emphasis> the listed attributes, while + ignoring additional attributes. For instance, + + <programlisting>{stdenv, fetchurl, fuse, ...}: <replaceable>...</replaceable></programlisting> + + defines a function that accepts any attribute set that includes + at least the three listed attributes.</para></listitem> + + <listitem><para>New primops: + <varname>builtins.parseDrvName</varname> (split a package name + string like <literal>"nix-0.12pre12876"</literal> into its name + and version components, e.g. <literal>"nix"</literal> and + <literal>"0.12pre12876"</literal>), + <varname>builtins.compareVersions</varname> (compare two version + strings using the same algorithm that <command>nix-env</command> + uses), <varname>builtins.length</varname> (efficiently compute + the length of a list), <varname>builtins.mul</varname> (integer + multiplication), <varname>builtins.div</varname> (integer + division). + <!-- <varname>builtins.genericClosure</varname> --> + </para></listitem> + + </itemizedlist> + + </para></listitem> + + <listitem><para><command>nix-prefetch-url</command> now supports + <literal>mirror://</literal> URLs, provided that the environment + variable <envar>NIXPKGS_ALL</envar> points at a Nixpkgs + tree.</para></listitem> + + <listitem><para>Removed the commands + <command>nix-pack-closure</command> and + <command>nix-unpack-closure</command>. You can do almost the same + thing but much more efficiently by doing <literal>nix-store --export + $(nix-store -qR <replaceable>paths</replaceable>) > closure</literal> and + <literal>nix-store --import < + closure</literal>.</para></listitem> + + <listitem><para>Lots of bug fixes, including a big performance bug in + the handling of <literal>with</literal>-expressions.</para></listitem> + +</itemizedlist> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ssec-relnotes-0.11"> + +<title>Release 0.11 (2007-12-31)</title> + +<para>Nix 0.11 has many improvements over the previous stable release. +The most important improvement is secure multi-user support. It also +features many usability enhancements and language extensions, many of +them prompted by NixOS, the purely functional Linux distribution based +on Nix. Here is an (incomplete) list:</para> + + +<itemizedlist> + + + <listitem><para>Secure multi-user support. A single Nix store can + now be shared between multiple (possible untrusted) users. This is + an important feature for NixOS, where it allows non-root users to + install software. The old setuid method for sharing a store between + multiple users has been removed. Details for setting up a + multi-user store can be found in the manual.</para></listitem> + + + <listitem><para>The new command <command>nix-copy-closure</command> + gives you an easy and efficient way to exchange software between + machines. It copies the missing parts of the closure of a set of + store path to or from a remote machine via + <command>ssh</command>.</para></listitem> + + + <listitem><para>A new kind of string literal: strings between double + single-quotes (<literal>''</literal>) have indentation + “intelligently” removed. This allows large strings (such as shell + scripts or configuration file fragments in NixOS) to cleanly follow + the indentation of the surrounding expression. It also requires + much less escaping, since <literal>''</literal> is less common in + most languages than <literal>"</literal>.</para></listitem> + + + <listitem><para><command>nix-env</command> <option>--set</option> + modifies the current generation of a profile so that it contains + exactly the specified derivation, and nothing else. For example, + <literal>nix-env -p /nix/var/nix/profiles/browser --set + firefox</literal> lets the profile named + <filename>browser</filename> contain just Firefox.</para></listitem> + + + <listitem><para><command>nix-env</command> now maintains + meta-information about installed packages in profiles. The + meta-information is the contents of the <varname>meta</varname> + attribute of derivations, such as <varname>description</varname> or + <varname>homepage</varname>. The command <literal>nix-env -q --xml + --meta</literal> shows all meta-information.</para></listitem> + + + <listitem><para><command>nix-env</command> now uses the + <varname>meta.priority</varname> attribute of derivations to resolve + filename collisions between packages. Lower priority values denote + a higher priority. For instance, the GCC wrapper package and the + Binutils package in Nixpkgs both have a file + <filename>bin/ld</filename>, so previously if you tried to install + both you would get a collision. Now, on the other hand, the GCC + wrapper declares a higher priority than Binutils, so the former’s + <filename>bin/ld</filename> is symlinked in the user + environment.</para></listitem> + + + <listitem><para><command>nix-env -i / -u</command>: instead of + breaking package ties by version, break them by priority and version + number. That is, if there are multiple packages with the same name, + then pick the package with the highest priority, and only use the + version if there are multiple packages with the same + priority.</para> + + <para>This makes it possible to mark specific versions/variant in + Nixpkgs more or less desirable than others. A typical example would + be a beta version of some package (e.g., + <literal>gcc-4.2.0rc1</literal>) which should not be installed even + though it is the highest version, except when it is explicitly + selected (e.g., <literal>nix-env -i + gcc-4.2.0rc1</literal>).</para></listitem> + + + <listitem><para><command>nix-env --set-flag</command> allows meta + attributes of installed packages to be modified. There are several + attributes that can be usefully modified, because they affect the + behaviour of <command>nix-env</command> or the user environment + build script: + + <itemizedlist> + + <listitem><para><varname>meta.priority</varname> can be changed + to resolve filename clashes (see above).</para></listitem> + + <listitem><para><varname>meta.keep</varname> can be set to + <literal>true</literal> to prevent the package from being + upgraded or replaced. Useful if you want to hang on to an older + version of a package.</para></listitem> + + <listitem><para><varname>meta.active</varname> can be set to + <literal>false</literal> to “disable” the package. That is, no + symlinks will be generated to the files of the package, but it + remains part of the profile (so it won’t be garbage-collected). + Set it back to <literal>true</literal> to re-enable the + package.</para></listitem> + + </itemizedlist> + + </para></listitem> + + + <listitem><para><command>nix-env -q</command> now has a flag + <option>--prebuilt-only</option> (<option>-b</option>) that causes + <command>nix-env</command> to show only those derivations whose + output is already in the Nix store or that can be substituted (i.e., + downloaded from somewhere). In other words, it shows the packages + that can be installed “quickly”, i.e., don’t need to be built from + source. The <option>-b</option> flag is also available in + <command>nix-env -i</command> and <command>nix-env -u</command> to + filter out derivations for which no pre-built binary is + available.</para></listitem> + + + <listitem><para>The new option <option>--argstr</option> (in + <command>nix-env</command>, <command>nix-instantiate</command> and + <command>nix-build</command>) is like <option>--arg</option>, except + that the value is a string. For example, <literal>--argstr system + i686-linux</literal> is equivalent to <literal>--arg system + \"i686-linux\"</literal> (note that <option>--argstr</option> + prevents annoying quoting around shell arguments).</para></listitem> + + + <listitem><para><command>nix-store</command> has a new operation + <option>--read-log</option> (<option>-l</option>) + <parameter>paths</parameter> that shows the build log of the given + paths.</para></listitem> + + + <!-- + <listitem><para>TODO: semantic cleanups of string concatenation + etc. (mostly in r6740).</para></listitem> + --> + + + <listitem><para>Nix now uses Berkeley DB 4.5. The database is + upgraded automatically, but you should be careful not to use old + versions of Nix that still use Berkeley DB 4.4.</para></listitem> + + + <!-- foo + <listitem><para>TODO: option <option>- -reregister</option> in + <command>nix-store - -register-validity</command>.</para></listitem> + --> + + + <listitem><para>The option <option>--max-silent-time</option> + (corresponding to the configuration setting + <literal>build-max-silent-time</literal>) allows you to set a + timeout on builds — if a build produces no output on + <literal>stdout</literal> or <literal>stderr</literal> for the given + number of seconds, it is terminated. This is useful for recovering + automatically from builds that are stuck in an infinite + loop.</para></listitem> + + + <listitem><para><command>nix-channel</command>: each subscribed + channel is its own attribute in the top-level expression generated + for the channel. This allows disambiguation (e.g. <literal>nix-env + -i -A nixpkgs_unstable.firefox</literal>).</para></listitem> + + + <listitem><para>The substitutes table has been removed from the + database. This makes operations such as <command>nix-pull</command> + and <command>nix-channel --update</command> much, much + faster.</para></listitem> + + + <listitem><para><command>nix-pull</command> now supports + bzip2-compressed manifests. This speeds up + channels.</para></listitem> + + + <listitem><para><command>nix-prefetch-url</command> now has a + limited form of caching. This is used by + <command>nix-channel</command> to prevent unnecessary downloads when + the channel hasn’t changed.</para></listitem> + + + <listitem><para><command>nix-prefetch-url</command> now by default + computes the SHA-256 hash of the file instead of the MD5 hash. In + calls to <function>fetchurl</function> you should pass the + <literal>sha256</literal> attribute instead of + <literal>md5</literal>. You can pass either a hexadecimal or a + base-32 encoding of the hash.</para></listitem> + + + <listitem><para>Nix can now perform builds in an automatically + generated “chroot”. This prevents a builder from accessing stuff + outside of the Nix store, and thus helps ensure purity. This is an + experimental feature.</para></listitem> + + + <listitem><para>The new command <command>nix-store + --optimise</command> reduces Nix store disk space usage by finding + identical files in the store and hard-linking them to each other. + It typically reduces the size of the store by something like + 25-35%.</para></listitem> + + + <listitem><para><filename>~/.nix-defexpr</filename> can now be a + directory, in which case the Nix expressions in that directory are + combined into an attribute set, with the file names used as the + names of the attributes. The command <command>nix-env + --import</command> (which set the + <filename>~/.nix-defexpr</filename> symlink) is + removed.</para></listitem> + + + <listitem><para>Derivations can specify the new special attribute + <varname>allowedReferences</varname> to enforce that the references + in the output of a derivation are a subset of a declared set of + paths. For example, if <varname>allowedReferences</varname> is an + empty list, then the output must not have any references. This is + used in NixOS to check that generated files such as initial ramdisks + for booting Linux don’t have any dependencies.</para></listitem> + + + <listitem><para>The new attribute + <varname>exportReferencesGraph</varname> allows builders access to + the references graph of their inputs. This is used in NixOS for + tasks such as generating ISO-9660 images that contain a Nix store + populated with the closure of certain paths.</para></listitem> + + + <listitem><para>Fixed-output derivations (like + <function>fetchurl</function>) can define the attribute + <varname>impureEnvVars</varname> to allow external environment + variables to be passed to builders. This is used in Nixpkgs to + support proxy configuration, among other things.</para></listitem> + + + <listitem><para>Several new built-in functions: + <function>builtins.attrNames</function>, + <function>builtins.filterSource</function>, + <function>builtins.isAttrs</function>, + <function>builtins.isFunction</function>, + <function>builtins.listToAttrs</function>, + <function>builtins.stringLength</function>, + <function>builtins.sub</function>, + <function>builtins.substring</function>, + <function>throw</function>, + <function>builtins.trace</function>, + <function>builtins.readFile</function>.</para></listitem> + + +</itemizedlist> + +</section> +<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’s in your subscribed + channels is <literal>nix-env -qc \*</literal>.</para></listitem> + + <listitem><para><literal>nix-env --query</literal> now takes as + arguments a list of package names about which to show + information, just like <option>--install</option>, etc.: for + example, <literal>nix-env -q gcc</literal>. Note that to show + all derivations, you need to specify + <literal>\*</literal>.</para></listitem> + + <listitem><para><literal>nix-env -i + <replaceable>pkgname</replaceable></literal> will now install + the highest available version of + <replaceable>pkgname</replaceable>, rather than installing all + available versions (which would probably give collisions) + (<literal>NIX-31</literal>).</para></listitem> + + <listitem><para><literal>nix-env (-i|-u) --dry-run</literal> now + shows exactly which missing paths will be built or + substituted.</para></listitem> + + <listitem><para><literal>nix-env -qa --description</literal> + shows human-readable descriptions of packages, provided that + they have a <literal>meta.description</literal> attribute (which + most packages in Nixpkgs don’t have yet).</para></listitem> + + </itemizedlist> + + </para></listitem> + + + <listitem><para>New language features: + + <itemizedlist> + + <listitem><para>Reference scanning (which happens after each + build) is much faster and takes a constant amount of + memory.</para></listitem> + + <listitem><para>String interpolation. Expressions like + +<programlisting> +"--with-freetype2-library=" + freetype + "/lib"</programlisting> + + can now be written as + +<programlisting> +"--with-freetype2-library=${freetype}/lib"</programlisting> + + You can write arbitrary expressions within + <literal>${<replaceable>...</replaceable>}</literal>, not just + identifiers.</para></listitem> + + <listitem><para>Multi-line string literals.</para></listitem> + + <listitem><para>String concatenations can now involve + derivations, as in the example <code>"--with-freetype2-library=" + + freetype + "/lib"</code>. This was not previously possible + because we need to register that a derivation that uses such a + string is dependent on <literal>freetype</literal>. The + evaluator now properly propagates this information. + Consequently, the subpath operator (<literal>~</literal>) has + been deprecated.</para></listitem> + + <listitem><para>Default values of function arguments can now + refer to other function arguments; that is, all arguments are in + scope in the default values + (<literal>NIX-45</literal>).</para></listitem> + + <!-- + <listitem><para>TODO: domain checks (r5895).</para></listitem> + --> + + <listitem><para>Lots of new built-in primitives, such as + functions for list manipulation and integer arithmetic. See the + manual for a complete list. All primops are now available in + the set <varname>builtins</varname>, allowing one to test for + the availability of primop in a backwards-compatible + way.</para></listitem> + + <listitem><para>Real let-expressions: <literal>let x = ...; + ... z = ...; in ...</literal>.</para></listitem> + + </itemizedlist> + + </para></listitem> + + + <listitem><para>New commands <command>nix-pack-closure</command> and + <command>nix-unpack-closure</command> than can be used to easily + transfer a store path with all its dependencies to another machine. + Very convenient whenever you have some package on your machine and + you want to copy it somewhere else.</para></listitem> + + + <listitem><para>XML support: + + <itemizedlist> + + <listitem><para><literal>nix-env -q --xml</literal> prints the + installed or available packages in an XML representation for + easy processing by other tools.</para></listitem> + + <listitem><para><literal>nix-instantiate --eval-only + --xml</literal> prints an XML representation of the resulting + term. (The new flag <option>--strict</option> forces ‘deep’ + evaluation of the result, i.e., list elements and attributes are + evaluated recursively.)</para></listitem> + + <listitem><para>In Nix expressions, the primop + <function>builtins.toXML</function> converts a term to an XML + representation. This is primarily useful for passing structured + information to builders.</para></listitem> + + </itemizedlist> + + </para></listitem> + + + <listitem><para>You can now unambiguously specify which derivation to + build or install in <command>nix-env</command>, + <command>nix-instantiate</command> and <command>nix-build</command> + using the <option>--attr</option> / <option>-A</option> flags, which + takes an attribute name as argument. (Unlike symbolic package names + such as <literal>subversion-1.4.0</literal>, attribute names in an + attribute set are unique.) For instance, a quick way to perform a + test build of a package in Nixpkgs is <literal>nix-build + pkgs/top-level/all-packages.nix -A + <replaceable>foo</replaceable></literal>. <literal>nix-env -q + --attr</literal> shows the attribute names corresponding to each + derivation.</para></listitem> + + + <listitem><para>If the top-level Nix expression used by + <command>nix-env</command>, <command>nix-instantiate</command> or + <command>nix-build</command> evaluates to a function whose arguments + all have default values, the function will be called automatically. + Also, the new command-line switch <option>--arg + <replaceable>name</replaceable> + <replaceable>value</replaceable></option> can be used to specify + function arguments on the command line.</para></listitem> + + + <listitem><para><literal>nix-install-package --url + <replaceable>URL</replaceable></literal> allows a package to be + installed directly from the given URL.</para></listitem> + + + <listitem><para>Nix now works behind an HTTP proxy server; just set + the standard environment variables <envar>http_proxy</envar>, + <envar>https_proxy</envar>, <envar>ftp_proxy</envar> or + <envar>all_proxy</envar> appropriately. Functions such as + <function>fetchurl</function> in Nixpkgs also respect these + variables.</para></listitem> + + + <listitem><para><literal>nix-build -o + <replaceable>symlink</replaceable></literal> allows the symlink to + the build result to be named something other than + <literal>result</literal>.</para></listitem> + + + <!-- Stability / performance / etc. --> + + + <listitem><para>Platform support: + + <itemizedlist> + + <listitem><para>Support for 64-bit platforms, provided a <link xlink:href="http://bugzilla.sen.cwi.nl:8080/show_bug.cgi?id=606">suitably + patched ATerm library</link> is used. Also, files larger than 2 + GiB are now supported.</para></listitem> + + <listitem><para>Added support for Cygwin (Windows, + <literal>i686-cygwin</literal>), Mac OS X on Intel + (<literal>i686-darwin</literal>) and Linux on PowerPC + (<literal>powerpc-linux</literal>).</para></listitem> + + <listitem><para>Users of SMP and multicore machines will + appreciate that the number of builds to be performed in parallel + can now be specified in the configuration file in the + <literal>build-max-jobs</literal> setting.</para></listitem> + + </itemizedlist> + + </para></listitem> + + + <listitem><para>Garbage collector improvements: + + <itemizedlist> + + <listitem><para>Open files (such as running programs) are now + used as roots of the garbage collector. This prevents programs + that have been uninstalled from being garbage collected while + they are still running. The script that detects these + additional runtime roots + (<filename>find-runtime-roots.pl</filename>) is inherently + system-specific, but it should work on Linux and on all + platforms that have the <command>lsof</command> + utility.</para></listitem> + + <listitem><para><literal>nix-store --gc</literal> + (a.k.a. <command>nix-collect-garbage</command>) prints out the + number of bytes freed on standard output. <literal>nix-store + --gc --print-dead</literal> shows how many bytes would be freed + by an actual garbage collection.</para></listitem> + + <listitem><para><literal>nix-collect-garbage -d</literal> + removes all old generations of <emphasis>all</emphasis> profiles + before calling the actual garbage collector (<literal>nix-store + --gc</literal>). This is an easy way to get rid of all old + packages in the Nix store.</para></listitem> + + <listitem><para><command>nix-store</command> now has an + operation <option>--delete</option> to delete specific paths + from the Nix store. It won’t delete reachable (non-garbage) + paths unless <option>--ignore-liveness</option> is + specified.</para></listitem> + + </itemizedlist> + + </para></listitem> + + + <listitem><para>Berkeley DB 4.4’s process registry feature is used + to recover from crashed Nix processes.</para></listitem> + + <!-- <listitem><para>TODO: shared stores.</para></listitem> --> + + <listitem><para>A performance issue has been fixed with the + <literal>referer</literal> table, which stores the inverse of the + <literal>references</literal> table (i.e., it tells you what store + paths refer to a given path). Maintaining this table could take a + quadratic amount of time, as well as a quadratic amount of Berkeley + DB log file space (in particular when running the garbage collector) + (<literal>NIX-23</literal>).</para></listitem> + + <listitem><para>Nix now catches the <literal>TERM</literal> and + <literal>HUP</literal> signals in addition to the + <literal>INT</literal> signal. So you can now do a <literal>killall + nix-store</literal> without triggering a database + recovery.</para></listitem> + + <listitem><para><command>bsdiff</command> updated to version + 4.3.</para></listitem> + + <listitem><para>Substantial performance improvements in expression + evaluation and <literal>nix-env -qa</literal>, all thanks to <link xlink:href="http://valgrind.org/">Valgrind</link>. Memory use has + been reduced by a factor 8 or so. Big speedup by memoisation of + path hashing.</para></listitem> + + <listitem><para>Lots of bug fixes, notably: + + <itemizedlist> + + <listitem><para>Make sure that the garbage collector can run + successfully when the disk is full + (<literal>NIX-18</literal>).</para></listitem> + + <listitem><para><command>nix-env</command> now locks the profile + to prevent races between concurrent <command>nix-env</command> + operations on the same profile + (<literal>NIX-7</literal>).</para></listitem> + + <listitem><para>Removed misleading messages from + <literal>nix-env -i</literal> (e.g., <literal>installing + `foo'</literal> followed by <literal>uninstalling + `foo'</literal>) (<literal>NIX-17</literal>).</para></listitem> + + </itemizedlist> + + </para></listitem> + + <listitem><para>Nix source distributions are a lot smaller now since + we no longer include a full copy of the Berkeley DB source + distribution (but only the bits we need).</para></listitem> + + <listitem><para>Header files are now installed so that external + programs can use the Nix libraries.</para></listitem> + +</itemizedlist> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-relnotes-0.9.2"> + +<title>Release 0.9.2 (2005-09-21)</title> + +<para>This bug fix release fixes two problems on Mac OS X: + +<itemizedlist> + + <listitem><para>If Nix was linked against statically linked versions + of the ATerm or Berkeley DB library, there would be dynamic link + errors at runtime.</para></listitem> + + <listitem><para><command>nix-pull</command> and + <command>nix-push</command> intermittently failed due to race + conditions involving pipes and child processes with error messages + such as <literal>open2: open(GLOB(0x180b2e4), >&=9) failed: Bad + file descriptor at /nix/bin/nix-pull line 77</literal> (issue + <literal>NIX-14</literal>).</para></listitem> + +</itemizedlist> + +</para> + +</section> +<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 <= 0.7)</screen> + +then you should unsubscribe from the offending channel +(<command>nix-channel --remove +<replaceable>URL</replaceable></command>; leave out +<literal>/MANIFEST</literal>), and subscribe to the same URL, with +<literal>channels</literal> replaced by <literal>channels-v3</literal> +(e.g., <link xlink:href="http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable"/>).</para> + +<para>Nix 0.8 has the following improvements: + +<itemizedlist> + + <listitem><para>The cryptographic hashes used in store paths are now + 160 bits long, but encoded in base-32 so that they are still only 32 + characters long (e.g., + <filename>/nix/store/csw87wag8bqlqk7ipllbwypb14xainap-atk-1.9.0</filename>). + (This is actually a 160 bit truncation of a SHA-256 + hash.)</para></listitem> + + <listitem><para>Big cleanups and simplifications of the basic store + semantics. The notion of “closure store expressions” is gone (and + so is the notion of “successors”); the file system references of a + store path are now just stored in the database.</para> + + <para>For instance, given any store path, you can query its closure: + + <screen> +$ nix-store -qR $(which firefox) +... lots of paths ...</screen> + + Also, Nix now remembers for each store path the derivation that + built it (the “deriver”): + + <screen> +$ nix-store -qR $(which firefox) +/nix/store/4b0jx7vq80l9aqcnkszxhymsf1ffa5jd-firefox-1.0.1.drv</screen> + + So to see the build-time dependencies, you can do + + <screen> +$ nix-store -qR $(nix-store -qd $(which firefox))</screen> + + or, in a nicer format: + + <screen> +$ nix-store -q --tree $(nix-store -qd $(which firefox))</screen> + + </para> + + <para>File system references are also stored in reverse. For + instance, you can query all paths that directly or indirectly use a + certain Glibc: + + <screen> +$ nix-store -q --referrers-closure \ + /nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4</screen> + + </para> + + </listitem> + + <listitem><para>The concept of fixed-output derivations has been + formalised. Previously, functions such as + <function>fetchurl</function> in Nixpkgs used a hack (namely, + explicitly specifying a store path hash) to prevent changes to, say, + the URL of the file from propagating upwards through the dependency + graph, causing rebuilds of everything. This can now be done cleanly + by specifying the <varname>outputHash</varname> and + <varname>outputHashAlgo</varname> attributes. Nix itself checks + that the content of the output has the specified hash. (This is + important for maintaining certain invariants necessary for future + work on secure shared stores.)</para></listitem> + + <listitem><para>One-click installation :-) It is now possible to + install any top-level component in Nixpkgs directly, through the web + — see, e.g., <link xlink:href="http://catamaran.labs.cs.uu.nl/dist/nixpkgs-0.8/"/>. + All you have to do is associate + <filename>/nix/bin/nix-install-package</filename> with the MIME type + <literal>application/nix-package</literal> (or the extension + <filename>.nixpkg</filename>), and clicking on a package link will + cause it to be installed, with all appropriate dependencies. If you + just want to install some specific application, this is easier than + subscribing to a channel.</para></listitem> + + <listitem><para><command>nix-store -r + <replaceable>PATHS</replaceable></command> now builds all the + derivations PATHS in parallel. Previously it did them sequentially + (though exploiting possible parallelism between subderivations). + This is nice for build farms.</para></listitem> + + <listitem><para><command>nix-channel</command> has new operations + <option>--list</option> and + <option>--remove</option>.</para></listitem> + + <listitem><para>New ways of installing components into user + environments: + + <itemizedlist> + + <listitem><para>Copy from another user environment: + + <screen> +$ nix-env -i --from-profile .../other-profile firefox</screen> + + </para></listitem> + + <listitem><para>Install a store derivation directly (bypassing the + Nix expression language entirely): + + <screen> +$ nix-env -i /nix/store/z58v41v21xd3...-aterm-2.3.1.drv</screen> + + (This is used to implement <command>nix-install-package</command>, + which is therefore immune to evolution in the Nix expression + language.)</para></listitem> + + <listitem><para>Install an already built store path directly: + + <screen> +$ nix-env -i /nix/store/hsyj5pbn0d9i...-aterm-2.3.1</screen> + + </para></listitem> + + <listitem><para>Install the result of a Nix expression specified + as a command-line argument: + + <screen> +$ nix-env -f .../i686-linux.nix -i -E 'x: x.firefoxWrapper'</screen> + + The difference with the normal installation mode is that + <option>-E</option> does not use the <varname>name</varname> + attributes of derivations. Therefore, this can be used to + disambiguate multiple derivations with the same + name.</para></listitem> + + </itemizedlist></para></listitem> + + <listitem><para>A hash of the contents of a store path is now stored + in the database after a successful build. This allows you to check + whether store paths have been tampered with: <command>nix-store + --verify --check-contents</command>.</para></listitem> + + <listitem> + + <para>Implemented a concurrent garbage collector. It is now + always safe to run the garbage collector, even if other Nix + operations are happening simultaneously.</para> + + <para>However, there can still be GC races if you use + <command>nix-instantiate</command> and <command>nix-store + --realise</command> directly to build things. To prevent races, + use the <option>--add-root</option> flag of those commands.</para> + + </listitem> + + <listitem><para>The garbage collector now finally deletes paths in + the right order (i.e., topologically sorted under the “references” + relation), thus making it safe to interrupt the collector without + risking a store that violates the closure + invariant.</para></listitem> + + <listitem><para>Likewise, the substitute mechanism now downloads + files in the right order, thus preserving the closure invariant at + all times.</para></listitem> + + <listitem><para>The result of <command>nix-build</command> is now + registered as a root of the garbage collector. If the + <filename>./result</filename> link is deleted, the GC root + disappears automatically.</para></listitem> + + <listitem> + + <para>The behaviour of the garbage collector can be changed + globally by setting options in + <filename>/nix/etc/nix/nix.conf</filename>. + + <itemizedlist> + + <listitem><para><literal>gc-keep-derivations</literal> specifies + whether deriver links should be followed when searching for live + paths.</para></listitem> + + <listitem><para><literal>gc-keep-outputs</literal> specifies + whether outputs of derivations should be followed when searching + for live paths.</para></listitem> + + <listitem><para><literal>env-keep-derivations</literal> + specifies whether user environments should store the paths of + derivations when they are added (thus keeping the derivations + alive).</para></listitem> + + </itemizedlist> + + </para></listitem> + + <listitem><para>New <command>nix-env</command> query flags + <option>--drv-path</option> and + <option>--out-path</option>.</para></listitem> + + <listitem><para><command>fetchurl</command> allows SHA-1 and SHA-256 + in addition to MD5. Just specify the attribute + <varname>sha1</varname> or <varname>sha256</varname> instead of + <varname>md5</varname>.</para></listitem> + + <listitem><para>Manual updates.</para></listitem> + +</itemizedlist> + +</para> + +</section> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="ch-relnotes-0.7"> + +<title>Release 0.7 (2005-01-12)</title> + +<itemizedlist> + + <listitem><para>Binary patching. When upgrading components using + pre-built binaries (through nix-pull / nix-channel), Nix can + automatically download and apply binary patches to already installed + components instead of full downloads. Patching is “smart”: if there + is a <emphasis>sequence</emphasis> of patches to an installed + component, Nix will use it. Patches are currently generated + automatically between Nixpkgs (pre-)releases.</para></listitem> + + <listitem><para>Simplifications to the substitute + mechanism.</para></listitem> + + <listitem><para>Nix-pull now stores downloaded manifests in + <filename>/nix/var/nix/manifests</filename>.</para></listitem> + + <listitem><para>Metadata on files in the Nix store is canonicalised + after builds: the last-modified timestamp is set to 0 (00:00:00 + 1/1/1970), the mode is set to 0444 or 0555 (readable and possibly + executable by all; setuid/setgid bits are dropped), and the group is + set to the default. This ensures that the result of a build and an + installation through a substitute is the same; and that timestamp + dependencies are revealed.</para></listitem> + +</itemizedlist> + +</section> +<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> |