From 8901acc97664aa8ebf687ee904428aa57a5192be Mon Sep 17 00:00:00 2001 From: Mikey Ariel Date: Wed, 27 Aug 2014 18:41:09 +0200 Subject: [PATCH] Restructuring the Nix manual --- doc/manual/{ => bugs}/bugs.xml | 0 doc/manual/builds/build-farm.xml | 22 + .../enabling-builds.xml} | 21 +- doc/manual/command-ref/command-ref.xml | 20 + doc/manual/{ => command-ref}/conf-file.xml | 0 doc/manual/{ => command-ref}/env-common.xml | 12 +- doc/manual/command-ref/files.xml | 14 + doc/manual/command-ref/main-commands.xml | 17 + doc/manual/{ => command-ref}/nix-build.xml | 7 +- doc/manual/{ => command-ref}/nix-channel.xml | 7 +- .../{ => command-ref}/nix-collect-garbage.xml | 7 +- .../{ => command-ref}/nix-copy-closure.xml | 0 doc/manual/{ => command-ref}/nix-daemon.xml | 7 +- doc/manual/{ => command-ref}/nix-env.xml | 7 +- doc/manual/{ => command-ref}/nix-hash.xml | 7 +- .../{ => command-ref}/nix-install-package.xml | 7 +- .../{ => command-ref}/nix-instantiate.xml | 7 +- .../{ => command-ref}/nix-prefetch-url.xml | 7 +- doc/manual/{ => command-ref}/nix-pull.xml | 7 +- doc/manual/{ => command-ref}/nix-push.xml | 7 +- doc/manual/{ => command-ref}/nix-shell.xml | 7 +- doc/manual/{ => command-ref}/nix-store.xml | 7 +- .../{ => command-ref}/opt-common-syn.xml | 0 doc/manual/{ => command-ref}/opt-common.xml | 6 +- doc/manual/{ => command-ref}/opt-inst-syn.xml | 0 doc/manual/command-ref/utilities.xml | 23 + .../expressions/advanced-attributes.xml | 243 ++ .../expressions/arguments-variables.xml | 121 + doc/manual/expressions/build-script.xml | 119 + doc/manual/expressions/builder-syntax.xml | 119 + doc/manual/{ => expressions}/builtins.xml | 9 +- doc/manual/expressions/custom-builder.xml | 26 + doc/manual/expressions/debug-build.xml | 33 + doc/manual/expressions/derivations.xml | 211 ++ .../expressions/expression-language.xml | 30 + doc/manual/expressions/expression-syntax.xml | 148 + doc/manual/expressions/generic-builder.xml | 98 + .../expressions/language-constructs.xml | 344 +++ doc/manual/expressions/language-operators.xml | 113 + doc/manual/expressions/language-values.xml | 268 ++ .../expressions/simple-building-testing.xml | 86 + doc/manual/expressions/simple-expression.xml | 47 + doc/manual/expressions/standard-env.xml | 60 + .../expressions/writing-nix-expressions.xml | 27 + doc/manual/{ => glossary}/glossary.xml | 0 doc/manual/installation.xml | 447 --- doc/manual/installation/building-source.xml | 57 + doc/manual/installation/env-variables.xml | 24 + doc/manual/installation/installation.xml | 34 + doc/manual/installation/installing-binary.xml | 81 + doc/manual/installation/installing-source.xml | 17 + doc/manual/installation/multi-user.xml | 106 + doc/manual/installation/nix-security.xml | 27 + doc/manual/installation/obtaining-source.xml | 30 + .../installation/prerequisites-source.xml | 73 + doc/manual/installation/single-user.xml | 21 + .../installation/supported-platforms.xml | 38 + .../about-nix.xml} | 32 +- doc/manual/introduction/introduction.xml | 16 + doc/manual/introduction/nix-license.xml | 20 + doc/manual/manual.xml | 73 +- doc/manual/package-management.xml | 591 ---- doc/manual/packages/basic-package-mgmt.xml | 170 ++ doc/manual/packages/channels.xml | 57 + doc/manual/packages/garbage-collection.xml | 70 + .../packages/garbage-collector-roots.xml | 29 + doc/manual/packages/one-click.xml | 37 + doc/manual/packages/package-management.xml | 24 + doc/manual/packages/profiles.xml | 159 ++ doc/manual/packages/sharing-packages.xml | 82 + .../getting-started.xml} | 56 +- doc/manual/quick-start/quick-start.xml | 17 + doc/manual/release-notes.xml | 2521 ----------------- doc/manual/release-notes/release-notes.xml | 43 + doc/manual/release-notes/rl-010.xml | 323 +++ doc/manual/release-notes/rl-0101.xml | 13 + doc/manual/release-notes/rl-011.xml | 261 ++ doc/manual/release-notes/rl-012.xml | 175 ++ doc/manual/release-notes/rl-013.xml | 106 + doc/manual/release-notes/rl-014.xml | 44 + doc/manual/release-notes/rl-015.xml | 14 + doc/manual/release-notes/rl-016.xml | 55 + doc/manual/release-notes/rl-05.xml | 11 + doc/manual/release-notes/rl-06.xml | 122 + doc/manual/release-notes/rl-07.xml | 35 + doc/manual/release-notes/rl-08.xml | 246 ++ doc/manual/release-notes/rl-081.xml | 21 + doc/manual/release-notes/rl-09.xml | 98 + doc/manual/release-notes/rl-091.xml | 13 + doc/manual/release-notes/rl-092.xml | 28 + doc/manual/release-notes/rl-10.xml | 119 + doc/manual/release-notes/rl-11.xml | 100 + doc/manual/release-notes/rl-12.xml | 157 + doc/manual/release-notes/rl-13.xml | 19 + doc/manual/release-notes/rl-14.xml | 39 + doc/manual/release-notes/rl-15.xml | 12 + doc/manual/release-notes/rl-151.xml | 12 + doc/manual/release-notes/rl-152.xml | 12 + doc/manual/release-notes/rl-16.xml | 127 + doc/manual/release-notes/rl-161.xml | 69 + doc/manual/release-notes/rl-17.xml | 263 ++ doc/manual/release-notes/rl-18.xml | 11 + doc/manual/troubleshooting.xml | 92 - .../troubleshooting/collisions-nixenv.xml | 43 + .../troubleshooting/links-nix-store.xml | 43 + .../troubleshooting/troubleshooting.xml | 18 + doc/manual/writing-nix-expressions.xml | 1901 ------------- 107 files changed, 6161 insertions(+), 5721 deletions(-) rename doc/manual/{ => bugs}/bugs.xml (100%) create mode 100644 doc/manual/builds/build-farm.xml rename doc/manual/{build-farm.xml => builds/enabling-builds.xml} (87%) create mode 100644 doc/manual/command-ref/command-ref.xml rename doc/manual/{ => command-ref}/conf-file.xml (100%) rename doc/manual/{ => command-ref}/env-common.xml (97%) create mode 100644 doc/manual/command-ref/files.xml create mode 100644 doc/manual/command-ref/main-commands.xml rename doc/manual/{ => command-ref}/nix-build.xml (97%) rename doc/manual/{ => command-ref}/nix-channel.xml (96%) rename doc/manual/{ => command-ref}/nix-collect-garbage.xml (93%) rename doc/manual/{ => command-ref}/nix-copy-closure.xml (100%) rename doc/manual/{ => command-ref}/nix-daemon.xml (83%) rename doc/manual/{ => command-ref}/nix-env.xml (99%) rename doc/manual/{ => command-ref}/nix-hash.xml (97%) rename doc/manual/{ => command-ref}/nix-install-package.xml (97%) rename doc/manual/{ => command-ref}/nix-instantiate.xml (98%) rename doc/manual/{ => command-ref}/nix-prefetch-url.xml (95%) rename doc/manual/{ => command-ref}/nix-pull.xml (90%) rename doc/manual/{ => command-ref}/nix-push.xml (98%) rename doc/manual/{ => command-ref}/nix-shell.xml (97%) rename doc/manual/{ => command-ref}/nix-store.xml (99%) rename doc/manual/{ => command-ref}/opt-common-syn.xml (100%) rename doc/manual/{ => command-ref}/opt-common.xml (99%) rename doc/manual/{ => command-ref}/opt-inst-syn.xml (100%) create mode 100644 doc/manual/command-ref/utilities.xml create mode 100644 doc/manual/expressions/advanced-attributes.xml create mode 100644 doc/manual/expressions/arguments-variables.xml create mode 100644 doc/manual/expressions/build-script.xml create mode 100644 doc/manual/expressions/builder-syntax.xml rename doc/manual/{ => expressions}/builtins.xml (99%) create mode 100644 doc/manual/expressions/custom-builder.xml create mode 100644 doc/manual/expressions/debug-build.xml create mode 100644 doc/manual/expressions/derivations.xml create mode 100644 doc/manual/expressions/expression-language.xml create mode 100644 doc/manual/expressions/expression-syntax.xml create mode 100644 doc/manual/expressions/generic-builder.xml create mode 100644 doc/manual/expressions/language-constructs.xml create mode 100644 doc/manual/expressions/language-operators.xml create mode 100644 doc/manual/expressions/language-values.xml create mode 100644 doc/manual/expressions/simple-building-testing.xml create mode 100644 doc/manual/expressions/simple-expression.xml create mode 100644 doc/manual/expressions/standard-env.xml create mode 100644 doc/manual/expressions/writing-nix-expressions.xml rename doc/manual/{ => glossary}/glossary.xml (100%) delete mode 100644 doc/manual/installation.xml create mode 100644 doc/manual/installation/building-source.xml create mode 100644 doc/manual/installation/env-variables.xml create mode 100644 doc/manual/installation/installation.xml create mode 100644 doc/manual/installation/installing-binary.xml create mode 100644 doc/manual/installation/installing-source.xml create mode 100644 doc/manual/installation/multi-user.xml create mode 100644 doc/manual/installation/nix-security.xml create mode 100644 doc/manual/installation/obtaining-source.xml create mode 100644 doc/manual/installation/prerequisites-source.xml create mode 100644 doc/manual/installation/single-user.xml create mode 100644 doc/manual/installation/supported-platforms.xml rename doc/manual/{introduction.xml => introduction/about-nix.xml} (91%) create mode 100644 doc/manual/introduction/introduction.xml create mode 100644 doc/manual/introduction/nix-license.xml delete mode 100644 doc/manual/package-management.xml create mode 100644 doc/manual/packages/basic-package-mgmt.xml create mode 100644 doc/manual/packages/channels.xml create mode 100644 doc/manual/packages/garbage-collection.xml create mode 100644 doc/manual/packages/garbage-collector-roots.xml create mode 100644 doc/manual/packages/one-click.xml create mode 100644 doc/manual/packages/package-management.xml create mode 100644 doc/manual/packages/profiles.xml create mode 100644 doc/manual/packages/sharing-packages.xml rename doc/manual/{quick-start.xml => quick-start/getting-started.xml} (63%) create mode 100644 doc/manual/quick-start/quick-start.xml delete mode 100644 doc/manual/release-notes.xml create mode 100644 doc/manual/release-notes/release-notes.xml create mode 100644 doc/manual/release-notes/rl-010.xml create mode 100644 doc/manual/release-notes/rl-0101.xml create mode 100644 doc/manual/release-notes/rl-011.xml create mode 100644 doc/manual/release-notes/rl-012.xml create mode 100644 doc/manual/release-notes/rl-013.xml create mode 100644 doc/manual/release-notes/rl-014.xml create mode 100644 doc/manual/release-notes/rl-015.xml create mode 100644 doc/manual/release-notes/rl-016.xml create mode 100644 doc/manual/release-notes/rl-05.xml create mode 100644 doc/manual/release-notes/rl-06.xml create mode 100644 doc/manual/release-notes/rl-07.xml create mode 100644 doc/manual/release-notes/rl-08.xml create mode 100644 doc/manual/release-notes/rl-081.xml create mode 100644 doc/manual/release-notes/rl-09.xml create mode 100644 doc/manual/release-notes/rl-091.xml create mode 100644 doc/manual/release-notes/rl-092.xml create mode 100644 doc/manual/release-notes/rl-10.xml create mode 100644 doc/manual/release-notes/rl-11.xml create mode 100644 doc/manual/release-notes/rl-12.xml create mode 100644 doc/manual/release-notes/rl-13.xml create mode 100644 doc/manual/release-notes/rl-14.xml create mode 100644 doc/manual/release-notes/rl-15.xml create mode 100644 doc/manual/release-notes/rl-151.xml create mode 100644 doc/manual/release-notes/rl-152.xml create mode 100644 doc/manual/release-notes/rl-16.xml create mode 100644 doc/manual/release-notes/rl-161.xml create mode 100644 doc/manual/release-notes/rl-17.xml create mode 100644 doc/manual/release-notes/rl-18.xml delete mode 100644 doc/manual/troubleshooting.xml create mode 100644 doc/manual/troubleshooting/collisions-nixenv.xml create mode 100644 doc/manual/troubleshooting/links-nix-store.xml create mode 100644 doc/manual/troubleshooting/troubleshooting.xml delete mode 100644 doc/manual/writing-nix-expressions.xml diff --git a/doc/manual/bugs.xml b/doc/manual/bugs/bugs.xml similarity index 100% rename from doc/manual/bugs.xml rename to doc/manual/bugs/bugs.xml diff --git a/doc/manual/builds/build-farm.xml b/doc/manual/builds/build-farm.xml new file mode 100644 index 000000000..e0e9f10f1 --- /dev/null +++ b/doc/manual/builds/build-farm.xml @@ -0,0 +1,22 @@ + + +Distributed Builds + + +Nix supports distributed builds, where a local Nix installation can +forward Nix builds to other machines over the network. This allows +multiple builds to be performed in parallel (thus improving +performance) and allows Nix to perform multi-platform builds in a +semi-transparent way. For instance, if you perform a build for a +powerpc-darwin on an i686-linux +machine, Nix can automatically forward the build to a +powerpc-darwin machine, if available. + + + + + diff --git a/doc/manual/build-farm.xml b/doc/manual/builds/enabling-builds.xml similarity index 87% rename from doc/manual/build-farm.xml rename to doc/manual/builds/enabling-builds.xml index 2e0d86b89..4b45812ee 100644 --- a/doc/manual/build-farm.xml +++ b/doc/manual/builds/enabling-builds.xml @@ -1,17 +1,10 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-enabling-builds"> -Setting Up Distributed Builds - -Nix supports distributed builds: a local Nix installation can -forward Nix builds to other machines over the network. This allows -multiple builds to be performed in parallel (thus improving -performance) and allows Nix to perform multi-platform builds in a -semi-transparent way. For instance, if you perform a build for a -powerpc-darwin on an i686-linux -machine, Nix can automatically forward the build to a -powerpc-darwin machine, if available. +Enabling Distributed Builds You can enable distributed builds by setting the environment variable NIX_BUILD_HOOK to point to a program that Nix @@ -109,5 +102,5 @@ load on the remote machine, so if you have multiple instances of Nix running, they should use the same NIX_CURRENT_LOAD file. Maybe in the future build-remote.pl will look at the actual remote load. - - + + \ No newline at end of file diff --git a/doc/manual/command-ref/command-ref.xml b/doc/manual/command-ref/command-ref.xml new file mode 100644 index 000000000..cfad9b7d7 --- /dev/null +++ b/doc/manual/command-ref/command-ref.xml @@ -0,0 +1,20 @@ + + +Command Reference + + +This section lists commands and options that you can use when you +work with Nix. + + + + + + + + + diff --git a/doc/manual/conf-file.xml b/doc/manual/command-ref/conf-file.xml similarity index 100% rename from doc/manual/conf-file.xml rename to doc/manual/command-ref/conf-file.xml diff --git a/doc/manual/env-common.xml b/doc/manual/command-ref/env-common.xml similarity index 97% rename from doc/manual/env-common.xml rename to doc/manual/command-ref/env-common.xml index 91a3e9e32..c501d1c01 100644 --- a/doc/manual/env-common.xml +++ b/doc/manual/command-ref/env-common.xml @@ -1,8 +1,10 @@ -
+ -Common environment variables +Common Environment Variables Most Nix commands interpret the following environment variables: @@ -335,4 +337,4 @@ $ mount -o bind /mnt/otherdisk/nix /nix -
+ diff --git a/doc/manual/command-ref/files.xml b/doc/manual/command-ref/files.xml new file mode 100644 index 000000000..7bbc96e89 --- /dev/null +++ b/doc/manual/command-ref/files.xml @@ -0,0 +1,14 @@ + + +Files + +This section lists configuration files that you can use when you +work with Nix. + + + + \ No newline at end of file diff --git a/doc/manual/command-ref/main-commands.xml b/doc/manual/command-ref/main-commands.xml new file mode 100644 index 000000000..0f4169243 --- /dev/null +++ b/doc/manual/command-ref/main-commands.xml @@ -0,0 +1,17 @@ + + +Main Commands + +This section lists commands and options that you can use when you +work with Nix. + + + + + + + \ No newline at end of file diff --git a/doc/manual/nix-build.xml b/doc/manual/command-ref/nix-build.xml similarity index 97% rename from doc/manual/nix-build.xml rename to doc/manual/command-ref/nix-build.xml index 3832f5fc3..669a48f8c 100644 --- a/doc/manual/nix-build.xml +++ b/doc/manual/command-ref/nix-build.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-build"> nix-build diff --git a/doc/manual/nix-channel.xml b/doc/manual/command-ref/nix-channel.xml similarity index 96% rename from doc/manual/nix-channel.xml rename to doc/manual/command-ref/nix-channel.xml index 2c4e1151b..e13394c7d 100644 --- a/doc/manual/nix-channel.xml +++ b/doc/manual/command-ref/nix-channel.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-channel"> nix-channel diff --git a/doc/manual/nix-collect-garbage.xml b/doc/manual/command-ref/nix-collect-garbage.xml similarity index 93% rename from doc/manual/nix-collect-garbage.xml rename to doc/manual/command-ref/nix-collect-garbage.xml index cf870740f..f2009dcbd 100644 --- a/doc/manual/nix-collect-garbage.xml +++ b/doc/manual/command-ref/nix-collect-garbage.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-collect-garbage"> nix-collect-garbage diff --git a/doc/manual/nix-copy-closure.xml b/doc/manual/command-ref/nix-copy-closure.xml similarity index 100% rename from doc/manual/nix-copy-closure.xml rename to doc/manual/command-ref/nix-copy-closure.xml diff --git a/doc/manual/nix-daemon.xml b/doc/manual/command-ref/nix-daemon.xml similarity index 83% rename from doc/manual/nix-daemon.xml rename to doc/manual/command-ref/nix-daemon.xml index c68605fd6..4311664ed 100644 --- a/doc/manual/nix-daemon.xml +++ b/doc/manual/command-ref/nix-daemon.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-daemon"> nix-daemon diff --git a/doc/manual/nix-env.xml b/doc/manual/command-ref/nix-env.xml similarity index 99% rename from doc/manual/nix-env.xml rename to doc/manual/command-ref/nix-env.xml index c44020803..494edc3e5 100644 --- a/doc/manual/nix-env.xml +++ b/doc/manual/command-ref/nix-env.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-env"> nix-env diff --git a/doc/manual/nix-hash.xml b/doc/manual/command-ref/nix-hash.xml similarity index 97% rename from doc/manual/nix-hash.xml rename to doc/manual/command-ref/nix-hash.xml index af4e361ff..897d92e2c 100644 --- a/doc/manual/nix-hash.xml +++ b/doc/manual/command-ref/nix-hash.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-hash"> nix-hash diff --git a/doc/manual/nix-install-package.xml b/doc/manual/command-ref/nix-install-package.xml similarity index 97% rename from doc/manual/nix-install-package.xml rename to doc/manual/command-ref/nix-install-package.xml index 54a66348f..fa3b46e22 100644 --- a/doc/manual/nix-install-package.xml +++ b/doc/manual/command-ref/nix-install-package.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-install-package"> nix-install-package diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/command-ref/nix-instantiate.xml similarity index 98% rename from doc/manual/nix-instantiate.xml rename to doc/manual/command-ref/nix-instantiate.xml index 936f154dd..a4e45cf97 100644 --- a/doc/manual/nix-instantiate.xml +++ b/doc/manual/command-ref/nix-instantiate.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-instantiate"> nix-instantiate diff --git a/doc/manual/nix-prefetch-url.xml b/doc/manual/command-ref/nix-prefetch-url.xml similarity index 95% rename from doc/manual/nix-prefetch-url.xml rename to doc/manual/command-ref/nix-prefetch-url.xml index c416e675b..885c958ce 100644 --- a/doc/manual/nix-prefetch-url.xml +++ b/doc/manual/command-ref/nix-prefetch-url.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-prefetch-url"> nix-prefetch-url diff --git a/doc/manual/nix-pull.xml b/doc/manual/command-ref/nix-pull.xml similarity index 90% rename from doc/manual/nix-pull.xml rename to doc/manual/command-ref/nix-pull.xml index 8e4a505e1..43d5a6c56 100644 --- a/doc/manual/nix-pull.xml +++ b/doc/manual/command-ref/nix-pull.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-pull"> nix-pull diff --git a/doc/manual/nix-push.xml b/doc/manual/command-ref/nix-push.xml similarity index 98% rename from doc/manual/nix-push.xml rename to doc/manual/command-ref/nix-push.xml index e789bbf7d..9c6cdfa2f 100644 --- a/doc/manual/nix-push.xml +++ b/doc/manual/command-ref/nix-push.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-push"> nix-push diff --git a/doc/manual/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml similarity index 97% rename from doc/manual/nix-shell.xml rename to doc/manual/command-ref/nix-shell.xml index d5f70a9e6..1cb2ebfdd 100644 --- a/doc/manual/nix-shell.xml +++ b/doc/manual/command-ref/nix-shell.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-shell"> nix-shell diff --git a/doc/manual/nix-store.xml b/doc/manual/command-ref/nix-store.xml similarity index 99% rename from doc/manual/nix-store.xml rename to doc/manual/command-ref/nix-store.xml index c9a912ff0..ae0f683f2 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/command-ref/nix-store.xml @@ -1,7 +1,8 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="sec-nix-store"> nix-store diff --git a/doc/manual/opt-common-syn.xml b/doc/manual/command-ref/opt-common-syn.xml similarity index 100% rename from doc/manual/opt-common-syn.xml rename to doc/manual/command-ref/opt-common-syn.xml diff --git a/doc/manual/opt-common.xml b/doc/manual/command-ref/opt-common.xml similarity index 99% rename from doc/manual/opt-common.xml rename to doc/manual/command-ref/opt-common.xml index f8584f4d6..3486c7e7d 100644 --- a/doc/manual/opt-common.xml +++ b/doc/manual/command-ref/opt-common.xml @@ -1,6 +1,6 @@ -
+ -Common options +Common Options Most Nix commands accept the following command-line options: @@ -386,4 +386,4 @@ -
+ diff --git a/doc/manual/opt-inst-syn.xml b/doc/manual/command-ref/opt-inst-syn.xml similarity index 100% rename from doc/manual/opt-inst-syn.xml rename to doc/manual/command-ref/opt-inst-syn.xml diff --git a/doc/manual/command-ref/utilities.xml b/doc/manual/command-ref/utilities.xml new file mode 100644 index 000000000..190962cea --- /dev/null +++ b/doc/manual/command-ref/utilities.xml @@ -0,0 +1,23 @@ + + +Utilities + +This section lists utilities that you can use when you +work with Nix. + + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/manual/expressions/advanced-attributes.xml b/doc/manual/expressions/advanced-attributes.xml new file mode 100644 index 000000000..40a5a80ac --- /dev/null +++ b/doc/manual/expressions/advanced-attributes.xml @@ -0,0 +1,243 @@ +
+ +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. + + + + + 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). + + + + + + 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; + md5 = "70c9ccf9fac07f762c24f2df2290784d"; +} + + + 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; + md5 = "70c9ccf9fac07f762c24f2df2290784d"; +} + + + 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, md5 }: + +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 MD5 hash md5. + outputHashMode = "flat"; + outputHashAlgo = "md5"; + outputHash = md5; + + inherit url; +} + + + + + The outputHashAlgo attribute specifies + the hash algorithm used to compute the hash. It can currently be + "md5", "sha1" or + "sha256". + + 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 md5sum 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). 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 + for information about converting to and from base-32 + notation.) + + + + + 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, where + impurities such as these are okay since (the hash of) the output + is known in advance. It is ignored for all other + derivations. + + + + + preferLocalBuild + + If this attribute is set to + true, it has two effects. First, the + derivation will always be built, not substituted, even if a + substitute is available. Second, if distributed building is + enabled, 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. + + + + + +
\ No newline at end of file diff --git a/doc/manual/expressions/arguments-variables.xml b/doc/manual/expressions/arguments-variables.xml new file mode 100644 index 000000000..bf60cb7ee --- /dev/null +++ b/doc/manual/expressions/arguments-variables.xml @@ -0,0 +1,121 @@ +
+ +Arguments and Variables + + + +Composing GNU Hello +(<filename>all-packages.nix</filename>) + +... + +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 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. 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 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 ). + + 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. + + + + + +
\ No newline at end of file diff --git a/doc/manual/expressions/build-script.xml b/doc/manual/expressions/build-script.xml new file mode 100644 index 000000000..7bad8f808 --- /dev/null +++ b/doc/manual/expressions/build-script.xml @@ -0,0 +1,119 @@ +
+ +Build Script + +Build script for GNU Hello +(<filename>builder.sh</filename>) + +source $stdenv/setup + +PATH=$perl/bin:$PATH + +tar xvfz $src +cd hello-* +./configure --prefix=$out +make +make install + + + 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 + emptyActually, it's initialised to + /path-not-set to prevent Bash from setting it + to a default value.. 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 , 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 option, +which causes the script to be aborted if any command fails without an +error check. + +
\ No newline at end of file diff --git a/doc/manual/expressions/builder-syntax.xml b/doc/manual/expressions/builder-syntax.xml new file mode 100644 index 000000000..e51bade44 --- /dev/null +++ b/doc/manual/expressions/builder-syntax.xml @@ -0,0 +1,119 @@ +
+ +Builder Syntax + +Build script for GNU Hello +(<filename>builder.sh</filename>) + +source $stdenv/setup + +PATH=$perl/bin:$PATH + +tar xvfz $src +cd hello-* +./configure --prefix=$out +make +make install + + + 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 + emptyActually, it's initialised to + /path-not-set to prevent Bash from setting it + to a default value.. 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 , 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 option, +which causes the script to be aborted if any command fails without an +error check. + +
\ No newline at end of file diff --git a/doc/manual/builtins.xml b/doc/manual/expressions/builtins.xml similarity index 99% rename from doc/manual/builtins.xml rename to doc/manual/expressions/builtins.xml index b289c6f0e..4edb3a1a7 100644 --- a/doc/manual/builtins.xml +++ b/doc/manual/expressions/builtins.xml @@ -1,9 +1,10 @@
- -Built-in functions + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id='ssec-builtins'> +Built-in Functions This section lists the functions and constants built into the Nix expression evaluator. (The built-in function diff --git a/doc/manual/expressions/custom-builder.xml b/doc/manual/expressions/custom-builder.xml new file mode 100644 index 000000000..c26deac40 --- /dev/null +++ b/doc/manual/expressions/custom-builder.xml @@ -0,0 +1,26 @@ +
+ +Customizing the Generic Builder + +The operation of the generic builder can be modified in many +places by setting certain variables. These hook +variables are typically set to the name of some shell +function defined by you. For instance, to perform some additional +steps after make install you would set the +postInstall variable: + + +postInstall=myPostInstall + +myPostInstall() { + mkdir $out/share/extra + cp extrafiles/* $out/share/extra +} + + + +
\ No newline at end of file diff --git a/doc/manual/expressions/debug-build.xml b/doc/manual/expressions/debug-build.xml new file mode 100644 index 000000000..508cb2c19 --- /dev/null +++ b/doc/manual/expressions/debug-build.xml @@ -0,0 +1,33 @@ +
+ +Debugging Build Failures + +At the beginning of each phase, the set of all shell variables +is written to the file env-vars at the top-level +build directory. This is useful for debugging: it allows you to +recreate the environment in which a build was performed. For +instance, if a build fails, then assuming you used the + flag, you can go to the output directory and +switch to the environment of the builder: + + +$ nix-build -K ./foo.nix +... fails, keeping build directory `/tmp/nix-1234-0' + +$ cd /tmp/nix-1234-0 + +$ source env-vars + +(edit some files...) + +$ make + +(execution continues with the same GCC, make, etc.) + + + +
\ No newline at end of file diff --git a/doc/manual/expressions/derivations.xml b/doc/manual/expressions/derivations.xml new file mode 100644 index 000000000..b57c33f4e --- /dev/null +++ b/doc/manual/expressions/derivations.xml @@ -0,0 +1,211 @@ +
+ +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 + "powerpc-darwin"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. 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 .) + + 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 integers 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 output 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 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 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 + 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. + + + + + + + +
\ No newline at end of file diff --git a/doc/manual/expressions/expression-language.xml b/doc/manual/expressions/expression-language.xml new file mode 100644 index 000000000..240ef80f1 --- /dev/null +++ b/doc/manual/expressions/expression-language.xml @@ -0,0 +1,30 @@ + + +Nix Expression Language + +The Nix expression language is a pure, lazy, functional +language. Purity means that operations in the language don't have +side-effects (for instance, there is no variable assignment). +Laziness means that arguments to functions are evaluated only when +they are needed. Functional means that functions are +normal values that can be passed around and manipulated +in interesting ways. The language is not a full-featured, general +purpose language. Its main job is to describe packages, +compositions of packages, and the variability within +packages. + +This section presents the various features of the +language. + + + + + + + + + diff --git a/doc/manual/expressions/expression-syntax.xml b/doc/manual/expressions/expression-syntax.xml new file mode 100644 index 000000000..6f1a3a10c --- /dev/null +++ b/doc/manual/expressions/expression-syntax.xml @@ -0,0 +1,148 @@ +
+ +Expression Syntax + +Nix expression for GNU Hello +(<filename>default.nix</filename>) + +{ stdenv, fetchurl, perl }: + +stdenv.mkDerivation { + name = "hello-2.1.1"; + builder = ./builder.sh; + src = fetchurl { + url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz; + md5 = "70c9ccf9fac07f762c24f2df2290784d"; + }; + inherit perl; +} + + + 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 , 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 an MD5 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. + + + + + + + +
\ No newline at end of file diff --git a/doc/manual/expressions/generic-builder.xml b/doc/manual/expressions/generic-builder.xml new file mode 100644 index 000000000..f8567a042 --- /dev/null +++ b/doc/manual/expressions/generic-builder.xml @@ -0,0 +1,98 @@ +
+ +Generic Builder Syntax + +Recall from 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 . + +Build script using the generic +build functions + +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.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. + + + + + + + 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 . 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 . + + + + + +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. + +
\ No newline at end of file diff --git a/doc/manual/expressions/language-constructs.xml b/doc/manual/expressions/language-constructs.xml new file mode 100644 index 000000000..ddb349894 --- /dev/null +++ b/doc/manual/expressions/language-constructs.xml @@ -0,0 +1,344 @@ +
+ +Language Constructs + +Recursive sets + +Recursive sets are just normal sets, but the attributes can +refer to each other. For example, + + +rec { + x = y; + y = 123; +}.x + + +evaluates to 123. Note that without +rec the binding x = y; would +refer to the variable y in the surrounding scope, +if one exists, and would be invalid if no such variable exists. That +is, in a normal (non-recursive) set, attributes are not added to the +lexical scope; in a recursive set, they are. + +Recursive sets of course introduce the danger of infinite +recursion. For example, + + +rec { + x = y; + y = x; +}.x + +does not terminateActually, Nix detects infinite +recursion in this case and aborts (infinite recursion +encountered).. + + + + +Let-expressions + +A let-expression allows you define local variables for an +expression. For instance, + + +let + x = "foo"; + y = "bar"; +in x + y + +evaluates to "foobar". + + + + + + +Inheriting attributes + +When defining a set 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; +} + +evaluates 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. + + + + +Functions + +Functions have the following form: + + +pattern: body + +The pattern specifies what the argument of the function must look +like, and binds variables in the body to (parts of) the +argument. There are three kinds of patterns: + + + + + If a pattern is a single identifier, then the + function matches any argument. Example: + + +let negate = x: !x; + concat = x: y: x + y; +in if negate true then concat "foo" "bar" else "" + + Note that concat is a function that takes one + argument and returns a function that takes another argument. This + allows partial parameterisation (i.e., only filling some of the + arguments of a function); e.g., + + +map (concat "foo") [ "bar" "bla" "abc" ] + + evaluates to [ "foobar" "foobla" + "fooabc" ]. + + + A set pattern of the form + { name1, name2, …, nameN } matches a set + containing the listed attributes, and binds the values of those + attributes to variables in the function body. For example, the + function + + +{ x, y, z }: z + y + x + + can only be called with a set containing exactly the attributes + x, y and + z. No other attributes are allowed. If you want + to allow additional arguments, you can use an ellipsis + (...): + + +{ x, y, z, ... }: z + y + x + + This works on any set that contains at least the three named + attributes. + + It is possible to provide default values + for attributes, in which case they are allowed to be missing. A + default value is specified by writing + name ? + e, where + e is an arbitrary expression. For example, + + +{ x, y ? "foo", z ? "bar" }: z + y + x + + specifies a function that only requires an attribute named + x, but optionally accepts y + and z. + + + An @-pattern provides a means of referring + to the whole value being matched: + + +args@{ x, y, z, ... }: z + y + x + args.a + + Here args is bound to the entire argument, which + is further matched against the pattern { x, y, z, + ... }. + + + + +Note that functions do not have names. If you want to give them +a name, you can bind them to an attribute, e.g., + + +let concat = { x, y }: x + y; +in concat { x = "foo"; y = "bar"; } + + + + + + +Conditionals + +Conditionals look like this: + + +if e1 then e2 else e3 + +where e1 is an expression that should +evaluate to a Boolean value (true or +false). + + + + +Assertions + +Assertions are generally used to check that certain requirements +on or between features and dependencies hold. They look like this: + + +assert e1; e2 + +where e1 is an expression that should +evaluate to a Boolean value. If it evaluates to +true, e2 is returned; +otherwise expression evaluation is aborted and a backtrace is printed. + +Nix expression for Subversion + +{ 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; + ... +} + + + 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. + + + + + + + + +With-expressions + +A with-expression, + + +with e1; e2 + +introduces the set e1 into the lexical +scope of the expression e2. For instance, + + +let as = { x = "foo"; y = "bar"; }; +in with as; x + y + +evaluates to "foobar" since the +with adds the x and +y attributes of as to the +lexical scope in the expression x + y. The most +common use of with is in conjunction with the +import function. E.g., + + +with (import ./definitions.nix); ... + +makes all attributes defined in the file +definitions.nix available as if they were defined +locally in a rec-expression. + + + + +Comments + +Comments can be single-line, started with a # +character, or inline/multi-line, enclosed within /* +... */. + + + + +
\ No newline at end of file diff --git a/doc/manual/expressions/language-operators.xml b/doc/manual/expressions/language-operators.xml new file mode 100644 index 000000000..a3323ced4 --- /dev/null +++ b/doc/manual/expressions/language-operators.xml @@ -0,0 +1,113 @@ +
+ +Operators + + lists the operators in the +Nix expression language, in order of precedence (from strongest to +weakest binding). + + + Operators + + + + Syntax + Associativity + Description + + + + + 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. + + + e1 e2 + left + Call function e1 with + argument e2. + + + e ? + attrpath + none + Test whether set e contains + the attribute denoted by attrpath; + return true or + false. + + + e1 ++ e2 + right + List concatenation. + + + e1 + e2 + left + String or path concatenation. + + + ! e + left + Boolean negation. + + + 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). + + + e1 == + e2 + none + Equality. + + + e1 != + e2 + none + Inequality. + + + e1 && + e2 + left + Logical AND. + + + e1 || + e2 + left + Logical OR. + + + e1 -> + e2 + none + Logical implication (equivalent to + !e1 || + e2). + + + +
+ +
\ No newline at end of file diff --git a/doc/manual/expressions/language-values.xml b/doc/manual/expressions/language-values.xml new file mode 100644 index 000000000..519657f15 --- /dev/null +++ b/doc/manual/expressions/language-values.xml @@ -0,0 +1,268 @@ +
+ +Values + + +Simple Values + +Nix has the following basic data types: + + + + + + Strings can be written in three + ways. + + The most common way is to enclose the string between double + quotes, e.g., "foo bar". Strings can span + multiple lines. The special characters " and + \ and the character sequence + ${ must be escaped by prefixing them with a + backslash (\). Newlines, carriage returns and + tabs can be written as \n, + \r and \t, + respectively. + + You can include the result of an expression into a string by + enclosing it in + ${...}, a feature + known as antiquotation. The enclosed + expression must evaluate to something that can be coerced into a + string (meaning that it must be a string, a path, or a + derivation). For instance, rather than writing + + +"--with-freetype2-library=" + freetype + "/lib" + + (where freetype is a derivation), you can + instead write the more natural + + +"--with-freetype2-library=${freetype}/lib" + + The latter is automatically translated to the former. A more + complicated example (from the Nix expression for Qt): + + +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., + '''. Finally, linefeed, carriage-return and + tab characters can be written as ''\n, + ''\r, ''\t. + + 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 + 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. + + + + Integers, e.g., + 123. + + 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 + pathIt's parsed as an expression that selects the + attribute sh from the variable + builder.. If the file name is + relative, i.e., if it does not begin with a slash, it is made + absolute at parse time relative to the directory of the Nix + expression that contained it. For instance, if a Nix expression in + /foo/bar/bla.nix refers to + ../xyzzy/fnord.nix, the absolute path is + /foo/xyzzy/fnord.nix. + + Booleans with values + true and + false. + + The null value, denoted as + null. + + + + + + + + +Lists + +Lists are formed by enclosing a whitespace-separated list of +values between square brackets. For example, + + +[ 123 ./foo.nix "abc" (f { x = y; }) ] + +defines a list of four elements, the last being the result of a call +to the function f. Note that function calls have +to be enclosed in parentheses. If they had been omitted, e.g., + + +[ 123 ./foo.nix "abc" f { x = y; } ] + +the result would be a list of five elements, the fourth one being a +function and the fifth being a set. + + + + +Sets + +Sets are really the core of the language, since ultimately the +Nix language is all about creating derivations, which are really just +sets of attributes to be passed to build scripts. + +Sets are just a list of name/value pairs (called +attributes) enclosed in curly brackets, where +each value is an arbitrary expression terminated by a semicolon. For +example: + + +{ x = 123; + text = "Hello"; + y = f { bla = 456; }; +} + +This defines a set with attributes named x, +text, y. The order of the +attributes is irrelevant. An attribute name may only occur +once. + +Attributes can be selected from a set using the +. operator. For instance, + + +{ a = "Foo"; b = "Bar"; }.a + +evaluates to "Foo". It is possible to provide a +default value in an attribute selection using the +or keyword. For example, + + +{ a = "Foo"; b = "Bar"; }.c or "Xyzzy" + +will evaluate to "Xyzzy" because there is no +c attribute in the set. + +You can use arbitrary double-quoted strings as attribute +names: + + +{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}" + + +This will evaluate to 123 (Assuming +bar is antiquotable). In the case where an +attribute name is just a single antiquotation, the quotes can be +dropped: + + +{ foo = 123; }.${bar} or 456 + +This will evaluate to 123 if +bar evaluates to "foo" when +coerced to a string and 456 otherwise (again +assuming bar is antiquotable). + +In the special case where an attribute name inside of a set declaration +evaluates to null (which is normally an error, as +null is not antiquotable), that attribute is simply not +added to the set: + + +{ ${if foo then "bar" else null} = true; } + +This will evaluate to {} if foo +evaluates to false. + + + + + +
\ No newline at end of file diff --git a/doc/manual/expressions/simple-building-testing.xml b/doc/manual/expressions/simple-building-testing.xml new file mode 100644 index 000000000..cc90409b5 --- /dev/null +++ b/doc/manual/expressions/simple-building-testing.xml @@ -0,0 +1,86 @@ +
+ +Building and Testing + +You can now try to build Hello. Of course, you could do +nix-env -f pkgs/top-level/all-packages.nix -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 pkgs/top-level/all-packages.nix -A hello +building path `/nix/store/632d2b22514d...-hello-2.1.1' +hello-2.1.1/ +hello-2.1.1/intl/ +hello-2.1.1/intl/ChangeLog +... + +$ ls -l result +lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1 + +$ ./result/bin/hello +Hello, world! + +The option selects +the hello attribute from +all-packages.nix. 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 switch to give the symlink another +name. + +Nix has a 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 pkgs/top-level/all-packages.nix -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). + +If you have a system with multiple CPUs, you may want to have +Nix build different derivations in parallel (insofar as possible). +Just pass the option , where +N is the maximum number of jobs to be run +in parallel, or set. Typically this should be the number of +CPUs. + +
\ No newline at end of file diff --git a/doc/manual/expressions/simple-expression.xml b/doc/manual/expressions/simple-expression.xml new file mode 100644 index 000000000..a8eb96f5a --- /dev/null +++ b/doc/manual/expressions/simple-expression.xml @@ -0,0 +1,47 @@ + + +Simple Nix Expression Use-Case + +This section shows how to add and test the GNU Hello +package to the Nix Packages collection. Hello is a program +that prints out the text Hello, world!. + +To add a package to the Nix Packages collection, you generally +need to do three things: + + + + 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. + + Write a builder. This is a + shell scriptIn fact, it can be written in any + language, but typically it's a bash shell + script. that actually builds the package from + the inputs. + + 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. + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/manual/expressions/standard-env.xml b/doc/manual/expressions/standard-env.xml new file mode 100644 index 000000000..2571f43fc --- /dev/null +++ b/doc/manual/expressions/standard-env.xml @@ -0,0 +1,60 @@ + + +The Standard Environment + + +The standard environment is used by passing it as an input +called stdenv to the derivation, and then doing + + +source $stdenv/setup + +at the top of the builder. + +Apart from adding the aforementioned commands to the +PATH, setup also does the +following: + + + + All input packages specified in the + buildInputs environment variable have their + /bin subdirectory added to PATH, + their /include subdirectory added to the C/C++ + header file search path, and their /lib + subdirectory added to the linker search path. This can be extended. + For instance, when the pkgconfig package is + used, the subdirectory /lib/pkgconfig of each + input is added to the PKG_CONFIG_PATH environment + variable. + + The environment variable + NIX_CFLAGS_STRIP is set so that the compiler strips + debug information from object files. This can be disabled by + setting NIX_STRIP_DEBUG to + 0. + + + + + +The setup script also exports a function +called genericBuild that knows how to build +typical Autoconf-style packages. It can be customised to perform +builds for any type of package. It is advisable to use +genericBuild since it provides facilities that +are almost always useful such as unpacking of sources, patching of +sources, nested logging, etc. + +The definitive, up-to-date documentation of the generic builder +is the source itself, which resides in +pkgs/stdenv/generic/setup.sh. + + + + + \ No newline at end of file diff --git a/doc/manual/expressions/writing-nix-expressions.xml b/doc/manual/expressions/writing-nix-expressions.xml new file mode 100644 index 000000000..6d64f24cd --- /dev/null +++ b/doc/manual/expressions/writing-nix-expressions.xml @@ -0,0 +1,27 @@ + + +Nix Expressions + + +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. + +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. + + + + + + + diff --git a/doc/manual/glossary.xml b/doc/manual/glossary/glossary.xml similarity index 100% rename from doc/manual/glossary.xml rename to doc/manual/glossary/glossary.xml diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml deleted file mode 100644 index 423bef5e2..000000000 --- a/doc/manual/installation.xml +++ /dev/null @@ -1,447 +0,0 @@ - - - -Installation - - -
Supported platforms - -Nix is currently supported on the following platforms: - - - - Linux (particularly on x86, x86_64, and - PowerPC). - - Mac OS X. - - FreeBSD (only tested on Intel). - - - - - - - -Nix is pretty portable, so it should work on most other Unix -platforms as well. - -
- - -
Installing a binary distribution - -The easiest way to install Nix is to run the following: - - -$ bash <(curl https://nixos.org/nix/install) - - -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: - - -$ mkdir /nix -$ chown alice /nix - - - - -You can also manually download and install a binary package. -Binary packages of the latest stable release are available for Fedora, -Debian, Ubuntu, Mac OS X and various other systems from the Nix homepage. -You can also get builds of the latest development release from our -continuous -build system. - -For Fedora, RPM packages are available. These can be installed -or upgraded using rpm -U. For example, - - -$ rpm -U nix-1.7-1.i386.rpm - - - -For Debian and Ubuntu, you can download a Deb package and -install it like this: - - -$ dpkg -i nix_1.7-1_amd64.deb - - - -For other platforms, including Mac OS X (Darwin), FreeBSD and -other Linux distributions, you can download a binary tarball that -contains Nix and all its dependencies. (This is what the install -script at https://nixos.org/nix/install uses.) 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.7-x86_64-darwin.tar.bz2 -alice$ cd nix-1.7-x86_64-darwin -alice$ ./install - - - - -Nix can be uninstalled using rpm -e nix or -dpkg -r nix on RPM- and Dpkg-based systems, -respectively. After this you should manually remove the Nix store and -other auxiliary data, if desired: - - -$ rm -rf /nix - - - -
- - -
Installing Nix from source - -If no binary package is available, you can download and compile -a source distribution. - -
Prerequisites - - - - GNU Make. - - A version of GCC or Clang that supports C++11. - - Perl 5.8 or higher. - - pkg-config to locate - dependencies. If your distribution does not provide it, you can get - it from . - - 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 . - - The SQLite embedded database library, version 3.6.19 - or higher. If your distribution does not provide it, please install - it from . - - The Perl DBI and DBD::SQLite libraries, which are - available from CPAN if your - distribution does not provide them. - - The Boehm - garbage collector to reduce the evaluator’s memory - consumption (optional). To enable it, install - pkgconfig and the Boehm garbage collector, and - pass the flag to - configure. - - 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 and optionally the DocBook 5.0 RELAX NG - schemas. Note that these are only required if you modify the - manual sources or when you are building from the 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. For Flex, you need version 2.5.35, which is - available on SourceForge. - Slightly older versions may also work, but ancient versions like the - ubiquitous 2.5.4a won't. Note that these are only required if you - modify the parser or when you are building from the Git - repository. - - - -
- - -
Obtaining a source distribution - -The source tarball of the most recent stable release can be -downloaded from the Nix homepage. -You can also grab the most -recent development release. - -Alternatively, the most recent sources of Nix can be obtained -from its Git -repository. 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 of the -repository. - -
- - -
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 - 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 -. - -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 -. - -If you want to rebuild the documentation, pass the full path to -the DocBook RELAX NG schemas and to the DocBook XSL stylesheets using -the - -and - -options. - -
- - -
- - - - - -
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. - - -
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. - -
- - -
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. - -Multi-user mode has one important limitation: only -root can run nix-pull to register the availability -of pre-built binaries. However, those registrations are shared by all -users, so they still get the benefit from nix-pulls -done by root. - - -
Setting up the build users - -The build users are the special UIDs under -which builds are performed. They should all be members of the -build users group nixbld. -This group should have no other members. The build users should not -be members of any other group. On Linux, you can create the group and -users as follows: - - -$ groupadd -r nixbld -$ for n in $(seq 1 10); do useradd -c "Nix build user $n" \ - -d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \ - nixbld$n; done - - -This creates 10 build users. There can never be more concurrent builds -than the number of build users, so you may want to increase this if -you expect to do many builds at the same time. - -
- - -
Running the daemon - -The Nix daemon 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 to daemon. So you should put a -line like - - -export NIX_REMOTE=daemon - -into the users’ login scripts. - -
- - -
Restricting access - -To limit which users can perform Nix operations, you can use the -permissions on the directory -/nix/var/nix/daemon-socket. For instance, if you -want to restrict the use of Nix to the members of a group called -nix-users, do - - -$ chgrp nix-users /nix/var/nix/daemon-socket -$ chmod ug=rwx,o= /nix/var/nix/daemon-socket - - -This way, users who are not in the nix-users group -cannot connect to the Unix domain socket -/nix/var/nix/daemon-socket/socket, so they cannot -perform Nix operations. - -
- - -
- - -
- - -
Using Nix - -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 - -
- - - diff --git a/doc/manual/installation/building-source.xml b/doc/manual/installation/building-source.xml new file mode 100644 index 000000000..2202ec73f --- /dev/null +++ b/doc/manual/installation/building-source.xml @@ -0,0 +1,57 @@ +
+ +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 + 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 +. + +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 +. + +If you want to rebuild the documentation, pass the full path to +the DocBook RELAX NG schemas and to the DocBook XSL stylesheets using +the + +and + +options. + +
\ No newline at end of file diff --git a/doc/manual/installation/env-variables.xml b/doc/manual/installation/env-variables.xml new file mode 100644 index 000000000..fc39cdd9d --- /dev/null +++ b/doc/manual/installation/env-variables.xml @@ -0,0 +1,24 @@ + + +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 + + \ No newline at end of file diff --git a/doc/manual/installation/installation.xml b/doc/manual/installation/installation.xml new file mode 100644 index 000000000..878959352 --- /dev/null +++ b/doc/manual/installation/installation.xml @@ -0,0 +1,34 @@ + + +Installation + + +This section describes how to install and configure Nix for first-time use. + + + + + + + + + + + diff --git a/doc/manual/installation/installing-binary.xml b/doc/manual/installation/installing-binary.xml new file mode 100644 index 000000000..a5f9ac844 --- /dev/null +++ b/doc/manual/installation/installing-binary.xml @@ -0,0 +1,81 @@ + + +Installing a Binary Distribution + +The easiest way to install Nix is to run the following command: + + +$ bash <(curl https://nixos.org/nix/install) + + +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: + + +$ mkdir /nix +$ chown alice /nix + + + + +You can also manually download and install a binary package. +Binary packages of the latest stable release are available for Fedora, +Debian, Ubuntu, Mac OS X and various other systems from the Nix homepage. +You can also get builds of the latest development release from our +continuous +build system. + +For Fedora, RPM packages are available. These can be installed +or upgraded using rpm -U. For example, + + +$ rpm -U nix-1.7-1.i386.rpm + + + +For Debian and Ubuntu, you can download a Deb package and +install it like this: + + +$ dpkg -i nix_1.7-1_amd64.deb + + + +For other platforms, including Mac OS X (Darwin), FreeBSD and +other Linux distributions, you can download a binary tarball that +contains Nix and all its dependencies. (This is what the install +script at https://nixos.org/nix/install uses.) 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.7-x86_64-darwin.tar.bz2 +alice$ cd nix-1.7-x86_64-darwin +alice$ ./install + + + + +Nix can be uninstalled using rpm -e nix or +dpkg -r nix on RPM- and Dpkg-based systems, +respectively. After this you should manually remove the Nix store and +other auxiliary data, if desired: + + +$ rm -rf /nix + + + + \ No newline at end of file diff --git a/doc/manual/installation/installing-source.xml b/doc/manual/installation/installing-source.xml new file mode 100644 index 000000000..77beff1bc --- /dev/null +++ b/doc/manual/installation/installing-source.xml @@ -0,0 +1,17 @@ + + +Installing Nix from Source + +If no binary package is available, you can download and compile +a source distribution. + + + + + + + \ No newline at end of file diff --git a/doc/manual/installation/multi-user.xml b/doc/manual/installation/multi-user.xml new file mode 100644 index 000000000..2eb4c258f --- /dev/null +++ b/doc/manual/installation/multi-user.xml @@ -0,0 +1,106 @@ +
+ +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. + +Multi-user mode has one important limitation: only +root can run nix-pull to register the availability +of pre-built binaries. However, those registrations are shared by all +users, so they still get the benefit from nix-pulls +done by root. + + + + +Setting up the build users + +The build users are the special UIDs under +which builds are performed. They should all be members of the +build users group nixbld. +This group should have no other members. The build users should not +be members of any other group. On Linux, you can create the group and +users as follows: + + +$ groupadd -r nixbld +$ for n in $(seq 1 10); do useradd -c "Nix build user $n" \ + -d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \ + nixbld$n; done + + +This creates 10 build users. There can never be more concurrent builds +than the number of build users, so you may want to increase this if +you expect to do many builds at the same time. + + + + + + +Running the daemon + +The Nix daemon 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 to daemon. So you should put a +line like + + +export NIX_REMOTE=daemon + +into the users’ login scripts. + + + + + +Restricting access + +To limit which users can perform Nix operations, you can use the +permissions on the directory +/nix/var/nix/daemon-socket. For instance, if you +want to restrict the use of Nix to the members of a group called +nix-users, do + + +$ chgrp nix-users /nix/var/nix/daemon-socket +$ chmod ug=rwx,o= /nix/var/nix/daemon-socket + + +This way, users who are not in the nix-users group +cannot connect to the Unix domain socket +/nix/var/nix/daemon-socket/socket, so they cannot +perform Nix operations. + + + + +
\ No newline at end of file diff --git a/doc/manual/installation/nix-security.xml b/doc/manual/installation/nix-security.xml new file mode 100644 index 000000000..d888ff14d --- /dev/null +++ b/doc/manual/installation/nix-security.xml @@ -0,0 +1,27 @@ + + +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. + + + + + \ No newline at end of file diff --git a/doc/manual/installation/obtaining-source.xml b/doc/manual/installation/obtaining-source.xml new file mode 100644 index 000000000..968822cc0 --- /dev/null +++ b/doc/manual/installation/obtaining-source.xml @@ -0,0 +1,30 @@ +
+ +Obtaining a Source Distribution + +The source tarball of the most recent stable release can be +downloaded from the Nix homepage. +You can also grab the most +recent development release. + +Alternatively, the most recent sources of Nix can be obtained +from its Git +repository. 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 of the +repository. + +
\ No newline at end of file diff --git a/doc/manual/installation/prerequisites-source.xml b/doc/manual/installation/prerequisites-source.xml new file mode 100644 index 000000000..47adc9a4f --- /dev/null +++ b/doc/manual/installation/prerequisites-source.xml @@ -0,0 +1,73 @@ +
+ +Prerequisites + + + + GNU Make. + + A version of GCC or Clang that supports C++11. + + Perl 5.8 or higher. + + pkg-config to locate + dependencies. If your distribution does not provide it, you can get + it from . + + 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 . + + The SQLite embedded database library, version 3.6.19 + or higher. If your distribution does not provide it, please install + it from . + + The Perl DBI and DBD::SQLite libraries, which are + available from CPAN if your + distribution does not provide them. + + The Boehm + garbage collector to reduce the evaluator’s memory + consumption (optional). To enable it, install + pkgconfig and the Boehm garbage collector, and + pass the flag to + configure. + + 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 and optionally the DocBook 5.0 RELAX NG + schemas. Note that these are only required if you modify the + manual sources or when you are building from the 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. For Flex, you need version 2.5.35, which is + available on SourceForge. + Slightly older versions may also work, but ancient versions like the + ubiquitous 2.5.4a won't. Note that these are only required if you + modify the parser or when you are building from the Git + repository. + + + +
\ No newline at end of file diff --git a/doc/manual/installation/single-user.xml b/doc/manual/installation/single-user.xml new file mode 100644 index 000000000..09cdaa5d4 --- /dev/null +++ b/doc/manual/installation/single-user.xml @@ -0,0 +1,21 @@ +
+ +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. + +
\ No newline at end of file diff --git a/doc/manual/installation/supported-platforms.xml b/doc/manual/installation/supported-platforms.xml new file mode 100644 index 000000000..a31c6431f --- /dev/null +++ b/doc/manual/installation/supported-platforms.xml @@ -0,0 +1,38 @@ + + +Supported Platforms + +Nix is currently supported on the following platforms: + + + + Linux (particularly on x86, x86_64, and + PowerPC). + + Mac OS X. + + FreeBSD (only tested on Intel). + + + + + + + +Nix is pretty portable, so it should work on most other Unix +platforms as well. + + \ No newline at end of file diff --git a/doc/manual/introduction.xml b/doc/manual/introduction/about-nix.xml similarity index 91% rename from doc/manual/introduction.xml rename to doc/manual/introduction/about-nix.xml index e0300dc86..38dd7e665 100644 --- a/doc/manual/introduction.xml +++ b/doc/manual/introduction/about-nix.xml @@ -1,11 +1,10 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-about-nix"> -Introduction - - -
About Nix +About Nix Nix is a purely functional package manager. This means that it treats packages like values in purely functional @@ -251,23 +250,4 @@ xlink:href="http://nixos.org/">NixOS homepage. --> -
- - -
License - -Nix is free software; you can redistribute it and/or modify it -under the terms of the GNU Lesser General -Public License as published by the Free Software Foundation; -either version 2.1 of the License, or (at your option) any later -version. Nix is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Lesser General Public License for more details. - -
- - - + \ No newline at end of file diff --git a/doc/manual/introduction/introduction.xml b/doc/manual/introduction/introduction.xml new file mode 100644 index 000000000..f7f0b012d --- /dev/null +++ b/doc/manual/introduction/introduction.xml @@ -0,0 +1,16 @@ + + +Introduction + + +This section describes the main features of Nix and the license under which you can use Nix. + + + + + + diff --git a/doc/manual/introduction/nix-license.xml b/doc/manual/introduction/nix-license.xml new file mode 100644 index 000000000..af9cef70e --- /dev/null +++ b/doc/manual/introduction/nix-license.xml @@ -0,0 +1,20 @@ + + +License + +Nix is free software; you can redistribute it and/or modify it +under the terms of the GNU Lesser General +Public License as published by the Free Software Foundation; +either version 2.1 of the License, or (at your option) any later +version. Nix is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + + \ No newline at end of file diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index 6593d1398..8fae04f61 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -1,9 +1,12 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="NixManual"> - Nix User's Guide + Nix Package Manager Guide Version @@ -27,58 +30,30 @@ + +Preface +This manual describes how to set up and use Nix package manager and Nix expressions. + - - - - - - - - - - Command Reference - - - -
- Main commands - - - - -
- -
- Utilities - - - - - - - - - - -
- -
- Files - -
- - - - + + + + + + + + - + - - + + + diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml deleted file mode 100644 index e1d24b147..000000000 --- a/doc/manual/package-management.xml +++ /dev/null @@ -1,591 +0,0 @@ - - -Package Management - - -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 -. - - -
Basic package management - -The main command for package management is nix-env. You can use -it to install, upgrade, and erase packages, and to query what -packages are installed or are available for installation. - -In Nix, different users can have different “views” -on the set of installed applications. That is, there might be lots of -applications present on the system (possibly in many different -versions), but users can have a specific selection of those active — -where “active” just means that it appears in a directory -in the user’s PATH. Such a view on the set of -installed applications is called a user -environment, which is just a directory tree consisting of -symlinks to the files of the active applications. - -Components are installed from a set of Nix -expressions that tell Nix how to build those packages, -including, if necessary, their dependencies. There is a collection of -Nix expressions called the Nix Package collection that contains -packages ranging from basic development stuff such as GCC and Glibc, -to end-user applications like Mozilla Firefox. (Nix is however not -tied to the Nix Package collection; you could write your own Nix -expressions based on it, or completely new ones.) You can download -the latest version from . - -Assuming that you have downloaded and unpacked a release of Nix -Packages, you can view the set of available packages in the release: - - -$ nix-env -qaf nixpkgs-version '*' -ant-blackdown-1.4.2 -aterm-2.2 -bash-3.0 -binutils-2.15 -bison-1.875d -blackdown-1.4.2 -bzip2-1.0.2 -... - -where nixpkgs-version is -where you’ve unpacked the release. The flag -specifies a query operation; means that you want -to show the “available” (i.e., installable) packages, as opposed to -the installed packages; and -nixpkgs-version -specifies the source of the packages. The argument -'*' shows all installable packages. (The quotes are -necessary to prevent shell expansion.) You can also select specific -packages by name: - - -$ nix-env -qaf nixpkgs-version gcc -gcc-3.4.6 -gcc-4.0.3 -gcc-4.1.1 - - - -It is also possible to see the status of -available packages, i.e., whether they are installed into the user -environment and/or present in the system: - - -$ nix-env -qasf nixpkgs-version '*' -... --PS bash-3.0 ---S binutils-2.15 -IPS bison-1.875d -... - -The first character (I) indicates whether the -package is installed in your current user environment. The second -(P) indicates whether it is present on your system -(in which case installing it into your user environment would be a -very quick operation). The last one (S) indicates -whether there is a so-called substitute for the -package, which is Nix’s mechanism for doing binary deployment. It -just means that Nix knows that it can fetch a pre-built package from -somewhere (typically a network server) instead of building it -locally. - -So now that we have a set of Nix expressions we can build the -packages contained in them. This is done using nix-env --i. For instance, - - -$ nix-env -f nixpkgs-version -i subversion - -will install the package called subversion (which -is, of course, the Subversion version -management system). - -When you do this for the first time, Nix will start building -Subversion and all its dependencies. This will take quite a while — -typically an hour or two on modern machines. Fortunately, there is a -faster way (so do a Ctrl-C on that install operation!): you just need -to tell Nix that pre-built binaries of all those packages are -available somewhere. This is done using the -nix-pull command, which must be supplied with a URL -containing a manifest describing what binaries -are available. This URL should correspond to the Nix Packages release -that you’re using. For instance, if you obtained a release from , then you should do: - - -$ nix-pull http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x/MANIFEST - -If you then issue the installation command, it should start -downloading binaries from nixos.org, instead of building -them from source. This might still take a while since all -dependencies must be downloaded, but on a reasonably fast connection -such as a DSL line it’s on the order of a few minutes. - -Naturally, packages can also be uninstalled: - - -$ nix-env -e subversion - - - -Upgrading to a new version is just as easy. If you have a new -release of Nix Packages, you can do: - - -$ nix-env -f nixpkgs-version -u subversion - -This will only upgrade Subversion if there is a -“newer” version in the new set of Nix expressions, as -defined by some pretty arbitrary rules regarding ordering of version -numbers (which generally do what you’d expect of them). To just -unconditionally replace Subversion with whatever version is in the Nix -expressions, use -i instead of --u; -i will remove -whatever version is already installed. - -You can also upgrade all packages for which there are newer -versions: - - -$ nix-env -f nixpkgs-version -u '*' - - - -Sometimes it’s useful to be able to ask what -nix-env would do, without actually doing it. For -instance, to find out what packages would be upgraded by -nix-env -u '*', you can do - - -$ nix-env ... -u '*' --dry-run -(dry run; not doing anything) -upgrading `libxslt-1.1.0' to `libxslt-1.1.10' -upgrading `graphviz-1.10' to `graphviz-1.12' -upgrading `coreutils-5.0' to `coreutils-5.2.1' - - - -
- - -
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 -hashes160-bit truncations of SHA-256 hashes encoded in -a base-32 notation, to be precise. 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. shows a part of a typical Nix -store. - -
User environments - - - - - -
- -Of course, you wouldn’t want to type - - -$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn - -every time you want to run Subversion. Of course we could set up the -PATH environment variable to include the -bin directory of every package we want to use, -but this is not very convenient since changing PATH -doesn’t take effect for already existing processes. The solution Nix -uses is to create directory trees of symlinks to -activated packages. These are called -user environments and they are packages -themselves (though automatically generated by -nix-env), so they too reside in the Nix store. For -instance, in 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 mozilla - -on a set of Nix expressions that contained Mozilla and a new version -of Subversion. - -Generations are grouped together into -profiles so that different users don’t interfere -with each other if they don’t want to. For example: - - -$ ls -l /nix/var/nix/profiles/ -... -lrwxrwxrwx 1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env -lrwxrwxrwx 1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env -lrwxrwxrwx 1 eelco ... default -> default-43-link - -This shows a profile called default. The file -default itself is actually a symlink that points -to the current generation. When we do a nix-env -operation, a new user environment and generation link are created -based on the current one, and finally the default -symlink is made to point at the new generation. This last step is -atomic on Unix, which explains how we can do atomic upgrades. (Note -that the building/installing of new packages doesn’t interfere in -any way with old packages, since they are stored in different -locations in the Nix store.) - -If you find that you want to undo a nix-env -operation, you can just do - - -$ nix-env --rollback - -which will just make the current generation link point at the previous -link. E.g., default would be made to point at -default-42-link. You can also switch to a -specific generation: - - -$ nix-env --switch-generation 43 - -which in this example would roll forward to generation 43 again. You -can also see all available generations: - - -$ nix-env --list-generations - -Actually, there is another level of indirection not shown in the -figure above. You generally wouldn’t have -/nix/var/nix/profiles/some-profile/bin -in your PATH. Rather, there is a symlink -~/.nix-profile that points to your current -profile. This means that you should put -~/.nix-profile/bin in your PATH -(and indeed, that’s what the initialisation script -/nix/etc/profile.d/nix.sh does). This makes it -easier to switch to a different profile. You can do that using the -command nix-env --switch-profile: - - -$ nix-env --switch-profile /nix/var/nix/profiles/my-profile - -$ nix-env --switch-profile /nix/var/nix/profiles/default - -These commands switch to the my-profile and -default profile, respectively. If the profile doesn’t exist, it will -be created automatically. You should be careful about storing a -profile in another location than the profiles -directory, since otherwise it might not be used as a root of the -garbage collector (see ). - -All nix-env operations work on the profile -pointed to by ~/.nix-profile, but you can override -this using the option (abbreviation -): - - -$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion - -This will not change the -~/.nix-profile symlink. - -
- - -
Garbage collection - -nix-env operations such as upgrades -() and uninstall () never -actually delete packages from the system. All they do (as shown -above) is to create a new user environment that no longer contains -symlinks to the “deleted” packages. - -Of course, since disk space is not infinite, unused packages -should be removed at some point. You can do this by running the Nix -garbage collector. It will remove from the Nix store any package -not used (directly or indirectly) by any generation of any -profile. - -Note however that as long as old generations reference a -package, it will not be deleted. After all, we wouldn’t be able to -do a rollback otherwise. So in order for garbage collection to be -effective, you should also delete (some) old generations. Of course, -this should only be done if you are certain that you will not need to -roll back. - -To delete all old (non-current) generations of your current -profile: - - -$ nix-env --delete-generations old - -Instead of old you can also specify a list of -generations, e.g., - - -$ nix-env --delete-generations 10 11 14 - - - -After removing appropriate old generations you can run the -garbage collector as follows: - - -$ nix-store --gc - -If you are feeling uncertain, you can also first view what files would -be deleted: - - -$ nix-store --gc --print-dead - -Likewise, the option will show the paths -that won’t be deleted. - -There is also a convenient little utility -nix-collect-garbage, which when invoked with the - () 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. - - - - -
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. - -
- -
- - -
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, use nix-pull to register -pre-built binaries (if available), and upgrade using -nix-env. Fortunately, there’s a better way: -Nix channels. - -A Nix channel is just a URL that points to a place that contains -a set of Nix expressions and a manifest. Using the command nix-channel you -can automatically stay up to date with whatever is available at that -URL. - -You can “subscribe” to a channel using -nix-channel --add, e.g., - - -$ nix-channel --add http://nixos.org/channels/nixpkgs-unstable - -subscribes you to a channel that always contains that latest version -of the Nix Packages collection. (Instead of -nixpkgs-unstable you could also subscribe to -nixpkgs-stable, which should have a higher level of -stability, but right now is just outdated.) Subscribing really just -means that the URL is added to the file -~/.nix-channels. Right now there is no command -to “unsubscribe”; you should just edit that file manually -and delete the offending URL. - -To obtain the latest Nix expressions available in a channel, do - - -$ nix-channel --update - -This downloads the Nix expressions in every channel (downloaded from -url/nixexprs.tar.bz2) -and registers any available pre-built binaries in every channel -(by nix-pulling -url/MANIFEST). It also -makes the union of each channel’s Nix expressions the default for -nix-env operations. Consequently, you can then say - - -$ nix-env -u '*' - -to upgrade all packages in your profile to the latest versions -available in the subscribed channels. - -
- - -
One-click installs - -Often, when you want to install a specific package (e.g., from -the Nix -Packages collection), subscribing to a channel is a bit -cumbersome. And channels don’t help you at all if you want to install -an older version of a package than the one provided by the current -contents of the channel, or a package that has been removed from the -channel. That’s when one-click installs come in -handy: you can just go to the web page that contains the package, -click on it, and it will be installed with all the necessary -dependencies. - -For instance, you can go to and click on any link for the individual packages for your -platform. The first time you do this, your browser will ask what to -do with application/nix-package files. You should -open them with /nix/bin/nix-install-package. -This will open a window that asks you to confirm that you want to -install the package. When you answer Y, the -package and all its dependencies will be installed. This is a binary -deployment mechanism — you get packages pre-compiled for the selected -platform type. - -You can also install application/nix-package -files from the command line directly. See for details. - -
- - -
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. - -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 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" - -But note that nix-copy-closure is generally more -efficient in this example because it only copies paths that are not -already present in the target Nix store. - -Finally, if you can mount the Nix store of a remote machine in -your local filesystem, Nix can copy paths from the remote Nix store to -the local Nix store on demand. For instance, -suppose that you mount a remote machine containing a Nix store via -sshfs: - - -$ sshfs alice@itchy.example.org:/ /mnt - -You should then set the NIX_OTHER_STORES environment -variable to tell Nix about this remote Nix store: - - -$ export NIX_OTHER_STORES=/mnt/nix - -Then if you do any Nix operation, e.g. - - -$ nix-env -i firefox - -and Nix has to build a path that it sees is already present in -/mnt/nix, then it will just copy from there -instead of building it from source. - - -
- - - diff --git a/doc/manual/packages/basic-package-mgmt.xml b/doc/manual/packages/basic-package-mgmt.xml new file mode 100644 index 000000000..69c955c1d --- /dev/null +++ b/doc/manual/packages/basic-package-mgmt.xml @@ -0,0 +1,170 @@ + + +Basic Package Management + +The main command for package management is nix-env. You can use +it to install, upgrade, and erase packages, and to query what +packages are installed or are available for installation. + +In Nix, different users can have different “views” +on the set of installed applications. That is, there might be lots of +applications present on the system (possibly in many different +versions), but users can have a specific selection of those active — +where “active” just means that it appears in a directory +in the user’s PATH. Such a view on the set of +installed applications is called a user +environment, which is just a directory tree consisting of +symlinks to the files of the active applications. + +Components are installed from a set of Nix +expressions that tell Nix how to build those packages, +including, if necessary, their dependencies. There is a collection of +Nix expressions called the Nix Package collection that contains +packages ranging from basic development stuff such as GCC and Glibc, +to end-user applications like Mozilla Firefox. (Nix is however not +tied to the Nix Package collection; you could write your own Nix +expressions based on it, or completely new ones.) You can download +the latest version from . + +Assuming that you have downloaded and unpacked a release of Nix +Packages, you can view the set of available packages in the release: + + +$ nix-env -qaf nixpkgs-version '*' +ant-blackdown-1.4.2 +aterm-2.2 +bash-3.0 +binutils-2.15 +bison-1.875d +blackdown-1.4.2 +bzip2-1.0.2 +... + +where nixpkgs-version is +where you’ve unpacked the release. The flag +specifies a query operation; means that you want +to show the “available” (i.e., installable) packages, as opposed to +the installed packages; and +nixpkgs-version +specifies the source of the packages. The argument +'*' shows all installable packages. (The quotes are +necessary to prevent shell expansion.) You can also select specific +packages by name: + + +$ nix-env -qaf nixpkgs-version gcc +gcc-3.4.6 +gcc-4.0.3 +gcc-4.1.1 + + + +It is also possible to see the status of +available packages, i.e., whether they are installed into the user +environment and/or present in the system: + + +$ nix-env -qasf nixpkgs-version '*' +... +-PS bash-3.0 +--S binutils-2.15 +IPS bison-1.875d +... + +The first character (I) indicates whether the +package is installed in your current user environment. The second +(P) indicates whether it is present on your system +(in which case installing it into your user environment would be a +very quick operation). The last one (S) indicates +whether there is a so-called substitute for the +package, which is Nix’s mechanism for doing binary deployment. It +just means that Nix knows that it can fetch a pre-built package from +somewhere (typically a network server) instead of building it +locally. + +So now that we have a set of Nix expressions we can build the +packages contained in them. This is done using nix-env +-i. For instance, + + +$ nix-env -f nixpkgs-version -i subversion + +will install the package called subversion (which +is, of course, the Subversion version +management system). + +When you do this for the first time, Nix will start building +Subversion and all its dependencies. This will take quite a while — +typically an hour or two on modern machines. Fortunately, there is a +faster way (so do a Ctrl-C on that install operation!): you just need +to tell Nix that pre-built binaries of all those packages are +available somewhere. This is done using the +nix-pull command, which must be supplied with a URL +containing a manifest describing what binaries +are available. This URL should correspond to the Nix Packages release +that you’re using. For instance, if you obtained a release from , then you should do: + + +$ nix-pull http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x/MANIFEST + +If you then issue the installation command, it should start +downloading binaries from nixos.org, instead of building +them from source. This might still take a while since all +dependencies must be downloaded, but on a reasonably fast connection +such as a DSL line it’s on the order of a few minutes. + +Naturally, packages can also be uninstalled: + + +$ nix-env -e subversion + + + +Upgrading to a new version is just as easy. If you have a new +release of Nix Packages, you can do: + + +$ nix-env -f nixpkgs-version -u subversion + +This will only upgrade Subversion if there is a +“newer” version in the new set of Nix expressions, as +defined by some pretty arbitrary rules regarding ordering of version +numbers (which generally do what you’d expect of them). To just +unconditionally replace Subversion with whatever version is in the Nix +expressions, use -i instead of +-u; -i will remove +whatever version is already installed. + +You can also upgrade all packages for which there are newer +versions: + + +$ nix-env -f nixpkgs-version -u '*' + + + +Sometimes it’s useful to be able to ask what +nix-env would do, without actually doing it. For +instance, to find out what packages would be upgraded by +nix-env -u '*', you can do + + +$ nix-env ... -u '*' --dry-run +(dry run; not doing anything) +upgrading `libxslt-1.1.0' to `libxslt-1.1.10' +upgrading `graphviz-1.10' to `graphviz-1.12' +upgrading `coreutils-5.0' to `coreutils-5.2.1' + + + + \ No newline at end of file diff --git a/doc/manual/packages/channels.xml b/doc/manual/packages/channels.xml new file mode 100644 index 000000000..094e11fe3 --- /dev/null +++ b/doc/manual/packages/channels.xml @@ -0,0 +1,57 @@ + + +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, use nix-pull to register +pre-built binaries (if available), and upgrade using +nix-env. Fortunately, there’s a better way: +Nix channels. + +A Nix channel is just a URL that points to a place that contains +a set of Nix expressions and a manifest. Using the command nix-channel you +can automatically stay up to date with whatever is available at that +URL. + +You can “subscribe” to a channel using +nix-channel --add, e.g., + + +$ nix-channel --add http://nixos.org/channels/nixpkgs-unstable + +subscribes you to a channel that always contains that latest version +of the Nix Packages collection. (Instead of +nixpkgs-unstable you could also subscribe to +nixpkgs-stable, which should have a higher level of +stability, but right now is just outdated.) Subscribing really just +means that the URL is added to the file +~/.nix-channels. Right now there is no command +to “unsubscribe”; you should just edit that file manually +and delete the offending URL. + +To obtain the latest Nix expressions available in a channel, do + + +$ nix-channel --update + +This downloads the Nix expressions in every channel (downloaded from +url/nixexprs.tar.bz2) +and registers any available pre-built binaries in every channel +(by nix-pulling +url/MANIFEST). It also +makes the union of each channel’s Nix expressions the default for +nix-env operations. Consequently, you can then say + + +$ nix-env -u '*' + +to upgrade all packages in your profile to the latest versions +available in the subscribed channels. + + \ No newline at end of file diff --git a/doc/manual/packages/garbage-collection.xml b/doc/manual/packages/garbage-collection.xml new file mode 100644 index 000000000..ae28c485f --- /dev/null +++ b/doc/manual/packages/garbage-collection.xml @@ -0,0 +1,70 @@ + + +Garbage Collection + +nix-env operations such as upgrades +() and uninstall () never +actually delete packages from the system. All they do (as shown +above) is to create a new user environment that no longer contains +symlinks to the “deleted” packages. + +Of course, since disk space is not infinite, unused packages +should be removed at some point. You can do this by running the Nix +garbage collector. It will remove from the Nix store any package +not used (directly or indirectly) by any generation of any +profile. + +Note however that as long as old generations reference a +package, it will not be deleted. After all, we wouldn’t be able to +do a rollback otherwise. So in order for garbage collection to be +effective, you should also delete (some) old generations. Of course, +this should only be done if you are certain that you will not need to +roll back. + +To delete all old (non-current) generations of your current +profile: + + +$ nix-env --delete-generations old + +Instead of old you can also specify a list of +generations, e.g., + + +$ nix-env --delete-generations 10 11 14 + + + +After removing appropriate old generations you can run the +garbage collector as follows: + + +$ nix-store --gc + +If you are feeling uncertain, you can also first view what files would +be deleted: + + +$ nix-store --gc --print-dead + +Likewise, the option will show the paths +that won’t be deleted. + +There is also a convenient little utility +nix-collect-garbage, which when invoked with the + () 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. + + + + \ No newline at end of file diff --git a/doc/manual/packages/garbage-collector-roots.xml b/doc/manual/packages/garbage-collector-roots.xml new file mode 100644 index 000000000..8338e5392 --- /dev/null +++ b/doc/manual/packages/garbage-collector-roots.xml @@ -0,0 +1,29 @@ +
+ +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. + +
\ No newline at end of file diff --git a/doc/manual/packages/one-click.xml b/doc/manual/packages/one-click.xml new file mode 100644 index 000000000..cef9a2bbf --- /dev/null +++ b/doc/manual/packages/one-click.xml @@ -0,0 +1,37 @@ + + +One-Click Installation + +Often, when you want to install a specific package (e.g., from +the Nix +Packages collection), subscribing to a channel is a bit +cumbersome. And channels don’t help you at all if you want to install +an older version of a package than the one provided by the current +contents of the channel, or a package that has been removed from the +channel. That’s when one-click installs come in +handy: you can just go to the web page that contains the package, +click on it, and it will be installed with all the necessary +dependencies. + +For instance, you can go to and click on any link for the individual packages for your +platform. The first time you do this, your browser will ask what to +do with application/nix-package files. You should +open them with /nix/bin/nix-install-package. +This will open a window that asks you to confirm that you want to +install the package. When you answer Y, the +package and all its dependencies will be installed. This is a binary +deployment mechanism — you get packages pre-compiled for the selected +platform type. + +You can also install application/nix-package +files from the command line directly. See for details. + + \ No newline at end of file diff --git a/doc/manual/packages/package-management.xml b/doc/manual/packages/package-management.xml new file mode 100644 index 000000000..5cc5c381b --- /dev/null +++ b/doc/manual/packages/package-management.xml @@ -0,0 +1,24 @@ + + +Package Management + + +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 +. + + + + + + + + + + diff --git a/doc/manual/packages/profiles.xml b/doc/manual/packages/profiles.xml new file mode 100644 index 000000000..ad5e92aeb --- /dev/null +++ b/doc/manual/packages/profiles.xml @@ -0,0 +1,159 @@ + + +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 +hashes160-bit truncations of SHA-256 hashes encoded in +a base-32 notation, to be precise. 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. shows a part of a typical Nix +store. + +
User environments + + + + + +
+ +Of course, you wouldn’t want to type + + +$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn + +every time you want to run Subversion. Of course we could set up the +PATH environment variable to include the +bin directory of every package we want to use, +but this is not very convenient since changing PATH +doesn’t take effect for already existing processes. The solution Nix +uses is to create directory trees of symlinks to +activated packages. These are called +user environments and they are packages +themselves (though automatically generated by +nix-env), so they too reside in the Nix store. For +instance, in 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 mozilla + +on a set of Nix expressions that contained Mozilla and a new version +of Subversion. + +Generations are grouped together into +profiles so that different users don’t interfere +with each other if they don’t want to. For example: + + +$ ls -l /nix/var/nix/profiles/ +... +lrwxrwxrwx 1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env +lrwxrwxrwx 1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env +lrwxrwxrwx 1 eelco ... default -> default-43-link + +This shows a profile called default. The file +default itself is actually a symlink that points +to the current generation. When we do a nix-env +operation, a new user environment and generation link are created +based on the current one, and finally the default +symlink is made to point at the new generation. This last step is +atomic on Unix, which explains how we can do atomic upgrades. (Note +that the building/installing of new packages doesn’t interfere in +any way with old packages, since they are stored in different +locations in the Nix store.) + +If you find that you want to undo a nix-env +operation, you can just do + + +$ nix-env --rollback + +which will just make the current generation link point at the previous +link. E.g., default would be made to point at +default-42-link. You can also switch to a +specific generation: + + +$ nix-env --switch-generation 43 + +which in this example would roll forward to generation 43 again. You +can also see all available generations: + + +$ nix-env --list-generations + +Actually, there is another level of indirection not shown in the +figure above. You generally wouldn’t have +/nix/var/nix/profiles/some-profile/bin +in your PATH. Rather, there is a symlink +~/.nix-profile that points to your current +profile. This means that you should put +~/.nix-profile/bin in your PATH +(and indeed, that’s what the initialisation script +/nix/etc/profile.d/nix.sh does). This makes it +easier to switch to a different profile. You can do that using the +command nix-env --switch-profile: + + +$ nix-env --switch-profile /nix/var/nix/profiles/my-profile + +$ nix-env --switch-profile /nix/var/nix/profiles/default + +These commands switch to the my-profile and +default profile, respectively. If the profile doesn’t exist, it will +be created automatically. You should be careful about storing a +profile in another location than the profiles +directory, since otherwise it might not be used as a root of the +garbage collector (see ). + +All nix-env operations work on the profile +pointed to by ~/.nix-profile, but you can override +this using the option (abbreviation +): + + +$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion + +This will not change the +~/.nix-profile symlink. + + \ No newline at end of file diff --git a/doc/manual/packages/sharing-packages.xml b/doc/manual/packages/sharing-packages.xml new file mode 100644 index 000000000..573b7c1e7 --- /dev/null +++ b/doc/manual/packages/sharing-packages.xml @@ -0,0 +1,82 @@ + + +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. + +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 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" + +But note that nix-copy-closure is generally more +efficient in this example because it only copies paths that are not +already present in the target Nix store. + +Finally, if you can mount the Nix store of a remote machine in +your local filesystem, Nix can copy paths from the remote Nix store to +the local Nix store on demand. For instance, +suppose that you mount a remote machine containing a Nix store via +sshfs: + + +$ sshfs alice@itchy.example.org:/ /mnt + +You should then set the NIX_OTHER_STORES environment +variable to tell Nix about this remote Nix store: + + +$ export NIX_OTHER_STORES=/mnt/nix + +Then if you do any Nix operation, e.g. + + +$ nix-env -i firefox + +and Nix has to build a path that it sees is already present in +/mnt/nix, then it will just copy from there +instead of building it from source. + + + \ No newline at end of file diff --git a/doc/manual/quick-start.xml b/doc/manual/quick-start/getting-started.xml similarity index 63% rename from doc/manual/quick-start.xml rename to doc/manual/quick-start/getting-started.xml index 170799063..a6b1f47b6 100644 --- a/doc/manual/quick-start.xml +++ b/doc/manual/quick-start/getting-started.xml @@ -1,17 +1,15 @@ + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-getting-started-nix"> -Quick Start +Getting Started with Nix +This tutorial takes you through the basic tasks you might perform when you start using Nix. + -This chapter is for impatient people who don't like reading -documentation. For more in-depth information you are kindly referred -to the following chapters. - - - -Install Nix by running the following: +Install Nix by running the following: $ bash <(curl https://nixos.org/nix/install) @@ -20,9 +18,9 @@ $ bash <(curl https://nixos.org/nix/install) This will install Nix in /nix. The install script will create /nix using sudo, so make sure you have sufficient rights. (For other installation -methods, see .) +methods, see .) -See what installable packages are currently available +See what installable packages are currently available in the channel: @@ -33,17 +31,17 @@ hello-2.1.1 libxslt-1.1.0 ... - + -Install some packages from the channel: +Install some packages from the channel: $ nix-env -i hello ... This should download pre-built packages; it should not build them -locally (if it does, something went wrong). +locally (if it does, something went wrong). -Test that they work: +Test that they work: $ which hello @@ -52,16 +50,16 @@ $ hello Hello, world! - + -Uninstall a package: +Uninstall a package: $ nix-env -e hello - + -To keep up-to-date with the channel, do: +To keep up-to-date with the channel, do: $ nix-channel --update nixpkgs @@ -69,9 +67,9 @@ $ nix-env -u '*' The latter command will upgrade each installed package for which there is a “newer” version (as determined by comparing the version -numbers). +numbers). -You can also install specific packages directly from +You can also install specific packages directly from your web browser. For instance, you can go to and click on any link for the individual packages for your @@ -79,18 +77,18 @@ platform. Associate application/nix-package with the program nix-install-package. A window should appear asking you whether it’s okay to install the package. Say Y. The package and all its dependencies will be -installed. +installed. -If you're unhappy with the result of a +If you're unhappy with the result of a nix-env action (e.g., an upgraded package turned out not to work properly), you can go back: $ nix-env --rollback - + -You should periodically run the Nix garbage collector +You should periodically run the Nix garbage collector to get rid of unused packages, since uninstalls or upgrades don't actually delete them: @@ -103,8 +101,8 @@ rollbacks impossible, but also making the packages in those old generations available for garbage collection), while the second command actually deletes them.--> - + - + - + \ No newline at end of file diff --git a/doc/manual/quick-start/quick-start.xml b/doc/manual/quick-start/quick-start.xml new file mode 100644 index 000000000..b4757cb22 --- /dev/null +++ b/doc/manual/quick-start/quick-start.xml @@ -0,0 +1,17 @@ + + +Quick-Start + + +This section is for impatient people who don't like reading +documentation. For more in-depth information you are kindly referred +to subsequent chapters. + + + + + diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml deleted file mode 100644 index 426078b82..000000000 --- a/doc/manual/release-notes.xml +++ /dev/null @@ -1,2521 +0,0 @@ -
- -Nix Release Notes - - - - -
Release 1.8 (TBA) - -TODO - -
- - - - -
Release 1.7 (April 11, 2014) - -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. - - - - 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, - , 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 - and - have been renamed to and - , respectively. - - - - nix-instantiate, - nix-build and nix-shell now - have a flag (or ) 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, (or - ), 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 setting; - otherwise, it will bind-mount the /dev from - outside the chroot. - - Similarly, if you don’t have /dev/pts listed - in , 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 - 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 flag now allows attribute names with - dots in them, e.g. - - -$ nix-instantiate --eval '<nixos>' -A 'config.systemd.units."nscd.service".text' - - - - - - - The 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 - - Nd, which deletes - all user environment generations older than - N days. Likewise, nix-env - --delete-generations accepts a - Nd 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. - -
- - - - -
Release 1.6.1 (October 28, 2013) - -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. - - - - -
- - - - -
Release 1.6 (September 10, 2013) - -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 - 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 - () to remove all - previous packages from the profile. This makes it easier to do - declarative package management similar to NixOS’s - . 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 - . - - - - -This release has contributions from Domen Kožar, Eelco Dolstra, -Florian Friesdorf, Gergely Risko, Ivan Kozik, Ludovic Courtès and Shea -Levy. - -
- - - - -
Release 1.5.3 (June 17, 2013) - -This is primarily a bug fix release. The following changes are -noteworthy: - - - - - Yet another security bug involving hard links to files - outside the store was fixed. This bug only affected multi-user - installations that do not have hard link restrictions - enabled. (NixOS is thus not vulnerable.) - - - - The default binary cache URL has changed from - http://nixos.org/binary-cache to - http://cache.nixos.org. The latter is hosted on Amazon - CloudFront (courtesy of LogicBlox) and - should provide better performance for users in both Europe and - North America. - - - - The binary cache substituter now prints a warning message if - fetching information from the cache takes more than five seconds. - Thus network or server problems no longer make Nix appear to just - hang. - - - - Stack traces now show function names, e.g. - -while evaluating `concatMapStrings' at `.../nixpkgs/pkgs/lib/strings.nix:18:25': - - Also, if a function is called with an unexpected argument, Nix - now shows the name of the argument. - - - - - -
- - - - -
Release 1.5.2 (May 13, 2013) - -This is primarily a bug fix release. It has contributions from -Eelco Dolstra, Lluís Batlle i Rossell and Shea Levy. - -
- - - - -
Release 1.5.1 (February 28, 2013) - -The bug fix to the bug fix had a bug itself, of course. But -this time it will work for sure! - -
- - - - -
Release 1.5 (February 27, 2013) - -This is a brown paper bag release to fix a regression introduced -by the hard link security fix in 1.4. - -
- - - - -
Release 1.4 (February 26, 2013) - -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). - -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. - - - -
- - - - -
Release 1.3 (January 4, 2013) - -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. - -
- - - - -
Release 1.2 (December 6, 2012) - -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 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. - - - - 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 - 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 () 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 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. - -
- - - - -
Release 1.1 (July 18, 2012) - -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 flag in - nix-env -qa is now much faster. - - - - -
- - - - -
Release 1.0 (May 11, 2012) - -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 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 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 (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 (). - - - - -
- - - - -
Release 0.16 (August 17, 2010) - -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. 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 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 flag. - - - - Several bug fixes. - - - - -
- - - - -
Release 0.15 (March 17, 2010) - -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. - -
- - - - -
Release 0.14 (February 4, 2010) - -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 and - garbage collector options. They were - not very useful in practice. - - - - On Windows, Nix now requires Cygwin 1.7.x. - - - - A few bug fixes. - - - - -
- - - - -
Release 0.13 (November 5, -2009) - -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 - 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. - - - - -
- - - - -
Release 0.12 (November 20, -2008) - - - - - 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 - . - - 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 - and 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 - tells the - collector to stop after at least N bytes - have been deleted. The option 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 - causes store paths to be deleted in order of ascending last access - time. This allows non-recently used stuff to be deleted. The - option - 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 is now - supported by nix-store -r and - nix-build. - - The information previously shown by - (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. - - - -
- - - - -
Release 0.11 (December 31, -2007) - -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 - 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 - () 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 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 (in - nix-env, nix-instantiate and - nix-build) is like , except - that the value is a string. For example, --argstr system - i686-linux is equivalent to --arg system - \"i686-linux\" (note that - prevents annoying quoting around shell arguments). - - - nix-store has a new operation - () - 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 - (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. - - - - -
- - - - - -
Release 0.10.1 (October 11, 2006) - -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. - -
- - - - - -
Release 0.10 (October 6, 2006) - -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. - -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 - (or ) 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 , 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 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 / 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 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 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 to delete specific paths - from the Nix store. It won’t delete reachable (non-garbage) - paths unless 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. 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. - - - -
- - - - - -
Release 0.9.2 (September 21, 2005) - -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). - - - - - -
- - - - - -
Release 0.9.1 (September 20, 2005) - -This bug fix release addresses a problem with the ATerm library -when the flag in -configure was not used. - -
- - - - - -
Release 0.9 (September 16, 2005) - -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. - - - -
- - - - - -
Release 0.8.1 (April 13, 2005) - -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. - - - -
- - - - - -
Release 0.8 (April 11, 2005) - -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 now 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., ). - -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., . - 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 - and - . - - 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 - 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 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 - and - . - - fetchurl allows SHA-1 and SHA-256 - in addition to MD5. Just specify the attribute - sha1 or sha256 instead of - md5. - - Manual updates. - - - - - -
- - - - - -
Release 0.7 (January 12, 2005) - - - - 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. - - - -
- - - - - -
Release 0.6 (November 14, 2004) - - - - - Rewrite of the normalisation engine. - - - - Multiple builds can now be performed in parallel - (option ). - - 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 allows - recovery from broken substitutes. - - Option 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 - ). - - by default now - uninstall previous derivations with the same - name. - - allows upgrading to a - specific version. - - New operation - 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 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. - - - -
- - - - - -
Release 0.5 and earlier - -Please refer to the Subversion commit log messages. - -
- - - -
diff --git a/doc/manual/release-notes/release-notes.xml b/doc/manual/release-notes/release-notes.xml new file mode 100644 index 000000000..c9bb2e189 --- /dev/null +++ b/doc/manual/release-notes/release-notes.xml @@ -0,0 +1,43 @@ + + +Nix Release Notes + + +This section lists the release notes for each stable version of Nix. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/manual/release-notes/rl-010.xml b/doc/manual/release-notes/rl-010.xml new file mode 100644 index 000000000..fb55bd24f --- /dev/null +++ b/doc/manual/release-notes/rl-010.xml @@ -0,0 +1,323 @@ + + +Release 0.10 (October 6, 2006) + +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. + +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 + (or ) 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 , 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 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 / 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 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 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 to delete specific paths + from the Nix store. It won’t delete reachable (non-garbage) + paths unless 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. 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. + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-0101.xml b/doc/manual/release-notes/rl-0101.xml new file mode 100644 index 000000000..884b1b8db --- /dev/null +++ b/doc/manual/release-notes/rl-0101.xml @@ -0,0 +1,13 @@ + + +Release 0.10.1 (October 11, 2006) + +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. + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-011.xml b/doc/manual/release-notes/rl-011.xml new file mode 100644 index 000000000..40f83bbc7 --- /dev/null +++ b/doc/manual/release-notes/rl-011.xml @@ -0,0 +1,261 @@ + + +Release 0.11 (December 31, 2007) + +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 + 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 + () 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 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 (in + nix-env, nix-instantiate and + nix-build) is like , except + that the value is a string. For example, --argstr system + i686-linux is equivalent to --arg system + \"i686-linux\" (note that + prevents annoying quoting around shell arguments). + + + nix-store has a new operation + () + 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 + (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. + + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-012.xml b/doc/manual/release-notes/rl-012.xml new file mode 100644 index 000000000..173ed79ff --- /dev/null +++ b/doc/manual/release-notes/rl-012.xml @@ -0,0 +1,175 @@ + + +Release 0.12 (November 20, 2008) + + + + + 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 + . + + 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 + and 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 + tells the + collector to stop after at least N bytes + have been deleted. The option 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 + causes store paths to be deleted in order of ascending last access + time. This allows non-recently used stuff to be deleted. The + option + 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 is now + supported by nix-store -r and + nix-build. + + The information previously shown by + (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. + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-013.xml b/doc/manual/release-notes/rl-013.xml new file mode 100644 index 000000000..c116e42f5 --- /dev/null +++ b/doc/manual/release-notes/rl-013.xml @@ -0,0 +1,106 @@ + + +Release 0.13 (November 5, 2009) + +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 + 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. + + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-014.xml b/doc/manual/release-notes/rl-014.xml new file mode 100644 index 000000000..456be8b80 --- /dev/null +++ b/doc/manual/release-notes/rl-014.xml @@ -0,0 +1,44 @@ +Release 0.14 (February 4, 2010) + +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 and + garbage collector options. They were + not very useful in practice. + + + + On Windows, Nix now requires Cygwin 1.7.x. + + + + A few bug fixes. + + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-015.xml b/doc/manual/release-notes/rl-015.xml new file mode 100644 index 000000000..ae6e12ada --- /dev/null +++ b/doc/manual/release-notes/rl-015.xml @@ -0,0 +1,14 @@ + + +Release 0.15 (March 17, 2010) + +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. + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-016.xml b/doc/manual/release-notes/rl-016.xml new file mode 100644 index 000000000..49ac2ce8c --- /dev/null +++ b/doc/manual/release-notes/rl-016.xml @@ -0,0 +1,55 @@ + + +Release 0.16 (August 17, 2010) + +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. 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 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 flag. + + + + Several bug fixes. + + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-05.xml b/doc/manual/release-notes/rl-05.xml new file mode 100644 index 000000000..f7b40c119 --- /dev/null +++ b/doc/manual/release-notes/rl-05.xml @@ -0,0 +1,11 @@ + + +Release 0.5 and earlier + +Please refer to the Subversion commit log messages. + + diff --git a/doc/manual/release-notes/rl-06.xml b/doc/manual/release-notes/rl-06.xml new file mode 100644 index 000000000..a4d78edb9 --- /dev/null +++ b/doc/manual/release-notes/rl-06.xml @@ -0,0 +1,122 @@ + + +Release 0.6 (November 14, 2004) + + + + + Rewrite of the normalisation engine. + + + + Multiple builds can now be performed in parallel + (option ). + + 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 allows + recovery from broken substitutes. + + Option 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 + ). + + by default now + uninstall previous derivations with the same + name. + + allows upgrading to a + specific version. + + New operation + 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 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. + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-07.xml b/doc/manual/release-notes/rl-07.xml new file mode 100644 index 000000000..d6d61c12b --- /dev/null +++ b/doc/manual/release-notes/rl-07.xml @@ -0,0 +1,35 @@ + + +Release 0.7 (January 12, 2005) + + + + 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. + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-08.xml b/doc/manual/release-notes/rl-08.xml new file mode 100644 index 000000000..5f1e940bb --- /dev/null +++ b/doc/manual/release-notes/rl-08.xml @@ -0,0 +1,246 @@ + + +Release 0.8 (April 11, 2005) + +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 now 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., ). + +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., . + 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 + and + . + + 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 + 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 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 + and + . + + fetchurl allows SHA-1 and SHA-256 + in addition to MD5. Just specify the attribute + sha1 or sha256 instead of + md5. + + Manual updates. + + + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-081.xml b/doc/manual/release-notes/rl-081.xml new file mode 100644 index 000000000..986e4cb83 --- /dev/null +++ b/doc/manual/release-notes/rl-081.xml @@ -0,0 +1,21 @@ + + +Release 0.8.1 (April 13, 2005) + +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. + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-09.xml b/doc/manual/release-notes/rl-09.xml new file mode 100644 index 000000000..be0e5fa28 --- /dev/null +++ b/doc/manual/release-notes/rl-09.xml @@ -0,0 +1,98 @@ + + +Release 0.9 (September 16, 2005) + +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. + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-091.xml b/doc/manual/release-notes/rl-091.xml new file mode 100644 index 000000000..f90206d95 --- /dev/null +++ b/doc/manual/release-notes/rl-091.xml @@ -0,0 +1,13 @@ + + +Release 0.9.1 (September 20, 2005) + +This bug fix release addresses a problem with the ATerm library +when the flag in +configure was not used. + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-092.xml b/doc/manual/release-notes/rl-092.xml new file mode 100644 index 000000000..ea0412df2 --- /dev/null +++ b/doc/manual/release-notes/rl-092.xml @@ -0,0 +1,28 @@ + + +Release 0.9.2 (September 21, 2005) + +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). + + + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-10.xml b/doc/manual/release-notes/rl-10.xml new file mode 100644 index 000000000..21721b6cc --- /dev/null +++ b/doc/manual/release-notes/rl-10.xml @@ -0,0 +1,119 @@ + + +Release 1.0 (May 11, 2012) + +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 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 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 (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 (). + + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-11.xml b/doc/manual/release-notes/rl-11.xml new file mode 100644 index 000000000..db9939be1 --- /dev/null +++ b/doc/manual/release-notes/rl-11.xml @@ -0,0 +1,100 @@ + + +Release 1.1 (July 18, 2012) + +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 flag in + nix-env -qa is now much faster. + + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-12.xml b/doc/manual/release-notes/rl-12.xml new file mode 100644 index 000000000..72d164f00 --- /dev/null +++ b/doc/manual/release-notes/rl-12.xml @@ -0,0 +1,157 @@ + + +Release 1.2 (December 6, 2012) + +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 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. + + + + 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 + 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 () 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 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. + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-13.xml b/doc/manual/release-notes/rl-13.xml new file mode 100644 index 000000000..8e5264840 --- /dev/null +++ b/doc/manual/release-notes/rl-13.xml @@ -0,0 +1,19 @@ + + +Release 1.3 (January 4, 2013) + +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. + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-14.xml b/doc/manual/release-notes/rl-14.xml new file mode 100644 index 000000000..d1a8cd6d8 --- /dev/null +++ b/doc/manual/release-notes/rl-14.xml @@ -0,0 +1,39 @@ + + +Release 1.4 (February 26, 2013) + +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). + +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. + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-15.xml b/doc/manual/release-notes/rl-15.xml new file mode 100644 index 000000000..7319b52d8 --- /dev/null +++ b/doc/manual/release-notes/rl-15.xml @@ -0,0 +1,12 @@ + + +Release 1.5 (February 27, 2013) + +This is a brown paper bag release to fix a regression introduced +by the hard link security fix in 1.4. + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-151.xml b/doc/manual/release-notes/rl-151.xml new file mode 100644 index 000000000..625d0afc4 --- /dev/null +++ b/doc/manual/release-notes/rl-151.xml @@ -0,0 +1,12 @@ + + +Release 1.5.1 (February 28, 2013) + +The bug fix to the bug fix had a bug itself, of course. But +this time it will work for sure! + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-152.xml b/doc/manual/release-notes/rl-152.xml new file mode 100644 index 000000000..1446992a9 --- /dev/null +++ b/doc/manual/release-notes/rl-152.xml @@ -0,0 +1,12 @@ + + +Release 1.5.2 (May 13, 2013) + +This is primarily a bug fix release. It has contributions from +Eelco Dolstra, Lluís Batlle i Rossell and Shea Levy. + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-16.xml b/doc/manual/release-notes/rl-16.xml new file mode 100644 index 000000000..c0285b66f --- /dev/null +++ b/doc/manual/release-notes/rl-16.xml @@ -0,0 +1,127 @@ + + +Release 1.6 (September 10, 2013) + +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 + 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 + () to remove all + previous packages from the profile. This makes it easier to do + declarative package management similar to NixOS’s + . 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 + . + + + + +This release has contributions from Domen Kožar, Eelco Dolstra, +Florian Friesdorf, Gergely Risko, Ivan Kozik, Ludovic Courtès and Shea +Levy. + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-161.xml b/doc/manual/release-notes/rl-161.xml new file mode 100644 index 000000000..f6d3a6ba6 --- /dev/null +++ b/doc/manual/release-notes/rl-161.xml @@ -0,0 +1,69 @@ + + +Release 1.6.1 (October 28, 2013) + +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. + + + + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-17.xml b/doc/manual/release-notes/rl-17.xml new file mode 100644 index 000000000..7257bc869 --- /dev/null +++ b/doc/manual/release-notes/rl-17.xml @@ -0,0 +1,263 @@ + + +Release 1.7 (April 11, 2014) + +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. + + + + 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, + , 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 + and + have been renamed to and + , respectively. + + + + nix-instantiate, + nix-build and nix-shell now + have a flag (or ) 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, (or + ), 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 setting; + otherwise, it will bind-mount the /dev from + outside the chroot. + + Similarly, if you don’t have /dev/pts listed + in , 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 + 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 flag now allows attribute names with + dots in them, e.g. + + +$ nix-instantiate --eval '<nixos>' -A 'config.systemd.units."nscd.service".text' + + + + + + + The 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 + + Nd, which deletes + all user environment generations older than + N days. Likewise, nix-env + --delete-generations accepts a + Nd 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. + + \ No newline at end of file diff --git a/doc/manual/release-notes/rl-18.xml b/doc/manual/release-notes/rl-18.xml new file mode 100644 index 000000000..0fe3c2de7 --- /dev/null +++ b/doc/manual/release-notes/rl-18.xml @@ -0,0 +1,11 @@ + + +Release 1.8 (TBA) + +TODO + + \ No newline at end of file diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml deleted file mode 100644 index ec8c4c924..000000000 --- a/doc/manual/troubleshooting.xml +++ /dev/null @@ -1,92 +0,0 @@ - - -Troubleshooting - - -This section provides solutions for some common problems. See -the Nix -bug tracker for a list of currently known issues. - - -
Collisions in <command>nix-env</command> - -Symptom: when installing or upgrading, you get an error message such as - - -$ nix-env -i docbook-xml -... -adding /nix/store/s5hyxgm62gk2...-docbook-xml-4.2 -collision between `/nix/store/s5hyxgm62gk2...-docbook-xml-4.2/xml/dtd/docbook/calstblx.dtd' - and `/nix/store/06h377hr4b33...-docbook-xml-4.3/xml/dtd/docbook/calstblx.dtd' - at /nix/store/...-builder.pl line 62. - - - -The cause is that two installed packages in the user environment -have overlapping filenames (e.g., -xml/dtd/docbook/calstblx.dtd. This usually -happens when you accidentally try to install two versions of the same -package. For instance, in the example above, the Nix Packages -collection contains two versions of docbook-xml, so -nix-env -i will try to install both. The default -user environment builder has no way to way to resolve such conflicts, -so it just gives up. - -Solution: remove one of the offending packages from the user -environment (if already installed) using nix-env --e, or specify exactly which version should be installed -(e.g., nix-env -i docbook-xml-4.2). - -Alternatively, you can modify the user environment builder -script (in -prefix/share/nix/corepkgs/buildenv/builder.pl) -to implement some conflict resolution policy. E.g., the script could -be modified to rename conflicting file names, or to pick one over the -other. - -
- - -
<quote>Too many links</quote> error in the Nix -store - - -Symptom: when building something, you get an error message such as - - -... -mkdir: cannot create directory `/nix/store/name': Too many links - - - -This is usually because you have more than 32,000 subdirectories -in /nix/store, as can be seen using ls --l: - - -$ ls -l /nix/store -drwxrwxrwt 32000 nix nix 4620288 Sep 8 15:08 store - -The ext2 file system is limited to an inode link -count of 32,000 (each subdirectory increasing the count by one). -Furthermore, the st_nlink field of the -stat system call is a 16-bit value. - -This only happens on very large Nix installations (such as build -machines). - -Quick solution: run the garbage collector. You may want to use -the option. - -Real solution: put the Nix store on a file system that supports -more than 32,000 subdirectories per directory, such as ReiserFS. -(This doesn’t solve the st_nlink limit, but -ReiserFS lies to the kernel by reporting a link count of 1 if it -exceeds the limit.) - -
- - - - diff --git a/doc/manual/troubleshooting/collisions-nixenv.xml b/doc/manual/troubleshooting/collisions-nixenv.xml new file mode 100644 index 000000000..addc4cc29 --- /dev/null +++ b/doc/manual/troubleshooting/collisions-nixenv.xml @@ -0,0 +1,43 @@ + + +Collisions in <command>nix-env</command> + +Symptom: when installing or upgrading, you get an error message such as + + +$ nix-env -i docbook-xml +... +adding /nix/store/s5hyxgm62gk2...-docbook-xml-4.2 +collision between `/nix/store/s5hyxgm62gk2...-docbook-xml-4.2/xml/dtd/docbook/calstblx.dtd' + and `/nix/store/06h377hr4b33...-docbook-xml-4.3/xml/dtd/docbook/calstblx.dtd' + at /nix/store/...-builder.pl line 62. + + + +The cause is that two installed packages in the user environment +have overlapping filenames (e.g., +xml/dtd/docbook/calstblx.dtd. This usually +happens when you accidentally try to install two versions of the same +package. For instance, in the example above, the Nix Packages +collection contains two versions of docbook-xml, so +nix-env -i will try to install both. The default +user environment builder has no way to way to resolve such conflicts, +so it just gives up. + +Solution: remove one of the offending packages from the user +environment (if already installed) using nix-env +-e, or specify exactly which version should be installed +(e.g., nix-env -i docbook-xml-4.2). + +Alternatively, you can modify the user environment builder +script (in +prefix/share/nix/corepkgs/buildenv/builder.pl) +to implement some conflict resolution policy. E.g., the script could +be modified to rename conflicting file names, or to pick one over the +other. + + \ No newline at end of file diff --git a/doc/manual/troubleshooting/links-nix-store.xml b/doc/manual/troubleshooting/links-nix-store.xml new file mode 100644 index 000000000..5efec8e8b --- /dev/null +++ b/doc/manual/troubleshooting/links-nix-store.xml @@ -0,0 +1,43 @@ + + +<quote>Too many links</quote> Error in the Nix store + + +Symptom: when building something, you get an error message such as + + +... +mkdir: cannot create directory `/nix/store/name': Too many links + + + +This is usually because you have more than 32,000 subdirectories +in /nix/store, as can be seen using ls +-l: + + +$ ls -l /nix/store +drwxrwxrwt 32000 nix nix 4620288 Sep 8 15:08 store + +The ext2 file system is limited to an inode link +count of 32,000 (each subdirectory increasing the count by one). +Furthermore, the st_nlink field of the +stat system call is a 16-bit value. + +This only happens on very large Nix installations (such as build +machines). + +Quick solution: run the garbage collector. You may want to use +the option. + +Real solution: put the Nix store on a file system that supports +more than 32,000 subdirectories per directory, such as ReiserFS. +(This doesn’t solve the st_nlink limit, but +ReiserFS lies to the kernel by reporting a link count of 1 if it +exceeds the limit.) + + \ No newline at end of file diff --git a/doc/manual/troubleshooting/troubleshooting.xml b/doc/manual/troubleshooting/troubleshooting.xml new file mode 100644 index 000000000..e538e536f --- /dev/null +++ b/doc/manual/troubleshooting/troubleshooting.xml @@ -0,0 +1,18 @@ + + +Troubleshooting + + +This section provides solutions for some common problems. See +the Nix +bug tracker for a list of currently known issues. + + + + + + diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml deleted file mode 100644 index 0470625ff..000000000 --- a/doc/manual/writing-nix-expressions.xml +++ /dev/null @@ -1,1901 +0,0 @@ - - -Writing Nix Expressions - - -This chapter shows you how to write Nix expressions, which are -the things that tell 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. - -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. - - -
A simple Nix expression - -This section shows how to add and test the GNU Hello -package to the Nix Packages collection. Hello is a program -that prints out the text Hello, world!. - -To add a package to the Nix Packages collection, you generally -need to do three things: - - - - 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. - - Write a builder. This is a - shell scriptIn fact, it can be written in any - language, but typically it's a bash shell - script. that actually builds the package from - the inputs. - - 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. - - - - - - -
The Nix expression - -Nix expression for GNU Hello -(<filename>default.nix</filename>) - -{ stdenv, fetchurl, perl }: - -stdenv.mkDerivation { - name = "hello-2.1.1"; - builder = ./builder.sh; - src = fetchurl { - url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz; - md5 = "70c9ccf9fac07f762c24f2df2290784d"; - }; - inherit perl; -} - - - 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 , 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 an MD5 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. - - - - - - - -
- - -
The builder - -Build script for GNU Hello -(<filename>builder.sh</filename>) - -source $stdenv/setup - -PATH=$perl/bin:$PATH - -tar xvfz $src -cd hello-* -./configure --prefix=$out -make -make install - - - 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 - emptyActually, it's initialised to - /path-not-set to prevent Bash from setting it - to a default value.. 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 , 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 option, -which causes the script to be aborted if any command fails without an -error check. - -
- - -
Composition - -Composing GNU Hello -(<filename>all-packages.nix</filename>) - -... - -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 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. 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 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 ). - - 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. - - - - - -
- - -
Testing - -You can now try to build Hello. Of course, you could do -nix-env -f pkgs/top-level/all-packages.nix -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 pkgs/top-level/all-packages.nix -A hello -building path `/nix/store/632d2b22514d...-hello-2.1.1' -hello-2.1.1/ -hello-2.1.1/intl/ -hello-2.1.1/intl/ChangeLog -... - -$ ls -l result -lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1 - -$ ./result/bin/hello -Hello, world! - -The option selects -the hello attribute from -all-packages.nix. 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 switch to give the symlink another -name. - -Nix has a 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 pkgs/top-level/all-packages.nix -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). - -If you have a system with multiple CPUs, you may want to have -Nix build different derivations in parallel (insofar as possible). -Just pass the option , where -N is the maximum number of jobs to be run -in parallel, or set. Typically this should be the number of -CPUs. - -
- - -
The generic builder - -Recall from 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 . - -Build script using the generic -build functions - -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.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. - - - - - - - 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 . 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 . - - - - - -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. - -
- - -
- - - -
The 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. - - -
Values - - -Simple values - -Nix has the following basic data types: - - - - - - Strings can be written in three - ways. - - The most common way is to enclose the string between double - quotes, e.g., "foo bar". Strings can span - multiple lines. The special characters " and - \ and the character sequence - ${ must be escaped by prefixing them with a - backslash (\). Newlines, carriage returns and - tabs can be written as \n, - \r and \t, - respectively. - - You can include the result of an expression into a string by - enclosing it in - ${...}, a feature - known as antiquotation. The enclosed - expression must evaluate to something that can be coerced into a - string (meaning that it must be a string, a path, or a - derivation). For instance, rather than writing - - -"--with-freetype2-library=" + freetype + "/lib" - - (where freetype is a derivation), you can - instead write the more natural - - -"--with-freetype2-library=${freetype}/lib" - - The latter is automatically translated to the former. A more - complicated example (from the Nix expression for Qt): - - -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., - '''. Finally, linefeed, carriage-return and - tab characters can be written as ''\n, - ''\r, ''\t. - - 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 - 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. - - - - Integers, e.g., - 123. - - 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 - pathIt's parsed as an expression that selects the - attribute sh from the variable - builder.. If the file name is - relative, i.e., if it does not begin with a slash, it is made - absolute at parse time relative to the directory of the Nix - expression that contained it. For instance, if a Nix expression in - /foo/bar/bla.nix refers to - ../xyzzy/fnord.nix, the absolute path is - /foo/xyzzy/fnord.nix. - - Booleans with values - true and - false. - - The null value, denoted as - null. - - - - - - - - -Lists - -Lists are formed by enclosing a whitespace-separated list of -values between square brackets. For example, - - -[ 123 ./foo.nix "abc" (f { x = y; }) ] - -defines a list of four elements, the last being the result of a call -to the function f. Note that function calls have -to be enclosed in parentheses. If they had been omitted, e.g., - - -[ 123 ./foo.nix "abc" f { x = y; } ] - -the result would be a list of five elements, the fourth one being a -function and the fifth being a set. - - - - -Sets - -Sets are really the core of the language, since ultimately the -Nix language is all about creating derivations, which are really just -sets of attributes to be passed to build scripts. - -Sets are just a list of name/value pairs (called -attributes) enclosed in curly brackets, where -each value is an arbitrary expression terminated by a semicolon. For -example: - - -{ x = 123; - text = "Hello"; - y = f { bla = 456; }; -} - -This defines a set with attributes named x, -text, y. The order of the -attributes is irrelevant. An attribute name may only occur -once. - -Attributes can be selected from a set using the -. operator. For instance, - - -{ a = "Foo"; b = "Bar"; }.a - -evaluates to "Foo". It is possible to provide a -default value in an attribute selection using the -or keyword. For example, - - -{ a = "Foo"; b = "Bar"; }.c or "Xyzzy" - -will evaluate to "Xyzzy" because there is no -c attribute in the set. - -You can use arbitrary double-quoted strings as attribute -names: - - -{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}" - - -This will evaluate to 123 (Assuming -bar is antiquotable). In the case where an -attribute name is just a single antiquotation, the quotes can be -dropped: - - -{ foo = 123; }.${bar} or 456 - -This will evaluate to 123 if -bar evaluates to "foo" when -coerced to a string and 456 otherwise (again -assuming bar is antiquotable). - -In the special case where an attribute name inside of a set declaration -evaluates to null (which is normally an error, as -null is not antiquotable), that attribute is simply not -added to the set: - - -{ ${if foo then "bar" else null} = true; } - -This will evaluate to {} if foo -evaluates to false. - - - - - -
- - -
Language constructs - - -Recursive sets - -Recursive sets are just normal sets, but the attributes can -refer to each other. For example, - - -rec { - x = y; - y = 123; -}.x - - -evaluates to 123. Note that without -rec the binding x = y; would -refer to the variable y in the surrounding scope, -if one exists, and would be invalid if no such variable exists. That -is, in a normal (non-recursive) set, attributes are not added to the -lexical scope; in a recursive set, they are. - -Recursive sets of course introduce the danger of infinite -recursion. For example, - - -rec { - x = y; - y = x; -}.x - -does not terminateActually, Nix detects infinite -recursion in this case and aborts (infinite recursion -encountered).. - - - - -Let-expressions - -A let-expression allows you define local variables for an -expression. For instance, - - -let - x = "foo"; - y = "bar"; -in x + y - -evaluates to "foobar". - - - - - - -Inheriting attributes - -When defining a set 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; -} - -evaluates 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. - - - - -Functions - -Functions have the following form: - - -pattern: body - -The pattern specifies what the argument of the function must look -like, and binds variables in the body to (parts of) the -argument. There are three kinds of patterns: - - - - - If a pattern is a single identifier, then the - function matches any argument. Example: - - -let negate = x: !x; - concat = x: y: x + y; -in if negate true then concat "foo" "bar" else "" - - Note that concat is a function that takes one - argument and returns a function that takes another argument. This - allows partial parameterisation (i.e., only filling some of the - arguments of a function); e.g., - - -map (concat "foo") [ "bar" "bla" "abc" ] - - evaluates to [ "foobar" "foobla" - "fooabc" ]. - - - A set pattern of the form - { name1, name2, …, nameN } matches a set - containing the listed attributes, and binds the values of those - attributes to variables in the function body. For example, the - function - - -{ x, y, z }: z + y + x - - can only be called with a set containing exactly the attributes - x, y and - z. No other attributes are allowed. If you want - to allow additional arguments, you can use an ellipsis - (...): - - -{ x, y, z, ... }: z + y + x - - This works on any set that contains at least the three named - attributes. - - It is possible to provide default values - for attributes, in which case they are allowed to be missing. A - default value is specified by writing - name ? - e, where - e is an arbitrary expression. For example, - - -{ x, y ? "foo", z ? "bar" }: z + y + x - - specifies a function that only requires an attribute named - x, but optionally accepts y - and z. - - - An @-pattern provides a means of referring - to the whole value being matched: - - -args@{ x, y, z, ... }: z + y + x + args.a - - Here args is bound to the entire argument, which - is further matched against the pattern { x, y, z, - ... }. - - - - -Note that functions do not have names. If you want to give them -a name, you can bind them to an attribute, e.g., - - -let concat = { x, y }: x + y; -in concat { x = "foo"; y = "bar"; } - - - - - - -Conditionals - -Conditionals look like this: - - -if e1 then e2 else e3 - -where e1 is an expression that should -evaluate to a Boolean value (true or -false). - - - - -Assertions - -Assertions are generally used to check that certain requirements -on or between features and dependencies hold. They look like this: - - -assert e1; e2 - -where e1 is an expression that should -evaluate to a Boolean value. If it evaluates to -true, e2 is returned; -otherwise expression evaluation is aborted and a backtrace is printed. - -Nix expression for Subversion - -{ 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; - ... -} - - - 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. - - - - - - - - -With-expressions - -A with-expression, - - -with e1; e2 - -introduces the set e1 into the lexical -scope of the expression e2. For instance, - - -let as = { x = "foo"; y = "bar"; }; -in with as; x + y - -evaluates to "foobar" since the -with adds the x and -y attributes of as to the -lexical scope in the expression x + y. The most -common use of with is in conjunction with the -import function. E.g., - - -with (import ./definitions.nix); ... - -makes all attributes defined in the file -definitions.nix available as if they were defined -locally in a rec-expression. - - - - -Comments - -Comments can be single-line, started with a # -character, or inline/multi-line, enclosed within /* -... */. - - - - -
- - -
Operators - - lists the operators in the -Nix expression language, in order of precedence (from strongest to -weakest binding). - - - Operators - - - - Syntax - Associativity - Description - - - - - 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. - - - e1 e2 - left - Call function e1 with - argument e2. - - - e ? - attrpath - none - Test whether set e contains - the attribute denoted by attrpath; - return true or - false. - - - e1 ++ e2 - right - List concatenation. - - - e1 + e2 - left - String or path concatenation. - - - ! e - left - Boolean negation. - - - 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). - - - e1 == - e2 - none - Equality. - - - e1 != - e2 - none - Inequality. - - - e1 && - e2 - left - Logical AND. - - - e1 || - e2 - left - Logical OR. - - - e1 -> - e2 - none - Logical implication (equivalent to - !e1 || - e2). - - - -
- -
- - -
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 - "powerpc-darwin"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. 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 .) - - 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 integers 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 output 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 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 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 - 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. - - - - - - -
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. - - - - - 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). - - - - - - 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; - md5 = "70c9ccf9fac07f762c24f2df2290784d"; -} - - - 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; - md5 = "70c9ccf9fac07f762c24f2df2290784d"; -} - - - 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, md5 }: - -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 MD5 hash md5. - outputHashMode = "flat"; - outputHashAlgo = "md5"; - outputHash = md5; - - inherit url; -} - - - - - The outputHashAlgo attribute specifies - the hash algorithm used to compute the hash. It can currently be - "md5", "sha1" or - "sha256". - - 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 md5sum 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). 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 - for information about converting to and from base-32 - notation.) - - - - - 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, where - impurities such as these are okay since (the hash of) the output - is known in advance. It is ignored for all other - derivations. - - - - - preferLocalBuild - - If this attribute is set to - true, it has two effects. First, the - derivation will always be built, not substituted, even if a - substitute is available. Second, if distributed building is - enabled, 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. - - - - - -
- - -
- - - - - - -
- - - -
The standard environment - - -The standard environment is used by passing it as an input -called stdenv to the derivation, and then doing - - -source $stdenv/setup - -at the top of the builder. - -Apart from adding the aforementioned commands to the -PATH, setup also does the -following: - - - - All input packages specified in the - buildInputs environment variable have their - /bin subdirectory added to PATH, - their /include subdirectory added to the C/C++ - header file search path, and their /lib - subdirectory added to the linker search path. This can be extended. - For instance, when the pkgconfig package is - used, the subdirectory /lib/pkgconfig of each - input is added to the PKG_CONFIG_PATH environment - variable. - - The environment variable - NIX_CFLAGS_STRIP is set so that the compiler strips - debug information from object files. This can be disabled by - setting NIX_STRIP_DEBUG to - 0. - - - - - -The setup script also exports a function -called genericBuild that knows how to build -typical Autoconf-style packages. It can be customised to perform -builds for any type of package. It is advisable to use -genericBuild since it provides facilities that -are almost always useful such as unpacking of sources, patching of -sources, nested logging, etc. - -The definitive, up-to-date documentation of the generic builder -is the source itself, which resides in -pkgs/stdenv/generic/setup.sh. - - -
Customising the generic builder - -The operation of the generic builder can be modified in many -places by setting certain variables. These hook -variables are typically set to the name of some shell -function defined by you. For instance, to perform some additional -steps after make install you would set the -postInstall variable: - - -postInstall=myPostInstall - -myPostInstall() { - mkdir $out/share/extra - cp extrafiles/* $out/share/extra -} - - - - -
- - -
Debugging failed builds - -At the beginning of each phase, the set of all shell variables -is written to the file env-vars at the top-level -build directory. This is useful for debugging: it allows you to -recreate the environment in which a build was performed. For -instance, if a build fails, then assuming you used the - flag, you can go to the output directory and -switch to the environment of the builder: - - -$ nix-build -K ./foo.nix -... fails, keeping build directory `/tmp/nix-1234-0' - -$ cd /tmp/nix-1234-0 - -$ source env-vars - -(edit some files...) - -$ make - -(execution continues with the same GCC, make, etc.) - - - -
- - -
- - -