Nix User's Guide

Nix is a purely functional package manager. This means that it treats packages like values in purely functional programming languages such as Haskell — they are built by functions that don’t have side-effects, and they never change after they have been built. Nix stores packages in the Nix store, usually the directory /nix/store, where each package has its own unique subdirectory such as

/nix/store/r8vvq9kq18pz08v249h8my6r9vs7s0n3-firefox-2.0.0.1/

where r8vvq9kq… 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.

$ nix-env --upgrade some-packages
$ nix-env --rollback

$ nix-env --uninstall firefox

$ nix-collect-garbage

$ nix-env --install firefox

Nix was originally developed at the Department of Information and Computing Sciences, Utrecht University by the TraCE project (2003-2008). The project was funded by the Software Engineering Research Program Jacquard to improve the support for variability in software systems. Further funding is now provided by the NIRICT LaQuSo Build Farm project.

This manual tells you how to install and use Nix and how to write Nix expressions for software not already in the Nix Packages collection. It also discusses some advanced topics, such as setting up a Nix-based build farm.

Nix is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. Nix is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

Some background information on Nix can be found in a number of papers. The ICSE 2004 paper Imposing a Memory Management Discipline on Software Deployment discusses the hashing mechanism used to ensure reliable dependency identification and non-interference between different versions and variants of packages. The LISA 2004 paper Nix: A Safe and Policy-Free System for Software Deployment gives a more general discussion of Nix from a system-administration perspective. The CBSE 2005 paper Efficient Upgrading in a Purely Functional Component Deployment Model is about transparent patch deployment in Nix. The SCM-12 paper Service Configuration Management shows how services (e.g., web servers) can be deployed and managed through Nix. A short overview of NixOS is given in the HotOS XI paper Purely Functional System Configuration Management. The Nix homepage has an up-to-date list of Nix-related papers.

Nix is the subject of Eelco Dolstra’s PhD thesis The Purely Functional Software Deployment Model, which contains most of the papers listed above.

Nix has a homepage at http://nixos.org/.

Nix is currently supported on the following platforms:

Nix is pretty portable, so it should work on most other Unix platforms as well.

The easiest way to obtain Nix is to download a source distribution. RPMs for Red Hat, SuSE, and Fedora Core are also available.

Alternatively, the most recent sources of Nix can be obtained from its Subversion repository. For example, the following command will check out the latest revision into a directory called nix:

$ svn checkout https://svn.nixos.org/repos/nix/nix/trunk nix

Likewise, specific releases can be obtained from the tags directory of the repository.

The following prerequisites only apply when you build from source. Binary releases (e.g., RPMs) have no prerequisites.

A fairly recent version of GCC/G++ is required. Version 2.95 and higher should work.

To build this manual and the man-pages you need the xmllint and xsltproc programs, which are part of the libxml2 and libxslt packages, respectively. You also need the DocBook XSL stylesheets and optionally the DocBook 5.0 RELAX NG schemas. Note that these are only required if you modify the manual sources or when you are building from the Subversion repository.

To build the parser, very recent versions of Bison and Flex are required. (This is because Nix needs GLR support in Bison and reentrancy support in Flex.) For Bison, you need version 2.3 or higher (1.875 does not work), which can be obtained from the GNU FTP server. For Flex, you need version 2.5.33, which is available on SourceForge. 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 Subversion repository.

Nix uses the bzip2 compressor (including the bzip2 library). It is included in the Nix source distribution. If you build from the Subversion repository, you must download it yourself and place it in the externals/ directory. See externals/Makefile.am for the precise URLs of this packages. Alternatively, if you already have it installed, you can use configure's --with-bzip2 options to point to their respective locations.

After unpacking or checking out the Nix sources, issue the following commands:

$ ./configure options...
$ make
$ make install

When building from the Subversion repository, these should be preceded by the command:

$ ./bootstrap.sh

The installation path can be specified by passing the --prefix=prefix to configure. The default installation directory is /usr/local. You can change this to any location you like. You must have write permission to the prefix path.

Nix keeps its store (the place where packages are stored) in /nix/store by default. This can be changed using --with-store-dir=path.

Nix keeps state (such as its database and log files) in /nix/var by default. This can be changed using --localstatedir=path.

If you want to rebuild the documentation, pass the full path to the DocBook RELAX NG schemas and to the DocBook XSL stylesheets using the --with-docbook-rng=path and --with-docbook-xsl=path options.

RPM and Deb packages of Nix for a number of different versions of Fedora, openSUSE, Debian and Ubuntu can be downloaded from http://nixos.org/. Once downloaded, the RPMs can be installed or upgraded using rpm -U. For example,

$ rpm -U nix-0.13pre18104-1.i386.rpm

Likewise, for a Deb package:

$ dpkg -i nix_0.13pre18104-1_amd64.deb

Nix can be uninstalled using rpm -e nix or dpkg -r nix. After this you should manually remove the Nix store and other auxiliary data, if desired:

$ rm -rf /nix/store
$ rm -rf /nix/var

Nix has two basic security models. First, it can be used in “single-user mode”, which is similar to what most other package management tools do: there is a single user (typically root) who performs all package management operations. All other users can then use the installed packages, but they cannot perform package management operations themselves.

Alternatively, you can configure Nix in “multi-user mode”. In this model, all users can perform package management operations — for instance, every user can install software without requiring root privileges. Nix ensures that this is secure. For instance, it’s not possible for one user to overwrite a package used by another user with a Trojan horse.

nixbld:!:30000:nixbld1,nixbld2,nixbld3,nixbld4,nixbld5,nixbld6,nixbld7,nixbld8,nixbld9,nixbld10

nixbld1:x:30001:65534:Nix build user 1:/var/empty:/noshell
nixbld2:x:30002:65534:Nix build user 2:/var/empty:/noshell
nixbld3:x:30003:65534:Nix build user 3:/var/empty:/noshell
...
nixbld10:x:30010:65534:Nix build user 10:/var/empty:/noshell

$ chgrp nixbld /nix/store
$ chmod 1777 /nix/store

build-users-group = nixbld

$ chown -R root /nix/store /nix/var/nix

$ nix-worker --daemon

export NIX_REMOTE=daemon

$ chown -R root /nix/store /nix/var/nix

$ su - nix -c "exec /nix/bin/nix-worker --daemon"

$ chown root.root /nix/libexec/nix-setuid-helper
$ chmod 4755 /nix/libexec/nix-setuid-helper

nix
nixbld

$ chgrp nix-users /nix/var/nix/daemon-socket
$ chmod ug=rwx,o= /nix/var/nix/daemon-socket

To use Nix, some environment variables should be set. In particular, PATH should contain the directories prefix/bin and ~/.nix-profile/bin. The first directory contains the Nix tools themselves, while ~/.nix-profile is a symbolic link to the current user environment (an automatically generated package consisting of symlinks to installed packages). The simplest way to set the required environment variables is to include the file prefix/etc/profile.d/nix.sh in your ~/.bashrc (or similar), like this:

source prefix/etc/profile.d/nix.sh

The main command for package management is nix-env. You can use it to install, upgrade, and erase packages, and to query what packages are installed or are available for installation.

In Nix, different users can have different “views” on the set of installed applications. That is, there might be lots of applications present on the system (possibly in many different versions), but users can have a specific selection of those active — where “active” just means that it appears in a directory in the user’s PATH. Such a view on the set of installed applications is called a user environment, which is just a directory tree consisting of symlinks to the files of the active applications.

Components are installed from a set of Nix expressions that tell Nix how to build those packages, including, if necessary, their dependencies. There is a collection of Nix expressions called the Nix Package collection that contains packages ranging from basic development stuff such as GCC and Glibc, to end-user applications like Mozilla Firefox. (Nix is however not tied to the Nix Package collection; you could write your own Nix expressions based on it, or completely new ones.) You can download the latest version from http://nixos.org/nixpkgs/download.html.

Assuming that you have downloaded and unpacked a release of Nix Packages, you can view the set of available packages in the release:

$ nix-env -qaf nixpkgs-version '*'
ant-blackdown-1.4.2
aterm-2.2
bash-3.0
binutils-2.15
bison-1.875d
blackdown-1.4.2
bzip2-1.0.2
...

where nixpkgs-version is where you’ve unpacked the release. The flag -q specifies a query operation; -a means that you want to show the “available” (i.e., installable) packages, as opposed to the installed packages; and -f nixpkgs-version specifies the source of the packages. The argument '*' shows all installable packages. (The quotes are necessary to prevent shell expansion.) You can also select specific packages by name:

$ nix-env -qaf nixpkgs-version gcc
gcc-3.4.6
gcc-4.0.3
gcc-4.1.1

It is also possible to see the status of available packages, i.e., whether they are installed into the user environment and/or present in the system:

$ nix-env -qasf nixpkgs-version '*'
...
-PS bash-3.0
--S binutils-2.15
IPS bison-1.875d
...

The first character (I) indicates whether the package is installed in your current user environment. The second (P) indicates whether it is present on your system (in which case installing it into your user environment would be a very quick operation). The last one (S) indicates whether there is a so-called substitute for the package, which is Nix’s mechanism for doing binary deployment. It just means that Nix knows that it can fetch a pre-built package from somewhere (typically a network server) instead of building it locally.

So now that we have a set of Nix expressions we can build the packages contained in them. This is done using nix-env -i. For instance,

$ nix-env -f nixpkgs-version -i subversion

will install the package called subversion (which is, of course, the Subversion version management system).

When you do this for the first time, Nix will start building Subversion and all its dependencies. This will take quite a while — typically an hour or two on modern machines. Fortunately, there is a faster way (so do a Ctrl-C on that install operation!): you just need to tell Nix that pre-built binaries of all those packages are available somewhere. This is done using the nix-pull command, which must be supplied with a URL containing a manifest describing what binaries are available. This URL should correspond to the Nix Packages release that you’re using. For instance, if you obtained a release from http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x, then you should do:

$ nix-pull http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x/MANIFEST

If you then issue the installation command, it should start downloading binaries from nixos.org, instead of building them from source. This might still take a while since all dependencies must be downloaded, but on a reasonably fast connection such as an DSL line it’s on the order of a few minutes.

Naturally, packages can also be uninstalled:

$ nix-env -e subversion

Upgrading to a new version is just as easy. If you have a new release of Nix Packages, you can do:

$ nix-env -f nixpkgs-version -u subversion

This will only upgrade Subversion if there is a “newer” version in the new set of Nix expressions, as defined by some pretty arbitrary rules regarding ordering of version numbers (which generally do what you’d expect of them). To just unconditionally replace Subversion with whatever version is in the Nix expressions, use -i instead of -u; -i will remove whatever version is already installed.

You can also upgrade all packages for which there are newer versions:

$ nix-env -f nixpkgs-version -u '*'

Sometimes it’s useful to be able to ask what nix-env would do, without actually doing it. For instance, to find out what packages would be upgraded by nix-env -u '*', you can do

$ nix-env ... -u '*' --dry-run
(dry run; not doing anything)
upgrading `libxslt-1.1.0' to `libxslt-1.1.10'
upgrading `graphviz-1.10' to `graphviz-1.12'
upgrading `coreutils-5.0' to `coreutils-5.2.1'

If you grow bored of specifying the Nix expressions using -f all the time, you can set a default location:

$ nix-env -I nixpkgs-version

After this you can just say, for instance, nix-env -u '*'.^[2]

Profiles and user environments are Nix’s mechanism for implementing the ability to allow different users to have different configurations, and to do atomic upgrades and rollbacks. To understand how they work, it’s useful to know a bit about how Nix works. In Nix, packages are stored in unique locations in the Nix store (typically, /nix/store). For instance, a particular version of the Subversion package might be stored in a directory /nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/, while another version might be stored in /nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2. The long strings prefixed to the directory names are cryptographic hashes^[3] of all inputs involved in building the package — sources, dependencies, compiler flags, and so on. So if two packages differ in any way, they end up in different locations in the file system, so they don’t interfere with each other. Figure 4.1, “User environments” shows a part of a typical Nix store.

Figure 4.1. User environments

Of course, you wouldn’t want to type

$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn

every time you want to run Subversion. Of course we could set up the PATH environment variable to include the bin directory of every package we want to use, but this is not very convenient since changing PATH doesn’t take effect for already existing processes. The solution Nix uses is to create directory trees of symlinks to activated packages. These are called user environments and they are packages themselves (though automatically generated by nix-env), so they too reside in the Nix store. For instance, in Figure 4.1, “User environments” the user environment /nix/store/5mq2jcn36ldl...-user-env contains a symlink to just Subversion 1.1.2 (arrows in the figure indicate symlinks). This would be what we would obtain if we had done

$ nix-env -i subversion

on a set of Nix expressions that contained Subversion 1.1.2.

This doesn’t in itself solve the problem, of course; you wouldn’t want to type /nix/store/0c1p5z4kda11...-user-env/bin/svn either. That’s why there are symlinks outside of the store that point to the user environments in the store; for instance, the symlinks default-42-link and default-43-link in the example. These are called generations since every time you perform a nix-env operation, a new user environment is generated based on the current one. For instance, generation 43 was created from generation 42 when we did

$ nix-env -i subversion mozilla

on a set of Nix expressions that contained Mozilla and a new version of Subversion.

Generations are grouped together into profiles so that different users don’t interfere with each other if they don’t want to. For example:

$ ls -l /nix/var/nix/profiles/
...
lrwxrwxrwx  1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env
lrwxrwxrwx  1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env
lrwxrwxrwx  1 eelco ... default -> default-43-link

This shows a profile called default. The file default itself is actually a symlink that points to the current generation. When we do a nix-env operation, a new user environment and generation link are created based on the current one, and finally the default symlink is made to point at the new generation. This last step is atomic on Unix, which explains how we can do atomic upgrades. (Note that the building/installing of new packages doesn’t interfere in any way with old packages, since they are stored in different locations in the Nix store.)

If you find that you want to undo a nix-env operation, you can just do

$ nix-env --rollback

which will just make the current generation link point at the previous link. E.g., default would be made to point at default-42-link. You can also switch to a specific generation:

$ nix-env --switch-generation 43

which in this example would roll forward to generation 43 again. You can also see all available generations:

$ nix-env --list-generations

Actually, there is another level of indirection not shown in the figure above. You generally wouldn’t have /nix/var/nix/profiles/some-profile/bin in your PATH. Rather, there is a symlink ~/.nix-profile that points to your current profile. This means that you should put ~/.nix-profile/bin in your PATH (and indeed, that’s what the initialisation script /nix/etc/profile.d/nix.sh does). This makes it easier to switch to a different profile. You can do that using the command nix-env --switch-profile:

$ nix-env --switch-profile /nix/var/nix/profiles/my-profile

$ nix-env --switch-profile /nix/var/nix/profiles/default

These commands switch to the my-profile and default profile, respectively. If the profile doesn’t exist, it will be created automatically. You should be careful about storing a profile in another location than the profiles directory, since otherwise it might not be used as a root of the garbage collector (see Section 4.3, “Garbage collection”).

All nix-env operations work on the profile pointed to by ~/.nix-profile, but you can override this using the --profile option (abbreviation -p):

$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion

This will not change the ~/.nix-profile symlink.

nix-env operations such as upgrades (-u) and uninstall (-e) never actually delete packages from the system. All they do (as shown above) is to create a new user environment that no longer contains symlinks to the “deleted” packages.

Of course, since disk space is not infinite, unused packages should be removed at some point. You can do this by running the Nix garbage collector. It will remove from the Nix store any package not used (directly or indirectly) by any generation of any profile.

Note however that as long as old generations reference a package, it will not be deleted. After all, we wouldn’t be able to do a rollback otherwise. So in order for garbage collection to be effective, you should also delete (some) old generations. Of course, this should only be done if you are certain that you will not need to roll back.

To delete all old (non-current) generations of your current profile:

$ nix-env --delete-generations old

Instead of old you can also specify a list of generations, e.g.,

$ nix-env --delete-generations 10 11 14

After removing appropriate old generations you can run the garbage collector as follows:

$ nix-store --gc

If you are feeling uncertain, you can also first view what files would be deleted:

$ nix-store --gc --print-dead

Likewise, the option --print-live will show the paths that won’t be deleted.

There is also a convenient little utility nix-collect-garbage, which when invoked with the -d (--delete-old) switch deletes all old generations of all profiles in /nix/var/nix/profiles. So

$ nix-collect-garbage -d

is a quick and easy way to clean up your system.

$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar

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, use nix-pull to register pre-built binaries (if available), and upgrade using nix-env. Fortunately, there’s a better way: Nix channels.

A Nix channel is just a URL that points to a place that contains a set of Nix expressions and a manifest. Using the command nix-channel you can automatically stay up to date with whatever is available at that URL.

You can “subscribe” to a channel using nix-channel --add, e.g.,

$ nix-channel --add http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable

subscribes you to a channel that always contains that latest version of the Nix Packages collection. (Instead of nixpkgs-unstable you could also subscribe to nixpkgs-stable, which should have a higher level of stability, but right now is just outdated.) Subscribing really just means that the URL is added to the file ~/.nix-channels. Right now there is no command to “unsubscribe”; you should just edit that file manually and delete the offending URL.

To obtain the latest Nix expressions available in a channel, do

$ nix-channel --update

This downloads the Nix expressions in every channel (downloaded from url/nixexprs.tar.bz2) and registers any available pre-built binaries in every channel (by nix-pulling url/MANIFEST). It also makes the union of each channel’s Nix expressions the default for nix-env operations. Consequently, you can then say

$ nix-env -u '*'

to upgrade all packages in your profile to the latest versions available in the subscribed channels.

Often, when you want to install a specific package (e.g., from the Nix Packages collection), subscribing to a channel is a bit cumbersome. And channels don’t help you at all if you want to install an older version of a package than the one provided by the current contents of the channel, or a package that has been removed from the channel. That’s when one-click installs come in handy: you can just go to the web page that contains the package, click on it, and it will be installed with all the necessary dependencies.

For instance, you can go to http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest and click on any link for the individual packages for your platform. The first time you do this, your browser will ask what to do with application/nix-package files. You should open them with /nix/bin/nix-install-package. This will open a window that asks you to confirm that you want to install the package. When you answer Y, the package and all its dependencies will be installed. This is a binary deployment mechanism — you get packages pre-compiled for the selected platform type.

You can also install application/nix-package files from the command line directly. See nix-install-package(1) for details.

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.

The command nix-copy-closure copies a Nix store path along with all its dependencies to or from another machine via the SSH protocol. It doesn’t copy store paths that are already present on the target machine. For example, the following command copies Firefox with all its dependencies:

$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)

See nix-copy-closure(1) for details.

With nix-store --export and nix-store --import you can write the closure of a store path (that is, the path and all its dependencies) to a file, and then unpack that file into another Nix store. For example,

$ nix-store --export $(type -p firefox) > firefox.closure

writes the closure of Firefox to a file. You can then copy this file to another machine and install the closure:

$ nix-store --import < firefox.closure

Any store paths in the closure that are already present in the target store are ignored. It is also possible to pipe the export into another command, e.g. to copy and install a closure directly to/on another machine:

$ nix-store --export $(type -p firefox) | bzip2 | \
    ssh alice@itchy.example.org "bunzip2 | nix-store --import"

But note that nix-copy-closure is generally more efficient in this example because it only copies paths that are not already present in the target Nix store.

Finally, if you can mount the Nix store of a remote machine in your local filesystem, Nix can copy paths from the remote Nix store to the local Nix store on demand. For instance, suppose that you mount a remote machine containing a Nix store via sshfs:

$ sshfs alice@itchy.example.org:/ /mnt

You should then set the NIX_OTHER_STORES environment variable to tell Nix about this remote Nix store:

$ export NIX_OTHER_STORES=/mnt/nix

Then if you do any Nix operation, e.g.

$ nix-env -i firefox

and Nix has to build a path that it sees is already present in /mnt/nix, then it will just copy from there instead of building it from source.

This section shows how to add and test the GNU Hello package to the Nix Packages collection. Hello is a program that prints out the text “Hello, world!”.

To add a package to the Nix Packages collection, you generally need to do three things:

{stdenv, fetchurl, perl}: 

stdenv.mkDerivation { 
  name = "hello-2.1.1"; 
  builder = ./builder.sh; 
  src = fetchurl { 
    url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
    md5 = "70c9ccf9fac07f762c24f2df2290784d";
  };
  inherit perl; 
}

perl = perl;

source $stdenv/setup 

PATH=$perl/bin:$PATH 

tar xvfz $src 
cd hello-*
./configure --prefix=$out 
make 
make install

...

rec { 
  
  hello = (import ../applications/misc/hello/ex-1 ) { 
    inherit fetchurl stdenv perl;
  };

  perl = (import ../development/interpreters/perl) { 
    inherit fetchurl stdenv;
  };

  fetchurl = (import ../build-support/fetchurl) { 
    inherit stdenv; ...
  };
  
  stdenv = ...;

}

$ nix-build pkgs/top-level/all-packages.nix -A hello
building path `/nix/store/632d2b22514d...-hello-2.1.1'
hello-2.1.1/
hello-2.1.1/intl/
hello-2.1.1/intl/ChangeLog
...

$ ls -l result
lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1

$ ./result/bin/hello
Hello, world!

$ nix-build pkgs/top-level/all-packages.nix -A hello
waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x'

PATH=$perl/bin:$PATH
tar xvfz $src
cd hello-*
./configure --prefix=$out
make
make install

buildInputs="$perl" 

source $stdenv/setup 

genericBuild 

  buildInputs = [perl];

source $stdenv/setup
genericBuild

The Nix expression language is a pure, lazy, functional language. Purity means that operations in the language don't have side-effects (for instance, there is no variable assignment). Laziness means that arguments to functions are evaluated only when they are needed. Functional means that functions are “normal” values that can be passed around and manipulated in interesting ways. The language is not a full-featured, general purpose language. It's main job is to describe packages, compositions of packages, and the variability within packages.

This section presents the various features of the language.

[ 123 ./foo.nix "abc" (f {x=y;}) ]

[ 123 ./foo.nix "abc" f {x=y;} ]

{ x = 123;
  text = "Hello";
  y = f { bla = 456; };
}

{ a = "Foo"; b = "Bar"; }.a

rec {
  x = y;
  y = 123;
}.x

rec {
  x = y;
  y = x;
}.x

let
  x = "foo";
  y = "bar";
in x + y

let
  x = 123;
in 
  {
    inherit x;
    y = 456;
  }

  graphviz = (import ../tools/graphics/graphviz) {
    inherit fetchurl stdenv libpng libjpeg expat x11 yacc;
    inherit (xlibs) libXaw;
  };

  xlibs = {
    libX11 = ...;
    libXaw = ...;
    ...
  }

  libpng = ...;
  libjpg = ...;
  ...

pattern: body

let concat = {x, y}: x + y;
in concat {x = "foo"; y = "bar";}

if e1 then e2 else e3

assert e1; e2

{ localServer ? false
, httpServer ? false
, sslSupport ? false
, pythonBindings ? false
, javaSwigBindings ? false
, javahlBindings ? false
, stdenv, fetchurl
, openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null
}:

assert localServer -> db4 != null; 
assert httpServer -> httpd != null && httpd.expat == expat; 
assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); 
assert pythonBindings -> swig != null && swig.pythonSupport;
assert javaSwigBindings -> swig != null && swig.javaSupport;
assert javahlBindings -> j2sdk != null;

stdenv.mkDerivation {
  name = "subversion-1.1.1";
  ...
  openssl = if sslSupport then openssl else null; 
  ...
}

with e1; e2

let as = {x = "foo"; y = "bar";};
in with as; x + y

with (import ./definitions.nix); ...

The standard environment is used by passing it as an input called stdenv to the derivation, and then doing

source $stdenv/setup

at the top of the builder.

Apart from adding the aforementioned commands to the PATH, setup also does the following:

The setup script also exports a function called genericBuild that knows how to build typical Autoconf-style packages. It can be customised to perform builds for any type of package. It is advisable to use genericBuild since it provides facilities that are almost always useful such as unpacking of sources, patching of sources, nested logging, etc.

The definitive, up-to-date documentation of the generic builder is the source itself, which resides in pkgs/stdenv/generic/setup.sh.

postInstall=myPostInstall

myPostInstall() {
    mkdir $out/share/extra
    cp extrafiles/* $out/share/extra
}

$ nix-build -K ./foo.nix
... fails, keeping build directory `/tmp/nix-1234-0'

$ cd /tmp/nix-1234-0

$ source env-vars

(edit some files...)

$ make

(execution continues with the same GCC, make, etc.)

TODO

The sources of the Nix build farm are at https://svn.nixos.org/repos/nix/release/trunk.

You can enable distributed builds by setting the environment variable NIX_BUILD_HOOK to point to a program that Nix will call whenever it wants to build a derivation. The build hook (typically a shell or Perl script) can decline the build, in which Nix will perform it in the usual way if possible, or it can accept it, in which case it is responsible for somehow getting the inputs of the build to another machine, doing the build there, and getting the results back. The details of the build hook protocol are described in the documentation of the NIX_BUILD_HOOK variable.

nix@mcflurry.labs.cs.uu.nl  powerpc-darwin  /home/nix/.ssh/id_quarterpounder_auto  2
nix@scratchy.labs.cs.uu.nl  i686-linux      /home/nix/.ssh/id_scratchy_auto        1

An example build hook can be found in the Nix build farm sources: https://svn.nixos.org/repos/nix/release/trunk/common/distributed/build-remote.pl. It should be suitable for most purposes, with maybe some minor adjustments. It uses ssh and rsync to copy the build inputs and outputs and perform the remote build. You should define a list of available build machines and set the environment variable REMOTE_SYSTEMS to point to it. An example configuration is shown in Example 6.1, “Remote machine configuration: remote-systems.conf”. Each line in the file specifies a machine, with the following bits of information:

You should also set up the environment variable CURRENT_LOAD to point at a file that build-remote.pl uses to remember how many jobs it is currently executing remotely. It doesn't look at the actual load on the remote machine, so if you have multiple instances of Nix running, they should use the same CURRENT_LOAD file^[10]. Maybe in the future build-remote.pl will look at the actual remote load. The load file should exist, so you should just create it as an empty file initially.