max/nix-super
1
0
Fork 0
mirror of https://github.com/privatevoid-net/nix-super.git synced 2024-11-22 05:56:15 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Pandoc conversion

Browse source
This commit is contained in:
Eelco Dolstra 2020-07-22 23:17:48 +02:00
parent d004715665
commit ef606760ab
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
84 changed files with 6715 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
doc/manual/manual.md
View file

@ -1,8 +0,0 @@
Title: Nix Package Manager Guide
1. Introduction
1. [About Nix](./introduction/about-nix.md)
1. [Quick Start](./introduction/quick-start.md)
1. Command Reference
1. Utilities
1. [nix-copy-closure](./command-ref/nix-copy-closure.md)

90
doc/manual/src/SUMMARY.md
View file

@ -1,7 +1,87 @@
# Table of Contents
- [Introduction](./introduction.md)
- [Quick Start](./quick-start.md)
- [Command Reference](./command-ref/command-ref.md)
- [Utilities](./command-ref/utilities.md)
- [nix-copy-closure](./command-ref/nix-copy-closure.md)
- [Introduction](introduction.md)
- [Quick Start](quick-start.md)
- [Installation](installation/installation.md)
- [Supported Platforms](installation/supported-platforms.md)
- [Installing a Binary Distribution](installation/installing-binary.md)
- [Installing Nix from Source](installation/installing-source.md)
- [Prerequisites](installation/prerequisites-source.md)
- [Obtaining a Source Distribution](installation/obtaining-source.md)
- [Building Nix from Source](installation/building-source.md)
- [Security](installation/nix-security.md)
- [Single-User Mode](installation/single-user.md)
- [Multi-User Mode](installation/multi-user.md)
- [Environment Variables](installation/env-variables.md)
- [Upgrading Nix](installation/upgrading.md)
- [Package Management](package-management/package-management.md)
- [Basic Package Management](package-management/basic-package-mgmt.md)
- [Profiles](package-management/profiles.md)
- [Garbage Collection](package-management/garbage-collection.md)
- [Garbage Collector Roots](package-management/garbage-collector-roots.md)
- [Channels](package-management/channels.md)
- [Sharing Packages Between Machines](package-management/sharing-packages.md)
- [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md)
- [Copying Closures Via SSH](package-management/copy-closure.md)
- [Serving a Nix store via SSH](package-management/ssh-substituter.md)
- [Serving a Nix store via AWS S3 or S3-compatible Service](package-management/s3-substituter.md)
- [Writing Nix Expressions](expressions/writing-nix-expressions.md)
- [A Simple Nix Expression](expressions/simple-expression.md)
- [Expression Syntax](expressions/expression-syntax.md)
- [Build Script](expressions/build-script.md)
- [Arguments and Variables](expressions/arguments-variables.md)
- [Building and Testing](expressions/simple-building-testing.md)
- [Generic Builder Syntax](expressions/generic-builder.md)
- [Writing Nix Expressions](expressions/expression-language.md)
- [Values](expressions/language-values.md)
- [Language Constructs](expressions/language-constructs.md)
- [Operators](expressions/language-operators.md)
- [Derivations](expressions/derivations.md)
- [Advanced Attributes](expressions/advanced-attributes.md)
- [Built-in Functions](expressions/builtins.md)
- [Advanced Topics](advanced-topics/advanced-topics.md)
- [Remote Builds](advanced-topics/distributed-builds.md)
- [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md)
- [Verifying Build Reproducibility](advanced-topics/diff-hook.md)
- [Using the `post-build-hook`](advanced-topics/post-build-hook.md)
- [Command Reference](command-ref/command-ref.md)
- [Utilities](command-ref/utilities.md)
- [nix-copy-closure](command-ref/nix-copy-closure.md)
- [Glossary](glossary.md)
- [Hacking](hacking.md)
- [Release Notes](release-notes/release-notes.md)
- [Release 2.3 (2019-09-04)](release-notes/rl-2.3.md)
- [Release 2.2 (2019-01-11)](release-notes/rl-2.2.md)
- [Release 2.1 (2018-09-02)](release-notes/rl-2.1.md)
- [Release 2.0 (2018-02-22)](release-notes/rl-2.0.md)
- [Release 1.11.10 (2017-06-12)](release-notes/rl-1.11.10.md)
- [Release 1.11 (2016-01-19)](release-notes/rl-1.11.md)
- [Release 1.10 (2015-09-03)](release-notes/rl-1.10.md)
- [Release 1.9 (2015-06-12)](release-notes/rl-1.9.md)
- [Release 1.8 (2014-12-14)](release-notes/rl-1.8.md)
- [Release 1.7 (2014-04-11)](release-notes/rl-1.7.md)
- [Release 1.6.1 (2013-10-28)](release-notes/rl-1.6.1.md)
- [Release 1.6 (2013-09-10)](release-notes/rl-1.6.md)
- [Release 1.5.2 (2013-05-13)](release-notes/rl-1.5.2.md)
- [Release 1.5 (2013-02-27)](release-notes/rl-1.5.md)
- [Release 1.4 (2013-02-26)](release-notes/rl-1.4.md)
- [Release 1.3 (2013-01-04)](release-notes/rl-1.3.md)
- [Release 1.2 (2012-12-06)](release-notes/rl-1.2.md)
- [Release 1.1 (2012-07-18)](release-notes/rl-1.1.md)
- [Release 1.0 (2012-05-11)](release-notes/rl-1.0.md)
- [Release 0.16 (2010-08-17)](release-notes/rl-0.16.md)
- [Release 0.15 (2010-03-17)](release-notes/rl-0.15.md)
- [Release 0.14 (2010-02-04)](release-notes/rl-0.14.md)
- [Release 0.13 (2009-11-05)](release-notes/rl-0.13.md)
- [Release 0.12 (2008-11-20)](release-notes/rl-0.12.md)
- [Release 0.11 (2007-12-31)](release-notes/rl-0.11.md)
- [Release 0.10.1 (2006-10-11)](release-notes/rl-0.10.1.md)
- [Release 0.10 (2006-10-06)](release-notes/rl-0.10.md)
- [Release 0.9.2 (2005-09-21)](release-notes/rl-0.9.2.md)
- [Release 0.9.1 (2005-09-20)](release-notes/rl-0.9.1.md)
- [Release 0.9 (2005-09-16)](release-notes/rl-0.9.md)
- [Release 0.8.1 (2005-04-13)](release-notes/rl-0.8.1.md)
- [Release 0.8 (2005-04-11)](release-notes/rl-0.8.md)
- [Release 0.7 (2005-01-12)](release-notes/rl-0.7.md)
- [Release 0.6 (2004-11-14)](release-notes/rl-0.6.md)
- [Release 0.5 and earlier](release-notes/rl-0.5.md)

1
doc/manual/src/advanced-topics/advanced-topics.md Normal file
View file

@ -0,0 +1 @@

42
doc/manual/src/advanced-topics/cores-vs-jobs.md Normal file
View file

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

141
doc/manual/src/advanced-topics/diff-hook.md Normal file
View file

@ -0,0 +1,141 @@
# Verifying Build Reproducibility
Specify a program with Nix's [???](#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.
For purposes of demonstration, we'll use the following Nix file,
`deterministic.nix` for testing:
let
inherit (import <nixpkgs> {}) runCommand;
in {
stable = runCommand "stable" {} ''
touch $out
'';
unstable = runCommand "unstable" {} ''
echo $RANDOM > $out
'';
}
Additionally, `nix.conf` contains:
diff-hook = /etc/nix/my-diff-hook
run-diff-hook = true
where `/etc/nix/my-diff-hook` is an executable file containing:
#!/bin/sh
exec >&2
echo "For derivation $3:"
/run/current-system/sw/bin/diff -r "$1" "$2"
The diff hook is executed by the same user and group who ran the build.
However, the diff hook does not have write access to the store path just
built.
# Spot-Checking Build Determinism
Verify a path which already exists in the Nix store by passing `--check`
to the build command.
If the build passes and is deterministic, Nix will exit with a status
code of 0:
$ nix-build ./deterministic.nix -A stable
this derivation will be built:
/nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv
building '/nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv'...
/nix/store/yyxlzw3vqaas7wfp04g0b1xg51f2czgq-stable
$ nix-build ./deterministic.nix -A stable --check
checking outputs of '/nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv'...
/nix/store/yyxlzw3vqaas7wfp04g0b1xg51f2czgq-stable
If the build is not deterministic, Nix will exit with a status code of
1:
$ nix-build ./deterministic.nix -A unstable
this derivation will be built:
/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv
building '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'...
/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable
$ nix-build ./deterministic.nix -A unstable --check
checking outputs of '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'...
error: derivation '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv' may not be deterministic: output '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable' differs
In the Nix daemon's log, we will now see:
For derivation /nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv:
1c1
< 8108
---
> 30204
Using `--check` with `--keep-failed` will cause Nix to keep the second
build's output in a special, `.check` path:
$ nix-build ./deterministic.nix -A unstable --check --keep-failed
checking outputs of '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'...
note: keeping build directory '/tmp/nix-build-unstable.drv-0'
error: derivation '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv' may not be deterministic: output '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable' differs from '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check'
In particular, notice the
`/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check` output. Nix
has copied the build results to that directory where you can examine it.
> **Note**
>
> Check paths are not protected against garbage collection, and this
> path will be deleted on the next garbage collection.
>
> The path is guaranteed to be alive for the duration of
> [???](#conf-diff-hook)'s execution, but may be deleted any time after.
>
> If the comparison is performed as part of automated tooling, please
> use the diff-hook or author your tooling to handle the case where the
> build was not deterministic and also a check path does not exist.
`--check` is only usable if the derivation has been built on the system
already. If the derivation has not been built Nix will fail with the
error:
error: some outputs of '/nix/store/hzi1h60z2qf0nb85iwnpvrai3j2w7rr6-unstable.drv' are not valid, so checking is not possible
Run the build without `--check`, and then try with `--check` again.
# Automatic and Optionally Enforced Determinism Verification
Automatically verify every build at build time by executing the build
multiple times.
Setting [???](#conf-repeat) and [???](#conf-enforce-determinism) in your
`nix.conf` permits the automated verification of every build Nix
performs.
The following configuration will run each build three times, and will
require the build to be deterministic:
enforce-determinism = true
repeat = 2
Setting [???](#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:
enforce-determinism = false
repeat = 1
An example output of this configuration:
$ nix-build ./test.nix -A unstable
this derivation will be built:
/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv
building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 1/2)...
building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 2/2)...
output '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable' of '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' differs from '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable.check' from previous round
/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable

141
doc/manual/src/advanced-topics/distributed-builds.md Normal file
View file

@ -0,0 +1,141 @@
# Remote Builds
Nix supports remote builds, where a local Nix installation can forward
Nix builds to other machines. This allows multiple builds to be
performed in parallel and allows Nix to perform multi-platform builds in
a semi-transparent way. For instance, if you perform a build for a
`x86_64-darwin` on an `i686-linux` machine, Nix can automatically
forward the build to a `x86_64-darwin` machine, if available.
To forward a build to a remote machine, it’s required that the remote
machine is accessible via SSH and that it has Nix installed. You can
test whether connecting to the remote Nix instance works, e.g.
$ nix ping-store --store ssh://mac
will try to connect to the machine named `mac`. It is possible to
specify an SSH identity file as part of the remote store URI, e.g.
$ nix ping-store --store ssh://mac?ssh-key=/home/alice/my-key
Since builds should be non-interactive, the key should not have a
passphrase. Alternatively, you can load identities ahead of time into
`ssh-agent` or `gpg-agent`.
If you get the error
bash: nix-store: command not found
error: cannot connect to 'mac'
then you need to ensure that the PATH of non-interactive login shells
contains Nix.
> **Warning**
>
> If you are building via the Nix daemon, it is the Nix daemon user
> account (that is, `root`) that should have SSH access to the remote
> machine. If you can’t or don’t want to configure `root` to be able to
> access to remote machine, you can use a private Nix store instead by
> passing e.g. `--store ~/my-nix`.
The list of remote machines can be specified on the command line or in
the Nix configuration file. The former is convenient for testing. For
example, the following command allows you to build a derivation for
`x86_64-darwin` on a Linux machine:
$ uname
Linux
$ nix build \
'(with import <nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \
--builders 'ssh://mac x86_64-darwin'
[1/0/1 built, 0.0 MiB DL] building foo on ssh://mac
$ cat ./result
Darwin
It is possible to specify multiple builders separated by a semicolon or
a newline, e.g.
```
--builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd'
```
Each machine specification consists of the following elements, separated
by spaces. Only the first element is required. To leave a field at its
default, set it to `-`.
1. The URI of the remote store in the format
`ssh://[username@]hostname`, e.g. `ssh://nix@mac` or `ssh://mac`.
For backward compatibility, `ssh://` may be omitted. The hostname
may be an alias defined in your `~/.ssh/config`.
2. A comma-separated list of Nix platform type identifiers, such as
`x86_64-darwin`. It is possible for a machine to support multiple
platform types, e.g., `i686-linux,x86_64-linux`. If omitted, this
defaults to the local platform type.
3. The SSH identity file to be used to log in to the remote machine. If
omitted, SSH will use its regular identities.
4. The maximum number of builds that Nix will execute in parallel on
the machine. Typically this should be equal to the number of CPU
cores. For instance, the machine `itchy` in the example will execute
up to 8 builds in parallel.
5. The “speed factor”, indicating the relative speed of the machine. If
there are multiple machines of the right type, Nix will prefer the
fastest, taking load into account.
6. A comma-separated list of *supported features*. If a derivation has
the `requiredSystemFeatures` attribute, then Nix will only perform
the derivation on a machine that has the specified features. For
instance, the attribute
requiredSystemFeatures = [ "kvm" ];
will cause the build to be performed on a machine that has the `kvm`
feature.
7. A comma-separated list of *mandatory features*. A machine will only
be used to build a derivation if all of the machine’s mandatory
features appear in the derivation’s `requiredSystemFeatures`
attribute..
For example, the machine specification
nix@scratchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 1 kvm
nix@itchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 2
nix@poochie.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 1 2 kvm benchmark
specifies several machines that can perform `i686-linux` builds.
However, `poochie` will only do builds that have the attribute
requiredSystemFeatures = [ "benchmark" ];
or
requiredSystemFeatures = [ "benchmark" "kvm" ];
`itchy` cannot do builds that require `kvm`, but `scratchy` does support
such builds. For regular builds, `itchy` will be preferred over
`scratchy` because it has a higher speed factor.
Remote builders can also be configured in `nix.conf`, e.g.
builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd
Finally, remote builders can be configured in a separate configuration
file included in `builders` via the syntax `@file`. For example,
builders = @/etc/nix/machines
causes the list of machines in `/etc/nix/machines` to be included. (This
is the default.)
If you want the builders to use caches, you likely want to set the
option [`builders-use-substitutes`](#conf-builders-use-substitutes) in
your local `nix.conf`.
To build only on remote builders and disable building on the local
machine, you can use the option `--max-jobs 0`.

113
doc/manual/src/advanced-topics/post-build-hook.md Normal file
View file

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

233
doc/manual/src/expressions/advanced-attributes.md Normal file
View file

@ -0,0 +1,233 @@
# Advanced Attributes
Derivations can declare some infrequently used optional attributes.
- `allowedReferences`
The optional attribute `allowedReferences` specifies a list of legal
references (dependencies) of the output of the builder. For example,
allowedReferences = [];
enforces that the output of a derivation cannot have any runtime
dependencies on its inputs. To allow an output to have a runtime
dependency on itself, use `"out"` as a list item. This is used in
NixOS to check that generated files such as initial ramdisks for
booting Linux don’t have accidental dependencies on other paths in
the Nix store.
- `allowedRequisites`
This attribute is similar to `allowedReferences`, but it specifies
the legal requisites of the whole closure, so all the dependencies
recursively. For example,
allowedRequisites = [ foobar ];
enforces that the output of a derivation cannot have any other
runtime dependency than `foobar`, and in addition it enforces that
`foobar` itself doesn't introduce any other dependency itself.
- `disallowedReferences`
The optional attribute `disallowedReferences` specifies a list of
illegal references (dependencies) of the output of the builder. For
example,
disallowedReferences = [ foo ];
enforces that the output of a derivation cannot have a direct
runtime dependencies on the derivation `foo`.
- `disallowedRequisites`
This attribute is similar to `disallowedReferences`, but it
specifies illegal requisites for the whole closure, so all the
dependencies recursively. For example,
disallowedRequisites = [ foobar ];
enforces that the output of a derivation cannot have any runtime
dependency on `foobar` or any other derivation depending recursively
on `foobar`.
- `exportReferencesGraph`
This attribute allows builders access to the references graph of
their inputs. The attribute is a list of inputs in the Nix store
whose references graph the builder needs to know. The value of this
attribute should be a list of pairs `[ name1
path1 name2
path2 ...
]`. The references graph of each pathN will be stored in a text file
nameN in the temporary build directory. The text files have the
format used by `nix-store
--register-validity` (with the deriver fields left empty). For
example, when the following derivation is built:
derivation {
...
exportReferencesGraph = [ "libfoo-graph" libfoo ];
};
the references graph of `libfoo` is placed in the file
`libfoo-graph` in the temporary build directory.
`exportReferencesGraph` is useful for builders that want to do
something with the closure of a store path. Examples include the
builders in NixOS that generate the initial ramdisk for booting
Linux (a `cpio` archive containing the closure of the boot script)
and the ISO-9660 image for the installation CD (which is populated
with a Nix store containing the closure of a bootable NixOS
configuration).
- `impureEnvVars`
This attribute allows you to specify a list of environment variables
that should be passed from the environment of the calling user to
the builder. Usually, the environment is cleared completely when the
builder is executed, but with this attribute you can allow specific
environment variables to be passed unmodified. For example,
`fetchurl` in Nixpkgs has the line
impureEnvVars = [ "http_proxy" "https_proxy" ... ];
to make it use the proxy server configuration specified by the user
in the environment variables http\_proxy and friends.
This attribute is only allowed in [fixed-output
derivations](#fixed-output-drvs), where impurities such as these are
okay since (the hash of) the output is known in advance. It is
ignored for all other derivations.
> **Warning**
>
> `impureEnvVars` implementation takes environment variables from
> the current builder process. When a daemon is building its
> environmental variables are used. Without the daemon, the
> environmental variables come from the environment of the
> `nix-build`.
- `outputHash`; `outputHashAlgo`; `outputHashMode`
These attributes declare that the derivation is a so-called
*fixed-output derivation*, which means that a cryptographic hash of
the output is already known in advance. When the build of a
fixed-output derivation finishes, Nix computes the cryptographic
hash of the output and compares it to the hash declared with these
attributes. If there is a mismatch, the build fails.
The rationale for fixed-output derivations is derivations such as
those produced by the `fetchurl` function. This function downloads a
file from a given URL. To ensure that the downloaded file has not
been modified, the caller must also specify a cryptographic hash of
the file. For example,
fetchurl {
url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz";
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
}
It sometimes happens that the URL of the file changes, e.g., because
servers are reorganised or no longer available. We then must update
the call to `fetchurl`, e.g.,
fetchurl {
url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
}
If a `fetchurl` derivation was treated like a normal derivation, the
output paths of the derivation and *all derivations depending on it*
would change. For instance, if we were to change the URL of the
Glibc source distribution in Nixpkgs (a package on which almost all
other packages depend) massive rebuilds would be needed. This is
unfortunate for a change which we know cannot have a real effect as
it propagates upwards through the dependency graph.
For fixed-output derivations, on the other hand, the name of the
output path only depends on the `outputHash*` and `name` attributes,
while all other attributes are ignored for the purpose of computing
the output path. (The `name` attribute is included because it is
part of the path.)
As an example, here is the (simplified) Nix expression for
`fetchurl`:
{ stdenv, curl }: # The curl program is used for downloading.
{ url, sha256 }:
stdenv.mkDerivation {
name = baseNameOf (toString url);
builder = ./builder.sh;
buildInputs = [ curl ];
# This is a fixed-output derivation; the output must be a regular
# file with SHA256 hash sha256.
outputHashMode = "flat";
outputHashAlgo = "sha256";
outputHash = sha256;
inherit url;
}
The `outputHashAlgo` attribute specifies the hash algorithm used to
compute the hash. It can currently be `"sha1"`, `"sha256"` or
`"sha512"`.
The `outputHashMode` attribute determines how the hash is computed.
It must be one of the following two values:
- `"flat"`
The output must be a non-executable regular file. If it isn’t,
the build fails. The hash is simply computed over the contents
of that file (so it’s equal to what Unix commands like
`sha256sum` or `sha1sum` produce).
This is the default.
- `"recursive"`
The hash is computed over the NAR archive dump of the output
(i.e., the result of [`nix-store
--dump`](#refsec-nix-store-dump)). In this case, the output can
be anything, including a directory tree.
The `outputHash` attribute, finally, must be a string containing the
hash in either hexadecimal or base-32 notation. (See the [`nix-hash`
command](#sec-nix-hash) for information about converting to and from
base-32 notation.)
- `passAsFile`
A list of names of attributes that should be passed via files rather
than environment variables. For example, if you have
```
passAsFile = ["big"];
big = "a very long string";
```
then when the builder runs, the environment variable bigPath will
contain the absolute path to a temporary file containing `a very
long
string`. That is, for any attribute x listed in `passAsFile`, Nix
will pass an environment variable xPath holding the path of the file
containing the value of attribute x. This is useful when you need to
pass large strings to a builder, since most operating systems impose
a limit on the size of the environment (typically, a few hundred
kilobyte).
- `preferLocalBuild`
If this attribute is set to `true` and [distributed building is
enabled](#chap-distributed-builds), then, if possible, the derivaton
will be built locally instead of forwarded to a remote machine. This
is appropriate for trivial builders where the cost of doing a
download or remote build would exceed the cost of building locally.
- `allowSubstitutes`
If this attribute is set to `false`, then Nix will always build this
derivation; it will not try to substitute its outputs. This is
useful for very trivial derivations (such as `writeText` in Nixpkgs)
that are cheaper to build than to substitute from a binary cache.
> **Note**
>
> You need to have a builder configured which satisfies the
> derivation’s `system` attribute, since the derivation cannot be
> substituted. Thus it is usually a good idea to align `system` with
> `builtins.currentSystem` when setting `allowSubstitutes` to
> `false`. For most trivial derivations this should be the case.

72
doc/manual/src/expressions/arguments-variables.md Normal file
View file

@ -0,0 +1,72 @@
# Arguments and Variables
...
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 = ...;
}
The Nix expression in [???](#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 `pkgs/top-level/all-packages.nix`,
where all Nix expressions for packages are imported and called with the
appropriate arguments. [example\_title](#ex-hello-composition) shows
some fragments of `all-packages.nix`.
- This file defines a set of attributes, all of which are concrete
derivations (i.e., not functions). In fact, we define a *mutually
recursive* set of attributes. That is, the attributes can refer to
each other. This is precisely what we want since we want to “plug”
the various packages into each other.
- Here we *import* the Nix expression for GNU Hello. The import
operation just loads and returns the specified Nix expression. In
fact, we could just have put the contents of [???](#ex-hello-nix) in
`all-packages.nix` at this point. That would be completely
equivalent, but it would make the file rather bulky.
Note that we refer to `../applications/misc/hello/ex-1`, not
`../applications/misc/hello/ex-1/default.nix`. When you try to
import a directory, Nix automatically appends `/default.nix` to the
file name.
- This is where the actual composition takes place. Here we *call* the
function imported from `../applications/misc/hello/ex-1` with a set
containing the things that the function expects, namely `fetchurl`,
`stdenv`, and `perl`. We use inherit again to use the attributes
defined in the surrounding scope (we could also have written
`fetchurl = fetchurl;`, etc.).
The result of this function call is an actual derivation that can be
built by Nix (since when we fill in the arguments of the function,
what we get is its body, which is the call to `stdenv.mkDerivation`
in [???](#ex-hello-nix)).
> **Note**
>
> Nixpkgs has a convenience function `callPackage` that imports and
> calls a function, filling in any missing arguments by passing the
> corresponding attribute from the Nixpkgs set, like this:
>
> hello = callPackage ../applications/misc/hello/ex-1 { };
>
> If necessary, you can set or override arguments:
>
> hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; };
- Likewise, we have to instantiate Perl, `fetchurl`, and the standard
environment.

72
doc/manual/src/expressions/build-script.md Normal file
View file

@ -0,0 +1,72 @@
# Build Script
source $stdenv/setup
PATH=$perl/bin:$PATH
tar xvfz $src
cd hello-*
./configure --prefix=$out
make
make install
[example\_title](#ex-hello-builder) shows the builder referenced from
Hello's Nix expression (stored in
`pkgs/applications/misc/hello/ex-1/builder.sh`). The builder can
actually be made a lot shorter by using the *generic builder* functions
provided by `stdenv`, but here we write out the build steps to elucidate
what a builder does. It performs the following steps:
- When Nix runs a builder, it initially completely clears the
environment (except for the attributes declared in the derivation).
For instance, the PATH variable is empty\[1\]. This is done to
prevent undeclared inputs from being used in the build process. If
for example the PATH contained `/usr/bin`, then you might
accidentally use `/usr/bin/gcc`.
So the first step is to set up the environment. This is done by
calling the `setup` script of the standard environment. The
environment variable stdenv points to the location of the standard
environment being used. (It wasn't specified explicitly as an
attribute in [???](#ex-hello-nix), but `mkDerivation` adds it
automatically.)
- Since Hello needs Perl, we have to make sure that Perl is in the
PATH. The perl environment variable points to the location of the
Perl package (since it was passed in as an attribute to the
derivation), so `$perl/bin` is the directory containing the Perl
interpreter.
- Now we have to unpack the sources. The `src` attribute was bound to
the result of fetching the Hello source tarball from the network, so
the src environment variable points to the location in the Nix store
to which the tarball was downloaded. After unpacking, we `cd` to the
resulting source directory.
The whole build is performed in a temporary directory created in
`/tmp`, by the way. This directory is removed after the builder
finishes, so there is no need to clean up the sources afterwards.
Also, the temporary directory is always newly created, so you don't
have to worry about files from previous builds interfering with the
current build.
- GNU Hello is a typical Autoconf-based package, so we first have to
run its `configure` script. In Nix every package is stored in a
separate location in the Nix store, for instance
`/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix
computes this path by cryptographically hashing all attributes of
the derivation. The path is passed to the builder through the out
environment variable. So here we give `configure` the parameter
`--prefix=$out` to cause Hello to be installed in the expected
location.
- Finally we build Hello (`make`) and install it into the location
specified by out (`make install`).
If you are wondering about the absence of error checking on the result
of various commands called in the builder: this is because the shell
script is evaluated with Bash's `-e` option, which causes the script to
be aborted if any command fails without an error check.
1. Actually, it's initialised to `/path-not-set` to prevent Bash from
setting it to a default value.

72
doc/manual/src/expressions/builder-syntax.md Normal file
View file

@ -0,0 +1,72 @@
# Builder Syntax
source $stdenv/setup
PATH=$perl/bin:$PATH
tar xvfz $src
cd hello-*
./configure --prefix=$out
make
make install
[example\_title](#ex-hello-builder) shows the builder referenced from
Hello's Nix expression (stored in
`pkgs/applications/misc/hello/ex-1/builder.sh`). The builder can
actually be made a lot shorter by using the *generic builder* functions
provided by `stdenv`, but here we write out the build steps to elucidate
what a builder does. It performs the following steps:
- When Nix runs a builder, it initially completely clears the
environment (except for the attributes declared in the derivation).
For instance, the PATH variable is empty\[1\]. This is done to
prevent undeclared inputs from being used in the build process. If
for example the PATH contained `/usr/bin`, then you might
accidentally use `/usr/bin/gcc`.
So the first step is to set up the environment. This is done by
calling the `setup` script of the standard environment. The
environment variable stdenv points to the location of the standard
environment being used. (It wasn't specified explicitly as an
attribute in [???](#ex-hello-nix), but `mkDerivation` adds it
automatically.)
- Since Hello needs Perl, we have to make sure that Perl is in the
PATH. The perl environment variable points to the location of the
Perl package (since it was passed in as an attribute to the
derivation), so `$perl/bin` is the directory containing the Perl
interpreter.
- Now we have to unpack the sources. The `src` attribute was bound to
the result of fetching the Hello source tarball from the network, so
the src environment variable points to the location in the Nix store
to which the tarball was downloaded. After unpacking, we `cd` to the
resulting source directory.
The whole build is performed in a temporary directory created in
`/tmp`, by the way. This directory is removed after the builder
finishes, so there is no need to clean up the sources afterwards.
Also, the temporary directory is always newly created, so you don't
have to worry about files from previous builds interfering with the
current build.
- GNU Hello is a typical Autoconf-based package, so we first have to
run its `configure` script. In Nix every package is stored in a
separate location in the Nix store, for instance
`/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix
computes this path by cryptographically hashing all attributes of
the derivation. The path is passed to the builder through the out
environment variable. So here we give `configure` the parameter
`--prefix=$out` to cause Hello to be installed in the expected
location.
- Finally we build Hello (`make`) and install it into the location
specified by out (`make install`).
If you are wondering about the absence of error checking on the result
of various commands called in the builder: this is because the shell
script is evaluated with Bash's `-e` option, which causes the script to
be aborted if any command fails without an error check.
1. Actually, it's initialised to `/path-not-set` to prevent Bash from
setting it to a default value.

839
doc/manual/src/expressions/builtins.md Normal file
View file

@ -0,0 +1,839 @@
# Built-in Functions
This section lists the functions and constants built into the Nix
expression evaluator. (The built-in function `derivation` is discussed
above.) Some built-ins, such as `derivation`, are always in scope of
every Nix expression; you can just access them right away. But to
prevent polluting the namespace too much, most built-ins are not in
scope. Instead, you can access them through the `builtins` built-in
value, which is a set that contains all built-in functions and values.
For instance, `derivation` is also available as `builtins.derivation`.
- `abort` s; `builtins.abort` s
Abort Nix expression evaluation, print error message s.
- `builtins.add` e1 e2
Return the sum of the numbers e1 and e2.
- `builtins.all` pred list
Return `true` if the function pred returns `true` for all elements
of list, and `false` otherwise.
- `builtins.any` pred list
Return `true` if the function pred returns `true` for at least one
element of list, and `false` otherwise.
- `builtins.attrNames` set
Return the names of the attributes in the set set in an
alphabetically sorted list. For instance, `builtins.attrNames { y
= 1; x = "foo"; }` evaluates to `[ "x" "y" ]`.
- `builtins.attrValues` set
Return the values of the attributes in the set set in the order
corresponding to the sorted attribute names.
- `baseNameOf` s
Return the *base name* of the string s, that is, everything
following the final slash in the string. This is similar to the GNU
`basename` command.
- `builtins.bitAnd` e1 e2
Return the bitwise AND of the integers e1 and e2.
- `builtins.bitOr` e1 e2
Return the bitwise OR of the integers e1 and e2.
- `builtins.bitXor` e1 e2
Return the bitwise XOR of the integers e1 and e2.
- `builtins`
The set `builtins` contains all the built-in functions and values.
You can use `builtins` to test for the availability of features in
the Nix installation, e.g.,
if builtins ? getEnv then builtins.getEnv "PATH" else ""
This allows a Nix expression to fall back gracefully on older Nix
installations that don’t have the desired built-in function.
- `builtins.compareVersions` s1 s2
Compare two strings representing versions and return `-1` if version
s1 is older than version s2, `0` if they are the same, and `1` if s1
is newer than s2. The version comparison algorithm is the same as
the one used by [`nix-env
-u`](#ssec-version-comparisons).
- `builtins.concatLists` lists
Concatenate a list of lists into a single list.
- `builtins.concatStringsSep` separator list
Concatenate a list of strings with a separator between each element,
e.g. `concatStringsSep "/"
["usr" "local" "bin"] == "usr/local/bin"`
- `builtins.currentSystem`
The built-in value `currentSystem` evaluates to the Nix platform
identifier for the Nix installation on which the expression is being
evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.
- `builtins.deepSeq` e1 e2
This is like `seq
e1
e2`, except that e1 is evaluated *deeply*: if it’s a list or set,
its elements or attributes are also evaluated recursively.
- `derivation` attrs; `builtins.derivation` attrs
`derivation` is described in [???](#ssec-derivation).
- `dirOf` s; `builtins.dirOf` s
Return the directory part of the string s, that is, everything
before the final slash in the string. This is similar to the GNU
`dirname` command.
- `builtins.div` e1 e2
Return the quotient of the numbers e1 and e2.
- `builtins.elem` x xs
Return `true` if a value equal to x occurs in the list xs, and
`false` otherwise.
- `builtins.elemAt` xs n
Return element n from the list xs. Elements are counted starting
from 0. A fatal error occurs if the index is out of bounds.
- `builtins.fetchurl` url
Download the specified URL and return the path of the downloaded
file. This function is not available if [restricted evaluation
mode](#conf-restrict-eval) is enabled.
- `fetchTarball` url; `builtins.fetchTarball` url
Download the specified URL, unpack it and return the path of the
unpacked tree. The file must be a tape archive (`.tar`) compressed
with `gzip`, `bzip2` or `xz`. The top-level path component of the
files in the tarball is removed, so it is best if the tarball
contains a single directory at top level. The typical use of the
function is to obtain external Nix expression dependencies, such as
a particular version of Nixpkgs, e.g.
with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz) {};
stdenv.mkDerivation { … }
The fetched tarball is cached for a certain amount of time (1 hour
by default) in `~/.cache/nix/tarballs/`. You can change the cache
timeout either on the command line with `--option tarball-ttl number
of seconds` or in the Nix configuration file with this option: `
number of seconds to cache `.
Note that when obtaining the hash with ` nix-prefetch-url
` the option `--unpack` is required.
This function can also verify the contents against a hash. In that
case, the function takes a set instead of a URL. The set requires
the attribute `url` and the attribute `sha256`, e.g.
with import (fetchTarball {
url = "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz";
sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2";
}) {};
stdenv.mkDerivation { … }
This function is not available if [restricted evaluation
mode](#conf-restrict-eval) is enabled.
- `builtins.fetchGit` args
Fetch a path from git. args can be a URL, in which case the HEAD of
the repo at that URL is fetched. Otherwise, it can be an attribute
with the following attributes (all except `url` optional):
- url
The URL of the repo.
- name
The name of the directory the repo should be exported to in the
store. Defaults to the basename of the URL.
- rev
The git revision to fetch. Defaults to the tip of `ref`.
- ref
The git ref to look for the requested revision under. This is
often a branch or tag name. Defaults to `HEAD`.
By default, the `ref` value is prefixed with `refs/heads/`. As
of Nix 2.3.0 Nix will not prefix `refs/heads/` if `ref` starts
with `refs/`.
- submodules
A Boolean parameter that specifies whether submodules should be
checked out. Defaults to `false`.
<!-- end list -->
builtins.fetchGit {
url = "git@github.com:my-secret/repository.git";
ref = "master";
rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
}
builtins.fetchGit {
url = "https://github.com/NixOS/nix.git";
ref = "refs/heads/0.5-release";
}
If the revision you're looking for is in the default branch of the
git repository you don't strictly need to specify the branch name in
the `ref` attribute.
However, if the revision you're looking for is in a future branch
for the non-default branch you will need to specify the the `ref`
attribute as well.
builtins.fetchGit {
url = "https://github.com/nixos/nix.git";
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
ref = "1.11-maintenance";
}
> **Note**
>
> It is nice to always specify the branch which a revision belongs
> to. Without the branch being specified, the fetcher might fail if
> the default branch changes. Additionally, it can be confusing to
> try a commit from a non-default branch and see the fetch fail. If
> the branch is specified the fault is much more obvious.
If the revision you're looking for is in the default branch of the
git repository you may omit the `ref` attribute.
builtins.fetchGit {
url = "https://github.com/nixos/nix.git";
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
}
builtins.fetchGit {
url = "https://github.com/nixos/nix.git";
ref = "refs/tags/1.9";
}
`builtins.fetchGit` can behave impurely fetch the latest version of
a remote branch.
> **Note**
>
> Nix will refetch the branch in accordance to
> [???](#conf-tarball-ttl).
> **Note**
>
> This behavior is disabled in *Pure evaluation mode*.
builtins.fetchGit {
url = "ssh://git@github.com/nixos/nix.git";
ref = "master";
}
- `builtins.filter` f xs
Return a list consisting of the elements of xs for which the
function f returns `true`.
- `builtins.filterSource` e1 e2
This function allows you to copy sources into the Nix store while
filtering certain files. For instance, suppose that you want to use
the directory `source-dir` as an input to a Nix expression, e.g.
stdenv.mkDerivation {
...
src = ./source-dir;
}
However, if `source-dir` is a Subversion working copy, then all
those annoying `.svn` subdirectories will also be copied to the
store. Worse, the contents of those directories may change a lot,
causing lots of spurious rebuilds. With `filterSource` you can
filter out the `.svn` directories:
```
src = builtins.filterSource
(path: type: type != "directory" || baseNameOf path != ".svn")
./source-dir;
```
Thus, the first argument e1 must be a predicate function that is
called for each regular file, directory or symlink in the source
tree e2. If the function returns `true`, the file is copied to the
Nix store, otherwise it is omitted. The function is called with two
arguments. The first is the full path of the file. The second is a
string that identifies the type of the file, which is either
`"regular"`, `"directory"`, `"symlink"` or `"unknown"` (for other
kinds of files such as device nodes or fifos — but note that those
cannot be copied to the Nix store, so if the predicate returns
`true` for them, the copy will fail). If you exclude a directory,
the entire corresponding subtree of e2 will be excluded.
- `builtins.foldl’` op nul list
Reduce a list by applying a binary operator, from left to right,
e.g. `foldl’ op nul [x0 x1 x2 ...] = op (op
(op nul x0) x1) x2) ...`. The operator is applied strictly, i.e.,
its arguments are evaluated first. For example, `foldl’ (x: y: x +
y) 0 [1 2 3]` evaluates to 6.
- `builtins.functionArgs` f
Return a set containing the names of the formal arguments expected
by the function f. The value of each attribute is a Boolean denoting
whether the corresponding argument has a default value. For
instance, `functionArgs ({ x, y ? 123}: ...) = { x = false; y =
true; }`.
"Formal argument" here refers to the attributes pattern-matched by
the function. Plain lambdas are not included, e.g. `functionArgs (x:
...) = { }`.
- `builtins.fromJSON` e
Convert a JSON string to a Nix value. For example,
builtins.fromJSON ''{"x": [1, 2, 3], "y": null}''
returns the value `{ x = [ 1 2 3 ]; y = null;
}`.
- `builtins.genList` generator length
Generate list of size length, with each element i equal to the value
returned by generator `i`. For example,
builtins.genList (x: x * x) 5
returns the list `[ 0 1 4 9 16 ]`.
- `builtins.getAttr` s set
`getAttr` returns the attribute named s from set. Evaluation aborts
if the attribute doesn’t exist. This is a dynamic version of the `.`
operator, since s is an expression rather than an identifier.
- `builtins.getEnv` s
`getEnv` returns the value of the environment variable s, or an
empty string if the variable doesn’t exist. This function should be
used with care, as it can introduce all sorts of nasty environment
dependencies in your Nix expression.
`getEnv` is used in Nix Packages to locate the file
`~/.nixpkgs/config.nix`, which contains user-local settings for Nix
Packages. (That is, it does a `getEnv "HOME"` to locate the user’s
home directory.)
- `builtins.hasAttr` s set
`hasAttr` returns `true` if set has an attribute named s, and
`false` otherwise. This is a dynamic version of the `?` operator,
since s is an expression rather than an identifier.
- `builtins.hashString` type s
Return a base-16 representation of the cryptographic hash of string
s. The hash algorithm specified by type must be one of `"md5"`,
`"sha1"`, `"sha256"` or `"sha512"`.
- `builtins.hashFile` type p
Return a base-16 representation of the cryptographic hash of the
file at path p. The hash algorithm specified by type must be one of
`"md5"`, `"sha1"`, `"sha256"` or `"sha512"`.
- `builtins.head` list
Return the first element of a list; abort evaluation if the argument
isn’t a list or is an empty list. You can test whether a list is
empty by comparing it with `[]`.
- `import` path; `builtins.import` path
Load, parse and return the Nix expression in the file path. If path
is a directory, the file ` default.nix
` in that directory is loaded. Evaluation aborts if the file
doesn’t exist or contains an incorrect Nix expression. `import`
implements Nix’s module system: you can put any Nix expression (such
as a set or a function) in a separate file, and use it from Nix
expressions in other files.
> **Note**
>
> Unlike some languages, `import` is a regular function in Nix.
> Paths using the angle bracket syntax (e.g., `
> > > > > import` \<foo\>) are normal path values (see [???](#ssec-values)).
A Nix expression loaded by `import` must not contain any *free
variables* (identifiers that are not defined in the Nix expression
itself and are not built-in). Therefore, it cannot refer to
variables that are in scope at the call site. For instance, if you
have a calling expression
rec {
x = 123;
y = import ./foo.nix;
}
then the following `foo.nix` will give an error:
x + 456
since `x` is not in scope in `foo.nix`. If you want `x` to be
available in `foo.nix`, you should pass it as a function argument:
rec {
x = 123;
y = import ./foo.nix x;
}
and
x: x + 456
(The function argument doesn’t have to be called `x` in `foo.nix`;
any name would work.)
- `builtins.intersectAttrs` e1 e2
Return a set consisting of the attributes in the set e2 that also
exist in the set e1.
- `builtins.isAttrs` e
Return `true` if e evaluates to a set, and `false` otherwise.
- `builtins.isList` e
Return `true` if e evaluates to a list, and `false` otherwise.
- `builtins.isFunction` e
Return `true` if e evaluates to a function, and `false` otherwise.
- `builtins.isString` e
Return `true` if e evaluates to a string, and `false` otherwise.
- `builtins.isInt` e
Return `true` if e evaluates to an int, and `false` otherwise.
- `builtins.isFloat` e
Return `true` if e evaluates to a float, and `false` otherwise.
- `builtins.isBool` e
Return `true` if e evaluates to a bool, and `false` otherwise.
- `builtins.isPath` e
Return `true` if e evaluates to a path, and `false` otherwise.
- `isNull` e; `builtins.isNull` e
Return `true` if e evaluates to `null`, and `false` otherwise.
> **Warning**
>
> This function is *deprecated*; just write `e == null` instead.
- `builtins.length` e
Return the length of the list e.
- `builtins.lessThan` e1 e2
Return `true` if the number e1 is less than the number e2, and
`false` otherwise. Evaluation aborts if either e1 or e2 does not
evaluate to a number.
- `builtins.listToAttrs` e
Construct a set from a list specifying the names and values of each
attribute. Each element of the list should be a set consisting of a
string-valued attribute `name` specifying the name of the attribute,
and an attribute `value` specifying its value. Example:
builtins.listToAttrs
[ { name = "foo"; value = 123; }
{ name = "bar"; value = 456; }
]
evaluates to
{ foo = 123; bar = 456; }
- `map` f list; `builtins.map` f list
Apply the function f to each element in the list list. For example,
map (x: "foo" + x) [ "bar" "bla" "abc" ]
evaluates to `[ "foobar" "foobla" "fooabc"
]`.
- `builtins.match` regex str
Returns a list if the [extended POSIX regular
expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04)
regex matches str precisely, otherwise returns `null`. Each item in
the list is a regex group.
builtins.match "ab" "abc"
Evaluates to `null`.
builtins.match "abc" "abc"
Evaluates to `[ ]`.
builtins.match "a(b)(c)" "abc"
Evaluates to `[ "b" "c" ]`.
builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO "
Evaluates to `[ "foo" ]`.
- `builtins.mul` e1 e2
Return the product of the numbers e1 and e2.
- `builtins.parseDrvName` s
Split the string s into a package name and version. The package name
is everything up to but not including the first dash followed by a
digit, and the version is everything following that dash. The result
is returned in a set `{ name, version }`. Thus,
`builtins.parseDrvName "nix-0.12pre12876"` returns `{ name = "nix";
version = "0.12pre12876";
}`.
- `builtins.path` args
An enrichment of the built-in path type, based on the attributes
present in args. All are optional except `path`:
- path
The underlying path.
- name
The name of the path when added to the store. This can used to
reference paths that have nix-illegal characters in their names,
like `@`.
- filter
A function of the type expected by
[builtins.filterSource](#builtin-filterSource), with the same
semantics.
- recursive
When `false`, when `path` is added to the store it is with a
flat hash, rather than a hash of the NAR serialization of the
file. Thus, `path` must refer to a regular file, not a
directory. This allows similar behavior to `fetchurl`. Defaults
to `true`.
- sha256
When provided, this is the expected hash of the file at the
path. Evaluation will fail if the hash is incorrect, and
providing a hash allows `builtins.path` to be used even when the
`pure-eval` nix config option is on.
- `builtins.pathExists` path
Return `true` if the path path exists at evaluation time, and
`false` otherwise.
- `builtins.placeholder` output
Return a placeholder string for the specified output that will be
substituted by the corresponding output path at build time. Typical
outputs would be `"out"`, `"bin"` or `"dev"`.
- `builtins.readDir` path
Return the contents of the directory path as a set mapping directory
entries to the corresponding file type. For instance, if directory
`A` contains a regular file `B` and another directory `C`, then
`builtins.readDir
./A` will return the set
{ B = "regular"; C = "directory"; }
The possible values for the file type are `"regular"`,
`"directory"`, `"symlink"` and `"unknown"`.
- `builtins.readFile` path
Return the contents of the file path as a string.
- `removeAttrs` set list; `builtins.removeAttrs` set list
Remove the attributes listed in list from set. The attributes don’t
have to exist in set. For instance,
removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]
evaluates to `{ y = 2; }`.
- `builtins.replaceStrings` from to s
Given string s, replace every occurrence of the strings in from with
the corresponding string in to. For example,
builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar"
evaluates to `"fabir"`.
- `builtins.seq` e1 e2
Evaluate e1, then evaluate and return e2. This ensures that a
computation is strict in the value of e1.
- `builtins.sort` comparator list
Return list in sorted order. It repeatedly calls the function
comparator with two elements. The comparator should return `true` if
the first element is less than the second, and `false` otherwise.
For example,
builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ]
produces the list `[ 42 77 147 249 483 526
]`.
This is a stable sort: it preserves the relative order of elements
deemed equal by the comparator.
- `builtins.split` regex str
Returns a list composed of non matched strings interleaved with the
lists of the [extended POSIX regular
expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04)
regex matches of str. Each item in the lists of matched sequences is
a regex group.
builtins.split "(a)b" "abc"
Evaluates to `[ "" [ "a" ] "c" ]`.
builtins.split "([ac])" "abc"
Evaluates to `[ "" [ "a" ] "b" [ "c" ] "" ]`.
builtins.split "(a)|(c)" "abc"
Evaluates to `[ "" [ "a" null ] "b" [ null "c" ] "" ]`.
builtins.split "([[:upper:]]+)" " FOO "
Evaluates to `[ " " [ "FOO" ] " " ]`.
- `builtins.splitVersion` s
Split a string representing a version into its components, by the
same version splitting logic underlying the version comparison in
[`nix-env -u`](#ssec-version-comparisons).
- `builtins.stringLength` e
Return the length of the string e. If e is not a string, evaluation
is aborted.
- `builtins.sub` e1 e2
Return the difference between the numbers e1 and e2.
- `builtins.substring` start len s
Return the substring of s from character position start (zero-based)
up to but not including start + len. If start is greater than the
length of the string, an empty string is returned, and if start +
len lies beyond the end of the string, only the substring up to the
end of the string is returned. start must be non-negative. For
example,
builtins.substring 0 3 "nixos"
evaluates to `"nix"`.
- `builtins.tail` list
Return the second to last elements of a list; abort evaluation if
the argument isn’t a list or is an empty list.
- `throw` s; `builtins.throw` s
Throw an error message s. This usually aborts Nix expression
evaluation, but in `nix-env -qa` and other commands that try to
evaluate a set of derivations to get information about those
derivations, a derivation that throws an error is silently skipped
(which is not the case for `abort`).
- `builtins.toFile` name s
Store the string s in a file in the Nix store and return its path.
The file has suffix name. This file can be used as an input to
derivations. One application is to write builders “inline”. For
instance, the following Nix expression combines [???](#ex-hello-nix)
and [???](#ex-hello-builder) into one file:
{ stdenv, fetchurl, perl }:
stdenv.mkDerivation {
name = "hello-2.1.1";
builder = builtins.toFile "builder.sh" "
source $stdenv/setup
PATH=$perl/bin:$PATH
tar xvfz $src
cd hello-*
./configure --prefix=$out
make
make install
";
src = fetchurl {
url = "http://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
};
inherit perl;
}
It is even possible for one file to refer to another, e.g.,
```
builder = let
configFile = builtins.toFile "foo.conf" "
# This is some dummy configuration file.
...
";
in builtins.toFile "builder.sh" "
source $stdenv/setup
...
cp ${configFile} $out/etc/foo.conf
";
```
Note that `${configFile}` is an antiquotation (see
[???](#ssec-values)), so the result of the expression `configFile`
(i.e., a path like `/nix/store/m7p7jfny445k...-foo.conf`) will be
spliced into the resulting string.
It is however *not* allowed to have files mutually referring to each
other, like so:
let
foo = builtins.toFile "foo" "...${bar}...";
bar = builtins.toFile "bar" "...${foo}...";
in foo
This is not allowed because it would cause a cyclic dependency in
the computation of the cryptographic hashes for `foo` and `bar`.
It is also not possible to reference the result of a derivation. If
you are using Nixpkgs, the `writeTextFile` function is able to do
that.
- `builtins.toJSON` e
Return a string containing a JSON representation of e. Strings,
integers, floats, booleans, nulls and lists are mapped to their JSON
equivalents. Sets (except derivations) are represented as objects.
Derivations are translated to a JSON string containing the
derivation’s output path. Paths are copied to the store and
represented as a JSON string of the resulting store path.
- `builtins.toPath` s
DEPRECATED. Use `/. + "/path"` to convert a string into an absolute
path. For relative paths, use `./. + "/path"`.
- `toString` e; `builtins.toString` e
Convert the expression e to a string. e can be:
- A string (in which case the string is returned unmodified).
- A path (e.g., `toString /foo/bar` yields `"/foo/bar"`.
- A set containing `{ __toString = self: ...; }`.
- An integer.
- A list, in which case the string representations of its elements
are joined with spaces.
- A Boolean (`false` yields `""`, `true` yields `"1"`).
- `null`, which yields the empty string.
- `builtins.toXML` e
Return a string containing an XML representation of e. The main
application for `toXML` is to communicate information with the
builder in a more structured format than plain environment
variables.
[example\_title](#ex-toxml) shows an example where this is the case.
The builder is supposed to generate the configuration file for a
[Jetty servlet container](http://jetty.mortbay.org/). A servlet
container contains a number of servlets (`*.war` files) each
exported under a specific URI prefix. So the servlet configuration
is a list of sets containing the `path` and `war` of the servlet
([co\_title](#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 `toXML`, which is unambiguous and can easily be
processed with the appropriate tools. For instance, in the example
an XSLT stylesheet ([co\_title](#ex-toxml-co-stylesheet)) is applied
to it ([co\_title](#ex-toxml-co-apply)) to generate the XML
configuration file for the Jetty server. The XML representation
produced from [co\_title](#ex-toxml-co-servlets) by `toXML` is shown
in [example\_title](#ex-toxml-result).
Note that [example\_title](#ex-toxml) uses the `toFile` built-in to
write the builder and the stylesheet “inline” in the Nix expression.
The path of the stylesheet is spliced into the builder at `xsltproc
${stylesheet}
...`.
{ stdenv, fetchurl, libxslt, jira, uberwiki }:
stdenv.mkDerivation (rec {
name = "web-server";
buildInputs = [ libxslt ];
builder = builtins.toFile "builder.sh" "
source $stdenv/setup
mkdir $out
echo "$servlets" | xsltproc ${stylesheet} - > $out/server-conf.xml
";
stylesheet = builtins.toFile "stylesheet.xsl"
"<?xml version='1.0' encoding='UTF-8'?>
<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>
<xsl:template match='/'>
<Configure>
<xsl:for-each select='/expr/list/attrs'>
<Call name='addWebApplication'>
<Arg><xsl:value-of select=\"attr[@name = 'path']/string/@value\" /></Arg>
<Arg><xsl:value-of select=\"attr[@name = 'war']/path/@value\" /></Arg>
</Call>
</xsl:for-each>
</Configure>
</xsl:template>
</xsl:stylesheet>
";
servlets = builtins.toXML [
{ path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; }
{ path = "/wiki"; war = uberwiki + "/uberwiki.war"; }
];
})
<?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>
- `builtins.trace` e1 e2
Evaluate e1 and print its abstract syntax representation on standard
error. Then return e2. This function is useful for debugging.
- `builtins.tryEval` e
Try to shallowly evaluate e. Return a set containing the attributes
`success` (`true` if e evaluated successfully, `false` if an error
was thrown) and `value`, equalling e if successful and `false`
otherwise. Note that this doesn't evaluate e deeply, so ` let e = {
x = throw ""; }; in (builtins.tryEval e).success
` will be `true`. Using ` builtins.deepSeq
` one can get the expected result: `let e = { x = throw "";
}; in (builtins.tryEval (builtins.deepSeq e e)).success` will be
`false`.
- `builtins.typeOf` e
Return a string representing the type of the value e, namely
`"int"`, `"bool"`, `"string"`, `"path"`, `"null"`, `"set"`,
`"list"`, `"lambda"` or `"float"`.

154
doc/manual/src/expressions/derivations.md Normal file
View file

@ -0,0 +1,154 @@
# Derivations
The most important built-in function is `derivation`, which is used to
describe a single derivation (a build action). It takes as input a set,
the attributes of which specify the inputs of the build.
- There must be an attribute named `system` whose value must be a
string specifying a Nix platform identifier, such as `"i686-linux"`
or `"x86_64-darwin"`\[1\] 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 [???](#chap-distributed-builds).)
- There must be an attribute named `name` whose value must be a
string. This is used as a symbolic name for the package by
`nix-env`, and it is appended to the output paths of the derivation.
- There must be an attribute named `builder` that identifies the
program that is executed to perform the build. It can be either a
derivation or a source (a local file reference, e.g.,
`./builder.sh`).
- Every attribute is passed as an environment variable to the builder.
Attribute values are translated to environment variables as follows:
- Strings and numbers are just passed verbatim.
- A *path* (e.g., `../foo/sources.tar`) causes the referenced file
to be copied to the store; its location in the store is put in
the environment variable. The idea is that all sources should
reside in the Nix store, since all inputs to a derivation should
reside in the Nix store.
- A *derivation* causes that derivation to be built prior to the
present derivation; its default output path is put in the
environment variable.
- Lists of the previous types are also allowed. They are simply
concatenated, separated by spaces.
- `true` is passed as the string `1`, `false` and `null` are
passed as an empty string.
- The optional attribute `args` specifies command-line arguments to be
passed to the builder. It should be a list.
- The optional attribute `outputs` specifies a list of symbolic
outputs of the derivation. By default, a derivation produces a
single output path, denoted as `out`. However, derivations can
produce multiple output paths. This is useful because it allows
outputs to be downloaded or garbage-collected separately. For
instance, imagine a library package that provides a dynamic library,
header files, and documentation. A program that links against the
library doesn’t need the header files and documentation at runtime,
and it doesn’t need the documentation at build time. Thus, the
library package could specify:
outputs = [ "lib" "headers" "doc" ];
This will cause Nix to pass environment variables `lib`, `headers`
and `doc` to the builder containing the intended store paths of each
output. The builder would typically do something like
./configure --libdir=$lib/lib --includedir=$headers/include --docdir=$doc/share/doc
for an Autoconf-style package. You can refer to each output of a
derivation by selecting it as an attribute, e.g.
buildInputs = [ pkg.lib pkg.headers ];
The first element of `outputs` determines the *default output*.
Thus, you could also write
buildInputs = [ pkg pkg.headers ];
since `pkg` is equivalent to `pkg.lib`.
The function `mkDerivation` in the Nixpkgs standard environment is a
wrapper around `derivation` that adds a default value for `system` and
always uses Bash as the builder, to which the supplied builder is passed
as a command-line argument. See the Nixpkgs manual for details.
The builder is executed as follows:
- A temporary directory is created under the directory specified by
TMPDIR (default `/tmp`) where the build will take place. The current
directory is changed to this directory.
- The environment is cleared and set to the derivation attributes, as
specified above.
- In addition, the following variables are set:
- NIX\_BUILD\_TOP contains the path of the temporary directory for
this build.
- Also, TMPDIR, TEMPDIR, TMP, TEMP are set to point to the
temporary directory. This is to prevent the builder from
accidentally writing temporary files anywhere else. Doing so
might cause interference by other processes.
- PATH is set to `/path-not-set` to prevent shells from
initialising it to their built-in default value.
- HOME is set to `/homeless-shelter` to prevent programs from
using `/etc/passwd` or the like to find the user's home
directory, which could cause impurity. Usually, when HOME is
set, it is used as the location of the home directory, even if
it points to a non-existent path.
- NIX\_STORE is set to the path of the top-level Nix store
directory (typically, `/nix/store`).
- For each output declared in `outputs`, the corresponding
environment variable is set to point to the intended path in the
Nix store for that output. Each output path is a concatenation
of the cryptographic hash of all build inputs, the `name`
attribute and the output name. (The output name is omitted if
it’s `out`.)
- If an output path already exists, it is removed. Also, locks are
acquired to prevent multiple Nix instances from performing the same
build at the same time.
- A log of the combined standard output and error is written to
`/nix/var/log/nix`.
- The builder is executed with the arguments specified by the
attribute `args`. If it exits with exit code 0, it is considered to
have succeeded.
- The temporary directory is removed (unless the `-K` option was
specified).
- If the build was successful, Nix scans each output path for
references to input paths by looking for the hash parts of the input
paths. Since these are potential runtime dependencies, Nix registers
them as dependencies of the output paths.
- After the build, Nix sets the last-modified timestamp on all files
in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to
the default group, and sets the mode of the file to 0444 or 0555
(i.e., read-only, with execute permission enabled if the file was
originally executable). Note that possible `setuid` and `setgid`
bits are cleared. Setuid and setgid programs are not currently
supported by Nix. This is because the Nix archives used in
deployment have no concept of ownership information, and because it
makes the build result dependent on the user performing the build.
<!-- end list -->
1. To figure out your platform identifier, look at the line “Checking
for the canonical Nix system name” in the output of Nix's
`configure` script.

12
doc/manual/src/expressions/expression-language.md Normal file
View file

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

91
doc/manual/src/expressions/expression-syntax.md Normal file
View file

@ -0,0 +1,91 @@
# Expression Syntax
{ stdenv, fetchurl, perl }:
stdenv.mkDerivation {
name = "hello-2.1.1";
builder = ./builder.sh;
src = fetchurl {
url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
};
inherit perl;
}
[example\_title](#ex-hello-nix) shows a Nix expression for GNU Hello.
It's actually already in the Nix Packages collection in
`pkgs/applications/misc/hello/ex-1/default.nix`. It is customary to
place each package in a separate directory and call the single Nix
expression in that directory `default.nix`. The file has the following
elements (referenced from the figure by number):
- This states that the expression is a *function* that expects to be
called with three arguments: `stdenv`, `fetchurl`, and `perl`. They
are needed to build Hello, but we don't know how to build them here;
that's why they are function arguments. `stdenv` is a package that
is used by almost all Nix Packages packages; it provides a
“standard” environment consisting of the things you would expect
in a basic Unix environment: a C/C++ compiler (GCC, to be precise),
the Bash shell, fundamental Unix tools such as `cp`, `grep`, `tar`,
etc. `fetchurl` is a function that downloads files. `perl` is the
Perl interpreter.
Nix functions generally have the form `{ x, y, ...,
z }: e` where `x`, `y`, etc. are the names of the expected
arguments, and where e is the body of the function. So here, the
entire remainder of the file is the body of the function; when given
the required arguments, the body should describe how to build an
instance of the Hello package.
- So we have to build a package. Building something from other stuff
is called a *derivation* in Nix (as opposed to sources, which are
built by humans instead of computers). We perform a derivation by
calling `stdenv.mkDerivation`. `mkDerivation` is a function provided
by `stdenv` that builds a package from a set of *attributes*. A set
is just a list of key/value pairs where each key is a string and
each value is an arbitrary Nix expression. They take the general
form `{
name1 =
expr1; ...
nameN =
exprN; }`.
- The attribute `name` specifies the symbolic name and version of the
package. Nix doesn't really care about these things, but they are
used by for instance `nix-env
-q` to show a “human-readable” name for packages. This attribute is
required by `mkDerivation`.
- The attribute `builder` specifies the builder. This attribute can
sometimes be omitted, in which case `mkDerivation` will fill in a
default builder (which does a `configure; make; make install`, in
essence). Hello is sufficiently simple that the default builder
would suffice, but in this case, we will show an actual builder for
educational purposes. The value `./builder.sh` refers to the shell
script shown in [???](#ex-hello-builder), discussed below.
- The builder has to know what the sources of the package are. Here,
the attribute `src` is bound to the result of a call to the
`fetchurl` function. Given a URL and a SHA-256 hash of the expected
contents of the file at that URL, this function builds a derivation
that downloads the file and checks its hash. So the sources are a
dependency that like all other dependencies is built before Hello
itself is built.
Instead of `src` any other name could have been used, and in fact
there can be any number of sources (bound to different attributes).
However, `src` is customary, and it's also expected by the default
builder (which we don't use in this example).
- Since the derivation requires Perl, we have to pass the value of the
`perl` function argument to the builder. All attributes in the set
are actually passed as environment variables to the builder, so
declaring an attribute
perl = perl;
will do the trick: it binds an attribute `perl` to the function
argument which also happens to be called `perl`. However, it looks a
bit silly, so there is a shorter syntax. The `inherit` keyword
causes the specified attributes to be bound to whatever variables
with the same name happen to be in scope.

61
doc/manual/src/expressions/generic-builder.md Normal file
View file

@ -0,0 +1,61 @@
# Generic Builder Syntax
Recall from [???](#ex-hello-builder) that the builder looked something
like this:
PATH=$perl/bin:$PATH
tar xvfz $src
cd hello-*
./configure --prefix=$out
make
make install
The builders for almost all Unix packages look like this — set up some
environment variables, unpack the sources, configure, build, and
install. For this reason the standard environment provides some Bash
functions that automate the build process. A builder using the generic
build facilities in shown in [example\_title](#ex-hello-builder2).
buildInputs="$perl"
source $stdenv/setup
genericBuild
- The buildInputs variable tells `setup` to use the indicated packages
as “inputs”. This means that if a package provides a `bin`
subdirectory, it's added to PATH; if it has a `include`
subdirectory, it's added to GCC's header search path; and so
on.\[1\]
- The function `genericBuild` is defined in the file `$stdenv/setup`.
- The final step calls the shell function `genericBuild`, which
performs the steps that were done explicitly in
[???](#ex-hello-builder). The generic builder is smart enough to
figure out whether to unpack the sources using `gzip`, `bzip2`, etc.
It can be customised in many ways; see the Nixpkgs manual for
details.
Discerning readers will note that the buildInputs could just as well
have been set in the Nix expression, like this:
```
buildInputs = [ perl ];
```
The `perl` attribute can then be removed, and the builder becomes even
shorter:
source $stdenv/setup
genericBuild
In fact, `mkDerivation` provides a default builder that looks exactly
like that, so it is actually possible to omit the builder for Hello
entirely.
1. How does it work? `setup` tries to source the file
`pkg/nix-support/setup-hook` of all dependencies. These “setup
hooks” can then set up whatever environment variables they want;
for instance, the setup hook for Perl sets the PERL5LIB environment
variable to contain the `lib/site_perl` directories of all inputs.

291
doc/manual/src/expressions/language-constructs.md Normal file
View file

@ -0,0 +1,291 @@
# Language Constructs
Recursive sets are just normal sets, but the attributes can refer to
each other. For example,
rec {
x = y;
y = 123;
}.x
evaluates to `123`. Note that without `rec` the binding `x = y;` would
refer to the variable `y` in the surrounding scope, if one exists, and
would be invalid if no such variable exists. That is, in a normal
(non-recursive) set, attributes are not added to the lexical scope; in a
recursive set, they are.
Recursive sets of course introduce the danger of infinite recursion. For
example,
rec {
x = y;
y = x;
}.x
does not terminate\[1\].
A let-expression allows you to define local variables for an expression.
For instance,
let
x = "foo";
y = "bar";
in x + y
evaluates to `"foobar"`.
When defining a set or in a let-expression it is often convenient to
copy variables from the surrounding lexical scope (e.g., when you want
to propagate attributes). This can be shortened using the `inherit`
keyword. For instance,
let x = 123; in
{ inherit x;
y = 456;
}
is equivalent to
let x = 123; in
{ x = x;
y = 456;
}
and both evaluate to `{ x = 123; y = 456; }`. (Note that this works
because `x` is added to the lexical scope by the `let` construct.) It is
also possible to inherit attributes from another set. For instance, in
this fragment from `all-packages.nix`,
```
graphviz = (import ../tools/graphics/graphviz) {
inherit fetchurl stdenv libpng libjpeg expat x11 yacc;
inherit (xlibs) libXaw;
};
xlibs = {
libX11 = ...;
libXaw = ...;
...
}
libpng = ...;
libjpg = ...;
...
```
the set used in the function call to the function defined in
`../tools/graphics/graphviz` inherits a number of variables from the
surrounding scope (`fetchurl` ... `yacc`), but also inherits `libXaw`
(the X Athena Widgets) from the `xlibs` (X11 client-side libraries) set.
Summarizing the fragment
...
inherit x y z;
inherit (src-set) a b c;
...
is equivalent to
...
x = x; y = y; z = z;
a = src-set.a; b = src-set.b; c = src-set.c;
...
when used while defining local variables in a let-expression or while
defining a set.
Functions have the following form:
pattern: body
The pattern specifies what the argument of the function must look like,
and binds variables in the body to (parts of) the argument. There are
three kinds of patterns:
- If a pattern is a single identifier, then the function matches any
argument. Example:
let negate = x: !x;
concat = x: y: x + y;
in if negate true then concat "foo" "bar" else ""
Note that `concat` is a function that takes one argument and returns
a function that takes another argument. This allows partial
parameterisation (i.e., only filling some of the arguments of a
function); e.g.,
map (concat "foo") [ "bar" "bla" "abc" ]
evaluates to `[ "foobar" "foobla"
"fooabc" ]`.
- A *set pattern* of the form `{ name1, name2, …, nameN }` matches a
set containing the listed attributes, and binds the values of those
attributes to variables in the function body. For example, the
function
{ x, y, z }: z + y + x
can only be called with a set containing exactly the attributes `x`,
`y` and `z`. No other attributes are allowed. If you want to allow
additional arguments, you can use an ellipsis (`...`):
{ x, y, z, ... }: z + y + x
This works on any set that contains at least the three named
attributes.
It is possible to provide *default values* for attributes, in which
case they are allowed to be missing. A default value is specified by
writing `name ?
e`, where e is an arbitrary expression. For example,
{ x, y ? "foo", z ? "bar" }: z + y + x
specifies a function that only requires an attribute named `x`, but
optionally accepts `y` and `z`.
- An `@`-pattern provides a means of referring to the whole value
being matched:
```
args@{ x, y, z, ... }: z + y + x + args.a
```
but can also be written as:
```
{ x, y, z, ... } @ args: z + y + x + args.a
```
Here `args` is bound to the entire argument, which is further
matched against the pattern `{ x, y, z,
... }`. `@`-pattern makes mainly sense with an ellipsis(`...`) as
you can access attribute names as `a`, using `args.a`, which was
given as an additional attribute to the function.
> **Warning**
>
> The `args@` expression is bound to the argument passed to the
> function which means that attributes with defaults that aren't
> explicitly specified in the function call won't cause an
> evaluation error, but won't exist in `args`.
>
> For instance
>
> let
> function = args@{ a ? 23, ... }: args;
> in
> function {}
>
> will evaluate to an empty attribute set.
Note that functions do not have names. If you want to give them a name,
you can bind them to an attribute, e.g.,
let concat = { x, y }: x + y;
in concat { x = "foo"; y = "bar"; }
Conditionals look like this:
if e1 then e2 else e3
where e1 is an expression that should evaluate to a Boolean value
(`true` or `false`).
Assertions are generally used to check that certain requirements on or
between features and dependencies hold. They look like this:
assert e1; e2
where e1 is an expression that should evaluate to a Boolean value. If it
evaluates to `true`, e2 is returned; otherwise expression evaluation is
aborted and a backtrace is printed.
{ 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;
...
}
[example\_title](#ex-subversion-nix) show how assertions are used in the
Nix expression for Subversion.
- This assertion states that if Subversion is to have support for
local repositories, then Berkeley DB is needed. So if the Subversion
function is called with the `localServer` argument set to `true` but
the `db4` argument set to `null`, then the evaluation fails.
- This is a more subtle condition: if Subversion is built with Apache
(`httpServer`) support, then the Expat library (an XML library) used
by Subversion should be same as the one used by Apache. This is
because in this configuration Subversion code ends up being linked
with Apache code, and if the Expat libraries do not match, a build-
or runtime link error or incompatibility might occur.
- This assertion says that in order for Subversion to have SSL support
(so that it can access `https` URLs), an OpenSSL library must be
passed. Additionally, it says that *if* Apache support is enabled,
then Apache's OpenSSL should match Subversion's. (Note that if
Apache support is not enabled, we don't care about Apache's
OpenSSL.)
- The conditional here is not really related to assertions, but is
worth pointing out: it ensures that if SSL support is disabled, then
the Subversion derivation is not dependent on OpenSSL, even if a
non-`null` value was passed. This prevents an unnecessary rebuild of
Subversion if OpenSSL changes.
A *with-expression*,
with e1; e2
introduces the set e1 into the lexical scope of the expression e2. For
instance,
let as = { x = "foo"; y = "bar"; };
in with as; x + y
evaluates to `"foobar"` since the `with` adds the `x` and `y` attributes
of `as` to the lexical scope in the expression `x + y`. The most common
use of `with` is in conjunction with the `import` function. E.g.,
with (import ./definitions.nix); ...
makes all attributes defined in the file `definitions.nix` available as
if they were defined locally in a `let`-expression.
The bindings introduced by `with` do not shadow bindings introduced by
other means, e.g.
let a = 3; in with { a = 1; }; let a = 4; in with { a = 2; }; ...
establishes the same scope as
let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...
Comments can be single-line, started with a `#` character, or
inline/multi-line, enclosed within `/*
... */`.
1. Actually, Nix detects infinite recursion in this case and aborts
(“infinite recursion encountered”).

32
doc/manual/src/expressions/language-operators.md Normal file
View file

@ -0,0 +1,32 @@
# Operators
[table\_title](#table-operators) lists the operators in the Nix
expression language, in order of precedence (from strongest to weakest
binding).
| Name | Syntax | Associativity | Description | Precedence |
| ------------------------ | ----------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| Select | e `.` attrpath \[ `or` def \] | none | Select attribute denoted by the attribute path attrpath from set e. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return def if provided, otherwise abort evaluation. | 1 |
| Application | e1 e2 | left | Call function e1 with argument e2. | 2 |
| Arithmetic Negation | `-` e | none | Arithmetic negation. | 3 |
| Has Attribute | e `?` attrpath | none | Test whether set e contains the attribute denoted by attrpath; return `true` or `false`. | 4 |
| List Concatenation | e1 `++` e2 | right | List concatenation. | 5 |
| Multiplication | e1 `*` e2, | left | Arithmetic multiplication. | 6 |
| Division | e1 `/` e2 | left | Arithmetic division. | 6 |
| Addition | e1 `+` e2 | left | Arithmetic addition. | 7 |
| Subtraction | e1 `-` e2 | left | Arithmetic subtraction. | 7 |
| String Concatenation | string1 `+` string2 | left | String concatenation. | 7 |
| Not | `!` e | none | Boolean negation. | 8 |
| Update | e1 `//` e2 | right | Return a set consisting of the attributes in e1 and e2 (with the latter taking precedence over the former in case of equally named attributes). | 9 |
| Less Than | e1 `<` e2, | none | Arithmetic comparison. | 10 |
| Less Than or Equal To | e1 `<=` e2 | none | Arithmetic comparison. | 10 |
| Greater Than | e1 `>` e2 | none | Arithmetic comparison. | 10 |
| Greater Than or Equal To | e1 `>=` e2 | none | Arithmetic comparison. | 10 |
| Equality | e1 `==` e2 | none | Equality. | 11 |
| Inequality | e1 `!=` e2 | none | Inequality. | 11 |
| Logical AND | e1 `&&` e2 | left | Logical AND. | 12 |
| Logical OR | e1 `\|\|` e2 | left | Logical OR. | 13 |
| Logical Implication | e1 `->` e2 | none | Logical implication (equivalent to `!e1 \|\|
e2`). | 14 |
Operators

209
doc/manual/src/expressions/language-values.md Normal file
View file

@ -0,0 +1,209 @@
# Values
Nix has the following basic data types:
- *Strings* can be written in three ways.
The most common way is to enclose the string between double quotes,
e.g., `"foo bar"`. Strings can span multiple lines. The special
characters `"` and `\` and the character sequence `${` must be
escaped by prefixing them with a backslash (`\`). Newlines, carriage
returns and tabs can be written as `\n`, `\r` and `\t`,
respectively.
You can include the result of an expression into a string by
enclosing it in `${...}`, a feature known as *antiquotation*. The
enclosed expression must evaluate to something that can be coerced
into a string (meaning that it must be a string, a path, or a
derivation). For instance, rather than writing
"--with-freetype2-library=" + freetype + "/lib"
(where `freetype` is a derivation), you can instead write the more
natural
"--with-freetype2-library=${freetype}/lib"
The latter is automatically translated to the former. A more
complicated example (from the Nix expression for
[Qt](http://www.trolltech.com/products/qt)):
configureFlags = "
-system-zlib -system-libpng -system-libjpeg
${if openglSupport then "-dlopen-opengl
-L${mesa}/lib -I${mesa}/include
-L${libXmu}/lib -I${libXmu}/include" else ""}
${if threadSupport then "-thread" else "-no-thread"}
";
Note that Nix expressions and strings can be arbitrarily nested; in
this case the outer string contains various antiquotations that
themselves contain strings (e.g., `"-thread"`), some of which in
turn contain expressions (e.g., `${mesa}`).
The second way to write string literals is as an *indented string*,
which is enclosed between pairs of *double single-quotes*, like so:
''
This is the first line.
This is the second line.
This is the third line.
''
This kind of string literal intelligently strips indentation from
the start of each line. To be precise, it strips from each line a
number of spaces equal to the minimal indentation of the string as a
whole (disregarding the indentation of empty lines). For instance,
the first and second line are indented two space, while the third
line is indented four spaces. Thus, two spaces are stripped from
each line, so the resulting string is
"This is the first line.\nThis is the second line.\n This is the third line.\n"
Note that the whitespace and newline following the opening `''` is
ignored if there is no non-whitespace text on the initial line.
Antiquotation (`${expr}`) is supported in indented strings.
Since `${` and `''` have special meaning in indented strings, you
need a way to quote them. `$` can be escaped by prefixing it with
`''` (that is, two single quotes), i.e., `''$`. `''` can be escaped
by prefixing it with `'`, i.e., `'''`. `$` removes any special
meaning from the following `$`. Linefeed, carriage-return and tab
characters can be written as `''\n`, `''\r`, `''\t`, and `''\`
escapes any other character.
Indented strings are primarily useful in that they allow multi-line
string literals to follow the indentation of the enclosing Nix
expression, and that less escaping is typically necessary for
strings representing languages such as shell scripts and
configuration files because `''` is much less common than `"`.
Example:
stdenv.mkDerivation {
...
postInstall =
''
mkdir $out/bin $out/etc
cp foo $out/bin
echo "Hello World" > $out/etc/foo.conf
${if enableBar then "cp bar $out/bin" else ""}
'';
...
}
Finally, as a convenience, *URIs* as defined in appendix B of
[RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as
is*, without quotes. For instance, the string
`"http://example.org/foo.tar.bz2"` can also be written as
`http://example.org/foo.tar.bz2`.
- Numbers, which can be *integers* (like `123`) or *floating point*
(like `123.43` or `.27e13`).
Numbers are type-compatible: pure integer operations will always
return integers, whereas any operation involving at least one
floating point number will have a floating point number as a result.
- *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
least one slash to be recognised as such; for instance, `builder.sh`
is not a path\[1\]. If the file name is relative, i.e., if it does
not begin with a slash, it is made absolute at parse time relative
to the directory of the Nix expression that contained it. For
instance, if a Nix expression in `/foo/bar/bla.nix` refers to
`../xyzzy/fnord.nix`, the absolute path is `/foo/xyzzy/fnord.nix`.
If the first component of a path is a `~`, it is interpreted as if
the rest of the path were relative to the user's home directory.
e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
whose home directory is `/home/edolstra`.
Paths can also be specified between angle brackets, e.g.
`<nixpkgs>`. This means that the directories listed in the
environment variable NIX\_PATH will be searched for the given file
or directory name.
- *Booleans* with values `true` and `false`.
- The null value, denoted as `null`.
Lists are formed by enclosing a whitespace-separated list of values
between square brackets. For example,
[ 123 ./foo.nix "abc" (f { x = y; }) ]
defines a list of four elements, the last being the result of a call to
the function `f`. Note that function calls have to be enclosed in
parentheses. If they had been omitted, e.g.,
[ 123 ./foo.nix "abc" f { x = y; } ]
the result would be a list of five elements, the fourth one being a
function and the fifth being a set.
Note that lists are only lazy in values, and they are strict in length.
Sets are really the core of the language, since ultimately the Nix
language is all about creating derivations, which are really just sets
of attributes to be passed to build scripts.
Sets are just a list of name/value pairs (called *attributes*) enclosed
in curly brackets, where each value is an arbitrary expression
terminated by a semicolon. For example:
{ x = 123;
text = "Hello";
y = f { bla = 456; };
}
This defines a set with attributes named `x`, `text`, `y`. The order of
the attributes is irrelevant. An attribute name may only occur once.
Attributes can be selected from a set using the `.` operator. For
instance,
{ a = "Foo"; b = "Bar"; }.a
evaluates to `"Foo"`. It is possible to provide a default value in an
attribute selection using the `or` keyword. For example,
{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"
will evaluate to `"Xyzzy"` because there is no `c` attribute in the set.
You can use arbitrary double-quoted strings as attribute names:
{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}"
This will evaluate to `123` (Assuming `bar` is antiquotable). In the
case where an attribute name is just a single antiquotation, the quotes
can be dropped:
{ foo = 123; }.${bar} or 456
This will evaluate to `123` if `bar` evaluates to `"foo"` when coerced
to a string and `456` otherwise (again assuming `bar` is antiquotable).
In the special case where an attribute name inside of a set declaration
evaluates to `null` (which is normally an error, as `null` is not
antiquotable), that attribute is simply not added to the set:
{ ${if foo then "bar" else null} = true; }
This will evaluate to `{}` if `foo` evaluates to `false`.
A set that has a `__functor` attribute whose value is callable (i.e. is
itself a function or a set with a `__functor` attribute whose value is
callable) can be applied as if it were a function, with the set itself
passed in first , e.g.,
let add = { __functor = self: x: x + self.x; };
inc = add // { x = 1; };
in inc 1
evaluates to `2`. This can be used to attach metadata to a function
without the caller needing to treat it specially, or to implement a form
of object-oriented programming, for example.
1. It's parsed as an expression that selects the attribute `sh` from
the variable `builder`.

57
doc/manual/src/expressions/simple-building-testing.md Normal file
View file

@ -0,0 +1,57 @@
# Building and Testing
You can now try to build Hello. Of course, you could do `nix-env -i
hello`, but you may not want to install a possibly broken package just
yet. The best way to test the package is by using the command
`nix-build`, which builds a Nix expression and creates a symlink named
`result` in the current directory:
$ nix-build -A hello
building path `/nix/store/632d2b22514d...-hello-2.1.1'
hello-2.1.1/
hello-2.1.1/intl/
hello-2.1.1/intl/ChangeLog
...
$ ls -l result
lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1
$ ./result/bin/hello
Hello, world!
The [`-A`](#opt-attr) option selects the `hello` attribute. This is
faster than using the symbolic package name specified by the `name`
attribute (which also happens to be `hello`) and is unambiguous (there
can be multiple packages with the symbolic name `hello`, but there can
be only one attribute in a set named `hello`).
`nix-build` registers the `./result` symlink as a garbage collection
root, so unless and until you delete the `./result` symlink, the output
of the build will be safely kept on your system. You can use
`nix-build`’s `-o` switch to give the symlink another name.
Nix has transactional semantics. Once a build finishes successfully, Nix
makes a note of this in its database: it registers that the path denoted
by out is now “valid”. If you try to build the derivation again, Nix
will see that the path is already valid and finish immediately. If a
build fails, either because it returns a non-zero exit code, because Nix
or the builder are killed, or because the machine crashes, then the
output paths will not be registered as valid. If you try to build the
derivation again, Nix will remove the output paths if they exist (e.g.,
because the builder died half-way through `make
install`) and try again. Note that there is no “negative caching”: Nix
doesn't remember that a build failed, and so a failed build can always
be repeated. This is because Nix cannot distinguish between permanent
failures (e.g., a compiler error due to a syntax error in the source)
and transient failures (e.g., a disk full condition).
Nix also performs locking. If you run multiple Nix builds
simultaneously, and they try to build the same derivation, the first Nix
instance that gets there will perform the build, while the others block
(or perform other derivations if available) until the build finishes:
$ nix-build -A hello
waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x'
So it is always safe to run multiple instances of Nix in parallel (which
isn’t the case with, say, `make`).

27
doc/manual/src/expressions/simple-expression.md Normal file
View file

@ -0,0 +1,27 @@
# A Simple Nix Expression
This section shows how to add and test the [GNU Hello
package](http://www.gnu.org/software/hello/hello.html) to the Nix
Packages collection. Hello is a program that prints out the text “Hello,
world\!”.
To add a package to the Nix Packages collection, you generally need to
do three things:
1. Write a Nix expression for the package. This is a file that
describes all the inputs involved in building the package, such as
dependencies, sources, and so on.
2. Write a *builder*. This is a shell script\[1\] that actually builds
the package from the inputs.
3. Add the package to the file `pkgs/top-level/all-packages.nix`. The
Nix expression written in the first step is a *function*; it
requires other packages in order to build it. In this step you put
it all together, i.e., you call the function with the right
arguments to build the actual package.
<!-- end list -->
1. In fact, it can be written in any language, but typically it's a
`bash` shell script.

12
doc/manual/src/expressions/writing-nix-expressions.md Normal file
View file

@ -0,0 +1,12 @@
This chapter shows you how to write Nix expressions, which instruct Nix
how to build packages. It starts with a simple example (a Nix expression
for GNU Hello), and then moves on to a more in-depth look at the Nix
expression language.
> **Note**
>
> This chapter is mostly about the Nix expression language. For more
> extensive information on adding packages to the Nix Packages
> collection (such as functions in the standard environment and coding
> conventions), please consult [its
> manual](http://nixos.org/nixpkgs/manual/).

102
doc/manual/src/glossary.md Normal file
View file

@ -0,0 +1,102 @@
# Glossary
- derivation
A description of a build action. The result of a derivation is a
store object. Derivations are typically specified in Nix expressions
using the [`derivation` primitive](#ssec-derivation). These are
translated into low-level *store derivations* (implicitly by
`nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
- store
The location in the file system where store objects live. Typically
`/nix/store`.
- store path
The location in the file system of a store object, i.e., an
immediate child of the Nix store directory.
- store object
A file that is an immediate child of the Nix store directory. These
can be regular files, but also entire directory trees. Store objects
can be sources (objects copied from outside of the store),
derivation outputs (objects produced by running a build action), or
derivations (files describing a build action).
- substitute
A substitute is a command invocation stored in the Nix database that
describes how to build a store object, bypassing the normal build
mechanism (i.e., derivations). Typically, the substitute builds the
store object by downloading a pre-built version of the store object
from some server.
- purity
The assumption that equal Nix derivations when run always produce
the same output. This cannot be guaranteed in general (e.g., a
builder can rely on external inputs such as the network or the
system time) but the Nix model assumes it.
- Nix expression
A high-level description of software packages and compositions
thereof. Deploying software using Nix entails writing Nix
expressions for your packages. Nix expressions are translated to
derivations that are stored in the Nix store. These derivations can
then be built.
- reference
A store path `P` is said to have a reference to a store path `Q` if
the store object at `P` contains the path `Q` somewhere. The
*references* of a store path are the set of store paths to which it
has a reference.
A derivation can reference other derivations and sources (but not
output paths), whereas an output path only references other output
paths.
- reachable
A store path `Q` is reachable from another store path `P` if `Q` is
in the [closure](#gloss-closure) of the
[references](#gloss-reference) relation.
- closure
The closure of a store path is the set of store paths that are
directly or indirectly “reachable” from that store path; that is,
it’s the closure of the path under the
[references](#gloss-reference) relation. For a package, the closure
of its derivation is equivalent to the build-time dependencies,
while the closure of its output path is equivalent to its runtime
dependencies. For correct deployment it is necessary to deploy whole
closures, since otherwise at runtime files could be missing. The
command `nix-store -qR` prints out closures of store paths.
As an example, if the store object at path `P` contains a reference
to path `Q`, then `Q` is in the closure of `P`. Further, if `Q`
references `R` then `R` is also in the closure of `P`.
- output path
A store path produced by a derivation.
- deriver
The deriver of an [output path](#gloss-output-path) is the store
derivation that built it.
- validity
A store path is considered *valid* if it exists in the file system,
is listed in the Nix database as being valid, and if all paths in
its closure are also valid.
- user environment
An automatically generated store object that consists of a set of
symlinks to “active” applications, i.e., other store paths. These
are generated automatically by [`nix-env`](#sec-nix-env). See
[???](#sec-profiles).
- profile
A symlink to the current [user environment](#gloss-user-env) of a
user, e.g., `/nix/var/nix/profiles/default`.
- NAR
A *N*ix *AR*chive. This is a serialisation of a path in the Nix
store. It can contain regular files, directories and symbolic links.
NARs are generated and unpacked using `nix-store --dump` and
`nix-store
--restore`.

47
doc/manual/src/hacking.md Normal file
View file

@ -0,0 +1,47 @@
# Hacking
This section provides some notes on how to hack on Nix. To get the
latest version of Nix from GitHub:
$ git clone https://github.com/NixOS/nix.git
$ cd nix
To build Nix for the current operating system/architecture use
$ nix-build
or if you have a flakes-enabled nix:
$ nix build
This will build `defaultPackage` attribute defined in the `flake.nix`
file. To build for other platforms add one of the following suffixes to
it: aarch64-linux, i686-linux, x86\_64-darwin, x86\_64-linux. i.e.
$ nix-build -A defaultPackage.x86_64-linux
To build all dependencies and start a shell in which all environment
variables are set up so that those dependencies can be found:
$ nix-shell
To build Nix itself in this shell:
[nix-shell]$ ./bootstrap.sh
[nix-shell]$ ./configure $configureFlags
[nix-shell]$ make -j $NIX_BUILD_CORES
To install it in `$(pwd)/inst` and test it:
[nix-shell]$ make install
[nix-shell]$ make installcheck
[nix-shell]$ ./inst/bin/nix --version
nix (Nix) 2.4
If you have a flakes-enabled nix you can replace:
$ nix-shell
by:
$ nix develop

34
doc/manual/src/installation/building-source.md Normal file
View file

@ -0,0 +1,34 @@
# Building Nix from Source
After unpacking or checking out the Nix sources, issue the following
commands:
$ ./configure options...
$ make
$ make install
Nix requires GNU Make so you may need to invoke `gmake` instead.
When building from the Git repository, these should be preceded by the
command:
$ ./bootstrap.sh
The installation path can be specified by passing the `--prefix=prefix`
to `configure`. The default installation directory is `/usr/local`. You
can change this to any location you like. You must have write permission
to the prefix path.
Nix keeps its *store* (the place where packages are stored) in
`/nix/store` by default. This can be changed using
`--with-store-dir=path`.
> **Warning**
>
> It is best *not* to change the Nix store from its default, since doing
> so makes it impossible to use pre-built binaries from the standard
> Nixpkgs channels — that is, all packages will need to be built from
> source.
Nix keeps state (such as its database and log files) in `/nix/var` by
default. This can be changed using `--localstatedir=path`.

56
doc/manual/src/installation/env-variables.md Normal file
View file

@ -0,0 +1,56 @@
# Environment Variables
To use Nix, some environment variables should be set. In particular,
PATH should contain the directories `prefix/bin` and
`~/.nix-profile/bin`. The first directory contains the Nix tools
themselves, while `~/.nix-profile` is a symbolic link to the current
*user environment* (an automatically generated package consisting of
symlinks to installed packages). The simplest way to set the required
environment variables is to include the file
`prefix/etc/profile.d/nix.sh` in your `~/.profile` (or similar), like
this:
source prefix/etc/profile.d/nix.sh
# NIX\_SSL\_CERT\_FILE
If you need to specify a custom certificate bundle to account for an
HTTPS-intercepting man in the middle proxy, you must specify the path to
the certificate bundle in the environment variable NIX\_SSL\_CERT\_FILE.
If you don't specify a NIX\_SSL\_CERT\_FILE manually, Nix will install
and use its own certificate bundle.
Set the environment variable and install Nix
$ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt
$ sh <(curl -L https://nixos.org/nix/install)
In the shell profile and rc files (for example, `/etc/bashrc`,
`/etc/zshrc`), add the following line:
export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt
> **Note**
>
> You must not add the export and then do the install, as the Nix
> installer will detect the presense of Nix configuration, and abort.
## NIX\_SSL\_CERT\_FILE with macOS and the Nix daemon
On macOS you must specify the environment variable for the Nix daemon
service, then restart it:
$ sudo launchctl setenv NIX_SSL_CERT_FILE /etc/ssl/my-certificate-bundle.crt
$ sudo launchctl kickstart -k system/org.nixos.nix-daemon
## Proxy Environment Variables
The Nix installer has special handling for these proxy-related
environment variables: `http_proxy`, `https_proxy`, `ftp_proxy`,
`no_proxy`, `HTTP_PROXY`, `HTTPS_PROXY`, `FTP_PROXY`, `NO_PROXY`.
If any of these variables are set when running the Nix installer, then
the installer will create an override file at
`/etc/systemd/system/nix-daemon.service.d/override.conf` so `nix-daemon`
will use them.

2
doc/manual/src/installation/installation.md Normal file
View file

@ -0,0 +1,2 @@
This section describes how to install and configure Nix for first-time
use.

273
doc/manual/src/installation/installing-binary.md Normal file
View file

@ -0,0 +1,273 @@
# Installing a Binary Distribution
If you are using Linux or macOS versions up to 10.14 (Mojave), the
easiest way to install Nix is to run the following command:
```
$ sh <(curl -L https://nixos.org/nix/install)
```
If you're using macOS 10.15 (Catalina) or newer, consult [the macOS
installation instructions](#sect-macos-installation) before installing.
As of Nix 2.1.0, the Nix installer will always default to creating a
single-user installation, however opting in to the multi-user
installation is highly recommended.
# Single User Installation
To explicitly select a single-user installation on your system:
```
sh <(curl -L https://nixos.org/nix/install) --no-daemon
```
This will perform a single-user installation of Nix, meaning that `/nix`
is owned by the invoking user. You should run this under your usual user
account, *not* as root. The script will invoke `sudo` to create `/nix`
if it doesn’t already exist. If you don’t have `sudo`, you should
manually create `/nix` first as root, e.g.:
$ mkdir /nix
$ chown alice /nix
The install script will modify the first writable file from amongst
`.bash_profile`, `.bash_login` and `.profile` to source
`~/.nix-profile/etc/profile.d/nix.sh`. You can set the
NIX\_INSTALLER\_NO\_MODIFY\_PROFILE environment variable before
executing the install script to disable this behaviour.
You can uninstall Nix simply by running:
$ rm -rf /nix
# Multi User Installation
The multi-user Nix installation creates system users, and a system
service for the Nix daemon.
- Linux running systemd, with SELinux disabled
- macOS
You can instruct the installer to perform a multi-user installation on
your system:
sh <(curl -L https://nixos.org/nix/install) --daemon
The multi-user installation of Nix will create build users between the
user IDs 30001 and 30032, and a group with the group ID 30000. You
should run this under your usual user account, *not* as root. The script
will invoke `sudo` as needed.
> **Note**
>
> If you need Nix to use a different group ID or user ID set, you will
> have to download the tarball manually and [edit the install
> script](#sect-nix-install-binary-tarball).
The installer will modify `/etc/bashrc`, and `/etc/zshrc` if they exist.
The installer will first back up these files with a `.backup-before-nix`
extension. The installer will also create `/etc/profile.d/nix.sh`.
You can uninstall Nix with the following commands:
sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels
# If you are on Linux with systemd, you will need to run:
sudo systemctl stop nix-daemon.socket
sudo systemctl stop nix-daemon.service
sudo systemctl disable nix-daemon.socket
sudo systemctl disable nix-daemon.service
sudo systemctl daemon-reload
# If you are on macOS, you will need to run:
sudo launchctl unload /Library/LaunchDaemons/org.nixos.nix-daemon.plist
sudo rm /Library/LaunchDaemons/org.nixos.nix-daemon.plist
There may also be references to Nix in `/etc/profile`, `/etc/bashrc`,
and `/etc/zshrc` which you may remove.
# macOS Installation
Starting with macOS 10.15 (Catalina), the root filesystem is read-only.
This means `/nix` can no longer live on your system volume, and that
you'll need a workaround to install Nix.
The recommended approach, which creates an unencrypted APFS volume for
your Nix store and a "synthetic" empty directory to mount it over at
`/nix`, is least likely to impair Nix or your system.
> **Note**
>
> With all separate-volume approaches, it's possible something on your
> system (particularly daemons/services and restored apps) may need
> access to your Nix store before the volume is mounted. Adding
> additional encryption makes this more likely.
If you're using a recent Mac with a [T2
chip](https://www.apple.com/euro/mac/shared/docs/Apple_T2_Security_Chip_Overview.pdf),
your drive will still be encrypted at rest (in which case "unencrypted"
is a bit of a misnomer). To use this approach, just install Nix with:
$ sh <(curl -L https://nixos.org/nix/install) --darwin-use-unencrypted-nix-store-volume
If you don't like the sound of this, you'll want to weigh the other
approaches and tradeoffs detailed in this section.
> **Note**
>
> All of the known workarounds have drawbacks, but we hope better
> solutions will be available in the future. Some that we have our eye
> on are:
>
> 1. A true firmlink would enable the Nix store to live on the primary
> data volume without the build problems caused by the symlink
> approach. End users cannot currently create true firmlinks.
>
> 2. If the Nix store volume shared FileVault encryption with the
> primary data volume (probably by using the same volume group and
> role), FileVault encryption could be easily supported by the
> installer without requiring manual setup by each user.
## Change the Nix store path prefix
Changing the default prefix for the Nix store is a simple approach which
enables you to leave it on your root volume, where it can take full
advantage of FileVault encryption if enabled. Unfortunately, this
approach also opts your device out of some benefits that are enabled by
using the same prefix across systems:
- Your system won't be able to take advantage of the binary cache
(unless someone is able to stand up and support duplicate caching
infrastructure), which means you'll spend more time waiting for
builds.
- It's harder to build and deploy packages to Linux systems.
It would also possible (and often requested) to just apply this change
ecosystem-wide, but it's an intrusive process that has side effects we
want to avoid for now.
## Use a separate encrypted volume
If you like, you can also add encryption to the recommended approach
taken by the installer. You can do this by pre-creating an encrypted
volume before you run the installer--or you can run the installer and
encrypt the volume it creates later.
In either case, adding encryption to a second volume isn't quite as
simple as enabling FileVault for your boot volume. Before you dive in,
there are a few things to weigh:
1. The additional volume won't be encrypted with your existing
FileVault key, so you'll need another mechanism to decrypt the
volume.
2. You can store the password in Keychain to automatically decrypt the
volume on boot--but it'll have to wait on Keychain and may not mount
before your GUI apps restore. If any of your launchd agents or apps
depend on Nix-installed software (for example, if you use a
Nix-installed login shell), the restore may fail or break.
On a case-by-case basis, you may be able to work around this problem
by using `wait4path` to block execution until your executable is
available.
It's also possible to decrypt and mount the volume earlier with a
login hook--but this mechanism appears to be deprecated and its
future is unclear.
3. You can hard-code the password in the clear, so that your store
volume can be decrypted before Keychain is available.
If you are comfortable navigating these tradeoffs, you can encrypt the
volume with something along the lines of:
alice$ diskutil apfs enableFileVault /nix -user disk
## Symlink the Nix store to a custom location
Another simple approach is using `/etc/synthetic.conf` to symlink the
Nix store to the data volume. This option also enables your store to
share any configured FileVault encryption. Unfortunately, builds that
resolve the symlink may leak the canonical path or even fail.
Because of these downsides, we can't recommend this approach.
## Notes on the recommended approach
This section goes into a little more detail on the recommended approach.
You don't need to understand it to run the installer, but it can serve
as a helpful reference if you run into trouble.
1. In order to compose user-writable locations into the new read-only
system root, Apple introduced a new concept called `firmlinks`,
which it describes as a "bi-directional wormhole" between two
filesystems. You can see the current firmlinks in
`/usr/share/firmlinks`. Unfortunately, firmlinks aren't (currently?)
user-configurable.
For special cases like NFS mount points or package manager roots,
[synthetic.conf(5)](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man5/synthetic.conf.5.html)
supports limited user-controlled file-creation (of symlinks, and
synthetic empty directories) at `/`. To create a synthetic empty
directory for mounting at `/nix`, add the following line to
`/etc/synthetic.conf` (create it if necessary):
nix
2. This configuration is applied at boot time, but you can use
`apfs.util` to trigger creation (not deletion) of new entries
without a reboot:
alice$ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B
3. Create the new APFS volume with diskutil:
alice$ sudo diskutil apfs addVolume diskX APFS 'Nix Store' -mountpoint /nix
4. Using `vifs`, add the new mount to `/etc/fstab`. If it doesn't
already have other entries, it should look something like:
#
# Warning - this file should only be modified with vifs(8)
#
# Failure to do so is unsupported and may be destructive.
#
LABEL=Nix\040Store /nix apfs rw,nobrowse
The nobrowse setting will keep Spotlight from indexing this volume,
and keep it from showing up on your desktop.
# Installing a pinned Nix version from a URL
NixOS.org hosts version-specific installation URLs for all Nix versions
since 1.11.16, at `https://releases.nixos.org/nix/nix-version/install`.
These install scripts can be used the same as the main NixOS.org
installation script:
```
sh <(curl -L https://nixos.org/nix/install)
```
In the same directory of the install script are sha256 sums, and gpg
signature files.
# Installing from a binary tarball
You can also download a binary tarball that contains Nix and all its
dependencies. (This is what the install script at
<https://nixos.org/nix/install> does automatically.) You should unpack
it somewhere (e.g. in `/tmp`), and then run the script named `install`
inside the binary tarball:
alice$ cd /tmp
alice$ tar xfj nix-1.8-x86_64-darwin.tar.bz2
alice$ cd nix-1.8-x86_64-darwin
alice$ ./install
If you need to edit the multi-user installation script to use different
group ID or a different user ID range, modify the variables set in the
file named `install-multi-user`.

4
doc/manual/src/installation/installing-source.md Normal file
View file

@ -0,0 +1,4 @@
# Installing Nix from Source
If no binary package is available, you can download and compile a source
distribution.

63
doc/manual/src/installation/multi-user.md Normal file
View file

@ -0,0 +1,63 @@
# Multi-User Mode
To allow a Nix store to be shared safely among multiple users, it is
important that users are not able to run builders that modify the Nix
store or database in arbitrary ways, or that interfere with builds
started by other users. If they could do so, they could install a Trojan
horse in some package and compromise the accounts of other users.
To prevent this, the Nix store and database are owned by some privileged
user (usually `root`) and builders are executed under special user
accounts (usually named `nixbld1`, `nixbld2`, etc.). When a unprivileged
user runs a Nix command, actions that operate on the Nix store (such as
builds) are forwarded to a *Nix daemon* running under the owner of the
Nix store/database that performs the operation.
> **Note**
>
> Multi-user mode has one important limitation: only root and a set of
> trusted users specified in `nix.conf` can specify arbitrary binary
> caches. So while unprivileged users may install packages from
> arbitrary Nix expressions, they may not get pre-built binaries.
The *build users* are the special UIDs under which builds are performed.
They should all be members of the *build users group* `nixbld`. This
group should have no other members. The build users should not be
members of any other group. On Linux, you can create the group and users
as follows:
$ groupadd -r nixbld
$ for n in $(seq 1 10); do useradd -c "Nix build user $n" \
-d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \
nixbld$n; done
This creates 10 build users. There can never be more concurrent builds
than the number of build users, so you may want to increase this if you
expect to do many builds at the same time.
The [Nix daemon](#sec-nix-daemon) should be started as follows (as
`root`):
$ nix-daemon
You’ll want to put that line somewhere in your system’s boot scripts.
To let unprivileged users use the daemon, they should set the
[NIX\_REMOTE environment variable](#envar-remote) to `daemon`. So you
should put a line like
export NIX_REMOTE=daemon
into the users’ login scripts.
To limit which users can perform Nix operations, you can use the
permissions on the directory `/nix/var/nix/daemon-socket`. For instance,
if you want to restrict the use of Nix to the members of a group called
`nix-users`, do
$ chgrp nix-users /nix/var/nix/daemon-socket
$ chmod ug=rwx,o= /nix/var/nix/daemon-socket
This way, users who are not in the `nix-users` group cannot connect to
the Unix domain socket `/nix/var/nix/daemon-socket/socket`, so they
cannot perform Nix operations.

15
doc/manual/src/installation/nix-security.md Normal file
View file

@ -0,0 +1,15 @@
# Security
Nix has two basic security models. First, it can be used in “single-user
mode”, which is similar to what most other package management tools do:
there is a single user (typically root) who performs all package
management operations. All other users can then use the installed
packages, but they cannot perform package management operations
themselves.
Alternatively, you can configure Nix in “multi-user mode”. In this
model, all users can perform package management operations — for
instance, every user can install software without requiring root
privileges. Nix ensures that this is secure. For instance, it’s not
possible for one user to overwrite a package used by another user with a
Trojan horse.

16
doc/manual/src/installation/obtaining-source.md Normal file
View file

@ -0,0 +1,16 @@
# Obtaining a Source Distribution
The source tarball of the most recent stable release can be downloaded
from the [Nix homepage](http://nixos.org/nix/download.html). You can
also grab the [most recent development
release](http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents).
Alternatively, the most recent sources of Nix can be obtained from its
[Git repository](https://github.com/NixOS/nix). For example, the
following command will check out the latest revision into a directory
called `nix`:
$ git clone https://github.com/NixOS/nix
Likewise, specific releases can be obtained from the
[tags](https://github.com/NixOS/nix/tags) of the repository.

80
doc/manual/src/installation/prerequisites-source.md Normal file
View file

@ -0,0 +1,80 @@
# Prerequisites
- GNU Autoconf (<https://www.gnu.org/software/autoconf/>) and the
autoconf-archive macro collection
(<https://www.gnu.org/software/autoconf-archive/>). These are only
needed to run the bootstrap script, and are not necessary if your
source distribution came with a pre-built `./configure` script.
- GNU Make.
- Bash Shell. The `./configure` script relies on bashisms, so Bash is
required.
- A version of GCC or Clang that supports C++17.
- `pkg-config` to locate dependencies. If your distribution does not
provide it, you can get it from
<http://www.freedesktop.org/wiki/Software/pkg-config>.
- The OpenSSL library to calculate cryptographic hashes. If your
distribution does not provide it, you can get it from
<https://www.openssl.org>.
- The `libbrotlienc` and `libbrotlidec` libraries to provide
implementation of the Brotli compression algorithm. They are
available for download from the official repository
<https://github.com/google/brotli>.
- The bzip2 compressor program and the `libbz2` library. Thus you must
have bzip2 installed, including development headers and libraries.
If your distribution does not provide these, you can obtain bzip2
from
<https://web.archive.org/web/20180624184756/http://www.bzip.org/>.
- `liblzma`, which is provided by XZ Utils. If your distribution does
not provide this, you can get it from <https://tukaani.org/xz/>.
- cURL and its library. If your distribution does not provide it, you
can get it from <https://curl.haxx.se/>.
- The SQLite embedded database library, version 3.6.19 or higher. If
your distribution does not provide it, please install it from
<http://www.sqlite.org/>.
- The [Boehm garbage collector](http://www.hboehm.info/gc/) to reduce
the evaluator’s memory consumption (optional). To enable it, install
`pkgconfig` and the Boehm garbage collector, and pass the flag
`--enable-gc` to `configure`.
- The `boost` library of version 1.66.0 or higher. It can be obtained
from the official web site <https://www.boost.org/>.
- The `editline` library of version 1.14.0 or higher. It can be
obtained from the its repository
<https://github.com/troglobit/editline>.
- The `xmllint` and `xsltproc` programs to build this manual and the
man-pages. These are part of the `libxml2` and `libxslt` packages,
respectively. You also need the [DocBook XSL
stylesheets](http://docbook.sourceforge.net/projects/xsl/) and
optionally the [DocBook 5.0 RELAX NG
schemas](http://www.docbook.org/schemas/5x). Note that these are
only required if you modify the manual sources or when you are
building from the Git repository.
- Recent versions of Bison and Flex to build the parser. (This is
because Nix needs GLR support in Bison and reentrancy support in
Flex.) For Bison, you need version 2.6, which can be obtained from
the [GNU FTP server](ftp://alpha.gnu.org/pub/gnu/bison). For Flex,
you need version 2.5.35, which is available on
[SourceForge](http://lex.sourceforge.net/). Slightly older versions
may also work, but ancient versions like the ubiquitous 2.5.4a
won't. Note that these are only required if you modify the parser or
when you are building from the Git repository.
- The `libseccomp` is used to provide syscall filtering on Linux. This
is an optional dependency and can be disabled passing a
`--disable-seccomp-sandboxing` option to the `configure` script (Not
recommended unless your system doesn't support `libseccomp`). To get
the library, visit <https://github.com/seccomp/libseccomp>.

9
doc/manual/src/installation/single-user.md Normal file
View file

@ -0,0 +1,9 @@
# Single-User Mode
In single-user mode, all Nix operations that access the database in
`prefix/var/nix/db` or modify the Nix store in `prefix/store` must be
performed under the user ID that owns those directories. This is
typically root. (If you install from RPM packages, that’s in fact the
default ownership.) However, on single-user machines, it is often
convenient to `chown` those directories to your normal user account so
that you don’t have to `su` to root all the time.

7
doc/manual/src/installation/supported-platforms.md Normal file
View file

@ -0,0 +1,7 @@
# Supported Platforms
Nix is currently supported on the following platforms:
- Linux (i686, x86\_64, aarch64).
- macOS (x86\_64).

14
doc/manual/src/installation/upgrading.md Normal file
View file

@ -0,0 +1,14 @@
# Upgrading Nix
Multi-user Nix users on macOS can upgrade Nix by running: `sudo -i sh -c
'nix-channel --update &&
nix-env -iA nixpkgs.nix &&
launchctl remove org.nixos.nix-daemon &&
launchctl load /Library/LaunchDaemons/org.nixos.nix-daemon.plist'`
Single-user installations of Nix should run this: `nix-channel --update;
nix-env -iA nixpkgs.nix nixpkgs.cacert`
Multi-user Nix users on Linux should run this with sudo: `nix-channel
--update; nix-env -iA nixpkgs.nix nixpkgs.cacert; systemctl
daemon-reload; systemctl restart nix-daemon`

148
doc/manual/src/package-management/basic-package-mgmt.md Normal file
View file

@ -0,0 +1,148 @@
# Basic Package Management
The main command for package management is [`nix-env`](#sec-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
Nixpkgs package collection that contains packages ranging from basic
development stuff such as GCC and Glibc, to end-user applications like
Mozilla Firefox. (Nix is however not tied to the Nixpkgs package
collection; you could write your own Nix expressions based on Nixpkgs,
or completely new ones.)
You can manually download the latest version of Nixpkgs from
<http://nixos.org/nixpkgs/download.html>. However, it’s much more
convenient to use the Nixpkgs *channel*, since it makes it easy to stay
up to date with new versions of Nixpkgs. (Channels are described in more
detail in [???](#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:
$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
$ nix-channel --update
> **Note**
>
> On NixOS, you’re automatically subscribed to a NixOS channel
> corresponding to your NixOS major release (e.g.
> <http://nixos.org/channels/nixos-14.12>). A NixOS channel is identical
> to the Nixpkgs channel, except that it contains only Linux binaries
> and is updated only if a set of regression tests succeed.
You can view the set of available packages in Nixpkgs:
$ nix-env -qa
aterm-2.2
bash-3.0
binutils-2.15
bison-1.875d
blackdown-1.4.2
bzip2-1.0.2
…
The flag `-q` specifies a query operation, and `-a` means that you want
to show the “available” (i.e., installable) packages, as opposed to the
installed packages. If you downloaded Nixpkgs yourself, or if you
checked it out from GitHub, then you need to pass the path to your
Nixpkgs tree using the `-f` flag:
$ nix-env -qaf /path/to/nixpkgs
where /path/to/nixpkgs is where you’ve unpacked or checked out Nixpkgs.
You can select specific packages by name:
$ nix-env -qa firefox
firefox-34.0.5
firefox-with-plugins-34.0.5
and using regular expressions:
$ nix-env -qa 'firefox.*'
It is also possible to see the *status* of available packages, i.e.,
whether they are installed into the user environment and/or present in
the system:
$ nix-env -qas
…
-PS bash-3.0
--S binutils-2.15
IPS bison-1.875d
…
The first character (`I`) indicates whether the package is installed in
your current user environment. The second (`P`) indicates whether it is
present on your system (in which case installing it into your user
environment would be a very quick operation). The last one (`S`)
indicates whether there is a so-called *substitute* for the package,
which is Nix’s mechanism for doing binary deployment. It just means that
Nix knows that it can fetch a pre-built package from somewhere
(typically a network server) instead of building it locally.
You can install a package using `nix-env -i`. For instance,
$ nix-env -i subversion
will install the package called `subversion` (which is, of course, the
[Subversion version management system](http://subversion.tigris.org/)).
> **Note**
>
> When you ask Nix to install a package, it will first try to get it in
> pre-compiled form from a *binary cache*. By default, Nix will use the
> binary cache <https://cache.nixos.org>; it contains binaries for most
> packages in Nixpkgs. Only if no binary is available in the binary
> cache, Nix will build the package from source. So if `nix-env
> -i subversion` results in Nix building stuff from source, then either
> the package is not built for your platform by the Nixpkgs build
> servers, or your version of Nixpkgs is too old or too new. For
> instance, if you have a very recent checkout of Nixpkgs, then the
> Nixpkgs build servers may not have had a chance to build everything
> and upload the resulting binaries to <https://cache.nixos.org>. The
> Nixpkgs channel is only updated after all binaries have been uploaded
> to the cache, so if you stick to the Nixpkgs channel (rather than
> using a Git checkout of the Nixpkgs tree), you will get binaries for
> most packages.
Naturally, packages can also be uninstalled:
$ nix-env -e subversion
Upgrading to a new version is just as easy. If you have a new release of
Nix Packages, you can do:
$ nix-env -u subversion
This will *only* upgrade Subversion if there is a “newer” version in the
new set of Nix expressions, as defined by some pretty arbitrary rules
regarding ordering of version numbers (which generally do what you’d
expect of them). To just unconditionally replace Subversion with
whatever version is in the Nix expressions, use `-i` instead of `-u`;
`-i` will remove whatever version is already installed.
You can also upgrade all packages for which there are newer versions:
$ nix-env -u
Sometimes it’s useful to be able to ask what `nix-env` would do, without
actually doing it. For instance, to find out what packages would be
upgraded by `nix-env -u`, you can do
$ nix-env -u --dry-run
(dry run; not doing anything)
upgrading `libxslt-1.1.0' to `libxslt-1.1.10'
upgrading `graphviz-1.10' to `graphviz-1.12'
upgrading `coreutils-5.0' to `coreutils-5.2.1'

42
doc/manual/src/package-management/binary-cache-substituter.md Normal file
View file

@ -0,0 +1,42 @@
# Serving a Nix store via HTTP
You can easily share the Nix store of a machine via HTTP. This allows
other machines to fetch store paths from that machine to speed up
installations. It uses the same *binary cache* mechanism that Nix
usually uses to fetch pre-built binaries from <https://cache.nixos.org>.
The daemon that handles binary cache requests via HTTP, `nix-serve`, is
not part of the Nix distribution, but you can install it from Nixpkgs:
$ nix-env -i nix-serve
You can then start the server, listening for HTTP connections on
whatever port you like:
$ nix-serve -p 8080
To check whether it works, try the following on the client:
$ curl http://avalon:8080/nix-cache-info
which should print something like:
StoreDir: /nix/store
WantMassQuery: 1
Priority: 30
On the client side, you can tell Nix to use your binary cache using
`--option extra-binary-caches`, e.g.:
$ nix-env -i firefox --option extra-binary-caches http://avalon:8080/
The option `extra-binary-caches` tells Nix to use this binary cache in
addition to your default caches, such as <https://cache.nixos.org>.
Thus, for any path in the closure of Firefox, Nix will first check if
the path is available on the server `avalon` or another binary caches.
If not, it will fall back to building from source.
You can also tell Nix to always use your binary cache by adding a line
to the `nix.conf` configuration file like this:
binary-caches = http://avalon:8080/ https://cache.nixos.org/

42
doc/manual/src/package-management/channels.md Normal file
View file

@ -0,0 +1,42 @@
# Channels
If you want to stay up to date with a set of packages, it’s not very
convenient to manually download the latest set of Nix expressions for
those packages and upgrade using `nix-env`. Fortunately, there’s a
better way: *Nix channels*.
A Nix channel is just a URL that points to a place that contains a set
of Nix expressions and a manifest. Using the command
[`nix-channel`](#sec-nix-channel) you can automatically stay up to date
with whatever is available at that URL.
To see the list of official NixOS channels, visit
<https://nixos.org/channels>.
You can “subscribe” to a channel using `nix-channel --add`, e.g.,
$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
subscribes you to a channel that always contains that latest version of
the Nix Packages collection. (Subscribing really just means that the URL
is added to the file `~/.nix-channels`, where it is read by subsequent
calls to `nix-channel
--update`.) You can “unsubscribe” using `nix-channel
--remove`:
$ nix-channel --remove nixpkgs
To obtain the latest Nix expressions available in a channel, do
$ nix-channel --update
This downloads and unpacks the Nix expressions in every channel
(downloaded from `url/nixexprs.tar.bz2`). It also makes the union of
each channel’s Nix expressions available by default to `nix-env`
operations (via the symlink `~/.nix-defexpr/channels`). Consequently,
you can then say
$ nix-env -u
to upgrade all packages in your profile to the latest versions available
in the subscribed channels.

34
doc/manual/src/package-management/copy-closure.md Normal file
View file

@ -0,0 +1,34 @@
# Copying Closures Via SSH
The command `nix-copy-closure` copies a Nix store path along with all
its dependencies to or from another machine via the SSH protocol. It
doesn’t copy store paths that are already present on the target machine.
For example, the following command copies Firefox with all its
dependencies:
$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)
See [???](#sec-nix-copy-closure) for details.
With `nix-store
--export` and `nix-store --import` you can write the closure of a store
path (that is, the path and all its dependencies) to a file, and then
unpack that file into another Nix store. For example,
$ nix-store --export $(nix-store -qR $(type -p firefox)) > firefox.closure
writes the closure of Firefox to a file. You can then copy this file to
another machine and install the closure:
$ nix-store --import < firefox.closure
Any store paths in the closure that are already present in the target
store are ignored. It is also possible to pipe the export into another
command, e.g. to copy and install a closure directly to/on another
machine:
$ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \
ssh alice@itchy.example.org "bunzip2 | nix-store --import"
However, `nix-copy-closure` is generally more efficient because it only
copies paths that are not already present in the target Nix store.

61
doc/manual/src/package-management/garbage-collection.md Normal file
View file

@ -0,0 +1,61 @@
# Garbage Collection
`nix-env` operations such as upgrades (`-u`) and uninstall (`-e`) never
actually delete packages from the system. All they do (as shown above)
is to create a new user environment that no longer contains symlinks to
the “deleted” packages.
Of course, since disk space is not infinite, unused packages should be
removed at some point. You can do this by running the Nix garbage
collector. It will remove from the Nix store any package not used
(directly or indirectly) by any generation of any profile.
Note however that as long as old generations reference a package, it
will not be deleted. After all, we wouldn’t be able to do a rollback
otherwise. So in order for garbage collection to be effective, you
should also delete (some) old generations. Of course, this should only
be done if you are certain that you will not need to roll back.
To delete all old (non-current) generations of your current profile:
$ nix-env --delete-generations old
Instead of `old` you can also specify a list of generations, e.g.,
$ nix-env --delete-generations 10 11 14
To delete all generations older than a specified number of days (except
the current generation), use the `d` suffix. For example,
$ nix-env --delete-generations 14d
deletes all generations older than two weeks.
After removing appropriate old generations you can run the garbage
collector as follows:
$ nix-store --gc
The behaviour of the gargage collector is affected by the
`keep-derivations` (default: true) and `keep-outputs` (default: false)
options in the Nix configuration file. The defaults will ensure that all
derivations that are build-time dependencies of garbage collector roots
will be kept and that all output paths that are runtime dependencies
will be kept as well. All other derivations or paths will be collected.
(This is usually what you want, but while you are developing it may make
sense to keep outputs to ensure that rebuild times are quick.) If you
are feeling uncertain, you can also first view what files would be
deleted:
$ nix-store --gc --print-dead
Likewise, the option `--print-live` will show the paths that *won’t* be
deleted.
There is also a convenient little utility `nix-collect-garbage`, which
when invoked with the `-d` (`--delete-old`) switch deletes all old
generations of all profiles in `/nix/var/nix/profiles`. So
$ nix-collect-garbage -d
is a quick and easy way to clean up your system.

16
doc/manual/src/package-management/garbage-collector-roots.md Normal file
View file

@ -0,0 +1,16 @@
# Garbage Collector Roots
The roots of the garbage collector are all store paths to which there
are symlinks in the directory `prefix/nix/var/nix/gcroots`. For
instance, the following command makes the path
`/nix/store/d718ef...-foo` a root of the collector:
$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar
That is, after this command, the garbage collector will not remove
`/nix/store/d718ef...-foo` or any of its dependencies.
Subdirectories of `prefix/nix/var/nix/gcroots` are also searched for
symlinks. Symlinks to non-store paths are followed and searched for
roots, but symlinks to non-store paths *inside* the paths reached in
that way are not followed to prevent infinite recursion.

4
doc/manual/src/package-management/package-management.md Normal file
View file

@ -0,0 +1,4 @@
This chapter discusses how to do package management with Nix, i.e., how
to obtain, install, upgrade, and erase packages. This is the “user’s”
perspective of the Nix system — people who want to *create* packages
should consult [???](#chap-writing-nix-expressions).

119
doc/manual/src/package-management/profiles.md Normal file
View file

@ -0,0 +1,119 @@
# Profiles
Profiles and user environments are Nix’s mechanism for implementing the
ability to allow different users to have different configurations, and
to do atomic upgrades and rollbacks. To understand how they work, it’s
useful to know a bit about how Nix works. In Nix, packages are stored in
unique locations in the *Nix store* (typically, `/nix/store`). For
instance, a particular version of the Subversion package might be stored
in a directory
`/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/`, while
another version might be stored in
`/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2`. The long
strings prefixed to the directory names are cryptographic hashes\[1\] 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\_title](#fig-user-environments) shows
a part of a typical Nix store.
![User environments](../figures/user-environments.png)
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\_title](#fig-user-environments) the user environment
`/nix/store/0c1p5z4kda11...-user-env` contains a symlink to just
Subversion 1.1.2 (arrows in the figure indicate symlinks). This would be
what we would obtain if we had done
$ nix-env -i subversion
on a set of Nix expressions that contained Subversion 1.1.2.
This doesn’t in itself solve the problem, of course; you wouldn’t want
to type `/nix/store/0c1p5z4kda11...-user-env/bin/svn` either. That’s why
there are symlinks outside of the store that point to the user
environments in the store; for instance, the symlinks `default-42-link`
and `default-43-link` in the example. These are called *generations*
since every time you perform a `nix-env` operation, a new user
environment is generated based on the current one. For instance,
generation 43 was created from generation 42 when we did
$ nix-env -i subversion firefox
on a set of Nix expressions that contained Firefox and a new version of
Subversion.
Generations are grouped together into *profiles* so that different users
don’t interfere with each other if they don’t want to. For example:
$ ls -l /nix/var/nix/profiles/
...
lrwxrwxrwx 1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env
lrwxrwxrwx 1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env
lrwxrwxrwx 1 eelco ... default -> default-43-link
This shows a profile called `default`. The file `default` itself is
actually a symlink that points to the current generation. When we do a
`nix-env` operation, a new user environment and generation link are
created based on the current one, and finally the `default` symlink is
made to point at the new generation. This last step is atomic on Unix,
which explains how we can do atomic upgrades. (Note that the
building/installing of new packages doesn’t interfere in any way with
old packages, since they are stored in different locations in the Nix
store.)
If you find that you want to undo a `nix-env` operation, you can just do
$ nix-env --rollback
which will just make the current generation link point at the previous
link. E.g., `default` would be made to point at `default-42-link`. You
can also switch to a specific generation:
$ nix-env --switch-generation 43
which in this example would roll forward to generation 43 again. You can
also see all available generations:
$ nix-env --list-generations
You generally wouldn’t have `/nix/var/nix/profiles/some-profile/bin` in
your PATH. Rather, there is a symlink `~/.nix-profile` that points to
your current profile. This means that you should put
`~/.nix-profile/bin` in your PATH (and indeed, that’s what the
initialisation script `/nix/etc/profile.d/nix.sh` does). This makes it
easier to switch to a different profile. You can do that using the
command `nix-env --switch-profile`:
$ nix-env --switch-profile /nix/var/nix/profiles/my-profile
$ nix-env --switch-profile /nix/var/nix/profiles/default
These commands switch to the `my-profile` and default profile,
respectively. If the profile doesn’t exist, it will be created
automatically. You should be careful about storing a profile in another
location than the `profiles` directory, since otherwise it might not be
used as a root of the garbage collector (see
[???](#sec-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.
1. 160-bit truncations of SHA-256 hashes encoded in a base-32 notation,
to be precise.

133
doc/manual/src/package-management/s3-substituter.md Normal file
View file

@ -0,0 +1,133 @@
# Serving a Nix store via AWS S3 or S3-compatible Service
Nix has built-in support for storing and fetching store paths from
Amazon S3 and S3 compatible services. This uses the same *binary* cache
mechanism that Nix usually uses to fetch prebuilt binaries from
[cache.nixos.org](cache.nixos.org).
The following options can be specified as URL parameters to the S3 URL:
- `profile`
The name of the AWS configuration profile to use. By default Nix
will use the `default` profile.
- `region`
The region of the S3 bucket. `us–east-1` by default.
If your bucket is not in `us–east-1`, you should always explicitly
specify the region parameter.
- `endpoint`
The URL to your S3-compatible service, for when not using Amazon S3.
Do not specify this value if you're using Amazon S3.
> **Note**
>
> This endpoint must support HTTPS and will use path-based
> addressing instead of virtual host based addressing.
- `scheme`
The scheme used for S3 requests, `https` (default) or `http`. This
option allows you to disable HTTPS for binary caches which don't
support it.
> **Note**
>
> HTTPS should be used if the cache might contain sensitive
> information.
In this example we will use the bucket named `example-nix-cache`.
## Anonymous Reads to your S3-compatible binary cache
If your binary cache is publicly accessible and does not require
authentication, the simplest and easiest way to use Nix with your S3
compatible binary cache is to use the HTTP URL for that cache.
For AWS S3 the binary cache URL for example bucket will be exactly
<https://example-nix-cache.s3.amazonaws.com> or
<s3://example-nix-cache>. For S3 compatible binary caches, consult that
cache's documentation.
Your bucket will need the following bucket policy:
{
"Id": "DirectReads",
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowDirectReads",
"Action": [
"s3:GetObject",
"s3:GetBucketLocation"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::example-nix-cache",
"arn:aws:s3:::example-nix-cache/*"
],
"Principal": "*"
}
]
}
## Authenticated Reads to your S3 binary cache
For AWS S3 the binary cache URL for example bucket will be exactly
<s3://example-nix-cache>.
Nix will use the [default credential provider
chain](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html)
for authenticating requests to Amazon S3.
Nix supports authenticated reads from Amazon S3 and S3 compatible binary
caches.
Your bucket will need a bucket policy allowing the desired users to
perform the `s3:GetObject` and `s3:GetBucketLocation` action on all
objects in the bucket. The anonymous policy in [Anonymous Reads to your
S3-compatible binary cache](#ssec-s3-substituter-anonymous-reads) can be
updated to have a restricted `Principal` to support this.
## Authenticated Writes to your S3-compatible binary cache
Nix support fully supports writing to Amazon S3 and S3 compatible
buckets. The binary cache URL for our example bucket will be
<s3://example-nix-cache>.
Nix will use the [default credential provider
chain](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credentials.html)
for authenticating requests to Amazon S3.
Your account will need the following IAM policy to upload to the cache:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "UploadToCache",
"Effect": "Allow",
"Action": [
"s3:AbortMultipartUpload",
"s3:GetBucketLocation",
"s3:GetObject",
"s3:ListBucket",
"s3:ListBucketMultipartUploads",
"s3:ListMultipartUploadParts",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::example-nix-cache",
"arn:aws:s3:::example-nix-cache/*"
]
}
]
}
`nix copy --to
's3://example-nix-cache?profile=cache-upload&region=eu-west-2'
nixpkgs.hello`
`nix copy --to
's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com'
nixpkgs.hello`

6
doc/manual/src/package-management/sharing-packages.md Normal file
View file

@ -0,0 +1,6 @@
# Sharing Packages Between Machines
Sometimes you want to copy a package from one machine to another. Or,
you want to install some packages and you know that another machine
already has some or all of those packages or their dependencies. In that
case there are mechanisms to quickly copy packages between machines.

52
doc/manual/src/package-management/ssh-substituter.md Normal file
View file

@ -0,0 +1,52 @@
# Serving a Nix store via SSH
You can tell Nix to automatically fetch needed binaries from a remote
Nix store via SSH. For example, the following installs Firefox,
automatically fetching any store paths in Firefox’s closure if they are
available on the server `avalon`:
$ nix-env -i firefox --substituters ssh://alice@avalon
This works similar to the binary cache substituter that Nix usually
uses, only using SSH instead of HTTP: if a store path `P` is needed, Nix
will first check if it’s available in the Nix store on `avalon`. If not,
it will fall back to using the binary cache substituter, and then to
building from source.
> **Note**
>
> The SSH substituter currently does not allow you to enter an SSH
> passphrase interactively. Therefore, you should use `ssh-add` to load
> the decrypted private key into `ssh-agent`.
You can also copy the closure of some store path, without installing it
into your profile, e.g.
$ nix-store -r /nix/store/m85bxg…-firefox-34.0.5 --substituters ssh://alice@avalon
This is essentially equivalent to doing
$ nix-copy-closure --from alice@avalon /nix/store/m85bxg…-firefox-34.0.5
You can use SSH’s *forced command* feature to set up a restricted user
account for SSH substituter access, allowing read-only access to the
local Nix store, but nothing more. For example, add the following lines
to `sshd_config` to restrict the user `nix-ssh`:
Match User nix-ssh
AllowAgentForwarding no
AllowTcpForwarding no
PermitTTY no
PermitTunnel no
X11Forwarding no
ForceCommand nix-store --serve
Match All
On NixOS, you can accomplish the same by adding the following to your
`configuration.nix`:
nix.sshServe.enable = true;
nix.sshServe.keys = [ "ssh-dss AAAAB3NzaC1k... bob@example.org" ];
where the latter line lists the public keys of users that are allowed to
connect.

1
doc/manual/src/release-notes/release-notes.md Normal file
View file

@ -0,0 +1 @@
# Nix Release Notes

5
doc/manual/src/release-notes/rl-0.10.1.md Normal file
View file

@ -0,0 +1,5 @@
# Release 0.10.1 (2006-10-11)
This release fixes two somewhat obscure bugs that occur when evaluating
Nix expressions that are stored inside the Nix store (`NIX-67`). These
do not affect most users.

212
doc/manual/src/release-notes/rl-0.10.md Normal file
View file

@ -0,0 +1,212 @@
# Release 0.10 (2006-10-06)
> **Note**
>
> This version of Nix uses Berkeley DB 4.4 instead of 4.3. The database
> is upgraded automatically, but you should be careful not to use old
> versions of Nix that still use Berkeley DB 4.3. In particular, if you
> use a Nix installed through Nix, you should run
>
> $ nix-store --clear-substitutes
>
> first.
> **Warning**
>
> Also, the database schema has changed slighted to fix a performance
> issue (see below). When you run any Nix 0.10 command for the first
> time, the database will be upgraded automatically. This is
> irreversible.
- `nix-env` usability improvements:
- An option `--compare-versions` (or `-c`) has been added to
`nix-env
--query` to allow you to compare installed versions of packages
to available versions, or vice versa. An easy way to see if you
are up to date with what’s in your subscribed channels is
`nix-env -qc \*`.
- `nix-env --query` now takes as arguments a list of package names
about which to show information, just like `--install`, etc.:
for example, `nix-env -q gcc`. Note that to show all
derivations, you need to specify `\*`.
- `nix-env -i
pkgname` will now install the highest available version of
pkgname, rather than installing all available versions (which
would probably give collisions) (`NIX-31`).
- `nix-env (-i|-u) --dry-run` now shows exactly which missing
paths will be built or substituted.
- `nix-env -qa --description` shows human-readable descriptions of
packages, provided that they have a `meta.description` attribute
(which most packages in Nixpkgs don’t have yet).
- New language features:
- Reference scanning (which happens after each build) is much
faster and takes a constant amount of memory.
- String interpolation. Expressions like
"--with-freetype2-library=" + freetype + "/lib"
can now be written as
"--with-freetype2-library=${freetype}/lib"
You can write arbitrary expressions within `${...}`, not just
identifiers.
- Multi-line string literals.
- String concatenations can now involve derivations, as in the
example `"--with-freetype2-library="
+ freetype + "/lib"`. This was not previously possible because
we need to register that a derivation that uses such a string is
dependent on `freetype`. The evaluator now properly propagates
this information. Consequently, the subpath operator (`~`) has
been deprecated.
- Default values of function arguments can now refer to other
function arguments; that is, all arguments are in scope in the
default values (`NIX-45`).
- Lots of new built-in primitives, such as functions for list
manipulation and integer arithmetic. See the manual for a
complete list. All primops are now available in the set
`builtins`, allowing one to test for the availability of primop
in a backwards-compatible way.
- Real let-expressions: `let x = ...;
... z = ...; in ...`.
- New commands `nix-pack-closure` and `nix-unpack-closure` than can be
used to easily transfer a store path with all its dependencies to
another machine. Very convenient whenever you have some package on
your machine and you want to copy it somewhere else.
- XML support:
- `nix-env -q --xml` prints the installed or available packages in
an XML representation for easy processing by other tools.
- `nix-instantiate --eval-only
--xml` prints an XML representation of the resulting term. (The
new flag `--strict` forces ‘deep’ evaluation of the result,
i.e., list elements and attributes are evaluated recursively.)
- In Nix expressions, the primop `builtins.toXML` converts a term
to an XML representation. This is primarily useful for passing
structured information to builders.
- You can now unambiguously specify which derivation to build or
install in `nix-env`, `nix-instantiate` and `nix-build` using the
`--attr` / `-A` flags, which takes an attribute name as argument.
(Unlike symbolic package names such as `subversion-1.4.0`, attribute
names in an attribute set are unique.) For instance, a quick way to
perform a test build of a package in Nixpkgs is `nix-build
pkgs/top-level/all-packages.nix -A
foo`. `nix-env -q
--attr` shows the attribute names corresponding to each derivation.
- If the top-level Nix expression used by `nix-env`, `nix-instantiate`
or `nix-build` evaluates to a function whose arguments all have
default values, the function will be called automatically. Also, the
new command-line switch `--arg
name
value` can be used to specify function arguments on the command
line.
- `nix-install-package --url
URL` allows a package to be installed directly from the given URL.
- Nix now works behind an HTTP proxy server; just set the standard
environment variables http\_proxy, https\_proxy, ftp\_proxy or
all\_proxy appropriately. Functions such as `fetchurl` in Nixpkgs
also respect these variables.
- `nix-build -o
symlink` allows the symlink to the build result to be named
something other than `result`.
- Platform support:
- Support for 64-bit platforms, provided a [suitably patched ATerm
library](http://bugzilla.sen.cwi.nl:8080/show_bug.cgi?id=606) is
used. Also, files larger than 2 GiB are now supported.
- Added support for Cygwin (Windows, `i686-cygwin`), Mac OS X on
Intel (`i686-darwin`) and Linux on PowerPC (`powerpc-linux`).
- Users of SMP and multicore machines will appreciate that the
number of builds to be performed in parallel can now be
specified in the configuration file in the `build-max-jobs`
setting.
- Garbage collector improvements:
- Open files (such as running programs) are now used as roots of
the garbage collector. This prevents programs that have been
uninstalled from being garbage collected while they are still
running. The script that detects these additional runtime roots
(`find-runtime-roots.pl`) is inherently system-specific, but it
should work on Linux and on all platforms that have the `lsof`
utility.
- `nix-store --gc` (a.k.a. `nix-collect-garbage`) prints out the
number of bytes freed on standard output. `nix-store
--gc --print-dead` shows how many bytes would be freed by an
actual garbage collection.
- `nix-collect-garbage -d` removes all old generations of *all*
profiles before calling the actual garbage collector (`nix-store
--gc`). This is an easy way to get rid of all old packages in
the Nix store.
- `nix-store` now has an operation `--delete` to delete specific
paths from the Nix store. It won’t delete reachable
(non-garbage) paths unless `--ignore-liveness` is specified.
- Berkeley DB 4.4’s process registry feature is used to recover from
crashed Nix processes.
- A performance issue has been fixed with the `referer` table, which
stores the inverse of the `references` table (i.e., it tells you
what store paths refer to a given path). Maintaining this table
could take a quadratic amount of time, as well as a quadratic amount
of Berkeley DB log file space (in particular when running the
garbage collector) (`NIX-23`).
- Nix now catches the `TERM` and `HUP` signals in addition to the
`INT` signal. So you can now do a `killall
nix-store` without triggering a database recovery.
- `bsdiff` updated to version 4.3.
- Substantial performance improvements in expression evaluation and
`nix-env -qa`, all thanks to [Valgrind](http://valgrind.org/).
Memory use has been reduced by a factor 8 or so. Big speedup by
memoisation of path hashing.
- Lots of bug fixes, notably:
- Make sure that the garbage collector can run successfully when
the disk is full (`NIX-18`).
- `nix-env` now locks the profile to prevent races between
concurrent `nix-env` operations on the same profile (`NIX-7`).
- Removed misleading messages from `nix-env -i` (e.g.,
``installing
`foo'`` followed by ``uninstalling
`foo'``) (`NIX-17`).
- Nix source distributions are a lot smaller now since we no longer
include a full copy of the Berkeley DB source distribution (but only
the bits we need).
- Header files are now installed so that external programs can use the
Nix libraries.

167
doc/manual/src/release-notes/rl-0.11.md Normal file
View file

@ -0,0 +1,167 @@
# Release 0.11 (2007-12-31)
Nix 0.11 has many improvements over the previous stable release. The
most important improvement is secure multi-user support. It also
features many usability enhancements and language extensions, many of
them prompted by NixOS, the purely functional Linux distribution based
on Nix. Here is an (incomplete) list:
- Secure multi-user support. A single Nix store can now be shared
between multiple (possible untrusted) users. This is an important
feature for NixOS, where it allows non-root users to install
software. The old setuid method for sharing a store between multiple
users has been removed. Details for setting up a multi-user store
can be found in the manual.
- The new command `nix-copy-closure` gives you an easy and efficient
way to exchange software between machines. It copies the missing
parts of the closure of a set of store path to or from a remote
machine via `ssh`.
- A new kind of string literal: strings between double single-quotes
(`''`) have indentation “intelligently” removed. This allows large
strings (such as shell scripts or configuration file fragments in
NixOS) to cleanly follow the indentation of the surrounding
expression. It also requires much less escaping, since `''` is less
common in most languages than `"`.
- `nix-env` `--set` modifies the current generation of a profile so
that it contains exactly the specified derivation, and nothing else.
For example, `nix-env -p /nix/var/nix/profiles/browser --set
firefox` lets the profile named `browser` contain just Firefox.
- `nix-env` now maintains meta-information about installed packages in
profiles. The meta-information is the contents of the `meta`
attribute of derivations, such as `description` or `homepage`. The
command `nix-env -q --xml
--meta` shows all meta-information.
- `nix-env` now uses the `meta.priority` attribute of derivations to
resolve filename collisions between packages. Lower priority values
denote a higher priority. For instance, the GCC wrapper package and
the Binutils package in Nixpkgs both have a file `bin/ld`, so
previously if you tried to install both you would get a collision.
Now, on the other hand, the GCC wrapper declares a higher priority
than Binutils, so the former’s `bin/ld` is symlinked in the user
environment.
- `nix-env -i / -u`: instead of breaking package ties by version,
break them by priority and version number. That is, if there are
multiple packages with the same name, then pick the package with the
highest priority, and only use the version if there are multiple
packages with the same priority.
This makes it possible to mark specific versions/variant in Nixpkgs
more or less desirable than others. A typical example would be a
beta version of some package (e.g., `gcc-4.2.0rc1`) which should not
be installed even though it is the highest version, except when it
is explicitly selected (e.g., `nix-env -i
gcc-4.2.0rc1`).
- `nix-env --set-flag` allows meta attributes of installed packages to
be modified. There are several attributes that can be usefully
modified, because they affect the behaviour of `nix-env` or the user
environment build script:
- `meta.priority` can be changed to resolve filename clashes (see
above).
- `meta.keep` can be set to `true` to prevent the package from
being upgraded or replaced. Useful if you want to hang on to an
older version of a package.
- `meta.active` can be set to `false` to “disable” the package.
That is, no symlinks will be generated to the files of the
package, but it remains part of the profile (so it won’t be
garbage-collected). Set it back to `true` to re-enable the
package.
- `nix-env -q` now has a flag `--prebuilt-only` (`-b`) that causes
`nix-env` to show only those derivations whose output is already in
the Nix store or that can be substituted (i.e., downloaded from
somewhere). In other words, it shows the packages that can be
installed “quickly”, i.e., don’t need to be built from source. The
`-b` flag is also available in `nix-env -i` and `nix-env -u` to
filter out derivations for which no pre-built binary is available.
- The new option `--argstr` (in `nix-env`, `nix-instantiate` and
`nix-build`) is like `--arg`, except that the value is a string. For
example, `--argstr system
i686-linux` is equivalent to `--arg system
\"i686-linux\"` (note that `--argstr` prevents annoying quoting
around shell arguments).
- `nix-store` has a new operation `--read-log` (`-l`) `paths` that
shows the build log of the given paths.
- Nix now uses Berkeley DB 4.5. The database is upgraded
automatically, but you should be careful not to use old versions of
Nix that still use Berkeley DB 4.4.
- The option `--max-silent-time` (corresponding to the configuration
setting `build-max-silent-time`) allows you to set a timeout on
builds — if a build produces no output on `stdout` or `stderr` for
the given number of seconds, it is terminated. This is useful for
recovering automatically from builds that are stuck in an infinite
loop.
- `nix-channel`: each subscribed channel is its own attribute in the
top-level expression generated for the channel. This allows
disambiguation (e.g. `nix-env
-i -A nixpkgs_unstable.firefox`).
- The substitutes table has been removed from the database. This makes
operations such as `nix-pull` and `nix-channel --update` much, much
faster.
- `nix-pull` now supports bzip2-compressed manifests. This speeds up
channels.
- `nix-prefetch-url` now has a limited form of caching. This is used
by `nix-channel` to prevent unnecessary downloads when the channel
hasn’t changed.
- `nix-prefetch-url` now by default computes the SHA-256 hash of the
file instead of the MD5 hash. In calls to `fetchurl` you should pass
the `sha256` attribute instead of `md5`. You can pass either a
hexadecimal or a base-32 encoding of the hash.
- Nix can now perform builds in an automatically generated “chroot”.
This prevents a builder from accessing stuff outside of the Nix
store, and thus helps ensure purity. This is an experimental
feature.
- The new command `nix-store
--optimise` reduces Nix store disk space usage by finding identical
files in the store and hard-linking them to each other. It typically
reduces the size of the store by something like 25-35%.
- `~/.nix-defexpr` can now be a directory, in which case the Nix
expressions in that directory are combined into an attribute set,
with the file names used as the names of the attributes. The command
`nix-env
--import` (which set the `~/.nix-defexpr` symlink) is removed.
- Derivations can specify the new special attribute
`allowedReferences` to enforce that the references in the output of
a derivation are a subset of a declared set of paths. For example,
if `allowedReferences` is an empty list, then the output must not
have any references. This is used in NixOS to check that generated
files such as initial ramdisks for booting Linux don’t have any
dependencies.
- The new attribute `exportReferencesGraph` allows builders access to
the references graph of their inputs. This is used in NixOS for
tasks such as generating ISO-9660 images that contain a Nix store
populated with the closure of certain paths.
- Fixed-output derivations (like `fetchurl`) can define the attribute
`impureEnvVars` to allow external environment variables to be passed
to builders. This is used in Nixpkgs to support proxy configuration,
among other things.
- Several new built-in functions: `builtins.attrNames`,
`builtins.filterSource`, `builtins.isAttrs`, `builtins.isFunction`,
`builtins.listToAttrs`, `builtins.stringLength`, `builtins.sub`,
`builtins.substring`, `throw`, `builtins.trace`,
`builtins.readFile`.

123
doc/manual/src/release-notes/rl-0.12.md Normal file
View file

@ -0,0 +1,123 @@
# Release 0.12 (2008-11-20)
- Nix no longer uses Berkeley DB to store Nix store metadata. The
principal advantages of the new storage scheme are: it works
properly over decent implementations of NFS (allowing Nix stores to
be shared between multiple machines); no recovery is needed when a
Nix process crashes; no write access is needed for read-only
operations; no more running out of Berkeley DB locks on certain
operations.
You still need to compile Nix with Berkeley DB support if you want
Nix to automatically convert your old Nix store to the new schema.
If you don’t need this, you can build Nix with the `configure`
option `--disable-old-db-compat`.
After the automatic conversion to the new schema, you can delete the
old Berkeley DB files:
$ cd /nix/var/nix/db
$ rm __db* log.* derivers references referrers reserved validpaths DB_CONFIG
The new metadata is stored in the directories `/nix/var/nix/db/info`
and `/nix/var/nix/db/referrer`. Though the metadata is stored in
human-readable plain-text files, they are not intended to be
human-editable, as Nix is rather strict about the format.
The new storage schema may or may not require less disk space than
the Berkeley DB environment, mostly depending on the cluster size of
your file system. With 1 KiB clusters (which seems to be the `ext3`
default nowadays) it usually takes up much less space.
- There is a new substituter that copies paths directly from other
(remote) Nix stores mounted somewhere in the filesystem. For
instance, you can speed up an installation by mounting some remote
Nix store that already has the packages in question via NFS or
`sshfs`. The environment variable NIX\_OTHER\_STORES specifies the
locations of the remote Nix directories, e.g. `/mnt/remote-fs/nix`.
- New `nix-store` operations `--dump-db` and `--load-db` to dump and
reload the Nix database.
- The garbage collector has a number of new options to allow only some
of the garbage to be deleted. The option `--max-freed N` tells the
collector to stop after at least N bytes have been deleted. The
option `--max-links
N` tells it to stop after the link count on `/nix/store` has dropped
below N. This is useful for very large Nix stores on filesystems
with a 32000 subdirectories limit (like `ext3`). The option
`--use-atime` causes store paths to be deleted in order of ascending
last access time. This allows non-recently used stuff to be deleted.
The option `--max-atime time` specifies an upper limit to the last
accessed time of paths that may be deleted. For instance,
```
$ nix-store --gc -v --max-atime $(date +%s -d "2 months ago")
```
deletes everything that hasn’t been accessed in two months.
- `nix-env` now uses optimistic profile locking when performing an
operation like installing or upgrading, instead of setting an
exclusive lock on the profile. This allows multiple `nix-env -i / -u
/ -e` operations on the same profile in parallel. If a `nix-env`
operation sees at the end that the profile was changed in the
meantime by another process, it will just restart. This is generally
cheap because the build results are still in the Nix store.
- The option `--dry-run` is now supported by `nix-store -r` and
`nix-build`.
- The information previously shown by `--dry-run` (i.e., which
derivations will be built and which paths will be substituted) is
now always shown by `nix-env`, `nix-store -r` and `nix-build`. The
total download size of substitutable paths is now also shown. For
instance, a build will show something like
the following derivations will be built:
/nix/store/129sbxnk5n466zg6r1qmq1xjv9zymyy7-activate-configuration.sh.drv
/nix/store/7mzy971rdm8l566ch8hgxaf89x7lr7ik-upstart-jobs.drv
...
the following paths will be downloaded/copied (30.02 MiB):
/nix/store/4m8pvgy2dcjgppf5b4cj5l6wyshjhalj-samba-3.2.4
/nix/store/7h1kwcj29ip8vk26rhmx6bfjraxp0g4l-libunwind-0.98.6
...
- Language features:
- @-patterns as in Haskell. For instance, in a function definition
f = args @ {x, y, z}: ...;
`args` refers to the argument as a whole, which is further
pattern-matched against the attribute set pattern `{x, y, z}`.
- “`...`” (ellipsis) patterns. An attribute set pattern can now
say `...` at the end of the attribute name list to specify that
the function takes *at least* the listed attributes, while
ignoring additional attributes. For instance,
{stdenv, fetchurl, fuse, ...}: ...
defines a function that accepts any attribute set that includes
at least the three listed attributes.
- New primops: `builtins.parseDrvName` (split a package name
string like `"nix-0.12pre12876"` into its name and version
components, e.g. `"nix"` and `"0.12pre12876"`),
`builtins.compareVersions` (compare two version strings using
the same algorithm that `nix-env` uses), `builtins.length`
(efficiently compute the length of a list), `builtins.mul`
(integer multiplication), `builtins.div` (integer division).
- `nix-prefetch-url` now supports `mirror://` URLs, provided that the
environment variable NIXPKGS\_ALL points at a Nixpkgs tree.
- Removed the commands `nix-pack-closure` and `nix-unpack-closure`.
You can do almost the same thing but much more efficiently by doing
`nix-store --export
$(nix-store -qR paths) > closure` and `nix-store --import <
closure`.
- Lots of bug fixes, including a big performance bug in the handling
of `with`-expressions.

55
doc/manual/src/release-notes/rl-0.13.md Normal file
View file

@ -0,0 +1,55 @@
# Release 0.13 (2009-11-05)
This is primarily a bug fix release. It has some new features:
- Syntactic sugar for writing nested attribute sets. Instead of
{
foo = {
bar = 123;
xyzzy = true;
};
a = { b = { c = "d"; }; };
}
you can write
{
foo.bar = 123;
foo.xyzzy = true;
a.b.c = "d";
}
This is useful, for instance, in NixOS configuration files.
- Support for Nix channels generated by Hydra, the Nix-based
continuous build system. (Hydra generates NAR archives on the fly,
so the size and hash of these archives isn’t known in advance.)
- Support `i686-linux` builds directly on `x86_64-linux` Nix
installations. This is implemented using the `personality()`
syscall, which causes `uname` to return `i686` in child processes.
- Various improvements to the `chroot` support. Building in a `chroot`
works quite well now.
- Nix no longer blocks if it tries to build a path and another process
is already building the same path. Instead it tries to build another
buildable path first. This improves parallelism.
- Support for large (\> 4 GiB) files in NAR archives.
- Various (performance) improvements to the remote build mechanism.
- New primops: `builtins.addErrorContext` (to add a string to stack
traces — useful for debugging), `builtins.isBool`,
`builtins.isString`, `builtins.isInt`, `builtins.intersectAttrs`.
- OpenSolaris support (Sander van der Burg).
- Stack traces are no longer displayed unless the `--show-trace`
option is used.
- The scoping rules for `inherit
(e) ...` in recursive attribute sets have changed. The expression e
can now refer to the attributes defined in the containing set.

21
doc/manual/src/release-notes/rl-0.14.md Normal file
View file

@ -0,0 +1,21 @@
# Release 0.14 (2010-02-04)
This release has the following improvements:
- The garbage collector now starts deleting garbage much faster than
before. It no longer determines liveness of all paths in the store,
but does so on demand.
- Added a new operation, `nix-store --query
--roots`, that shows the garbage collector roots that directly or
indirectly point to the given store paths.
- Removed support for converting Berkeley DB-based Nix databases to
the new schema.
- Removed the `--use-atime` and `--max-atime` garbage collector
options. They were not very useful in practice.
- On Windows, Nix now requires Cygwin 1.7.x.
- A few bug fixes.

5
doc/manual/src/release-notes/rl-0.15.md Normal file
View file

@ -0,0 +1,5 @@
# Release 0.15 (2010-03-17)
This is a bug-fix release. Among other things, it fixes building on Mac
OS X (Snow Leopard), and improves the contents of `/etc/passwd` and
`/etc/group` in `chroot` builds.

25
doc/manual/src/release-notes/rl-0.16.md Normal file
View file

@ -0,0 +1,25 @@
# Release 0.16 (2010-08-17)
This release has the following improvements:
- The Nix expression evaluator is now much faster in most cases:
typically, [3 to 8 times compared to the old
implementation](http://www.mail-archive.com/nix-dev@cs.uu.nl/msg04113.html).
It also uses less memory. It no longer depends on the ATerm library.
- Support for configurable parallelism inside builders. Build scripts
have always had the ability to perform multiple build actions in
parallel (for instance, by running `make -j
2`), but this was not desirable because the number of actions to be
performed in parallel was not configurable. Nix now has an option
`--cores
N` as well as a configuration setting `build-cores =
N` that causes the environment variable NIX\_BUILD\_CORES to be set
to N when the builder is invoked. The builder can use this at its
discretion to perform a parallel build, e.g., by calling `make -j
N`. In Nixpkgs, this can be enabled on a per-package basis by
setting the derivation attribute `enableParallelBuilding` to `true`.
- `nix-store -q` now supports XML output through the `--xml` flag.
- Several bug fixes.

3
doc/manual/src/release-notes/rl-0.5.md Normal file
View file

@ -0,0 +1,3 @@
# Release 0.5 and earlier
Please refer to the Subversion commit log messages.

64
doc/manual/src/release-notes/rl-0.6.md Normal file
View file

@ -0,0 +1,64 @@
# Release 0.6 (2004-11-14)
- Rewrite of the normalisation engine.
- Multiple builds can now be performed in parallel (option `-j`).
- Distributed builds. Nix can now call a shell script to forward
builds to Nix installations on remote machines, which may or may
not be of the same platform type.
- Option `--fallback` allows recovery from broken substitutes.
- Option `--keep-going` causes building of other (unaffected)
derivations to continue if one failed.
- Improvements to the garbage collector (i.e., it should actually work
now).
- Setuid Nix installations allow a Nix store to be shared among
multiple users.
- Substitute registration is much faster now.
- A utility `nix-build` to build a Nix expression and create a symlink
to the result int the current directory; useful for testing Nix
derivations.
- Manual updates.
- `nix-env` changes:
- Derivations for other platforms are filtered out (which can be
overridden using `--system-filter`).
- `--install` by default now uninstall previous derivations with
the same name.
- `--upgrade` allows upgrading to a specific version.
- New operation `--delete-generations` to remove profile
generations (necessary for effective garbage collection).
- Nicer output (sorted, columnised).
- More sensible verbosity levels all around (builder output is now
shown always, unless `-Q` is given).
- Nix expression language changes:
- New language construct: `with
E1;
E2` brings all attributes defined in the attribute set E1 in
scope in E2.
- Added a `map` function.
- Various new operators (e.g., string concatenation).
- Expression evaluation is much faster.
- An Emacs mode for editing Nix expressions (with syntax highlighting
and indentation) has been added.
- Many bug fixes.

21
doc/manual/src/release-notes/rl-0.7.md Normal file
View file

@ -0,0 +1,21 @@
# Release 0.7 (2005-01-12)
- Binary patching. When upgrading components using pre-built binaries
(through nix-pull / nix-channel), Nix can automatically download and
apply binary patches to already installed components instead of full
downloads. Patching is “smart”: if there is a *sequence* of patches
to an installed component, Nix will use it. Patches are currently
generated automatically between Nixpkgs (pre-)releases.
- Simplifications to the substitute mechanism.
- Nix-pull now stores downloaded manifests in
`/nix/var/nix/manifests`.
- Metadata on files in the Nix store is canonicalised after builds:
the last-modified timestamp is set to 0 (00:00:00 1/1/1970), the
mode is set to 0444 or 0555 (readable and possibly executable by
all; setuid/setgid bits are dropped), and the group is set to the
default. This ensures that the result of a build and an installation
through a substitute is the same; and that timestamp dependencies
are revealed.

8
doc/manual/src/release-notes/rl-0.8.1.md Normal file
View file

@ -0,0 +1,8 @@
# Release 0.8.1 (2005-04-13)
This is a bug fix release.
- Patch downloading was broken.
- The garbage collector would not delete paths that had references
from invalid (but substitutable) paths.

166
doc/manual/src/release-notes/rl-0.8.md Normal file
View file

@ -0,0 +1,166 @@
# Release 0.8 (2005-04-11)
NOTE: the hashing scheme in Nix 0.8 changed (as detailed below). As a
result, `nix-pull` manifests and channels built for Nix 0.7 and below
will not work anymore. However, the Nix expression language has not
changed, so you can still build from source. Also, existing user
environments continue to work. Nix 0.8 will automatically upgrade the
database schema of previous installations when it is first run.
If you get the error message
you have an old-style manifest `/nix/var/nix/manifests/[...]'; please
delete it
you should delete previously downloaded manifests:
$ rm /nix/var/nix/manifests/*
If `nix-channel` gives the error message
manifest `http://catamaran.labs.cs.uu.nl/dist/nix/channels/[channel]/MANIFEST'
is too old (i.e., for Nix <= 0.7)
then you should unsubscribe from the offending channel (`nix-channel
--remove
URL`; leave out `/MANIFEST`), and subscribe to the same URL, with
`channels` replaced by `channels-v3` (e.g.,
<http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable>).
Nix 0.8 has the following improvements:
- The cryptographic hashes used in store paths are now 160 bits long,
but encoded in base-32 so that they are still only 32 characters
long (e.g.,
`/nix/store/csw87wag8bqlqk7ipllbwypb14xainap-atk-1.9.0`). (This is
actually a 160 bit truncation of a SHA-256 hash.)
- Big cleanups and simplifications of the basic store semantics. The
notion of “closure store expressions” is gone (and so is the notion
of “successors”); the file system references of a store path are now
just stored in the database.
For instance, given any store path, you can query its closure:
$ nix-store -qR $(which firefox)
... lots of paths ...
Also, Nix now remembers for each store path the derivation that
built it (the “deriver”):
$ nix-store -qR $(which firefox)
/nix/store/4b0jx7vq80l9aqcnkszxhymsf1ffa5jd-firefox-1.0.1.drv
So to see the build-time dependencies, you can do
$ nix-store -qR $(nix-store -qd $(which firefox))
or, in a nicer format:
$ nix-store -q --tree $(nix-store -qd $(which firefox))
File system references are also stored in reverse. For instance, you
can query all paths that directly or indirectly use a certain Glibc:
$ nix-store -q --referrers-closure \
/nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4
- The concept of fixed-output derivations has been formalised.
Previously, functions such as `fetchurl` in Nixpkgs used a hack
(namely, explicitly specifying a store path hash) to prevent changes
to, say, the URL of the file from propagating upwards through the
dependency graph, causing rebuilds of everything. This can now be
done cleanly by specifying the `outputHash` and `outputHashAlgo`
attributes. Nix itself checks that the content of the output has the
specified hash. (This is important for maintaining certain
invariants necessary for future work on secure shared stores.)
- One-click installation :-) It is now possible to install any
top-level component in Nixpkgs directly, through the web — see,
e.g., <http://catamaran.labs.cs.uu.nl/dist/nixpkgs-0.8/>. All you
have to do is associate `/nix/bin/nix-install-package` with the MIME
type `application/nix-package` (or the extension `.nixpkg`), and
clicking on a package link will cause it to be installed, with all
appropriate dependencies. If you just want to install some specific
application, this is easier than subscribing to a channel.
- `nix-store -r
PATHS` now builds all the derivations PATHS in parallel. Previously
it did them sequentially (though exploiting possible parallelism
between subderivations). This is nice for build farms.
- `nix-channel` has new operations `--list` and `--remove`.
- New ways of installing components into user environments:
- Copy from another user environment:
$ nix-env -i --from-profile .../other-profile firefox
- Install a store derivation directly (bypassing the Nix
expression language entirely):
$ nix-env -i /nix/store/z58v41v21xd3...-aterm-2.3.1.drv
(This is used to implement `nix-install-package`, which is
therefore immune to evolution in the Nix expression language.)
- Install an already built store path directly:
$ nix-env -i /nix/store/hsyj5pbn0d9i...-aterm-2.3.1
- Install the result of a Nix expression specified as a
command-line argument:
$ nix-env -f .../i686-linux.nix -i -E 'x: x.firefoxWrapper'
The difference with the normal installation mode is that `-E`
does not use the `name` attributes of derivations. Therefore,
this can be used to disambiguate multiple derivations with the
same name.
- A hash of the contents of a store path is now stored in the database
after a successful build. This allows you to check whether store
paths have been tampered with: `nix-store
--verify --check-contents`.
- Implemented a concurrent garbage collector. It is now always safe to
run the garbage collector, even if other Nix operations are
happening simultaneously.
However, there can still be GC races if you use `nix-instantiate`
and `nix-store
--realise` directly to build things. To prevent races, use the
`--add-root` flag of those commands.
- The garbage collector now finally deletes paths in the right order
(i.e., topologically sorted under the “references” relation), thus
making it safe to interrupt the collector without risking a store
that violates the closure invariant.
- Likewise, the substitute mechanism now downloads files in the right
order, thus preserving the closure invariant at all times.
- The result of `nix-build` is now registered as a root of the garbage
collector. If the `./result` link is deleted, the GC root disappears
automatically.
- The behaviour of the garbage collector can be changed globally by
setting options in `/nix/etc/nix/nix.conf`.
- `gc-keep-derivations` specifies whether deriver links should be
followed when searching for live paths.
- `gc-keep-outputs` specifies whether outputs of derivations
should be followed when searching for live paths.
- `env-keep-derivations` specifies whether user environments
should store the paths of derivations when they are added (thus
keeping the derivations alive).
- New `nix-env` query flags `--drv-path` and `--out-path`.
- `fetchurl` allows SHA-1 and SHA-256 in addition to MD5. Just specify
the attribute `sha1` or `sha256` instead of `md5`.
- Manual updates.

4
doc/manual/src/release-notes/rl-0.9.1.md Normal file
View file

@ -0,0 +1,4 @@
# Release 0.9.1 (2005-09-20)
This bug fix release addresses a problem with the ATerm library when the
`--with-aterm` flag in `configure` was *not* used.

11
doc/manual/src/release-notes/rl-0.9.2.md Normal file
View file

@ -0,0 +1,11 @@
# Release 0.9.2 (2005-09-21)
This bug fix release fixes two problems on Mac OS X:
- If Nix was linked against statically linked versions of the ATerm or
Berkeley DB library, there would be dynamic link errors at runtime.
- `nix-pull` and `nix-push` intermittently failed due to race
conditions involving pipes and child processes with error messages
such as `open2: open(GLOB(0x180b2e4), >&=9) failed: Bad
file descriptor at /nix/bin/nix-pull line 77` (issue `NIX-14`).

72
doc/manual/src/release-notes/rl-0.9.md Normal file
View file

@ -0,0 +1,72 @@
# Release 0.9 (2005-09-16)
NOTE: this version of Nix uses Berkeley DB 4.3 instead of 4.2. The
database is upgraded automatically, but you should be careful not to use
old versions of Nix that still use Berkeley DB 4.2. In particular, if
you use a Nix installed through Nix, you should run
$ nix-store --clear-substitutes
first.
- Unpacking of patch sequences is much faster now since we no longer
do redundant unpacking and repacking of intermediate paths.
- Nix now uses Berkeley DB 4.3.
- The `derivation` primitive is lazier. Attributes of dependent
derivations can mutually refer to each other (as long as there are
no data dependencies on the `outPath` and `drvPath` attributes
computed by `derivation`).
For example, the expression `derivation
attrs` now evaluates to (essentially)
attrs // {
type = "derivation";
outPath = derivation! attrs;
drvPath = derivation! attrs;
}
where `derivation!` is a primop that does the actual derivation
instantiation (i.e., it does what `derivation` used to do). The
advantage is that it allows commands such as `nix-env -qa` and
`nix-env -i` to be much faster since they no longer need to
instantiate all derivations, just the `name` attribute.
Also, it allows derivations to cyclically reference each other, for
example,
webServer = derivation {
...
hostName = "svn.cs.uu.nl";
services = [svnService];
};
svnService = derivation {
...
hostName = webServer.hostName;
};
Previously, this would yield a black hole (infinite recursion).
- `nix-build` now defaults to using `./default.nix` if no Nix
expression is specified.
- `nix-instantiate`, when applied to a Nix expression that evaluates
to a function, will call the function automatically if all its
arguments have defaults.
- Nix now uses libtool to build dynamic libraries. This reduces the
size of executables.
- A new list concatenation operator `++`. For example, `[1 2 3] ++
[4 5
6]` evaluates to `[1 2 3 4 5
6]`.
- Some currently undocumented primops to support low-level build
management using Nix (i.e., using Nix as a Make replacement). See
the commit messages for `r3578` and `r3580`.
- Various bug fixes and performance improvements.

68
doc/manual/src/release-notes/rl-1.0.md Normal file
View file

@ -0,0 +1,68 @@
# Release 1.0 (2012-05-11)
There have been numerous improvements and bug fixes since the previous
release. Here are the most significant:
- Nix can now optionally use the Boehm garbage collector. This
significantly reduces the Nix evaluator’s memory footprint,
especially when evaluating large NixOS system configurations. It can
be enabled using the `--enable-gc` configure option.
- Nix now uses SQLite for its database. This is faster and more
flexible than the old *ad hoc* format. SQLite is also used to cache
the manifests in `/nix/var/nix/manifests`, resulting in a
significant speedup.
- Nix now has an search path for expressions. The search path is set
using the environment variable NIX\_PATH and the `-I` command line
option. In Nix expressions, paths between angle brackets are used to
specify files that must be looked up in the search path. For
instance, the expression `<nixpkgs/default.nix>` looks for a file
`nixpkgs/default.nix` relative to every element in the search path.
- The new command `nix-build --run-env` builds all dependencies of a
derivation, then starts a shell in an environment containing all
variables from the derivation. This is useful for reproducing the
environment of a derivation for development.
- The new command `nix-store --verify-path` verifies that the contents
of a store path have not changed.
- The new command `nix-store --print-env` prints out the environment
of a derivation in a format that can be evaluated by a shell.
- Attribute names can now be arbitrary strings. For instance, you can
write `{ "foo-1.2" = …; "bla bla" = …; }."bla
bla"`.
- Attribute selection can now provide a default value using the `or`
operator. For instance, the expression `x.y.z or e` evaluates to the
attribute `x.y.z` if it exists, and `e` otherwise.
- The right-hand side of the `?` operator can now be an attribute
path, e.g., `attrs ?
a.b.c`.
- On Linux, Nix will now make files in the Nix store immutable on
filesystems that support it. This prevents accidental modification
of files in the store by the root user.
- Nix has preliminary support for derivations with multiple outputs.
This is useful because it allows parts of a package to be deployed
and garbage-collected separately. For instance, development parts of
a package such as header files or static libraries would typically
not be part of the closure of an application, resulting in reduced
disk usage and installation time.
- The Nix store garbage collector is faster and holds the global lock
for a shorter amount of time.
- The option `--timeout` (corresponding to the configuration setting
`build-timeout`) allows you to set an absolute timeout on builds —
if a build runs for more than the given number of seconds, it is
terminated. This is useful for recovering automatically from builds
that are stuck in an infinite loop but keep producing output, and
for which `--max-silent-time` is ineffective.
- Nix development has moved to GitHub
(<https://github.com/NixOS/nix>).

61
doc/manual/src/release-notes/rl-1.1.md Normal file
View file

@ -0,0 +1,61 @@
# Release 1.1 (2012-07-18)
This release has the following improvements:
- On Linux, when doing a chroot build, Nix now uses various namespace
features provided by the Linux kernel to improve build isolation.
Namely:
- The private network namespace ensures that builders cannot talk
to the outside world (or vice versa): each build only sees a
private loopback interface. This also means that two concurrent
builds can listen on the same port (e.g. as part of a test)
without conflicting with each other.
- The PID namespace causes each build to start as PID 1. Processes
outside of the chroot are not visible to those on the inside. On
the other hand, processes inside the chroot *are* visible from
the outside (though with different PIDs).
- The IPC namespace prevents the builder from communicating with
outside processes using SysV IPC mechanisms (shared memory,
message queues, semaphores). It also ensures that all IPC
objects are destroyed when the builder exits.
- The UTS namespace ensures that builders see a hostname of
`localhost` rather than the actual hostname.
- The private mount namespace was already used by Nix to ensure
that the bind-mounts used to set up the chroot are cleaned up
automatically.
- Build logs are now compressed using `bzip2`. The command `nix-store
-l` decompresses them on the fly. This can be disabled by setting
the option `build-compress-log` to `false`.
- The creation of build logs in `/nix/var/log/nix/drvs` can be
disabled by setting the new option `build-keep-log` to `false`. This
is useful, for instance, for Hydra build machines.
- Nix now reserves some space in `/nix/var/nix/db/reserved` to ensure
that the garbage collector can run successfully if the disk is full.
This is necessary because SQLite transactions fail if the disk is
full.
- Added a basic `fetchurl` function. This is not intended to replace
the `fetchurl` in Nixpkgs, but is useful for bootstrapping; e.g., it
will allow us to get rid of the bootstrap binaries in the Nixpkgs
source tree and download them instead. You can use it by doing
`import <nix/fetchurl.nix> { url =
url; sha256 =
"hash"; }`. (Shea Levy)
- Improved RPM spec file. (Michel Alexandre Salim)
- Support for on-demand socket-based activation in the Nix daemon with
`systemd`.
- Added a manpage for nix.conf5.
- When using the Nix daemon, the `-s` flag in `nix-env -qa` is now
much faster.

31
doc/manual/src/release-notes/rl-1.10.md Normal file
View file

@ -0,0 +1,31 @@
# Release 1.10 (2015-09-03)
This is primarily a bug fix release. It also has a number of new
features:
- A number of builtin functions have been added to reduce
Nixpkgs/NixOS evaluation time and memory consumption: `all`, `any`,
`concatStringsSep`, `foldl’`, `genList`, `replaceStrings`, `sort`.
- The garbage collector is more robust when the disk is full.
- Nix supports a new API for building derivations that doesn’t require
a `.drv` file to be present on disk; it only requires an in-memory
representation of the derivation. This is used by the Hydra
continuous build system to make remote builds more efficient.
- The function `<nix/fetchurl.nix>` now uses a *builtin* builder (i.e.
it doesn’t require starting an external process; the download is
performed by Nix itself). This ensures that derivation paths don’t
change when Nix is upgraded, and obviates the need for ugly hacks to
support chroot execution.
- `--version -v` now prints some configuration information, in
particular what compile-time optional features are enabled, and the
paths of various directories.
- Build users have their supplementary groups set correctly.
This release has contributions from Eelco Dolstra, Guillaume Maudoux,
Iwan Aucamp, Jaka Hudoklin, Kirill Elagin, Ludovic Courtès, Manolis
Ragkousis, Nicolas B. Pierron and Shea Levy.

21
doc/manual/src/release-notes/rl-1.11.10.md Normal file
View file

@ -0,0 +1,21 @@
# Release 1.11.10 (2017-06-12)
This release fixes a security bug in Nix’s “build user” build isolation
mechanism. Previously, Nix builders had the ability to create setuid
binaries owned by a `nixbld` user. Such a binary could then be used by
an attacker to assume a `nixbld` identity and interfere with subsequent
builds running under the same UID.
To prevent this issue, Nix now disallows builders to create setuid and
setgid binaries. On Linux, this is done using a seccomp BPF filter. Note
that this imposes a small performance penalty (e.g. 1% when building GNU
Hello). Using seccomp, we now also prevent the creation of extended
attributes and POSIX ACLs since these cannot be represented in the NAR
format and (in the case of POSIX ACLs) allow bypassing regular Nix store
permissions. On macOS, the restriction is implemented using the existing
sandbox mechanism, which now uses a minimal “allow all except the
creation of setuid/setgid binaries” profile when regular sandboxing is
disabled. On other platforms, the “build user” mechanism is now
disabled.
Thanks go to Linus Heckemann for discovering and reporting this bug.

87
doc/manual/src/release-notes/rl-1.11.md Normal file
View file

@ -0,0 +1,87 @@
# Release 1.11 (2016-01-19)
This is primarily a bug fix release. It also has a number of new
features:
- `nix-prefetch-url` can now download URLs specified in a Nix
expression. For example,
$ nix-prefetch-url -A hello.src
will prefetch the file specified by the `fetchurl` call in the
attribute `hello.src` from the Nix expression in the current
directory, and print the cryptographic hash of the resulting file on
stdout. This differs from `nix-build -A
hello.src` in that it doesn't verify the hash, and is thus useful
when you’re updating a Nix expression.
You can also prefetch the result of functions that unpack a tarball,
such as `fetchFromGitHub`. For example:
$ nix-prefetch-url --unpack https://github.com/NixOS/patchelf/archive/0.8.tar.gz
or from a Nix expression:
$ nix-prefetch-url -A nix-repl.src
- The builtin function `<nix/fetchurl.nix>` now supports downloading
and unpacking NARs. This removes the need to have multiple downloads
in the Nixpkgs stdenv bootstrap process (like a separate busybox
binary for Linux, or curl/mkdir/sh/bzip2 for Darwin). Now all those
files can be combined into a single NAR, optionally compressed using
`xz`.
- Nix now supports SHA-512 hashes for verifying fixed-output
derivations, and in `builtins.hashString`.
- The new flag `--option build-repeat
N` will cause every build to be executed N+1 times. If the build
output differs between any round, the build is rejected, and the
output paths are not registered as valid. This is primarily useful
to verify build determinism. (We already had a `--check` option to
repeat a previously succeeded build. However, with `--check`,
non-deterministic builds are registered in the DB. Preventing that
is useful for Hydra to ensure that non-deterministic builds don't
end up getting published to the binary cache.)
- The options `--check` and `--option
build-repeat N`, if they detect a difference between two runs of the
same derivation and `-K` is given, will make the output of the other
run available under `store-path-check`. This makes it easier to
investigate the non-determinism using tools like `diffoscope`, e.g.,
$ nix-build pkgs/stdenv/linux -A stage1.pkgs.zlib --check -K
error: derivation ‘/nix/store/l54i8wlw2265…-zlib-1.2.8.drv’ may not
be deterministic: output ‘/nix/store/11a27shh6n2i…-zlib-1.2.8’
differs from ‘/nix/store/11a27shh6n2i…-zlib-1.2.8-check’
$ diffoscope /nix/store/11a27shh6n2i…-zlib-1.2.8 /nix/store/11a27shh6n2i…-zlib-1.2.8-check
…
├── lib/libz.a
│ ├── metadata
│ │ @@ -1,15 +1,15 @@
│ │ -rw-r--r-- 30001/30000 3096 Jan 12 15:20 2016 adler32.o
…
│ │ +rw-r--r-- 30001/30000 3096 Jan 12 15:28 2016 adler32.o
…
- Improved FreeBSD support.
- `nix-env -qa --xml --meta` now prints license information.
- The maximum number of parallel TCP connections that the binary cache
substituter will use has been decreased from 150 to 25. This should
prevent upsetting some broken NAT routers, and also improves
performance.
- All "chroot"-containing strings got renamed to "sandbox". In
particular, some Nix options got renamed, but the old names are
still accepted as lower-priority aliases.
This release has contributions from Anders Claesson, Anthony Cowley,
Bjørn Forsman, Brian McKenna, Danny Wilson, davidak, Eelco Dolstra,
Fabian Schmitthenner, FrankHB, Ilya Novoselov, janus, Jim Garrison, John
Ericson, Jude Taylor, Ludovic Courtès, Manuel Jacob, Mathnerd314, Pascal
Wittmann, Peter Simons, Philip Potter, Preston Bennes, Rommel M.
Martinez, Sander van der Burg, Shea Levy, Tim Cuthbertson, Tuomas
Tynkkynen, Utku Demir and Vladimír Čunát.

97
doc/manual/src/release-notes/rl-1.2.md Normal file
View file

@ -0,0 +1,97 @@
# Release 1.2 (2012-12-06)
This release has the following improvements and changes:
- Nix has a new binary substituter mechanism: the *binary cache*. A
binary cache contains pre-built binaries of Nix packages. Whenever
Nix wants to build a missing Nix store path, it will check a set of
binary caches to see if any of them has a pre-built binary of that
path. The configuration setting `binary-caches` contains a list of
URLs of binary caches. For instance, doing
$ nix-env -i thunderbird --option binary-caches http://cache.nixos.org
will install Thunderbird and its dependencies, using the available
pre-built binaries in <http://cache.nixos.org>. The main advantage
over the old “manifest”-based method of getting pre-built binaries
is that you don’t have to worry about your manifest being in sync
with the Nix expressions you’re installing from; i.e., you don’t
need to run `nix-pull` to update your manifest. It’s also more
scalable because you don’t need to redownload a giant manifest file
every time.
A Nix channel can provide a binary cache URL that will be used
automatically if you subscribe to that channel. If you use the
Nixpkgs or NixOS channels (<http://nixos.org/channels>) you
automatically get the cache <http://cache.nixos.org>.
Binary caches are created using `nix-push`. For details on the
operation and format of binary caches, see the `nix-push` manpage.
More details are provided in [this nix-dev
posting](https://nixos.org/nix-dev/2012-September/009826.html).
- Multiple output support should now be usable. A derivation can
declare that it wants to produce multiple store paths by saying
something like
outputs = [ "lib" "headers" "doc" ];
This will cause Nix to pass the intended store path of each output
to the builder through the environment variables `lib`, `headers`
and `doc`. Other packages can refer to a specific output by
referring to `pkg.output`, e.g.
buildInputs = [ pkg.lib pkg.headers ];
If you install a package with multiple outputs using `nix-env`, each
output path will be symlinked into the user environment.
- Dashes are now valid as part of identifiers and attribute names.
- The new operation `nix-store --repair-path` allows corrupted or
missing store paths to be repaired by redownloading them. `nix-store
--verify --check-contents
--repair` will scan and repair all paths in the Nix store.
Similarly, `nix-env`, `nix-build`, `nix-instantiate` and `nix-store
--realise` have a `--repair` flag to detect and fix bad paths by
rebuilding or redownloading them.
- Nix no longer sets the immutable bit on files in the Nix store.
Instead, the recommended way to guard the Nix store against
accidental modification on Linux is to make it a read-only bind
mount, like this:
$ mount --bind /nix/store /nix/store
$ mount -o remount,ro,bind /nix/store
Nix will automatically make `/nix/store` writable as needed (using a
private mount namespace) to allow modifications.
- Store optimisation (replacing identical files in the store with hard
links) can now be done automatically every time a path is added to
the store. This is enabled by setting the configuration option
`auto-optimise-store` to `true` (disabled by default).
- Nix now supports `xz` compression for NARs in addition to `bzip2`.
It compresses about 30% better on typical archives and decompresses
about twice as fast.
- Basic Nix expression evaluation profiling: setting the environment
variable NIX\_COUNT\_CALLS to `1` will cause Nix to print how many
times each primop or function was executed.
- New primops: `concatLists`, `elem`, `elemAt` and `filter`.
- The command `nix-copy-closure` has a new flag `--use-substitutes`
(`-s`) to download missing paths on the target machine using the
substitute mechanism.
- The command `nix-worker` has been renamed to `nix-daemon`. Support
for running the Nix worker in “slave” mode has been removed.
- The `--help` flag of every Nix command now invokes `man`.
- Chroot builds are now supported on systemd machines.
This release has contributions from Eelco Dolstra, Florian Friesdorf,
Mats Erik Andersson and Shea Levy.

10
doc/manual/src/release-notes/rl-1.3.md Normal file
View file

@ -0,0 +1,10 @@
# Release 1.3 (2013-01-04)
This is primarily a bug fix release. When this version is first run on
Linux, it removes any immutable bits from the Nix store and increases
the schema version of the Nix store. (The previous release removed
support for setting the immutable bit; this release clears any remaining
immutable bits to make certain operations more efficient.)
This release has contributions from Eelco Dolstra and Stuart
Pernsteiner.

22
doc/manual/src/release-notes/rl-1.4.md Normal file
View file

@ -0,0 +1,22 @@
# Release 1.4 (2013-02-26)
This release fixes a security bug in multi-user operation. It was
possible for derivations to cause the mode of files outside of the Nix
store to be changed to 444 (read-only but world-readable) by creating
hard links to those files
([details](https://github.com/NixOS/nix/commit/5526a282b5b44e9296e61e07d7d2626a79141ac4)).
There are also the following improvements:
- New built-in function: `builtins.hashString`.
- Build logs are now stored in `/nix/var/log/nix/drvs/XX/`, where XX
is the first two characters of the derivation. This is useful on
machines that keep a lot of build logs (such as Hydra servers).
- The function `corepkgs/fetchurl` can now make the downloaded file
executable. This will allow getting rid of all bootstrap binaries in
the Nixpkgs source tree.
- Language change: The expression `"${./path}
..."` now evaluates to a string instead of a path.

4
doc/manual/src/release-notes/rl-1.5.1.md Normal file
View file

@ -0,0 +1,4 @@
# Release 1.5.1 (2013-02-28)
The bug fix to the bug fix had a bug itself, of course. But this time it
will work for sure\!

4
doc/manual/src/release-notes/rl-1.5.2.md Normal file
View file

@ -0,0 +1,4 @@
# Release 1.5.2 (2013-05-13)
This is primarily a bug fix release. It has contributions from Eelco
Dolstra, Lluís Batlle i Rossell and Shea Levy.

4
doc/manual/src/release-notes/rl-1.5.md Normal file
View file

@ -0,0 +1,4 @@
# Release 1.5 (2013-02-27)
This is a brown paper bag release to fix a regression introduced by the
hard link security fix in 1.4.

32
doc/manual/src/release-notes/rl-1.6.1.md Normal file
View file

@ -0,0 +1,32 @@
# Release 1.6.1 (2013-10-28)
This is primarily a bug fix release. Changes of interest are:
- Nix 1.6 accidentally changed the semantics of antiquoted paths in
strings, such as `"${/foo}/bar"`. This release reverts to the Nix
1.5.3 behaviour.
- Previously, Nix optimised expressions such as `"${expr}"` to expr.
Thus it neither checked whether expr could be coerced to a string,
nor applied such coercions. This meant that `"${123}"` evaluatued to
`123`, and `"${./foo}"` evaluated to `./foo` (even though `"${./foo}
"` evaluates to `"/nix/store/hash-foo "`). Nix now checks the type
of antiquoted expressions and applies coercions.
- Nix now shows the exact position of undefined variables. In
particular, undefined variable errors in a `with` previously didn't
show *any* position information, so this makes it a lot easier to
fix such errors.
- Undefined variables are now treated consistently. Previously, the
`tryEval` function would catch undefined variables inside a `with`
but not outside. Now `tryEval` never catches undefined variables.
- Bash completion in `nix-shell` now works correctly.
- Stack traces are less verbose: they no longer show calls to builtin
functions and only show a single line for each derivation on the
call stack.
- New built-in function: `builtins.typeOf`, which returns the type of
its argument as a string.

72
doc/manual/src/release-notes/rl-1.6.md Normal file
View file

@ -0,0 +1,72 @@
# Release 1.6 (2013-09-10)
In addition to the usual bug fixes, this release has several new
features:
- The command `nix-build --run-env` has been renamed to `nix-shell`.
- `nix-shell` now sources `$stdenv/setup` *inside* the interactive
shell, rather than in a parent shell. This ensures that shell
functions defined by `stdenv` can be used in the interactive shell.
- `nix-shell` has a new flag `--pure` to clear the environment, so you
get an environment that more closely corresponds to the “real” Nix
build.
- `nix-shell` now sets the shell prompt (PS1) to ensure that Nix
shells are distinguishable from your regular shells.
- `nix-env` no longer requires a `*` argument to match all packages,
so `nix-env -qa` is equivalent to `nix-env
-qa '*'`.
- `nix-env -i` has a new flag `--remove-all` (`-r`) to remove all
previous packages from the profile. This makes it easier to do
declarative package management similar to NixOS’s
`environment.systemPackages`. For instance, if you have a
specification `my-packages.nix` like this:
with import <nixpkgs> {};
[ thunderbird
geeqie
...
]
then after any change to this file, you can run:
$ nix-env -f my-packages.nix -ir
to update your profile to match the specification.
- The ‘`with`’ language construct is now more lazy. It only evaluates
its argument if a variable might actually refer to an attribute in
the argument. For instance, this now works:
let
pkgs = with pkgs; { foo = "old"; bar = foo; } // overrides;
overrides = { foo = "new"; };
in pkgs.bar
This evaluates to `"new"`, while previously it gave an “infinite
recursion” error.
- Nix now has proper integer arithmetic operators. For instance, you
can write `x + y` instead of `builtins.add x y`, or `x <
y` instead of `builtins.lessThan x y`. The comparison operators also
work on strings.
- On 64-bit systems, Nix integers are now 64 bits rather than 32 bits.
- When using the Nix daemon, the `nix-daemon` worker process now runs
on the same CPU as the client, on systems that support setting CPU
affinity. This gives a significant speedup on some systems.
- If a stack overflow occurs in the Nix evaluator, you now get a
proper error message (rather than “Segmentation fault”) on some
systems.
- In addition to directories, you can now bind-mount regular files in
chroots through the (now misnamed) option `build-chroot-dirs`.
This release has contributions from Domen Kožar, Eelco Dolstra, Florian
Friesdorf, Gergely Risko, Ivan Kozik, Ludovic Courtès and Shea Levy.

140
doc/manual/src/release-notes/rl-1.7.md Normal file
View file

@ -0,0 +1,140 @@
# Release 1.7 (2014-04-11)
In addition to the usual bug fixes, this release has the following new
features:
- Antiquotation is now allowed inside of quoted attribute names (e.g.
`set."${foo}"`). In the case where the attribute name is just a
single antiquotation, the quotes can be dropped (e.g. the above
example can be written `set.${foo}`). If an attribute name inside of
a set declaration evaluates to `null` (e.g. `{ ${null} = false; }`),
then that attribute is not added to the set.
- Experimental support for cryptographically signed binary caches. See
[the commit for
details](https://github.com/NixOS/nix/commit/0fdf4da0e979f992db75cc17376e455ddc5a96d8).
- An experimental new substituter, `download-via-ssh`, that fetches
binaries from remote machines via SSH. Specifying the flags
`--option
use-ssh-substituter true --option ssh-substituter-hosts
user@hostname` will cause Nix to download binaries from the
specified machine, if it has them.
- `nix-store -r` and `nix-build` have a new flag, `--check`, that
builds a previously built derivation again, and prints an error
message if the output is not exactly the same. This helps to verify
whether a derivation is truly deterministic. For example:
$ nix-build '<nixpkgs>' -A patchelf
…
$ nix-build '<nixpkgs>' -A patchelf --check
…
error: derivation `/nix/store/1ipvxs…-patchelf-0.6' may not be deterministic:
hash mismatch in output `/nix/store/4pc1dm…-patchelf-0.6.drv'
- The `nix-instantiate` flags `--eval-only` and `--parse-only` have
been renamed to `--eval` and `--parse`, respectively.
- `nix-instantiate`, `nix-build` and `nix-shell` now have a flag
`--expr` (or `-E`) that allows you to specify the expression to be
evaluated as a command line argument. For instance, `nix-instantiate
--eval -E
'1 + 2'` will print `3`.
- `nix-shell` improvements:
- It has a new flag, `--packages` (or `-p`), that sets up a build
environment containing the specified packages from Nixpkgs. For
example, the command
$ nix-shell -p sqlite xorg.libX11 hello
will start a shell in which the given packages are present.
- It now uses `shell.nix` as the default expression, falling back
to `default.nix` if the former doesn’t exist. This makes it
convenient to have a `shell.nix` in your project to set up a
nice development environment.
- It evaluates the derivation attribute `shellHook`, if set. Since
`stdenv` does not normally execute this hook, it allows you to
do `nix-shell`-specific setup.
- It preserves the user’s timezone setting.
- In chroots, Nix now sets up a `/dev` containing only a minimal set
of devices (such as `/dev/null`). Note that it only does this if you
*don’t* have `/dev` listed in your `build-chroot-dirs` setting;
otherwise, it will bind-mount the `/dev` from outside the chroot.
Similarly, if you don’t have `/dev/pts` listed in
`build-chroot-dirs`, Nix will mount a private `devpts` filesystem on
the chroot’s `/dev/pts`.
- New built-in function: `builtins.toJSON`, which returns a JSON
representation of a value.
- `nix-env -q` has a new flag `--json` to print a JSON representation
of the installed or available packages.
- `nix-env` now supports meta attributes with more complex values,
such as attribute sets.
- The `-A` flag now allows attribute names with dots in them, e.g.
$ nix-instantiate --eval '<nixos>' -A 'config.systemd.units."nscd.service".text'
- The `--max-freed` option to `nix-store --gc` now accepts a unit
specifier. For example, `nix-store --gc --max-freed
1G` will free up to 1 gigabyte of disk space.
- `nix-collect-garbage` has a new flag `--delete-older-than` N`d`,
which deletes all user environment generations older than N days.
Likewise, `nix-env
--delete-generations` accepts a N`d` age limit.
- Nix now heuristically detects whether a build failure was due to a
disk-full condition. In that case, the build is not flagged as
“permanently failed”. This is mostly useful for Hydra, which needs
to distinguish between permanent and transient build failures.
- There is a new symbol `__curPos` that expands to an attribute set
containing its file name and line and column numbers, e.g. `{ file =
"foo.nix"; line = 10;
column = 5; }`. There also is a new builtin function,
`unsafeGetAttrPos`, that returns the position of an attribute. This
is used by Nixpkgs to provide location information in error
messages, e.g.
$ nix-build '<nixpkgs>' -A libreoffice --argstr system x86_64-darwin
error: the package ‘libreoffice-4.0.5.2’ in ‘.../applications/office/libreoffice/default.nix:263’
is not supported on ‘x86_64-darwin’
- The garbage collector is now more concurrent with other Nix
processes because it releases certain locks earlier.
- The binary tarball installer has been improved. You can now install
Nix by running:
$ bash <(curl https://nixos.org/nix/install)
- More evaluation errors include position information. For instance,
selecting a missing attribute will print something like
error: attribute `nixUnstabl' missing, at /etc/nixos/configurations/misc/eelco/mandark.nix:216:15
- The command `nix-setuid-helper` is gone.
- Nix no longer uses Automake, but instead has a non-recursive, GNU
Make-based build system.
- All installed libraries now have the prefix `libnix`. In particular,
this gets rid of `libutil`, which could clash with libraries with
the same name from other packages.
- Nix now requires a compiler that supports C++11.
This release has contributions from Danny Wilson, Domen Kožar, Eelco
Dolstra, Ian-Woo Kim, Ludovic Courtès, Maxim Ivanov, Petr Rockai,
Ricardo M. Correia and Shea Levy.

88
doc/manual/src/release-notes/rl-1.8.md Normal file
View file

@ -0,0 +1,88 @@
# Release 1.8 (2014-12-14)
- Breaking change: to address a race condition, the remote build hook
mechanism now uses `nix-store
--serve` on the remote machine. This requires build slaves to be
updated to Nix 1.8.
- Nix now uses HTTPS instead of HTTP to access the default binary
cache, `cache.nixos.org`.
- `nix-env` selectors are now regular expressions. For instance, you
can do
$ nix-env -qa '.*zip.*'
to query all packages with a name containing `zip`.
- `nix-store --read-log` can now fetch remote build logs. If a build
log is not available locally, then ‘nix-store -l’ will now try to
download it from the servers listed in the ‘log-servers’ option in
nix.conf. For instance, if you have the configuration option
log-servers = http://hydra.nixos.org/log
then it will try to get logs from `http://hydra.nixos.org/log/base
name of the
store path`. This allows you to do things like:
$ nix-store -l $(which xterm)
and get a log even if `xterm` wasn't built locally.
- New builtin functions: `attrValues`, `deepSeq`, `fromJSON`,
`readDir`, `seq`.
- `nix-instantiate --eval` now has a `--json` flag to print the
resulting value in JSON format.
- `nix-copy-closure` now uses `nix-store --serve` on the remote side
to send or receive closures. This fixes a race condition between
`nix-copy-closure` and the garbage collector.
- Derivations can specify the new special attribute
`allowedRequisites`, which has a similar meaning to
`allowedReferences`. But instead of only enforcing to explicitly
specify the immediate references, it requires the derivation to
specify all the dependencies recursively (hence the name,
requisites) that are used by the resulting output.
- On Mac OS X, Nix now handles case collisions when importing closures
from case-sensitive file systems. This is mostly useful for running
NixOps on Mac OS X.
- The Nix daemon has new configuration options `allowed-users`
(specifying the users and groups that are allowed to connect to the
daemon) and `trusted-users` (specifying the users and groups that
can perform privileged operations like specifying untrusted binary
caches).
- The configuration option `build-cores` now defaults to the number of
available CPU cores.
- Build users are now used by default when Nix is invoked as root.
This prevents builds from accidentally running as root.
- Nix now includes systemd units and Upstart jobs.
- Speed improvements to `nix-store
--optimise`.
- Language change: the `==` operator now ignores string contexts (the
“dependencies” of a string).
- Nix now filters out Nix-specific ANSI escape sequences on standard
error. They are supposed to be invisible, but some terminals show
them anyway.
- Various commands now automatically pipe their output into the pager
as specified by the PAGER environment variable.
- Several improvements to reduce memory consumption in the evaluator.
This release has contributions from Adam Szkoda, Aristid Breitkreuz, Bob
van der Linden, Charles Strahan, darealshinji, Eelco Dolstra, Gergely
Risko, Joel Taylor, Ludovic Courtès, Marko Durkovic, Mikey Ariel, Paul
Colomiets, Ricardo M. Correia, Ricky Elrod, Robert Helgesson, Rob
Vermaas, Russell O'Connor, Shea Levy, Shell Turner, Sönke Hahn, Steve
Purcell, Vladimír Čunát and Wout Mertens.

143
doc/manual/src/release-notes/rl-1.9.md Normal file
View file

@ -0,0 +1,143 @@
# Release 1.9 (2015-06-12)
In addition to the usual bug fixes, this release has the following new
features:
- Signed binary cache support. You can enable signature checking by
adding the following to `nix.conf`:
signed-binary-caches = *
binary-cache-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
This will prevent Nix from downloading any binary from the cache
that is not signed by one of the keys listed in
`binary-cache-public-keys`.
Signature checking is only supported if you built Nix with the
`libsodium` package.
Note that while Nix has had experimental support for signed binary
caches since version 1.7, this release changes the signature format
in a backwards-incompatible way.
- Automatic downloading of Nix expression tarballs. In various places,
you can now specify the URL of a tarball containing Nix expressions
(such as Nixpkgs), which will be downloaded and unpacked
automatically. For example:
- In `nix-env`:
$ nix-env -f https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox
This installs Firefox from the latest tested and built revision
of the NixOS 14.12 channel.
- In `nix-build` and `nix-shell`:
$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello
This builds GNU Hello from the latest revision of the Nixpkgs
master branch.
- In the Nix search path (as specified via NIX\_PATH or `-I`). For
example, to start a shell containing the Pan package from a
specific version of Nixpkgs:
$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz
- In `nixos-rebuild` (on NixOS):
$ nixos-rebuild test -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-unstable.tar.gz
- In Nix expressions, via the new builtin function `fetchTarball`:
with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {}; …
(This is not allowed in restricted mode.)
- `nix-shell` improvements:
- `nix-shell` now has a flag `--run` to execute a command in the
`nix-shell` environment, e.g. `nix-shell --run make`. This is
like the existing `--command` flag, except that it uses a
non-interactive shell (ensuring that hitting Ctrl-C won’t drop
you into the child shell).
- `nix-shell` can now be used as a `#!`-interpreter. This allows
you to write scripts that dynamically fetch their own
dependencies. For example, here is a Haskell script that, when
invoked, first downloads GHC and the Haskell packages on which
it depends:
#! /usr/bin/env nix-shell
#! nix-shell -i runghc -p haskellPackages.ghc haskellPackages.HTTP
import Network.HTTP
main = do
resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/")
body <- getResponseBody resp
print (take 100 body)
Of course, the dependencies are cached in the Nix store, so the
second invocation of this script will be much faster.
- Chroot improvements:
- Chroot builds are now supported on Mac OS X (using its sandbox
mechanism).
- If chroots are enabled, they are now used for all derivations,
including fixed-output derivations (such as `fetchurl`). The
latter do have network access, but can no longer access the host
filesystem. If you need the old behaviour, you can set the
option `build-use-chroot` to `relaxed`.
- On Linux, if chroots are enabled, builds are performed in a
private PID namespace once again. (This functionality was lost
in Nix 1.8.)
- Store paths listed in `build-chroot-dirs` are now automatically
expanded to their closure. For instance, if you want
`/nix/store/…-bash/bin/sh` mounted in your chroot as `/bin/sh`,
you only need to say `build-chroot-dirs =
/bin/sh=/nix/store/…-bash/bin/sh`; it is no longer necessary to
specify the dependencies of Bash.
- The new derivation attribute `passAsFile` allows you to specify that
the contents of derivation attributes should be passed via files
rather than environment variables. This is useful if you need to
pass very long strings that exceed the size limit of the
environment. The Nixpkgs function `writeTextFile` uses this.
- You can now use `~` in Nix file names to refer to your home
directory, e.g. `import
~/.nixpkgs/config.nix`.
- Nix has a new option `restrict-eval` that allows limiting what paths
the Nix evaluator has access to. By passing `--option restrict-eval
true` to Nix, the evaluator will throw an exception if an attempt is
made to access any file outside of the Nix search path. This is
primarily intended for Hydra to ensure that a Hydra jobset only
refers to its declared inputs (and is therefore reproducible).
- `nix-env` now only creates a new “generation” symlink in
`/nix/var/nix/profiles` if something actually changed.
- The environment variable NIX\_PAGER can now be set to override
PAGER. You can set it to `cat` to disable paging for Nix commands
only.
- Failing `<...>` lookups now show position information.
- Improved Boehm GC use: we disabled scanning for interior pointers,
which should reduce the “`Repeated
allocation of very large block`” warnings and associated retention
of memory.
This release has contributions from aszlig, Benjamin Staffin, Charles
Strahan, Christian Theune, Daniel Hahler, Danylo Hlynskyi Daniel
Peebles, Dan Peebles, Domen Kožar, Eelco Dolstra, Harald van Dijk, Hoang
Xuan Phu, Jaka Hudoklin, Jeff Ramnani, j-keck, Linquize, Luca Bruno,
Michael Merickel, Oliver Dunkl, Rob Vermaas, Rok Garbas, Shea Levy,
Tobias Geerinckx-Rice and William A. Kennington III.

557
doc/manual/src/release-notes/rl-2.0.md Normal file
View file

@ -0,0 +1,557 @@
# Release 2.0 (2018-02-22)
The following incompatible changes have been made:
- The manifest-based substituter mechanism
(`download-using-manifests`) has been
[removed](https://github.com/NixOS/nix/commit/867967265b80946dfe1db72d40324b4f9af988ed).
It has been superseded by the binary cache substituter mechanism
since several years. As a result, the following programs have been
removed:
- `nix-pull`
- `nix-generate-patches`
- `bsdiff`
- `bspatch`
- The “copy from other stores” substituter mechanism
(`copy-from-other-stores` and the NIX\_OTHER\_STORES environment
variable) has been removed. It was primarily used by the NixOS
installer to copy available paths from the installation medium. The
replacement is to use a chroot store as a substituter (e.g.
`--substituters /mnt`), or to build into a chroot store (e.g.
`--store /mnt --substituters /`).
- The command `nix-push` has been removed as part of the effort to
eliminate Nix's dependency on Perl. You can use `nix copy` instead,
e.g. `nix copy
--to file:///tmp/my-binary-cache paths…`
- The “nested” log output feature (`--log-type
pretty`) has been removed. As a result, `nix-log2xml` was also
removed.
- OpenSSL-based signing has been
[removed](https://github.com/NixOS/nix/commit/f435f8247553656774dd1b2c88e9de5d59cab203).
This feature was never well-supported. A better alternative is
provided by the `secret-key-files` and `trusted-public-keys`
options.
- Failed build caching has been
[removed](https://github.com/NixOS/nix/commit/8cffec84859cec8b610a2a22ab0c4d462a9351ff).
This feature was introduced to support the Hydra continuous build
system, but Hydra no longer uses it.
- `nix-mode.el` has been removed from Nix. It is now [a separate
repository](https://github.com/NixOS/nix-mode) and can be installed
through the MELPA package repository.
This release has the following new features:
- It introduces a new command named `nix`, which is intended to
eventually replace all `nix-*` commands with a more consistent and
better designed user interface. It currently provides replacements
for some (but not all) of the functionality provided by `nix-store`,
`nix-build`, `nix-shell -p`, `nix-env -qa`, `nix-instantiate
--eval`, `nix-push` and `nix-copy-closure`. It has the following
major features:
- Unlike the legacy commands, it has a consistent way to refer to
packages and package-like arguments (like store paths). For
example, the following commands all copy the GNU Hello package
to a remote machine:
nix copy --to ssh://machine nixpkgs.hello
nix copy --to ssh://machine /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10
nix copy --to ssh://machine '(with import <nixpkgs> {}; hello)'
By contrast, `nix-copy-closure` only accepted store paths as
arguments.
- It is self-documenting: `--help` shows all available
command-line arguments. If `--help` is given after a subcommand,
it shows examples for that subcommand. `nix
--help-config` shows all configuration options.
- It is much less verbose. By default, it displays a single-line
progress indicator that shows how many packages are left to be
built or downloaded, and (if there are running builds) the most
recent line of builder output. If a build fails, it shows the
last few lines of builder output. The full build log can be
retrieved using `nix
log`.
- It
[provides](https://github.com/NixOS/nix/commit/b8283773bd64d7da6859ed520ee19867742a03ba)
all `nix.conf` configuration options as command line flags. For
example, instead of `--option
http-connections 100` you can write `--http-connections 100`.
Boolean options can be written as `--foo` or `--no-foo` (e.g.
`--no-auto-optimise-store`).
- Many subcommands have a `--json` flag to write results to stdout
in JSON format.
> **Warning**
>
> Please note that the `nix` command is a work in progress and the
> interface is subject to change.
It provides the following high-level (“porcelain”) subcommands:
- `nix build` is a replacement for `nix-build`.
- `nix run` executes a command in an environment in which the
specified packages are available. It is (roughly) a replacement
for `nix-shell
-p`. Unlike that command, it does not execute the command in a
shell, and has a flag (`-c`) that specifies the unquoted command
line to be executed.
It is particularly useful in conjunction with chroot stores,
allowing Linux users who do not have permission to install Nix
in `/nix/store` to still use binary substitutes that assume
`/nix/store`. For example,
nix run --store ~/my-nix nixpkgs.hello -c hello --greeting 'Hi everybody!'
downloads (or if not substitutes are available, builds) the GNU
Hello package into `~/my-nix/nix/store`, then runs `hello` in a
mount namespace where `~/my-nix/nix/store` is mounted onto
`/nix/store`.
- `nix search` replaces `nix-env
-qa`. It searches the available packages for occurrences of a
search string in the attribute name, package name or
description. Unlike `nix-env -qa`, it has a cache to speed up
subsequent searches.
- `nix copy` copies paths between arbitrary Nix stores,
generalising `nix-copy-closure` and `nix-push`.
- `nix repl` replaces the external program `nix-repl`. It provides
an interactive environment for evaluating and building Nix
expressions. Note that it uses `linenoise-ng` instead of GNU
Readline.
- `nix upgrade-nix` upgrades Nix to the latest stable version.
This requires that Nix is installed in a profile. (Thus it won’t
work on NixOS, or if it’s installed outside of the Nix store.)
- `nix verify` checks whether store paths are unmodified and/or
“trusted” (see below). It replaces `nix-store --verify` and
`nix-store
--verify-path`.
- `nix log` shows the build log of a package or path. If the build
log is not available locally, it will try to obtain it from the
configured substituters (such as
[cache.nixos.org](cache.nixos.org), which now provides build
logs).
- `nix edit` opens the source code of a package in your editor.
- `nix eval` replaces `nix-instantiate --eval`.
- `nix
why-depends` shows why one store path has another in its
closure. This is primarily useful to finding the causes of
closure bloat. For example,
nix why-depends nixpkgs.vlc nixpkgs.libdrm.dev
shows a chain of files and fragments of file contents that cause
the VLC package to have the “dev” output of `libdrm` in its
closure — an undesirable situation.
- `nix path-info` shows information about store paths, replacing
`nix-store -q`. A useful feature is the option `--closure-size`
(`-S`). For example, the following command show the closure
sizes of every path in the current NixOS system closure, sorted
by size:
nix path-info -rS /run/current-system | sort -nk2
- `nix optimise-store` replaces `nix-store --optimise`. The main
difference is that it has a progress indicator.
A number of low-level (“plumbing”) commands are also available:
- `nix ls-store` and `nix
ls-nar` list the contents of a store path or NAR file. The
former is primarily useful in conjunction with remote stores,
e.g.
nix ls-store --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10
lists the contents of path in a binary cache.
- `nix cat-store` and `nix
cat-nar` allow extracting a file from a store path or NAR file.
- `nix dump-path` writes the contents of a store path to stdout in
NAR format. This replaces `nix-store --dump`.
- `nix
show-derivation` displays a store derivation in JSON format.
This is an alternative to `pp-aterm`.
- `nix
add-to-store` replaces `nix-store
--add`.
- `nix sign-paths` signs store paths.
- `nix copy-sigs` copies signatures from one store to another.
- `nix show-config` shows all configuration options and their
current values.
- The store abstraction that Nix has had for a long time to support
store access via the Nix daemon has been extended significantly. In
particular, substituters (which used to be external programs such as
`download-from-binary-cache`) are now subclasses of the abstract
`Store` class. This allows many Nix commands to operate on such
store types. For example, `nix path-info` shows information about
paths in your local Nix store, while `nix path-info --store
https://cache.nixos.org/` shows information about paths in the
specified binary cache. Similarly, `nix-copy-closure`, `nix-push`
and substitution are all instances of the general notion of copying
paths between different kinds of Nix stores.
Stores are specified using an URI-like syntax, e.g.
<https://cache.nixos.org/> or <ssh://machine>. The following store
types are supported:
- `LocalStore` (stori URI `local` or an absolute path) and the
misnamed `RemoteStore` (`daemon`) provide access to a local Nix
store, the latter via the Nix daemon. You can use `auto` or the
empty string to auto-select a local or daemon store depending on
whether you have write permission to the Nix store. It is no
longer necessary to set the NIX\_REMOTE environment variable to
use the Nix daemon.
As noted above, `LocalStore` now supports chroot builds,
allowing the “physical” location of the Nix store (e.g.
`/home/alice/nix/store`) to differ from its “logical” location
(typically `/nix/store`). This allows non-root users to use Nix
while still getting the benefits from prebuilt binaries from
[cache.nixos.org](cache.nixos.org).
- `BinaryCacheStore` is the abstract superclass of all binary
cache stores. It supports writing build logs and NAR content
listings in JSON format.
- `HttpBinaryCacheStore` (`http://`, `https://`) supports binary
caches via HTTP or HTTPS. If the server supports `PUT` requests,
it supports uploading store paths via commands such as `nix
copy`.
- `LocalBinaryCacheStore` (`file://`) supports binary caches in
the local filesystem.
- `S3BinaryCacheStore` (`s3://`) supports binary caches stored in
Amazon S3, if enabled at compile time.
- `LegacySSHStore` (`ssh://`) is used to implement remote builds
and `nix-copy-closure`.
- `SSHStore` (`ssh-ng://`) supports arbitrary Nix operations on a
remote machine via the same protocol used by `nix-daemon`.
- Security has been improved in various ways:
- Nix now stores signatures for local store paths. When paths are
copied between stores (e.g., copied from a binary cache to a
local store), signatures are propagated.
Locally-built paths are signed automatically using the secret
keys specified by the `secret-key-files` store option.
Secret/public key pairs can be generated using `nix-store
--generate-binary-cache-key`.
In addition, locally-built store paths are marked as “ultimately
trusted”, but this bit is not propagated when paths are copied
between stores.
- Content-addressable store paths no longer require signatures —
they can be imported into a store by unprivileged users even if
they lack signatures.
- The command `nix verify` checks whether the specified paths are
trusted, i.e., have a certain number of trusted signatures, are
ultimately trusted, or are content-addressed.
- Substitutions from binary caches
[now](https://github.com/NixOS/nix/commit/ecbc3fedd3d5bdc5a0e1a0a51b29062f2874ac8b)
require signatures by default. This was already the case on
NixOS.
- In Linux sandbox builds, we
[now](https://github.com/NixOS/nix/commit/eba840c8a13b465ace90172ff76a0db2899ab11b)
use `/build` instead of `/tmp` as the temporary build directory.
This fixes potential security problems when a build accidentally
stores its TMPDIR in some security-sensitive place, such as an
RPATH.
- *Pure evaluation mode*. With the `--pure-eval` flag, Nix enables a
variant of the existing restricted evaluation mode that forbids
access to anything that could cause different evaluations of the
same command line arguments to produce a different result. This
includes builtin functions such as `builtins.getEnv`, but more
importantly, *all* filesystem or network access unless a content
hash or commit hash is specified. For example, calls to
`builtins.fetchGit` are only allowed if a `rev` attribute is
specified.
The goal of this feature is to enable true reproducibility and
traceability of builds (including NixOS system configurations) at
the evaluation level. For example, in the future, `nixos-rebuild`
might build configurations from a Nix expression in a Git repository
in pure mode. That expression might fetch other repositories such as
Nixpkgs via `builtins.fetchGit`. The commit hash of the top-level
repository then uniquely identifies a running system, and, in
conjunction with that repository, allows it to be reproduced or
modified.
- There are several new features to support binary reproducibility
(i.e. to help ensure that multiple builds of the same derivation
produce exactly the same output). When `enforce-determinism` is set
to `false`, it’s [no
longer](https://github.com/NixOS/nix/commit/8bdf83f936adae6f2c907a6d2541e80d4120f051)
a fatal error if build rounds produce different output. Also, a hook
named `diff-hook` is
[provided](https://github.com/NixOS/nix/commit/9a313469a4bdea2d1e8df24d16289dc2a172a169)
to allow you to run tools such as `diffoscope` when build rounds
produce different output.
- Configuring remote builds is a lot easier now. Provided you are not
using the Nix daemon, you can now just specify a remote build
machine on the command line, e.g. `--option builders
'ssh://my-mac x86_64-darwin'`. The environment variable
NIX\_BUILD\_HOOK has been removed and is no longer needed. The
environment variable NIX\_REMOTE\_SYSTEMS is still supported for
compatibility, but it is also possible to specify builders in
`nix.conf` by setting the option `builders =
@path`.
- If a fixed-output derivation produces a result with an incorrect
hash, the output path is moved to the location corresponding to the
actual hash and registered as valid. Thus, a subsequent build of the
fixed-output derivation with the correct hash is unnecessary.
- `nix-shell`
[now](https://github.com/NixOS/nix/commit/ea59f39326c8e9dc42dfed4bcbf597fbce58797c)
sets the `IN_NIX_SHELL` environment variable during evaluation and
in the shell itself. This can be used to perform different actions
depending on whether you’re in a Nix shell or in a regular build.
Nixpkgs provides `lib.inNixShell` to check this variable during
evaluation.
- NIX\_PATH is now lazy, so URIs in the path are only downloaded if
they are needed for evaluation.
- You can now use <channel:> as a short-hand for
<https://nixos.org/channels//nixexprs.tar.xz>. For example,
`nix-build channel:nixos-15.09 -A hello` will build the GNU Hello
package from the `nixos-15.09` channel. In the future, this may use
Git to fetch updates more efficiently.
- When `--no-build-output` is given, the last 10 lines of the build
log will be shown if a build fails.
- Networking has been improved:
- HTTP/2 is now supported. This makes binary cache lookups [much
more
efficient](https://github.com/NixOS/nix/commit/90ad02bf626b885a5dd8967894e2eafc953bdf92).
- We now retry downloads on many HTTP errors, making binary caches
substituters more resilient to temporary failures.
- HTTP credentials can now be configured via the standard `netrc`
mechanism.
- If S3 support is enabled at compile time, <s3://> URIs are
[supported](https://github.com/NixOS/nix/commit/9ff9c3f2f80ba4108e9c945bbfda2c64735f987b)
in all places where Nix allows URIs.
- Brotli compression is now supported. In particular,
[cache.nixos.org](cache.nixos.org) build logs are now compressed
using Brotli.
- `nix-env`
[now](https://github.com/NixOS/nix/commit/b0cb11722626e906a73f10dd9a0c9eea29faf43a)
ignores packages with bad derivation names (in particular those
starting with a digit or containing a dot).
- Many configuration options have been renamed, either because they
were unnecessarily verbose (e.g. `build-use-sandbox` is now just
`sandbox`) or to reflect generalised behaviour (e.g. `binary-caches`
is now `substituters` because it allows arbitrary store URIs). The
old names are still supported for compatibility.
- The `max-jobs` option can
[now](https://github.com/NixOS/nix/commit/7251d048fa812d2551b7003bc9f13a8f5d4c95a5)
be set to `auto` to use the number of CPUs in the system.
- Hashes can
[now](https://github.com/NixOS/nix/commit/c0015e87af70f539f24d2aa2bc224a9d8b84276b)
be specified in base-64 format, in addition to base-16 and the
non-standard base-32.
- `nix-shell` now uses `bashInteractive` from Nixpkgs, rather than the
`bash` command that happens to be in the caller’s PATH. This is
especially important on macOS where the `bash` provided by the
system is seriously outdated and cannot execute `stdenv`’s setup
script.
- Nix can now automatically trigger a garbage collection if free disk
space drops below a certain level during a build. This is configured
using the `min-free` and `max-free` options.
- `nix-store -q --roots` and `nix-store --gc --print-roots` now show
temporary and in-memory roots.
- Nix can now be extended with plugins. See the documentation of the
`plugin-files` option for more details.
The Nix language has the following new features:
- It supports floating point numbers. They are based on the C++
`float` type and are supported by the existing numerical operators.
Export and import to and from JSON and XML works, too.
- Derivation attributes can now reference the outputs of the
derivation using the `placeholder` builtin function. For example,
the attribute
configureFlags = "--prefix=${placeholder "out"} --includedir=${placeholder "dev"}";
will cause the configureFlags environment variable to contain the
actual store paths corresponding to the `out` and `dev` outputs.
The following builtin functions are new or extended:
- `builtins.fetchGit` allows Git repositories to be fetched at
evaluation time. Thus it differs from the `fetchgit` function in
Nixpkgs, which fetches at build time and cannot be used to fetch Nix
expressions during evaluation. A typical use case is to import
external NixOS modules from your configuration, e.g.
imports = [ (builtins.fetchGit https://github.com/edolstra/dwarffs + "/module.nix") ];
- Similarly, `builtins.fetchMercurial` allows you to fetch Mercurial
repositories.
- `builtins.path` generalises `builtins.filterSource` and path
literals (e.g. `./foo`). It allows specifying a store path name that
differs from the source path name (e.g. `builtins.path { path =
./foo; name = "bar";
}`) and also supports filtering out unwanted files.
- `builtins.fetchurl` and `builtins.fetchTarball` now support `sha256`
and `name` attributes.
- `builtins.split` splits a string using a POSIX extended regular
expression as the separator.
- `builtins.partition` partitions the elements of a list into two
lists, depending on a Boolean predicate.
- `<nix/fetchurl.nix>` now uses the content-addressable tarball cache
at <http://tarballs.nixos.org/>, just like `fetchurl` in Nixpkgs.
(f2682e6e18a76ecbfb8a12c17e3a0ca15c084197)
- In restricted and pure evaluation mode, builtin functions that
download from the network (such as `fetchGit`) are permitted to
fetch underneath a list of URI prefixes specified in the option
`allowed-uris`.
The Nix build environment has the following changes:
- Values such as Booleans, integers, (nested) lists and attribute sets
can
[now](https://github.com/NixOS/nix/commit/6de33a9c675b187437a2e1abbcb290981a89ecb1)
be passed to builders in a non-lossy way. If the special attribute
`__structuredAttrs` is set to `true`, the other derivation
attributes are serialised in JSON format and made available to the
builder via the file .attrs.json in the builder’s temporary
directory. This obviates the need for `passAsFile` since JSON files
have no size restrictions, unlike process environments.
[As a convenience to Bash
builders](https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699),
Nix writes a script named .attrs.sh to the builder’s directory that
initialises shell variables corresponding to all attributes that are
representable in Bash. This includes non-nested (associative)
arrays. For example, the attribute `hardening.format =
true` ends up as the Bash associative array element
`${hardening[format]}`.
- Builders can
[now](https://github.com/NixOS/nix/commit/88e6bb76de5564b3217be9688677d1c89101b2a3)
communicate what build phase they are in by writing messages to the
file descriptor specified in NIX\_LOG\_FD. The current phase is
shown by the `nix` progress indicator.
- In Linux sandbox builds, we
[now](https://github.com/NixOS/nix/commit/a2d92bb20e82a0957067ede60e91fab256948b41)
provide a default `/bin/sh` (namely `ash` from BusyBox).
- In structured attribute mode, `exportReferencesGraph`
[exports](https://github.com/NixOS/nix/commit/c2b0d8749f7e77afc1c4b3e8dd36b7ee9720af4a)
extended information about closures in JSON format. In particular,
it includes the sizes and hashes of paths. This is primarily useful
for NixOS image builders.
- Builds are
[now](https://github.com/NixOS/nix/commit/21948deed99a3295e4d5666e027a6ca42dc00b40)
killed as soon as Nix receives EOF on the builder’s stdout or
stderr. This fixes a bug that allowed builds to hang Nix
indefinitely, regardless of timeouts.
- The `sandbox-paths` configuration option can now specify optional
paths by appending a `?`, e.g. `/dev/nvidiactl?` will bind-mount
`/dev/nvidiactl` only if it exists.
- On Linux, builds are now executed in a user namespace with UID 1000
and GID 100.
A number of significant internal changes were made:
- Nix no longer depends on Perl and all Perl components have been
rewritten in C++ or removed. The Perl bindings that used to be part
of Nix have been moved to a separate package, `nix-perl`.
- All `Store` classes are now thread-safe. `RemoteStore` supports
multiple concurrent connections to the daemon. This is primarily
useful in multi-threaded programs such as `hydra-queue-runner`.
This release has contributions from Adrien Devresse, Alexander Ried,
Alex Cruice, Alexey Shmalko, AmineChikhaoui, Andy Wingo, Aneesh Agrawal,
Anthony Cowley, Armijn Hemel, aszlig, Ben Gamari, Benjamin Hipple,
Benjamin Staffin, Benno Fünfstück, Bjørn Forsman, Brian McKenna, Charles
Strahan, Chase Adams, Chris Martin, Christian Theune, Chris Warburton,
Daiderd Jordan, Dan Connolly, Daniel Peebles, Dan Peebles, davidak,
David McFarland, Dmitry Kalinkin, Domen Kožar, Eelco Dolstra, Emery
Hemingway, Eric Litak, Eric Wolf, Fabian Schmitthenner, Frederik
Rietdijk, Gabriel Gonzalez, Giorgio Gallo, Graham Christensen, Guillaume
Maudoux, Harmen, Iavael, James Broadhead, James Earl Douglas, Janus
Troelsen, Jeremy Shaw, Joachim Schiele, Joe Hermaszewski, Joel Moberg,
Johannes 'fish' Ziemke, Jörg Thalheim, Jude Taylor, kballou, Keshav
Kini, Kjetil Orbekk, Langston Barrett, Linus Heckemann, Ludovic Courtès,
Manav Rathi, Marc Scholten, Markus Hauck, Matt Audesse, Matthew Bauer,
Matthias Beyer, Matthieu Coudron, N1X, Nathan Zadoks, Neil Mayhew,
Nicolas B. Pierron, Niklas Hambüchen, Nikolay Amiantov, Ole Jørgen
Brønner, Orivej Desh, Peter Simons, Peter Stuart, Pyry Jahkola, regnat,
Renzo Carbonara, Rhys, Robert Vollmert, Scott Olson, Scott R. Parish,
Sergei Trofimovich, Shea Levy, Sheena Artrip, Spencer Baugh, Stefan
Junker, Susan Potter, Thomas Tuegel, Timothy Allen, Tristan Hume, Tuomas
Tynkkynen, tv, Tyson Whitehead, Vladimír Čunát, Will Dietz, wmertens,
Wout Mertens, zimbatm and Zoran Plesivčak.

49
doc/manual/src/release-notes/rl-2.1.md Normal file
View file

@ -0,0 +1,49 @@
# Release 2.1 (2018-09-02)
This is primarily a bug fix release. It also reduces memory consumption
in certain situations. In addition, it has the following new features:
- The Nix installer will no longer default to the Multi-User
installation for macOS. You can still [instruct the installer to run
in multi-user mode](#sect-multi-user-installation).
- The Nix installer now supports performing a Multi-User installation
for Linux computers which are running systemd. You can [select a
Multi-User installation](#sect-multi-user-installation) by passing
the `--daemon` flag to the installer: `sh <(curl
https://nixos.org/nix/install) --daemon`.
The multi-user installer cannot handle systems with SELinux. If your
system has SELinux enabled, you can [force the installer to run in
single-user mode](#sect-single-user-installation).
- New builtin functions: `builtins.bitAnd`, `builtins.bitOr`,
`builtins.bitXor`, `builtins.fromTOML`, `builtins.concatMap`,
`builtins.mapAttrs`.
- The S3 binary cache store now supports uploading NARs larger than 5
GiB.
- The S3 binary cache store now supports uploading to S3-compatible
services with the `endpoint` option.
- The flag `--fallback` is no longer required to recover from
disappeared NARs in binary caches.
- `nix-daemon` now respects `--store`.
- `nix run` now respects `nix-support/propagated-user-env-packages`.
This release has contributions from Adrien Devresse, Aleksandr Pashkov,
Alexandre Esteves, Amine Chikhaoui, Andrew Dunham, Asad Saeeduddin,
aszlig, Ben Challenor, Ben Gamari, Benjamin Hipple, Bogdan Seniuc, Corey
O'Connor, Daiderd Jordan, Daniel Peebles, Daniel Poelzleithner, Danylo
Hlynskyi, Dmitry Kalinkin, Domen Kožar, Doug Beardsley, Eelco Dolstra,
Erik Arvstedt, Félix Baylac-Jacqué, Gleb Peregud, Graham Christensen,
Guillaume Maudoux, Ivan Kozik, John Arnold, Justin Humm, Linus
Heckemann, Lorenzo Manacorda, Matthew Justin Bauer, Matthew O'Gorman,
Maximilian Bosch, Michael Bishop, Michael Fiano, Michael Mercier,
Michael Raskin, Michael Weiss, Nicolas Dudebout, Peter Simons, Ryan
Trinkle, Samuel Dionne-Riel, Sean Seefried, Shea Levy, Symphorien Gibol,
Tim Engler, Tim Sears, Tuomas Tynkkynen, volth, Will Dietz, Yorick van
Pelt and zimbatm.

82
doc/manual/src/release-notes/rl-2.2.md Normal file
View file

@ -0,0 +1,82 @@
# Release 2.2 (2019-01-11)
This is primarily a bug fix release. It also has the following changes:
- In derivations that use structured attributes (i.e. that specify set
the `__structuredAttrs` attribute to `true` to cause all attributes
to be passed to the builder in JSON format), you can now specify
closure checks per output, e.g.:
outputChecks."out" = {
# The closure of 'out' must not be larger than 256 MiB.
maxClosureSize = 256 * 1024 * 1024;
# It must not refer to C compiler or to the 'dev' output.
disallowedRequisites = [ stdenv.cc "dev" ];
};
outputChecks."dev" = {
# The 'dev' output must not be larger than 128 KiB.
maxSize = 128 * 1024;
};
- The derivation attribute `requiredSystemFeatures` is now enforced
for local builds, and not just to route builds to remote builders.
The supported features of a machine can be specified through the
configuration setting `system-features`.
By default, `system-features` includes `kvm` if `/dev/kvm` exists.
For compatibility, it also includes the pseudo-features
`nixos-test`, `benchmark` and `big-parallel` which are used by
Nixpkgs to route builds to particular Hydra build machines.
- Sandbox builds are now enabled by default on Linux.
- The new command `nix doctor` shows potential issues with your Nix
installation.
- The `fetchGit` builtin function now uses a caching scheme that puts
different remote repositories in distinct local repositories, rather
than a single shared repository. This may require more disk space
but is faster.
- The `dirOf` builtin function now works on relative paths.
- Nix now supports [SRI hashes](https://www.w3.org/TR/SRI/), allowing
the hash algorithm and hash to be specified in a single string. For
example, you can write:
import <nix/fetchurl.nix> {
url = https://nixos.org/releases/nix/nix-2.1.3/nix-2.1.3.tar.xz;
hash = "sha256-XSLa0FjVyADWWhFfkZ2iKTjFDda6mMXjoYMXLRSYQKQ=";
};
instead of
import <nix/fetchurl.nix> {
url = https://nixos.org/releases/nix/nix-2.1.3/nix-2.1.3.tar.xz;
sha256 = "5d22dad058d5c800d65a115f919da22938c50dd6ba98c5e3a183172d149840a4";
};
In fixed-output derivations, the `outputHashAlgo` attribute is no
longer mandatory if `outputHash` specifies the hash.
`nix hash-file` and `nix
hash-path` now print hashes in SRI format by default. They also use
SHA-256 by default instead of SHA-512 because that's what we use
most of the time in Nixpkgs.
- Integers are now 64 bits on all platforms.
- The evaluator now prints profiling statistics (enabled via the
NIX\_SHOW\_STATS and NIX\_COUNT\_CALLS environment variables) in
JSON format.
- The option `--xml` in `nix-store
--query` has been removed. Instead, there now is an option
`--graphml` to output the dependency graph in GraphML format.
- All `nix-*` commands are now symlinks to `nix`. This saves a bit of
disk space.
- `nix repl` now uses `libeditline` or `libreadline`.

44
doc/manual/src/release-notes/rl-2.3.md Normal file
View file

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