mdebray/tvl-depot
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Restructuring the Nix manual

Browse source
This commit is contained in:
Mikey Ariel 2014-08-27 18:41:09 +02:00
parent 3f0a4bf0e7
commit 8901acc976
107 changed files with 6161 additions and 5721 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

0
doc/manual/bugs.xml → doc/manual/bugs/bugs.xml
View file

22
doc/manual/builds/build-farm.xml Normal file
View file

@ -0,0 +1,22 @@
<part xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='chap-distributed-builds'>
<title>Distributed Builds</title>
<partintro>
<para>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
<literal>powerpc-darwin</literal> on an <literal>i686-linux</literal>
machine, Nix can automatically forward the build to a
<literal>powerpc-darwin</literal> machine, if available.</para>
</partintro>
<xi:include href="enabling-builds.xml" />
</part>

15
doc/manual/build-farm.xml → doc/manual/builds/enabling-builds.xml
View file

@ -1,17 +1,10 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id='chap-distributed-builds'>
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-enabling-builds">
<title>Setting Up Distributed Builds</title>
<para>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
<literal>powerpc-darwin</literal> on an <literal>i686-linux</literal>
machine, Nix can automatically forward the build to a
<literal>powerpc-darwin</literal> machine, if available.</para>
<title>Enabling Distributed Builds</title>
<para>You can enable distributed builds by setting the environment
variable <envar>NIX_BUILD_HOOK</envar> to point to a program that Nix

20
doc/manual/command-ref/command-ref.xml Normal file
View file

@ -0,0 +1,20 @@
<part xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='part-command-ref'>
<title>Command Reference</title>
<partintro>
<para>This section lists commands and options that you can use when you
work with Nix.</para>
</partintro>
<xi:include href="opt-common.xml" />
<xi:include href="env-common.xml" />
<xi:include href="main-commands.xml" />
<xi:include href="utilities.xml" />
<xi:include href="files.xml" />
</part>

0
doc/manual/conf-file.xml → doc/manual/command-ref/conf-file.xml
View file

8
doc/manual/env-common.xml → doc/manual/command-ref/env-common.xml
View file

@ -1,8 +1,10 @@
<section xmlns="http://docbook.org/ns/docbook"
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-common-env">
<title>Common environment variables</title>
<title>Common Environment Variables</title>
<para>Most Nix commands interpret the following environment variables:</para>
@ -335,4 +337,4 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
</variablelist>
</section>
</chapter>

14
doc/manual/command-ref/files.xml Normal file
View file

@ -0,0 +1,14 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='ch-files'>
<title>Files</title>
<para>This section lists configuration files that you can use when you
work with Nix.</para>
<xi:include href="conf-file.xml" />
</chapter>

17
doc/manual/command-ref/main-commands.xml Normal file
View file

@ -0,0 +1,17 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='ch-main-commands'>
<title>Main Commands</title>
<para>This section lists commands and options that you can use when you
work with Nix.</para>
<xi:include href="nix-env.xml" />
<xi:include href="nix-build.xml" />
<xi:include href="nix-shell.xml" />
<xi:include href="nix-store.xml" />
</chapter>

1
doc/manual/nix-build.xml → doc/manual/command-ref/nix-build.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-build">
<refmeta>

1
doc/manual/nix-channel.xml → doc/manual/command-ref/nix-channel.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-channel">
<refmeta>

1
doc/manual/nix-collect-garbage.xml → doc/manual/command-ref/nix-collect-garbage.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-collect-garbage">
<refmeta>

0
doc/manual/nix-copy-closure.xml → doc/manual/command-ref/nix-copy-closure.xml
View file

1
doc/manual/nix-daemon.xml → doc/manual/command-ref/nix-daemon.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-daemon">
<refmeta>

1
doc/manual/nix-env.xml → doc/manual/command-ref/nix-env.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-env">
<refmeta>

1
doc/manual/nix-hash.xml → doc/manual/command-ref/nix-hash.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-hash">
<refmeta>

1
doc/manual/nix-install-package.xml → doc/manual/command-ref/nix-install-package.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-install-package">
<refmeta>

1
doc/manual/nix-instantiate.xml → doc/manual/command-ref/nix-instantiate.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-instantiate">
<refmeta>

1
doc/manual/nix-prefetch-url.xml → doc/manual/command-ref/nix-prefetch-url.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-prefetch-url">
<refmeta>

1
doc/manual/nix-pull.xml → doc/manual/command-ref/nix-pull.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-pull">
<refmeta>

1
doc/manual/nix-push.xml → doc/manual/command-ref/nix-push.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-push">
<refmeta>

1
doc/manual/nix-shell.xml → doc/manual/command-ref/nix-shell.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-shell">
<refmeta>

1
doc/manual/nix-store.xml → doc/manual/command-ref/nix-store.xml
View file

@ -1,6 +1,7 @@
<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-store">
<refmeta>

0
doc/manual/opt-common-syn.xml → doc/manual/command-ref/opt-common-syn.xml
View file

6
doc/manual/opt-common.xml → doc/manual/command-ref/opt-common.xml
View file

@ -1,6 +1,6 @@
<section xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options">
<chapter xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options">
<title>Common options</title>
<title>Common Options</title>
<para>Most Nix commands accept the following command-line options:</para>
@ -386,4 +386,4 @@
</variablelist>
</section>
</chapter>

0
doc/manual/opt-inst-syn.xml → doc/manual/command-ref/opt-inst-syn.xml
View file

23
doc/manual/command-ref/utilities.xml Normal file
View file

@ -0,0 +1,23 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='ch-utilities'>
<title>Utilities</title>
<para>This section lists utilities that you can use when you
work with Nix.</para>
<xi:include href="nix-channel.xml" />
<xi:include href="nix-collect-garbage.xml" />
<xi:include href="nix-copy-closure.xml" />
<xi:include href="nix-daemon.xml" />
<xi:include href="nix-hash.xml" />
<xi:include href="nix-install-package.xml" />
<xi:include href="nix-instantiate.xml" />
<xi:include href="nix-prefetch-url.xml" />
<xi:include href="nix-pull.xml" />
<xi:include href="nix-push.xml" />
</chapter>

243
doc/manual/expressions/advanced-attributes.xml Normal file
View file

@ -0,0 +1,243 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-advanced-attributes">
<title>Advanced Attributes</title>
<para>Derivations can declare some infrequently used optional
attributes.</para>
<variablelist>
<varlistentry><term><varname>allowedReferences</varname></term>
<listitem><para>The optional attribute
<varname>allowedReferences</varname> specifies a list of legal
references (dependencies) of the output of the builder. For
example,
<programlisting>
allowedReferences = [];
</programlisting>
enforces that the output of a derivation cannot have any runtime
dependencies on its inputs. To allow an output to have a runtime
dependency on itself, use <literal>"out"</literal> as a list item.
This is used in NixOS to check that generated files such as
initial ramdisks for booting Linux don’t have accidental
dependencies on other paths in the Nix store.</para></listitem>
</varlistentry>
<varlistentry><term><varname>exportReferencesGraph</varname></term>
<listitem><para>This attribute allows builders access to the
references graph of their inputs. The attribute is a list of
inputs in the Nix store whose references graph the builder needs
to know. The value of this attribute should be a list of pairs
<literal>[ <replaceable>name1</replaceable>
<replaceable>path1</replaceable> <replaceable>name2</replaceable>
<replaceable>path2</replaceable> <replaceable>...</replaceable>
]</literal>. The references graph of each
<replaceable>pathN</replaceable> will be stored in a text file
<replaceable>nameN</replaceable> in the temporary build directory.
The text files have the format used by <command>nix-store
--register-validity</command> (with the deriver fields left
empty). For example, when the following derivation is built:
<programlisting>
derivation {
...
exportReferencesGraph = [ "libfoo-graph" libfoo ];
};
</programlisting>
the references graph of <literal>libfoo</literal> is placed in the
file <filename>libfoo-graph</filename> in the temporary build
directory.</para>
<para><varname>exportReferencesGraph</varname> is useful for
builders that want to do something with the closure of a store
path. Examples include the builders in NixOS that generate the
initial ramdisk for booting Linux (a <command>cpio</command>
archive containing the closure of the boot script) and the
ISO-9660 image for the installation CD (which is populated with a
Nix store containing the closure of a bootable NixOS
configuration).</para></listitem>
</varlistentry>
<varlistentry xml:id="fixed-output-drvs">
<term><varname>outputHash</varname></term>
<term><varname>outputHashAlgo</varname></term>
<term><varname>outputHashMode</varname></term>
<listitem><para>These attributes declare that the derivation is a
so-called <emphasis>fixed-output derivation</emphasis>, which
means that a cryptographic hash of the output is already known in
advance. When the build of a fixed-output derivation finishes,
Nix computes the cryptographic hash of the output and compares it
to the hash declared with these attributes. If there is a
mismatch, the build fails.</para>
<para>The rationale for fixed-output derivations is derivations
such as those produced by the <function>fetchurl</function>
function. This function downloads a file from a given URL. To
ensure that the downloaded file has not been modified, the caller
must also specify a cryptographic hash of the file. For example,
<programlisting>
fetchurl {
url = http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz;
md5 = "70c9ccf9fac07f762c24f2df2290784d";
}
</programlisting>
It sometimes happens that the URL of the file changes, e.g.,
because servers are reorganised or no longer available. We then
must update the call to <function>fetchurl</function>, e.g.,
<programlisting>
fetchurl {
url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
md5 = "70c9ccf9fac07f762c24f2df2290784d";
}
</programlisting>
If a <function>fetchurl</function> derivation was treated like a
normal derivation, the output paths of the derivation and
<emphasis>all derivations depending on it</emphasis> would change.
For instance, if we were to change the URL of the Glibc source
distribution in Nixpkgs (a package on which almost all other
packages depend) massive rebuilds would be needed. This is
unfortunate for a change which we know cannot have a real effect
as it propagates upwards through the dependency graph.</para>
<para>For fixed-output derivations, on the other hand, the name of
the output path only depends on the <varname>outputHash*</varname>
and <varname>name</varname> attributes, while all other attributes
are ignored for the purpose of computing the output path. (The
<varname>name</varname> attribute is included because it is part
of the path.)</para>
<para>As an example, here is the (simplified) Nix expression for
<varname>fetchurl</varname>:
<programlisting>
{ stdenv, curl }: # The <command>curl</command> program is used for downloading.
{ url, 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 <varname>md5</varname>.
outputHashMode = "flat";
outputHashAlgo = "md5";
outputHash = md5;
inherit url;
}
</programlisting>
</para>
<para>The <varname>outputHashAlgo</varname> attribute specifies
the hash algorithm used to compute the hash. It can currently be
<literal>"md5"</literal>, <literal>"sha1"</literal> or
<literal>"sha256"</literal>.</para>
<para>The <varname>outputHashMode</varname> attribute determines
how the hash is computed. It must be one of the following two
values:
<variablelist>
<varlistentry><term><literal>"flat"</literal></term>
<listitem><para>The output must be a non-executable regular
file. If it isn’t, the build fails. The hash is simply
computed over the contents of that file (so it’s equal to what
Unix commands like <command>md5sum</command> or
<command>sha1sum</command> produce).</para>
<para>This is the default.</para></listitem>
</varlistentry>
<varlistentry><term><literal>"recursive"</literal></term>
<listitem><para>The hash is computed over the NAR archive dump
of the output (i.e., the result of <link
linkend="refsec-nix-store-dump"><command>nix-store
--dump</command></link>). In this case, the output can be
anything, including a directory tree.</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>The <varname>outputHash</varname> attribute, finally, must
be a string containing the hash in either hexadecimal or base-32
notation. (See the <link
linkend="sec-nix-hash"><command>nix-hash</command> command</link>
for information about converting to and from base-32
notation.)</para></listitem>
</varlistentry>
<varlistentry><term><varname>impureEnvVars</varname></term>
<listitem><para>This attribute allows you to specify a list of
environment variables that should be passed from the environment
of the calling user to the builder. Usually, the environment is
cleared completely when the builder is executed, but with this
attribute you can allow specific environment variables to be
passed unmodified. For example, <function>fetchurl</function> in
Nixpkgs has the line
<programlisting>
impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ];
</programlisting>
to make it use the proxy server configuration specified by the
user in the environment variables <envar>http_proxy</envar> and
friends.</para>
<para>This attribute is only allowed in <link
linkend="fixed-output-drvs">fixed-output derivations</link>, where
impurities such as these are okay since (the hash of) the output
is known in advance. It is ignored for all other
derivations.</para></listitem>
</varlistentry>
<varlistentry><term><varname>preferLocalBuild</varname></term>
<listitem><para>If this attribute is set to
<literal>true</literal>, it has two effects. First, the
derivation will always be built, not substituted, even if a
substitute is available. Second, if <link
linkend="chap-distributed-builds">distributed building is
enabled</link>, then, if possible, the derivaton will be built
locally instead of forwarded to a remote machine. This is
appropriate for trivial builders where the cost of doing a
download or remote build would exceed the cost of building
locally.</para></listitem>
</varlistentry>
</variablelist>
</section>

121
doc/manual/expressions/arguments-variables.xml Normal file
View file

@ -0,0 +1,121 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='sec-arguments'>
<title>Arguments and Variables</title>
<example xml:id='ex-hello-composition'>
<title>Composing GNU Hello
(<filename>all-packages.nix</filename>)</title>
<programlisting>
...
rec { <co xml:id='ex-hello-composition-co-1' />
hello = import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' /> { <co xml:id='ex-hello-composition-co-3' />
inherit fetchurl stdenv perl;
};
perl = import ../development/interpreters/perl { <co xml:id='ex-hello-composition-co-4' />
inherit fetchurl stdenv;
};
fetchurl = import ../build-support/fetchurl {
inherit stdenv; ...
};
stdenv = ...;
}
</programlisting>
</example>
<para>The Nix expression in <xref linkend='ex-hello-nix' /> is a
function; it is missing some arguments that have to be filled in
somewhere. In the Nix Packages collection this is done in the file
<filename>pkgs/top-level/all-packages.nix</filename>, where all
Nix expressions for packages are imported and called with the
appropriate arguments. <xref linkend='ex-hello-composition' /> shows
some fragments of
<filename>all-packages.nix</filename>.</para>
<calloutlist>
<callout arearefs='ex-hello-composition-co-1'>
<para>This file defines a set of attributes, all of which are
concrete derivations (i.e., not functions). In fact, we define a
<emphasis>mutually recursive</emphasis> set of attributes. That
is, the attributes can refer to each other. This is precisely
what we want since we want to <quote>plug</quote> the
various packages into each other.</para>
</callout>
<callout arearefs='ex-hello-composition-co-2'>
<para>Here we <emphasis>import</emphasis> the Nix expression for
GNU Hello. The import operation just loads and returns the
specified Nix expression. In fact, we could just have put the
contents of <xref linkend='ex-hello-nix' /> in
<filename>all-packages.nix</filename> at this point. That
would be completely equivalent, but it would make the file rather
bulky.</para>
<para>Note that we refer to
<filename>../applications/misc/hello/ex-1</filename>, not
<filename>../applications/misc/hello/ex-1/default.nix</filename>.
When you try to import a directory, Nix automatically appends
<filename>/default.nix</filename> to the file name.</para>
</callout>
<callout arearefs='ex-hello-composition-co-3'>
<para>This is where the actual composition takes place. Here we
<emphasis>call</emphasis> the function imported from
<filename>../applications/misc/hello/ex-1</filename> with a set
containing the things that the function expects, namely
<varname>fetchurl</varname>, <varname>stdenv</varname>, and
<varname>perl</varname>. We use inherit again to use the
attributes defined in the surrounding scope (we could also have
written <literal>fetchurl = fetchurl;</literal>, etc.).</para>
<para>The result of this function call is an actual derivation
that can be built by Nix (since when we fill in the arguments of
the function, what we get is its body, which is the call to
<varname>stdenv.mkDerivation</varname> in <xref
linkend='ex-hello-nix' />).</para>
<note><para>Nixpkgs has a convenience function
<function>callPackage</function> that imports and calls a
function, filling in any missing arguments by passing the
corresponding attribute from the Nixpkgs set, like this:
<programlisting>
hello = callPackage ../applications/misc/hello/ex-1 { };
</programlisting>
If necessary, you can set or override arguments:
<programlisting>
hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; };
</programlisting>
</para></note>
</callout>
<callout arearefs='ex-hello-composition-co-4'>
<para>Likewise, we have to instantiate Perl,
<varname>fetchurl</varname>, and the standard environment.</para>
</callout>
</calloutlist>
</section>

119
doc/manual/expressions/build-script.xml Normal file
View file

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

119
doc/manual/expressions/builder-syntax.xml Normal file
View file

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

5
doc/manual/builtins.xml → doc/manual/expressions/builtins.xml
View file

@ -1,9 +1,10 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='ssec-builtins'>
<title>Built-in functions</title>
<title>Built-in Functions</title>
<para>This section lists the functions and constants built into the
Nix expression evaluator. (The built-in function

26
doc/manual/expressions/custom-builder.xml Normal file
View file

@ -0,0 +1,26 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-custom-builder">
<title>Customizing the Generic Builder</title>
<para>The operation of the generic builder can be modified in many
places by setting certain variables. These <emphasis>hook
variables</emphasis> are typically set to the name of some shell
function defined by you. For instance, to perform some additional
steps after <command>make install</command> you would set the
<varname>postInstall</varname> variable:
<programlisting>
postInstall=myPostInstall
myPostInstall() {
mkdir $out/share/extra
cp extrafiles/* $out/share/extra
}</programlisting>
</para>
</section>

33
doc/manual/expressions/debug-build.xml Normal file
View file

@ -0,0 +1,33 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-debug-build">
<title>Debugging Build Failures</title>
<para>At the beginning of each phase, the set of all shell variables
is written to the file <filename>env-vars</filename> 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
<option>-K</option> flag, you can go to the output directory and
<quote>switch</quote> to the environment of the builder:
<screen>
$ nix-build -K ./foo.nix
... fails, keeping build directory `/tmp/nix-1234-0'
$ cd /tmp/nix-1234-0
$ source env-vars
<lineannotation>(edit some files...)</lineannotation>
$ make
<lineannotation>(execution continues with the same GCC, make, etc.)</lineannotation></screen>
</para>
</section>

211
doc/manual/expressions/derivations.xml Normal file
View file

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

30
doc/manual/expressions/expression-language.xml Normal file
View file

@ -0,0 +1,30 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-expression-language">
<title>Nix Expression Language</title>
<para>The Nix expression language is a pure, lazy, functional
language. Purity means that operations in the language don't have
side-effects (for instance, there is no variable assignment).
Laziness means that arguments to functions are evaluated only when
they are needed. Functional means that functions are
<quote>normal</quote> values that can be passed around and manipulated
in interesting ways. The language is not a full-featured, general
purpose language. Its main job is to describe packages,
compositions of packages, and the variability within
packages.</para>
<para>This section presents the various features of the
language.</para>
<xi:include href="language-values.xml" />
<xi:include href="language-constructs.xml" />
<xi:include href="language-operators.xml" />
<xi:include href="derivations.xml" />
<xi:include href="builtins.xml" />
</chapter>

148
doc/manual/expressions/expression-syntax.xml Normal file
View file

@ -0,0 +1,148 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='sec-expression-syntax'>
<title>Expression Syntax</title>
<example xml:id='ex-hello-nix'><title>Nix expression for GNU Hello
(<filename>default.nix</filename>)</title>
<programlisting>
{ stdenv, fetchurl, perl }: <co xml:id='ex-hello-nix-co-1' />
stdenv.mkDerivation { <co xml:id='ex-hello-nix-co-2' />
name = "hello-2.1.1"; <co xml:id='ex-hello-nix-co-3' />
builder = ./builder.sh; <co xml:id='ex-hello-nix-co-4' />
src = fetchurl { <co xml:id='ex-hello-nix-co-5' />
url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
md5 = "70c9ccf9fac07f762c24f2df2290784d";
};
inherit perl; <co xml:id='ex-hello-nix-co-6' />
}</programlisting>
</example>
<para><xref linkend='ex-hello-nix' /> shows a Nix expression for GNU
Hello. It's actually already in the Nix Packages collection in
<filename>pkgs/applications/misc/hello/ex-1/default.nix</filename>.
It is customary to place each package in a separate directory and call
the single Nix expression in that directory
<filename>default.nix</filename>. The file has the following elements
(referenced from the figure by number):
<calloutlist>
<callout arearefs='ex-hello-nix-co-1'>
<para>This states that the expression is a
<emphasis>function</emphasis> that expects to be called with three
arguments: <varname>stdenv</varname>, <varname>fetchurl</varname>,
and <varname>perl</varname>. They are needed to build Hello, but
we don't know how to build them here; that's why they are function
arguments. <varname>stdenv</varname> is a package that is used
by almost all Nix Packages packages; it provides a
<quote>standard</quote> environment consisting of the things you
would expect in a basic Unix environment: a C/C++ compiler (GCC,
to be precise), the Bash shell, fundamental Unix tools such as
<command>cp</command>, <command>grep</command>,
<command>tar</command>, etc. <varname>fetchurl</varname> is a
function that downloads files. <varname>perl</varname> is the
Perl interpreter.</para>
<para>Nix functions generally have the form <literal>{ x, y, ...,
z }: e</literal> where <varname>x</varname>, <varname>y</varname>,
etc. are the names of the expected arguments, and where
<replaceable>e</replaceable> is the body of the function. So
here, the entire remainder of the file is the body of the
function; when given the required arguments, the body should
describe how to build an instance of the Hello package.</para>
</callout>
<callout arearefs='ex-hello-nix-co-2'>
<para>So we have to build a package. Building something from
other stuff is called a <emphasis>derivation</emphasis> in Nix (as
opposed to sources, which are built by humans instead of
computers). We perform a derivation by calling
<varname>stdenv.mkDerivation</varname>.
<varname>mkDerivation</varname> is a function provided by
<varname>stdenv</varname> that builds a package from a set of
<emphasis>attributes</emphasis>. A set is just a list of
key/value pairs where each key is a string and each value is an
arbitrary Nix expression. They take the general form <literal>{
<replaceable>name1</replaceable> =
<replaceable>expr1</replaceable>; <replaceable>...</replaceable>
<replaceable>nameN</replaceable> =
<replaceable>exprN</replaceable>; }</literal>.</para>
</callout>
<callout arearefs='ex-hello-nix-co-3'>
<para>The attribute <varname>name</varname> specifies the symbolic
name and version of the package. Nix doesn't really care about
these things, but they are used by for instance <command>nix-env
-q</command> to show a <quote>human-readable</quote> name for
packages. This attribute is required by
<varname>mkDerivation</varname>.</para>
</callout>
<callout arearefs='ex-hello-nix-co-4'>
<para>The attribute <varname>builder</varname> specifies the
builder. This attribute can sometimes be omitted, in which case
<varname>mkDerivation</varname> will fill in a default builder
(which does a <literal>configure; make; make install</literal>, in
essence). Hello is sufficiently simple that the default builder
would suffice, but in this case, we will show an actual builder
for educational purposes. The value
<command>./builder.sh</command> refers to the shell script shown
in <xref linkend='ex-hello-builder' />, discussed below.</para>
</callout>
<callout arearefs='ex-hello-nix-co-5'>
<para>The builder has to know what the sources of the package
are. Here, the attribute <varname>src</varname> is bound to the
result of a call to the <command>fetchurl</command> function.
Given a URL and 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.</para>
<para>Instead of <varname>src</varname> any other name could have
been used, and in fact there can be any number of sources (bound
to different attributes). However, <varname>src</varname> is
customary, and it's also expected by the default builder (which we
don't use in this example).</para>
</callout>
<callout arearefs='ex-hello-nix-co-6'>
<para>Since the derivation requires Perl, we have to pass the
value of the <varname>perl</varname> function argument to the
builder. All attributes in the set are actually passed as
environment variables to the builder, so declaring an attribute
<programlisting>
perl = perl;</programlisting>
will do the trick: it binds an attribute <varname>perl</varname>
to the function argument which also happens to be called
<varname>perl</varname>. However, it looks a bit silly, so there
is a shorter syntax. The <literal>inherit</literal> keyword
causes the specified attributes to be bound to whatever variables
with the same name happen to be in scope.</para>
</callout>
</calloutlist>
</para>
</section>

98
doc/manual/expressions/generic-builder.xml Normal file
View file

@ -0,0 +1,98 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='sec-generic-builder'>
<title>Generic Builder Syntax</title>
<para>Recall from <xref linkend='ex-hello-builder' /> that the builder
looked something like this:
<programlisting>
PATH=$perl/bin:$PATH
tar xvfz $src
cd hello-*
./configure --prefix=$out
make
make install</programlisting>
The builders for almost all Unix packages look like this — set up some
environment variables, unpack the sources, configure, build, and
install. For this reason the standard environment provides some Bash
functions that automate the build process. A builder using the
generic build facilities in shown in <xref linkend='ex-hello-builder2'
/>.</para>
<example xml:id='ex-hello-builder2'><title>Build script using the generic
build functions</title>
<programlisting>
buildInputs="$perl" <co xml:id='ex-hello-builder2-co-1' />
source $stdenv/setup <co xml:id='ex-hello-builder2-co-2' />
genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting>
</example>
<calloutlist>
<callout arearefs='ex-hello-builder2-co-1'>
<para>The <envar>buildInputs</envar> variable tells
<filename>setup</filename> to use the indicated packages as
<quote>inputs</quote>. This means that if a package provides a
<filename>bin</filename> subdirectory, it's added to
<envar>PATH</envar>; if it has a <filename>include</filename>
subdirectory, it's added to GCC's header search path; and so
on.<footnote><para>How does it work? <filename>setup</filename>
tries to source the file
<filename><replaceable>pkg</replaceable>/nix-support/setup-hook</filename>
of all dependencies. These “setup hooks” can then set up whatever
environment variables they want; for instance, the setup hook for
Perl sets the <envar>PERL5LIB</envar> environment variable to
contain the <filename>lib/site_perl</filename> directories of all
inputs.</para></footnote>
</para>
</callout>
<callout arearefs='ex-hello-builder2-co-2'>
<para>The function <function>genericBuild</function> is defined in
the file <literal>$stdenv/setup</literal>.</para>
</callout>
<callout arearefs='ex-hello-builder2-co-3'>
<para>The final step calls the shell function
<function>genericBuild</function>, which performs the steps that
were done explicitly in <xref linkend='ex-hello-builder' />. The
generic builder is smart enough to figure out whether to unpack
the sources using <command>gzip</command>,
<command>bzip2</command>, etc. It can be customised in many ways;
see <xref linkend='sec-standard-environment' />.</para>
</callout>
</calloutlist>
<para>Discerning readers will note that the
<envar>buildInputs</envar> could just as well have been set in the Nix
expression, like this:
<programlisting>
buildInputs = [ perl ];</programlisting>
The <varname>perl</varname> attribute can then be removed, and the
builder becomes even shorter:
<programlisting>
source $stdenv/setup
genericBuild</programlisting>
In fact, <varname>mkDerivation</varname> provides a default builder
that looks exactly like that, so it is actually possible to omit the
builder for Hello entirely.</para>
</section>

344
doc/manual/expressions/language-constructs.xml Normal file
View file

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

113
doc/manual/expressions/language-operators.xml Normal file
View file

@ -0,0 +1,113 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-language-operators">
<title>Operators</title>
<para><xref linkend='table-operators' /> lists the operators in the
Nix expression language, in order of precedence (from strongest to
weakest binding).</para>
<table xml:id='table-operators'>
<title>Operators</title>
<tgroup cols='3'>
<thead>
<row>
<entry>Syntax</entry>
<entry>Associativity</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><replaceable>e</replaceable> <literal>.</literal>
<replaceable>attrpath</replaceable>
[ <literal>or</literal> <replaceable>def</replaceable> ]
</entry>
<entry>none</entry>
<entry>Select attribute denoted by the attribute path
<replaceable>attrpath</replaceable> from set
<replaceable>e</replaceable>. (An attribute path is a
dot-separated list of attribute names.) If the attribute
doesn’t exist, return <replaceable>def</replaceable> if
provided, otherwise abort evaluation.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> <replaceable>e2</replaceable></entry>
<entry>left</entry>
<entry>Call function <replaceable>e1</replaceable> with
argument <replaceable>e2</replaceable>.</entry>
</row>
<row>
<entry><replaceable>e</replaceable> <literal>?</literal>
<replaceable>attrpath</replaceable></entry>
<entry>none</entry>
<entry>Test whether set <replaceable>e</replaceable> contains
the attribute denoted by <replaceable>attrpath</replaceable>;
return <literal>true</literal> or
<literal>false</literal>.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> <literal>++</literal> <replaceable>e2</replaceable></entry>
<entry>right</entry>
<entry>List concatenation.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable></entry>
<entry>left</entry>
<entry>String or path concatenation.</entry>
</row>
<row>
<entry><literal>!</literal> <replaceable>e</replaceable></entry>
<entry>left</entry>
<entry>Boolean negation.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> <literal>//</literal>
<replaceable>e2</replaceable></entry>
<entry>right</entry>
<entry>Return a set consisting of the attributes in
<replaceable>e1</replaceable> and
<replaceable>e2</replaceable> (with the latter taking
precedence over the former in case of equally named
attributes).</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> <literal>==</literal>
<replaceable>e2</replaceable></entry>
<entry>none</entry>
<entry>Equality.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> <literal>!=</literal>
<replaceable>e2</replaceable></entry>
<entry>none</entry>
<entry>Inequality.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> <literal>&amp;&amp;</literal>
<replaceable>e2</replaceable></entry>
<entry>left</entry>
<entry>Logical AND.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> <literal>||</literal>
<replaceable>e2</replaceable></entry>
<entry>left</entry>
<entry>Logical OR.</entry>
</row>
<row>
<entry><replaceable>e1</replaceable> <literal>-></literal>
<replaceable>e2</replaceable></entry>
<entry>none</entry>
<entry>Logical implication (equivalent to
<literal>!<replaceable>e1</replaceable> ||
<replaceable>e2</replaceable></literal>).</entry>
</row>
</tbody>
</tgroup>
</table>
</section>

268
doc/manual/expressions/language-values.xml Normal file
View file

@ -0,0 +1,268 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='ssec-values'>
<title>Values</title>
<simplesect><title>Simple Values</title>
<para>Nix has the following basic data types:
<itemizedlist>
<listitem>
<para><emphasis>Strings</emphasis> can be written in three
ways.</para>
<para>The most common way is to enclose the string between double
quotes, e.g., <literal>"foo bar"</literal>. Strings can span
multiple lines. The special characters <literal>"</literal> and
<literal>\</literal> and the character sequence
<literal>${</literal> must be escaped by prefixing them with a
backslash (<literal>\</literal>). Newlines, carriage returns and
tabs can be written as <literal>\n</literal>,
<literal>\r</literal> and <literal>\t</literal>,
respectively.</para>
<para>You can include the result of an expression into a string by
enclosing it in
<literal>${<replaceable>...</replaceable>}</literal>, a feature
known as <emphasis>antiquotation</emphasis>. The enclosed
expression must evaluate to something that can be coerced into a
string (meaning that it must be a string, a path, or a
derivation). For instance, rather than writing
<programlisting>
"--with-freetype2-library=" + freetype + "/lib"</programlisting>
(where <varname>freetype</varname> is a derivation), you can
instead write the more natural
<programlisting>
"--with-freetype2-library=${freetype}/lib"</programlisting>
The latter is automatically translated to the former. A more
complicated example (from the Nix expression for <link
xlink:href='http://www.trolltech.com/products/qt'>Qt</link>):
<programlisting>
configureFlags = "
-system-zlib -system-libpng -system-libjpeg
${if openglSupport then "-dlopen-opengl
-L${mesa}/lib -I${mesa}/include
-L${libXmu}/lib -I${libXmu}/include" else ""}
${if threadSupport then "-thread" else "-no-thread"}
";</programlisting>
Note that Nix expressions and strings can be arbitrarily nested;
in this case the outer string contains various antiquotations that
themselves contain strings (e.g., <literal>"-thread"</literal>),
some of which in turn contain expressions (e.g.,
<literal>${mesa}</literal>).</para>
<para>The second way to write string literals is as an
<emphasis>indented string</emphasis>, which is enclosed between
pairs of <emphasis>double single-quotes</emphasis>, like so:
<programlisting>
''
This is the first line.
This is the second line.
This is the third line.
''</programlisting>
This kind of string literal intelligently strips indentation from
the start of each line. To be precise, it strips from each line a
number of spaces equal to the minimal indentation of the string as
a whole (disregarding the indentation of empty lines). For
instance, the first and second line are indented two space, while
the third line is indented four spaces. Thus, two spaces are
stripped from each line, so the resulting string is
<programlisting>
"This is the first line.\nThis is the second line.\n This is the third line.\n"</programlisting>
</para>
<para>Note that the whitespace and newline following the opening
<literal>''</literal> is ignored if there is no non-whitespace
text on the initial line.</para>
<para>Antiquotation
(<literal>${<replaceable>expr</replaceable>}</literal>) is
supported in indented strings.</para>
<para>Since <literal>${</literal> and <literal>''</literal> have
special meaning in indented strings, you need a way to quote them.
<literal>${</literal> can be escaped by prefixing it with
<literal>''</literal> (that is, two single quotes), i.e.,
<literal>''${</literal>. <literal>''</literal> can be escaped by
prefixing it with <literal>'</literal>, i.e.,
<literal>'''</literal>. Finally, linefeed, carriage-return and
tab characters can be written as <literal>''\n</literal>,
<literal>''\r</literal>, <literal>''\t</literal>.</para>
<para>Indented strings are primarily useful in that they allow
multi-line string literals to follow the indentation of the
enclosing Nix expression, and that less escaping is typically
necessary for strings representing languages such as shell scripts
and configuration files because <literal>''</literal> is much less
common than <literal>"</literal>. Example:
<programlisting>
stdenv.mkDerivation {
<replaceable>...</replaceable>
postInstall =
''
mkdir $out/bin $out/etc
cp foo $out/bin
echo "Hello World" > $out/etc/foo.conf
${if enableBar then "cp bar $out/bin" else ""}
'';
<replaceable>...</replaceable>
}
</programlisting>
</para>
<para>Finally, as a convenience, <emphasis>URIs</emphasis> as
defined in appendix B of <link
xlink:href='http://www.ietf.org/rfc/rfc2396.txt'>RFC 2396</link>
can be written <emphasis>as is</emphasis>, without quotes. For
instance, the string
<literal>"http://example.org/foo.tar.bz2"</literal>
can also be written as
<literal>http://example.org/foo.tar.bz2</literal>.</para>
</listitem>
<listitem><para><emphasis>Integers</emphasis>, e.g.,
<literal>123</literal>.</para></listitem>
<listitem><para><emphasis>Paths</emphasis>, e.g.,
<filename>/bin/sh</filename> or <filename>./builder.sh</filename>.
A path must contain at least one slash to be recognised as such; for
instance, <filename>builder.sh</filename> is not a
path<footnote><para>It's parsed as an expression that selects the
attribute <varname>sh</varname> from the variable
<varname>builder</varname>.</para></footnote>. If the file name is
relative, i.e., if it does not begin with a slash, it is made
absolute at parse time relative to the directory of the Nix
expression that contained it. For instance, if a Nix expression in
<filename>/foo/bar/bla.nix</filename> refers to
<filename>../xyzzy/fnord.nix</filename>, the absolute path is
<filename>/foo/xyzzy/fnord.nix</filename>.</para></listitem>
<listitem><para><emphasis>Booleans</emphasis> with values
<literal>true</literal> and
<literal>false</literal>.</para></listitem>
<listitem><para>The null value, denoted as
<literal>null</literal>.</para></listitem>
</itemizedlist>
</para>
</simplesect>
<simplesect><title>Lists</title>
<para>Lists are formed by enclosing a whitespace-separated list of
values between square brackets. For example,
<programlisting>
[ 123 ./foo.nix "abc" (f { x = y; }) ]</programlisting>
defines a list of four elements, the last being the result of a call
to the function <varname>f</varname>. Note that function calls have
to be enclosed in parentheses. If they had been omitted, e.g.,
<programlisting>
[ 123 ./foo.nix "abc" f { x = y; } ]</programlisting>
the result would be a list of five elements, the fourth one being a
function and the fifth being a set.</para>
</simplesect>
<simplesect><title>Sets</title>
<para>Sets are really the core of the language, since ultimately the
Nix language is all about creating derivations, which are really just
sets of attributes to be passed to build scripts.</para>
<para>Sets are just a list of name/value pairs (called
<emphasis>attributes</emphasis>) enclosed in curly brackets, where
each value is an arbitrary expression terminated by a semicolon. For
example:
<programlisting>
{ x = 123;
text = "Hello";
y = f { bla = 456; };
}</programlisting>
This defines a set with attributes named <varname>x</varname>,
<varname>text</varname>, <varname>y</varname>. The order of the
attributes is irrelevant. An attribute name may only occur
once.</para>
<para>Attributes can be selected from a set using the
<literal>.</literal> operator. For instance,
<programlisting>
{ a = "Foo"; b = "Bar"; }.a</programlisting>
evaluates to <literal>"Foo"</literal>. It is possible to provide a
default value in an attribute selection using the
<literal>or</literal> keyword. For example,
<programlisting>
{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"</programlisting>
will evaluate to <literal>"Xyzzy"</literal> because there is no
<varname>c</varname> attribute in the set.</para>
<para>You can use arbitrary double-quoted strings as attribute
names:
<programlisting>
{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}"
</programlisting>
This will evaluate to <literal>123</literal> (Assuming
<literal>bar</literal> is antiquotable). In the case where an
attribute name is just a single antiquotation, the quotes can be
dropped:
<programlisting>
{ foo = 123; }.${bar} or 456 </programlisting>
This will evaluate to <literal>123</literal> if
<literal>bar</literal> evaluates to <literal>"foo"</literal> when
coerced to a string and <literal>456</literal> otherwise (again
assuming <literal>bar</literal> is antiquotable).</para>
<para>In the special case where an attribute name inside of a set declaration
evaluates to <literal>null</literal> (which is normally an error, as
<literal>null</literal> is not antiquotable), that attribute is simply not
added to the set:
<programlisting>
{ ${if foo then "bar" else null} = true; }</programlisting>
This will evaluate to <literal>{}</literal> if <literal>foo</literal>
evaluates to <literal>false</literal>.</para>
</simplesect>
</section>

86
doc/manual/expressions/simple-building-testing.xml Normal file
View file

@ -0,0 +1,86 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='sec-building-simple'>
<title>Building and Testing</title>
<para>You can now try to build Hello. Of course, you could do
<literal>nix-env -f pkgs/top-level/all-packages.nix -i hello</literal>,
but you may not want to install a possibly broken package just yet.
The best way to test the package is by using the command <command
linkend="sec-nix-build">nix-build</command>, which builds a Nix
expression and creates a symlink named <filename>result</filename> in
the current directory:
<screen>
$ nix-build 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
<replaceable>...</replaceable>
$ ls -l result
lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1
$ ./result/bin/hello
Hello, world!</screen>
The <link linkend='opt-attr'><option>-A</option></link> option selects
the <literal>hello</literal> attribute from
<filename>all-packages.nix</filename>. This is faster than using the
symbolic package name specified by the <literal>name</literal>
attribute (which also happens to be <literal>hello</literal>) and is
unambiguous (there can be multiple packages with the symbolic name
<literal>hello</literal>, but there can be only one attribute in a set
named <literal>hello</literal>).</para>
<para><command>nix-build</command> registers the
<filename>./result</filename> symlink as a garbage collection root, so
unless and until you delete the <filename>./result</filename> symlink,
the output of the build will be safely kept on your system. You can
use <command>nix-build</command>’s <option
linkend='opt-out-link'>-o</option> switch to give the symlink another
name.</para>
<para>Nix has a transactional semantics. Once a build finishes
successfully, Nix makes a note of this in its database: it registers
that the path denoted by <envar>out</envar> is now
<quote>valid</quote>. If you try to build the derivation again, Nix
will see that the path is already valid and finish immediately. If a
build fails, either because it returns a non-zero exit code, because
Nix or the builder are killed, or because the machine crashes, then
the output paths will not be registered as valid. If you try to build
the derivation again, Nix will remove the output paths if they exist
(e.g., because the builder died half-way through <literal>make
install</literal>) and try again. Note that there is no
<quote>negative caching</quote>: Nix doesn't remember that a build
failed, and so a failed build can always be repeated. This is because
Nix cannot distinguish between permanent failures (e.g., a compiler
error due to a syntax error in the source) and transient failures
(e.g., a disk full condition).</para>
<para>Nix also performs locking. If you run multiple Nix builds
simultaneously, and they try to build the same derivation, the first
Nix instance that gets there will perform the build, while the others
block (or perform other derivations if available) until the build
finishes:
<screen>
$ nix-build pkgs/top-level/all-packages.nix -A hello
waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x'</screen>
So it is always safe to run multiple instances of Nix in parallel
(which isn’t the case with, say, <command>make</command>).</para>
<para>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 <link linkend='opt-max-jobs'><option>-j
<replaceable>N</replaceable></option></link>, where
<replaceable>N</replaceable> is the maximum number of jobs to be run
in parallel, or set. Typically this should be the number of
CPUs.</para>
</section>

47
doc/manual/expressions/simple-expression.xml Normal file
View file

@ -0,0 +1,47 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-simple-expression">
<title>Simple Nix Expression Use-Case</title>
<para>This section shows how to add and test the <link
xlink:href='http://www.gnu.org/software/hello/hello.html'>GNU Hello
package</link> to the Nix Packages collection. Hello is a program
that prints out the text <quote>Hello, world!</quote>.</para>
<para>To add a package to the Nix Packages collection, you generally
need to do three things:
<orderedlist>
<listitem><para>Write a Nix expression for the package. This is a
file that describes all the inputs involved in building the package,
such as dependencies, sources, and so on.</para></listitem>
<listitem><para>Write a <emphasis>builder</emphasis>. This is a
shell script<footnote><para>In fact, it can be written in any
language, but typically it's a <command>bash</command> shell
script.</para></footnote> that actually builds the package from
the inputs.</para></listitem>
<listitem><para>Add the package to the file
<filename>pkgs/top-level/all-packages.nix</filename>. The Nix
expression written in the first step is a
<emphasis>function</emphasis>; it requires other packages in order
to build it. In this step you put it all together, i.e., you call
the function with the right arguments to build the actual
package.</para></listitem>
</orderedlist>
</para>
<xi:include href="expression-syntax.xml" />
<xi:include href="build-script.xml" />
<xi:include href="arguments-variables.xml" />
<xi:include href="simple-building-testing.xml" />
<xi:include href="generic-builder.xml" />
</chapter>

60
doc/manual/expressions/standard-env.xml Normal file
View file

@ -0,0 +1,60 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='sec-standard-environment'>
<title>The Standard Environment</title>
<para>The standard environment is used by passing it as an input
called <envar>stdenv</envar> to the derivation, and then doing
<programlisting>
source $stdenv/setup</programlisting>
at the top of the builder.</para>
<para>Apart from adding the aforementioned commands to the
<envar>PATH</envar>, <filename>setup</filename> also does the
following:
<itemizedlist>
<listitem><para>All input packages specified in the
<envar>buildInputs</envar> environment variable have their
<filename>/bin</filename> subdirectory added to <envar>PATH</envar>,
their <filename>/include</filename> subdirectory added to the C/C++
header file search path, and their <filename>/lib</filename>
subdirectory added to the linker search path. This can be extended.
For instance, when the <command>pkgconfig</command> package is
used, the subdirectory <filename>/lib/pkgconfig</filename> of each
input is added to the <envar>PKG_CONFIG_PATH</envar> environment
variable.</para></listitem>
<listitem><para>The environment variable
<envar>NIX_CFLAGS_STRIP</envar> is set so that the compiler strips
debug information from object files. This can be disabled by
setting <envar>NIX_STRIP_DEBUG</envar> to
<literal>0</literal>.</para></listitem>
</itemizedlist>
</para>
<para>The <filename>setup</filename> script also exports a function
called <function>genericBuild</function> 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
<function>genericBuild</function> since it provides facilities that
are almost always useful such as unpacking of sources, patching of
sources, nested logging, etc.</para>
<para>The definitive, up-to-date documentation of the generic builder
is the source itself, which resides in
<filename>pkgs/stdenv/generic/setup.sh</filename>.</para>
<xi:include href="custom-builder.xml" />
<xi:include href="debug-build.xml" />
</chapter>

27
doc/manual/expressions/writing-nix-expressions.xml Normal file
View file

@ -0,0 +1,27 @@
<part xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='chap-writing-nix-expressions'>
<title>Nix Expressions</title>
<partintro>
<para>This chapter shows you how to write Nix expressions, which
instruct Nix how to build packages. It starts with a
simple example (a Nix expression for GNU Hello), and then moves
on to a more in-depth look at the Nix expression language.</para>
<note><para>This chapter is mostly about the Nix expression language.
For more extensive information on adding packages to the Nix Packages
collection (such as functions in the standard environment and coding
conventions), please consult <link
xlink:href="http://nixos.org/nixpkgs/manual/">its
manual</link>.</para></note>
</partintro>
<xi:include href="simple-expression.xml" />
<xi:include href="expression-language.xml" />
<xi:include href="standard-env.xml" />
</part>

0
doc/manual/glossary.xml → doc/manual/glossary/glossary.xml
View file

447
doc/manual/installation.xml
View file

@ -1,447 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id="chap-installation">
<title>Installation</title>
<section><title>Supported platforms</title>
<para>Nix is currently supported on the following platforms:
<itemizedlist>
<listitem><para>Linux (particularly on x86, x86_64, and
PowerPC).</para></listitem>
<listitem><para>Mac OS X.</para></listitem>
<listitem><para>FreeBSD (only tested on Intel).</para></listitem>
<!--
<listitem><para>Windows through <link
xlink:href="http://www.cygwin.com/">Cygwin</link>.</para>
<warning><para>On Cygwin, Nix <emphasis>must</emphasis> be installed
on an NTFS partition. It will not work correctly on a FAT
partition.</para></warning>
</listitem>
-->
</itemizedlist>
</para>
<para>Nix is pretty portable, so it should work on most other Unix
platforms as well.</para>
</section>
<section><title>Installing a binary distribution</title>
<para>The easiest way to install Nix is to run the following:
<screen>
$ bash &lt;(curl https://nixos.org/nix/install)
</screen>
This will perform a single-user installation of Nix, meaning that
<filename>/nix</filename> is owned by the invoking user. You should
run this under your usual user account, <emphasis>not</emphasis> as
root. The script will invoke <command>sudo</command> to create
<filename>/nix</filename> if it doesn’t already exist. If you don’t
have <command>sudo</command>, you should manually create
<command>/nix</command> first as root:
<screen>
$ mkdir /nix
$ chown alice /nix
</screen>
</para>
<para>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 <link
xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>.
You can also get builds of the latest development release from our
<link
xlink:href="http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents">continuous
build system</link>.</para>
<para>For Fedora, RPM packages are available. These can be installed
or upgraded using <command>rpm -U</command>. For example,
<screen>
$ rpm -U nix-1.7-1.i386.rpm</screen>
</para>
<para>For Debian and Ubuntu, you can download a Deb package and
install it like this:
<screen>
$ dpkg -i nix_1.7-1_amd64.deb</screen>
</para>
<para>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 <uri>https://nixos.org/nix/install</uri> uses.) You should
unpack it somewhere (e.g. in <filename>/tmp</filename>), and then run
the script named <command>install</command> inside the binary tarball:
<screen>
alice$ cd /tmp
alice$ tar xfj nix-1.7-x86_64-darwin.tar.bz2
alice$ cd nix-1.7-x86_64-darwin
alice$ ./install
</screen>
</para>
<para>Nix can be uninstalled using <command>rpm -e nix</command> or
<command>dpkg -r nix</command> on RPM- and Dpkg-based systems,
respectively. After this you should manually remove the Nix store and
other auxiliary data, if desired:
<screen>
$ rm -rf /nix</screen>
</para>
</section>
<section><title>Installing Nix from source</title>
<para>If no binary package is available, you can download and compile
a source distribution.</para>
<section><title>Prerequisites</title>
<itemizedlist>
<listitem><para>GNU Make.</para></listitem>
<listitem><para>A version of GCC or Clang that supports C++11.</para></listitem>
<listitem><para>Perl 5.8 or higher.</para></listitem>
<listitem><para><command>pkg-config</command> to locate
dependencies. If your distribution does not provide it, you can get
it from <link
xlink:href="http://www.freedesktop.org/wiki/Software/pkg-config"
/>.</para></listitem>
<listitem><para>The bzip2 compressor program and the
<literal>libbz2</literal> library. Thus you must have bzip2
installed, including development headers and libraries. If your
distribution does not provide these, you can obtain bzip2 from <link
xlink:href="http://www.bzip.org/"/>.</para></listitem>
<listitem><para>The SQLite embedded database library, version 3.6.19
or higher. If your distribution does not provide it, please install
it from <link xlink:href="http://www.sqlite.org/" />.</para></listitem>
<listitem><para>The Perl DBI and DBD::SQLite libraries, which are
available from <link
xlink:href="http://search.cpan.org/">CPAN</link> if your
distribution does not provide them.</para></listitem>
<listitem><para>The <link
xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm
garbage collector</link> to reduce the evaluator’s memory
consumption (optional). To enable it, install
<literal>pkgconfig</literal> and the Boehm garbage collector, and
pass the flag <option>--enable-gc</option> to
<command>configure</command>.</para></listitem>
<listitem><para>The <command>xmllint</command> and
<command>xsltproc</command> programs to build this manual and the
man-pages. These are part of the <literal>libxml2</literal> and
<literal>libxslt</literal> packages, respectively. You also need
the <link
xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook
XSL stylesheets</link> and optionally the <link
xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG
schemas</link>. Note that these are only required if you modify the
manual sources or when you are building from the Git
repository.</para></listitem>
<listitem><para>Recent versions of Bison and Flex to build the
parser. (This is because Nix needs GLR support in Bison and
reentrancy support in Flex.) For Bison, you need version 2.6, which
can be obtained from the <link
xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP
server</link>. For Flex, you need version 2.5.35, which is
available on <link
xlink:href="http://lex.sourceforge.net/">SourceForge</link>.
Slightly older versions may also work, but ancient versions like the
ubiquitous 2.5.4a won't. Note that these are only required if you
modify the parser or when you are building from the Git
repository.</para></listitem>
</itemizedlist>
</section>
<section><title>Obtaining a source distribution</title>
<para>The source tarball of the most recent stable release can be
downloaded from the <link
xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>.
You can also grab the <link
xlink:href="http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents">most
recent development release</link>.</para>
<para>Alternatively, the most recent sources of Nix can be obtained
from its <link
xlink:href="https://github.com/NixOS/nix">Git
repository</link>. For example, the following command will check out
the latest revision into a directory called
<filename>nix</filename>:</para>
<screen>
$ git clone https://github.com/NixOS/nix</screen>
<para>Likewise, specific releases can be obtained from the <link
xlink:href="https://github.com/NixOS/nix/tags">tags</link> of the
repository.</para>
</section>
<section><title>Building Nix from source</title>
<para>After unpacking or checking out the Nix sources, issue the
following commands:
<screen>
$ ./configure <replaceable>options...</replaceable>
$ make
$ make install</screen>
Nix requires GNU Make so you may need to invoke
<command>gmake</command> instead.</para>
<para>When building from the Git repository, these should be preceded
by the command:
<screen>
$ ./bootstrap.sh</screen>
</para>
<para>The installation path can be specified by passing the
<option>--prefix=<replaceable>prefix</replaceable></option> to
<command>configure</command>. The default installation directory is
<filename>/usr/local</filename>. You can change this to any location
you like. You must have write permission to the
<replaceable>prefix</replaceable> path.</para>
<para>Nix keeps its <emphasis>store</emphasis> (the place where
packages are stored) in <filename>/nix/store</filename> by default.
This can be changed using
<option>--with-store-dir=<replaceable>path</replaceable></option>.</para>
<warning><para>It is best <emphasis>not</emphasis> to change the Nix
store from its default, since doing so makes it impossible to use
pre-built binaries from the standard Nixpkgs channels — that is, all
packages will need to be built from source.</para></warning>
<para>Nix keeps state (such as its database and log files) in
<filename>/nix/var</filename> by default. This can be changed using
<option>--localstatedir=<replaceable>path</replaceable></option>.</para>
<para>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
<option>--with-docbook-rng=<replaceable>path</replaceable></option>
and
<option>--with-docbook-xsl=<replaceable>path</replaceable></option>
options.</para>
</section>
</section>
<!-- TODO: should be updated
<section><title>Upgrading Nix through Nix</title>
<para>You can install the latest stable version of Nix through Nix
itself by subscribing to the channel <link
xlink:href="http://nixos.org/releases/nix/channels/nix-stable" />,
or the latest unstable version by subscribing to the channel <link
xlink:href="http://nixos.org/releases/nix/channels/nix-unstable" />.
You can also do a <link linkend="sec-one-click">one-click
installation</link> by clicking on the package links at <link
xlink:href="http://nixos.org/releases/full-index-nix.html" />.</para>
</section>
-->
<section><title>Security</title>
<para>Nix has two basic security models. First, it can be used in
“single-user mode”, which is similar to what most other package
management tools do: there is a single user (typically <systemitem
class="username">root</systemitem>) who performs all package
management operations. All other users can then use the installed
packages, but they cannot perform package management operations
themselves.</para>
<para>Alternatively, you can configure Nix in “multi-user mode”. In
this model, all users can perform package management operations — for
instance, every user can install software without requiring root
privileges. Nix ensures that this is secure. For instance, it’s not
possible for one user to overwrite a package used by another user with
a Trojan horse.</para>
<section><title>Single-user mode</title>
<para>In single-user mode, all Nix operations that access the database
in <filename><replaceable>prefix</replaceable>/var/nix/db</filename>
or modify the Nix store in
<filename><replaceable>prefix</replaceable>/store</filename> must be
performed under the user ID that owns those directories. This is
typically <systemitem class="username">root</systemitem>. (If you
install from RPM packages, that’s in fact the default ownership.)
However, on single-user machines, it is often convenient to
<command>chown</command> those directories to your normal user account
so that you don’t have to <command>su</command> to <systemitem
class="username">root</systemitem> all the time.</para>
</section>
<section xml:id="ssec-multi-user"><title>Multi-user mode</title>
<para>To allow a Nix store to be shared safely among multiple users,
it is important that users are not able to run builders that modify
the Nix store or database in arbitrary ways, or that interfere with
builds started by other users. If they could do so, they could
install a Trojan horse in some package and compromise the accounts of
other users.</para>
<para>To prevent this, the Nix store and database are owned by some
privileged user (usually <literal>root</literal>) and builders are
executed under special user accounts (usually named
<literal>nixbld1</literal>, <literal>nixbld2</literal>, etc.). When a
unprivileged user runs a Nix command, actions that operate on the Nix
store (such as builds) are forwarded to a <emphasis>Nix
daemon</emphasis> running under the owner of the Nix store/database
that performs the operation.</para>
<note><para>Multi-user mode has one important limitation: only
<systemitem class="username">root</systemitem> can run <command
linkend="sec-nix-pull">nix-pull</command> to register the availability
of pre-built binaries. However, those registrations are shared by all
users, so they still get the benefit from <command>nix-pull</command>s
done by <systemitem class="username">root</systemitem>.</para></note>
<section><title>Setting up the build users</title>
<para>The <emphasis>build users</emphasis> are the special UIDs under
which builds are performed. They should all be members of the
<emphasis>build users group</emphasis> <literal>nixbld</literal>.
This group should have no other members. The build users should not
be members of any other group. On Linux, you can create the group and
users as follows:
<screen>
$ groupadd -r nixbld
$ for n in $(seq 1 10); do useradd -c "Nix build user $n" \
-d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \
nixbld$n; done
</screen>
This creates 10 build users. There can never be more concurrent builds
than the number of build users, so you may want to increase this if
you expect to do many builds at the same time.</para>
</section>
<section><title>Running the daemon</title>
<para>The <link linkend="sec-nix-daemon">Nix daemon</link> should be
started as follows (as <literal>root</literal>):
<screen>
$ nix-daemon</screen>
You’ll want to put that line somewhere in your system’s boot
scripts.</para>
<para>To let unprivileged users use the daemon, they should set the
<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment
variable</link> to <literal>daemon</literal>. So you should put a
line like
<programlisting>
export NIX_REMOTE=daemon</programlisting>
into the users’ login scripts.</para>
</section>
<section><title>Restricting access</title>
<para>To limit which users can perform Nix operations, you can use the
permissions on the directory
<filename>/nix/var/nix/daemon-socket</filename>. For instance, if you
want to restrict the use of Nix to the members of a group called
<literal>nix-users</literal>, do
<screen>
$ chgrp nix-users /nix/var/nix/daemon-socket
$ chmod ug=rwx,o= /nix/var/nix/daemon-socket
</screen>
This way, users who are not in the <literal>nix-users</literal> group
cannot connect to the Unix domain socket
<filename>/nix/var/nix/daemon-socket/socket</filename>, so they cannot
perform Nix operations.</para>
</section>
</section> <!-- end of multi-user -->
</section> <!-- end of security -->
<section><title>Using Nix</title>
<para>To use Nix, some environment variables should be set. In
particular, <envar>PATH</envar> should contain the directories
<filename><replaceable>prefix</replaceable>/bin</filename> and
<filename>~/.nix-profile/bin</filename>. The first directory contains
the Nix tools themselves, while <filename>~/.nix-profile</filename> is
a symbolic link to the current <emphasis>user environment</emphasis>
(an automatically generated package consisting of symlinks to
installed packages). The simplest way to set the required environment
variables is to include the file
<filename><replaceable>prefix</replaceable>/etc/profile.d/nix.sh</filename>
in your <filename>~/.profile</filename> (or similar), like this:</para>
<screen>
source <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen>
</section>
</chapter>

57
doc/manual/installation/building-source.xml Normal file
View file

@ -0,0 +1,57 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-building-source">
<title>Building Nix from Source</title>
<para>After unpacking or checking out the Nix sources, issue the
following commands:
<screen>
$ ./configure <replaceable>options...</replaceable>
$ make
$ make install</screen>
Nix requires GNU Make so you may need to invoke
<command>gmake</command> instead.</para>
<para>When building from the Git repository, these should be preceded
by the command:
<screen>
$ ./bootstrap.sh</screen>
</para>
<para>The installation path can be specified by passing the
<option>--prefix=<replaceable>prefix</replaceable></option> to
<command>configure</command>. The default installation directory is
<filename>/usr/local</filename>. You can change this to any location
you like. You must have write permission to the
<replaceable>prefix</replaceable> path.</para>
<para>Nix keeps its <emphasis>store</emphasis> (the place where
packages are stored) in <filename>/nix/store</filename> by default.
This can be changed using
<option>--with-store-dir=<replaceable>path</replaceable></option>.</para>
<warning><para>It is best <emphasis>not</emphasis> to change the Nix
store from its default, since doing so makes it impossible to use
pre-built binaries from the standard Nixpkgs channels — that is, all
packages will need to be built from source.</para></warning>
<para>Nix keeps state (such as its database and log files) in
<filename>/nix/var</filename> by default. This can be changed using
<option>--localstatedir=<replaceable>path</replaceable></option>.</para>
<para>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
<option>--with-docbook-rng=<replaceable>path</replaceable></option>
and
<option>--with-docbook-xsl=<replaceable>path</replaceable></option>
options.</para>
</section>

24
doc/manual/installation/env-variables.xml Normal file
View file

@ -0,0 +1,24 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-env-variables">
<title>Environment Variables</title>
<para>To use Nix, some environment variables should be set. In
particular, <envar>PATH</envar> should contain the directories
<filename><replaceable>prefix</replaceable>/bin</filename> and
<filename>~/.nix-profile/bin</filename>. The first directory contains
the Nix tools themselves, while <filename>~/.nix-profile</filename> is
a symbolic link to the current <emphasis>user environment</emphasis>
(an automatically generated package consisting of symlinks to
installed packages). The simplest way to set the required environment
variables is to include the file
<filename><replaceable>prefix</replaceable>/etc/profile.d/nix.sh</filename>
in your <filename>~/.profile</filename> (or similar), like this:</para>
<screen>
source <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen>
</chapter>

34
doc/manual/installation/installation.xml Normal file
View file

@ -0,0 +1,34 @@
<part xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="chap-installation">
<title>Installation</title>
<partintro>
<para>This section describes how to install and configure Nix for first-time use.</para>
</partintro>
<xi:include href="supported-platforms.xml" />
<xi:include href="installing-binary.xml" />
<xi:include href="installing-source.xml" />
<xi:include href="nix-security.xml" />
<xi:include href="env-variables.xml" />
<!-- TODO: should be updated
<section><title>Upgrading Nix through Nix</title>
<para>You can install the latest stable version of Nix through Nix
itself by subscribing to the channel <link
xlink:href="http://nixos.org/releases/nix/channels/nix-stable" />,
or the latest unstable version by subscribing to the channel <link
xlink:href="http://nixos.org/releases/nix/channels/nix-unstable" />.
You can also do a <link linkend="sec-one-click">one-click
installation</link> by clicking on the package links at <link
xlink:href="http://nixos.org/releases/full-index-nix.html" />.</para>
</section>
-->
</part>

81
doc/manual/installation/installing-binary.xml Normal file
View file

@ -0,0 +1,81 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-installing-binary">
<title>Installing a Binary Distribution</title>
<para>The easiest way to install Nix is to run the following command:
<screen>
$ bash &lt;(curl https://nixos.org/nix/install)
</screen>
This will perform a single-user installation of Nix, meaning that
<filename>/nix</filename> is owned by the invoking user. You should
run this under your usual user account, <emphasis>not</emphasis> as
root. The script will invoke <command>sudo</command> to create
<filename>/nix</filename> if it doesn’t already exist. If you don’t
have <command>sudo</command>, you should manually create
<command>/nix</command> first as root:
<screen>
$ mkdir /nix
$ chown alice /nix
</screen>
</para>
<para>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 <link
xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>.
You can also get builds of the latest development release from our
<link
xlink:href="http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents">continuous
build system</link>.</para>
<para>For Fedora, RPM packages are available. These can be installed
or upgraded using <command>rpm -U</command>. For example,
<screen>
$ rpm -U nix-1.7-1.i386.rpm</screen>
</para>
<para>For Debian and Ubuntu, you can download a Deb package and
install it like this:
<screen>
$ dpkg -i nix_1.7-1_amd64.deb</screen>
</para>
<para>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 <uri>https://nixos.org/nix/install</uri> uses.) You should
unpack it somewhere (e.g. in <filename>/tmp</filename>), and then run
the script named <command>install</command> inside the binary tarball:
<screen>
alice$ cd /tmp
alice$ tar xfj nix-1.7-x86_64-darwin.tar.bz2
alice$ cd nix-1.7-x86_64-darwin
alice$ ./install
</screen>
</para>
<para>Nix can be uninstalled using <command>rpm -e nix</command> or
<command>dpkg -r nix</command> on RPM- and Dpkg-based systems,
respectively. After this you should manually remove the Nix store and
other auxiliary data, if desired:
<screen>
$ rm -rf /nix</screen>
</para>
</chapter>

17
doc/manual/installation/installing-source.xml Normal file
View file

@ -0,0 +1,17 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-installing-source">
<title>Installing Nix from Source</title>
<para>If no binary package is available, you can download and compile
a source distribution.</para>
<xi:include href="prerequisites-source.xml" />
<xi:include href="obtaining-source.xml" />
<xi:include href="installing-source.xml" />
<xi:include href="building-source.xml" />
</chapter>

106
doc/manual/installation/multi-user.xml Normal file
View file

@ -0,0 +1,106 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-multi-user">
<title>Multi-User Mode</title>
<para>To allow a Nix store to be shared safely among multiple users,
it is important that users are not able to run builders that modify
the Nix store or database in arbitrary ways, or that interfere with
builds started by other users. If they could do so, they could
install a Trojan horse in some package and compromise the accounts of
other users.</para>
<para>To prevent this, the Nix store and database are owned by some
privileged user (usually <literal>root</literal>) and builders are
executed under special user accounts (usually named
<literal>nixbld1</literal>, <literal>nixbld2</literal>, etc.). When a
unprivileged user runs a Nix command, actions that operate on the Nix
store (such as builds) are forwarded to a <emphasis>Nix
daemon</emphasis> running under the owner of the Nix store/database
that performs the operation.</para>
<note>Multi-user mode has one important limitation: only
<systemitem class="username">root</systemitem> can run <command
linkend="sec-nix-pull">nix-pull</command> to register the availability
of pre-built binaries. However, those registrations are shared by all
users, so they still get the benefit from <command>nix-pull</command>s
done by <systemitem class="username">root</systemitem>.</note>
<simplesect>
<title>Setting up the build users</title>
<para>The <emphasis>build users</emphasis> are the special UIDs under
which builds are performed. They should all be members of the
<emphasis>build users group</emphasis> <literal>nixbld</literal>.
This group should have no other members. The build users should not
be members of any other group. On Linux, you can create the group and
users as follows:
<screen>
$ groupadd -r nixbld
$ for n in $(seq 1 10); do useradd -c "Nix build user $n" \
-d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \
nixbld$n; done
</screen>
This creates 10 build users. There can never be more concurrent builds
than the number of build users, so you may want to increase this if
you expect to do many builds at the same time.</para>
</simplesect>
<simplesect>
<title>Running the daemon</title>
<para>The <link linkend="sec-nix-daemon">Nix daemon</link> should be
started as follows (as <literal>root</literal>):
<screen>
$ nix-daemon</screen>
You’ll want to put that line somewhere in your system’s boot
scripts.</para>
<para>To let unprivileged users use the daemon, they should set the
<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment
variable</link> to <literal>daemon</literal>. So you should put a
line like
<programlisting>
export NIX_REMOTE=daemon</programlisting>
into the users’ login scripts.</para>
</simplesect>
<simplesect>
<title>Restricting access</title>
<para>To limit which users can perform Nix operations, you can use the
permissions on the directory
<filename>/nix/var/nix/daemon-socket</filename>. For instance, if you
want to restrict the use of Nix to the members of a group called
<literal>nix-users</literal>, do
<screen>
$ chgrp nix-users /nix/var/nix/daemon-socket
$ chmod ug=rwx,o= /nix/var/nix/daemon-socket
</screen>
This way, users who are not in the <literal>nix-users</literal> group
cannot connect to the Unix domain socket
<filename>/nix/var/nix/daemon-socket/socket</filename>, so they cannot
perform Nix operations.</para>
</simplesect>
</section>

27
doc/manual/installation/nix-security.xml Normal file
View file

@ -0,0 +1,27 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-nix-security">
<title>Security</title>
<para>Nix has two basic security models. First, it can be used in
“single-user mode”, which is similar to what most other package
management tools do: there is a single user (typically <systemitem
class="username">root</systemitem>) who performs all package
management operations. All other users can then use the installed
packages, but they cannot perform package management operations
themselves.</para>
<para>Alternatively, you can configure Nix in “multi-user mode”. In
this model, all users can perform package management operations — for
instance, every user can install software without requiring root
privileges. Nix ensures that this is secure. For instance, it’s not
possible for one user to overwrite a package used by another user with
a Trojan horse.</para>
<xi:include href="single-user.xml" />
<xi:include href="multi-user.xml" />
</chapter>

30
doc/manual/installation/obtaining-source.xml Normal file
View file

@ -0,0 +1,30 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-obtaining-source">
<title>Obtaining a Source Distribution</title>
<para>The source tarball of the most recent stable release can be
downloaded from the <link
xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>.
You can also grab the <link
xlink:href="http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents">most
recent development release</link>.</para>
<para>Alternatively, the most recent sources of Nix can be obtained
from its <link
xlink:href="https://github.com/NixOS/nix">Git
repository</link>. For example, the following command will check out
the latest revision into a directory called
<filename>nix</filename>:</para>
<screen>
$ git clone https://github.com/NixOS/nix</screen>
<para>Likewise, specific releases can be obtained from the <link
xlink:href="https://github.com/NixOS/nix/tags">tags</link> of the
repository.</para>
</section>

73
doc/manual/installation/prerequisites-source.xml Normal file
View file

@ -0,0 +1,73 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-prerequisites-source">
<title>Prerequisites</title>
<itemizedlist>
<listitem><para>GNU Make.</para></listitem>
<listitem><para>A version of GCC or Clang that supports C++11.</para></listitem>
<listitem><para>Perl 5.8 or higher.</para></listitem>
<listitem><para><command>pkg-config</command> to locate
dependencies. If your distribution does not provide it, you can get
it from <link
xlink:href="http://www.freedesktop.org/wiki/Software/pkg-config"
/>.</para></listitem>
<listitem><para>The bzip2 compressor program and the
<literal>libbz2</literal> library. Thus you must have bzip2
installed, including development headers and libraries. If your
distribution does not provide these, you can obtain bzip2 from <link
xlink:href="http://www.bzip.org/"/>.</para></listitem>
<listitem><para>The SQLite embedded database library, version 3.6.19
or higher. If your distribution does not provide it, please install
it from <link xlink:href="http://www.sqlite.org/" />.</para></listitem>
<listitem><para>The Perl DBI and DBD::SQLite libraries, which are
available from <link
xlink:href="http://search.cpan.org/">CPAN</link> if your
distribution does not provide them.</para></listitem>
<listitem><para>The <link
xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm
garbage collector</link> to reduce the evaluator’s memory
consumption (optional). To enable it, install
<literal>pkgconfig</literal> and the Boehm garbage collector, and
pass the flag <option>--enable-gc</option> to
<command>configure</command>.</para></listitem>
<listitem><para>The <command>xmllint</command> and
<command>xsltproc</command> programs to build this manual and the
man-pages. These are part of the <literal>libxml2</literal> and
<literal>libxslt</literal> packages, respectively. You also need
the <link
xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook
XSL stylesheets</link> and optionally the <link
xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG
schemas</link>. Note that these are only required if you modify the
manual sources or when you are building from the Git
repository.</para></listitem>
<listitem><para>Recent versions of Bison and Flex to build the
parser. (This is because Nix needs GLR support in Bison and
reentrancy support in Flex.) For Bison, you need version 2.6, which
can be obtained from the <link
xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP
server</link>. For Flex, you need version 2.5.35, which is
available on <link
xlink:href="http://lex.sourceforge.net/">SourceForge</link>.
Slightly older versions may also work, but ancient versions like the
ubiquitous 2.5.4a won't. Note that these are only required if you
modify the parser or when you are building from the Git
repository.</para></listitem>
</itemizedlist>
</section>

21
doc/manual/installation/single-user.xml Normal file
View file

@ -0,0 +1,21 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-single-user">
<title>Single-User Mode</title>
<para>In single-user mode, all Nix operations that access the database
in <filename><replaceable>prefix</replaceable>/var/nix/db</filename>
or modify the Nix store in
<filename><replaceable>prefix</replaceable>/store</filename> must be
performed under the user ID that owns those directories. This is
typically <systemitem class="username">root</systemitem>. (If you
install from RPM packages, that’s in fact the default ownership.)
However, on single-user machines, it is often convenient to
<command>chown</command> those directories to your normal user account
so that you don’t have to <command>su</command> to <systemitem
class="username">root</systemitem> all the time.</para>
</section>

38
doc/manual/installation/supported-platforms.xml Normal file
View file

@ -0,0 +1,38 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-supported-platforms">
<title>Supported Platforms</title>
<para>Nix is currently supported on the following platforms:
<itemizedlist>
<listitem><para>Linux (particularly on x86, x86_64, and
PowerPC).</para></listitem>
<listitem><para>Mac OS X.</para></listitem>
<listitem><para>FreeBSD (only tested on Intel).</para></listitem>
<!--
<listitem><para>Windows through <link
xlink:href="http://www.cygwin.com/">Cygwin</link>.</para>
<warning><para>On Cygwin, Nix <emphasis>must</emphasis> be installed
on an NTFS partition. It will not work correctly on a FAT
partition.</para></warning>
</listitem>
-->
</itemizedlist>
</para>
<para>Nix is pretty portable, so it should work on most other Unix
platforms as well.</para>
</chapter>

28
doc/manual/introduction.xml → doc/manual/introduction/about-nix.xml
View file

@ -1,11 +1,10 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id="chap-introduction">
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-about-nix">
<title>Introduction</title>
<section><title>About Nix</title>
<title>About Nix</title>
<para>Nix is a <emphasis>purely functional package manager</emphasis>.
This means that it treats packages like values in purely functional
@ -251,23 +250,4 @@ xlink:href="http://nixos.org/">NixOS homepage</link>.</para>
-->
</section>
<section><title>License</title>
<para>Nix is free software; you can redistribute it and/or modify it
under the terms of the <link
xlink:href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser General
Public License</link> as published by the <link
xlink:href="http://www.fsf.org/">Free Software Foundation</link>;
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.</para>
</section>
</chapter>

16
doc/manual/introduction/introduction.xml Normal file
View file

@ -0,0 +1,16 @@
<part xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="chap-introduction">
<title>Introduction</title>
<partintro>
<para>This section describes the main features of Nix and the license under which you can use Nix.</para>
</partintro>
<xi:include href="about-nix.xml" />
<xi:include href="nix-license.xml" />
</part>

20
doc/manual/introduction/nix-license.xml Normal file
View file

@ -0,0 +1,20 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-nix-license">
<title>License</title>
<para>Nix is free software; you can redistribute it and/or modify it
under the terms of the <link
xlink:href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser General
Public License</link> as published by the <link
xlink:href="http://www.fsf.org/">Free Software Foundation</link>;
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.</para>
</chapter>

71
doc/manual/manual.xml
View file

@ -1,9 +1,12 @@
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude">
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="NixManual">
<info>
<title>Nix User's Guide</title>
<title>Nix Package Manager Guide</title>
<edition>Version <xi:include href="version.txt" parse="text" /></edition>
@ -27,58 +30,30 @@
</info>
<preface>
<title>Preface</title>
<para>This manual describes how to set up and use Nix package manager and Nix expressions.</para>
</preface>
<xi:include href="introduction.xml" />
<xi:include href="quick-start.xml" />
<xi:include href="installation.xml" />
<xi:include href="package-management.xml" />
<xi:include href="writing-nix-expressions.xml" />
<xi:include href="build-farm.xml" />
<appendix>
<title>Command Reference</title>
<xi:include href="opt-common.xml" />
<xi:include href="env-common.xml" />
<section>
<title>Main commands</title>
<xi:include href="nix-env.xml" />
<xi:include href="nix-build.xml" />
<xi:include href="nix-shell.xml" />
<xi:include href="nix-store.xml" />
</section>
<section>
<title>Utilities</title>
<xi:include href="nix-channel.xml" />
<xi:include href="nix-collect-garbage.xml" />
<xi:include href="nix-copy-closure.xml" />
<xi:include href="nix-daemon.xml" />
<xi:include href="nix-hash.xml" />
<xi:include href="nix-install-package.xml" />
<xi:include href="nix-instantiate.xml" />
<xi:include href="nix-prefetch-url.xml" />
<xi:include href="nix-pull.xml" />
<xi:include href="nix-push.xml" />
</section>
<section>
<title>Files</title>
<xi:include href="conf-file.xml" />
</section>
</appendix>
<xi:include href="troubleshooting.xml" />
<xi:include href="introduction/introduction.xml" />
<xi:include href="quicks-start/quick-start.xml" />
<xi:include href="installation/installation.xml" />
<xi:include href="packages/package-management.xml" />
<xi:include href="expressions/writing-nix-expressions.xml" />
<xi:include href="builds/build-farm.xml" />
<xi:include href="command-ref/command-ref.xml" />
<xi:include href="troubleshooting/troubleshooting.xml" />
<!-- <xi:include href="bugs.xml" /> -->
<xi:include href="glossary.xml" />
<xi:include href="glossary/glossary.xml" />
<xi:include href="hacking.xml" />
<xi:include href="release-notes/release-notes.xml" />
<appendix>
<!--
<appendix>
<title>Nix Release Notes</title>
<xi:include href="release-notes.xml"
<xi:include href="release-notes/release-notes.xml"
xpointer="xmlns(x=http://docbook.org/ns/docbook)xpointer(x:article/x:section)" />
</appendix>
-->
</book>

591
doc/manual/package-management.xml
View file

@ -1,591 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id='chap-package-management'>
<title>Package Management</title>
<para>This chapter discusses how to do package management with Nix,
i.e., how to obtain, install, upgrade, and erase packages. This is
the “user’s” perspective of the Nix system — people
who want to <emphasis>create</emphasis> packages should consult
<xref linkend='chap-writing-nix-expressions' />.</para>
<section><title>Basic package management</title>
<para>The main command for package management is <link
linkend="sec-nix-env"><command>nix-env</command></link>. You can use
it to install, upgrade, and erase packages, and to query what
packages are installed or are available for installation.</para>
<para>In Nix, different users can have different “views”
on the set of installed applications. That is, there might be lots of
applications present on the system (possibly in many different
versions), but users can have a specific selection of those active —
where “active” just means that it appears in a directory
in the user’s <envar>PATH</envar>. Such a view on the set of
installed applications is called a <emphasis>user
environment</emphasis>, which is just a directory tree consisting of
symlinks to the files of the active applications. </para>
<para>Components are installed from a set of <emphasis>Nix
expressions</emphasis> that tell Nix how to build those packages,
including, if necessary, their dependencies. There is a collection of
Nix expressions called the 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 <link
xlink:href='http://nixos.org/nixpkgs/download.html' />.</para>
<para>Assuming that you have downloaded and unpacked a release of Nix
Packages, you can view the set of available packages in the release:
<screen>
$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> '*'
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
...</screen>
where <literal>nixpkgs-<replaceable>version</replaceable></literal> is
where you’ve unpacked the release. The flag <option>-q</option>
specifies a query operation; <option>-a</option> means that you want
to show the “available” (i.e., installable) packages, as opposed to
the installed packages; and <option>-f</option>
<filename>nixpkgs-<replaceable>version</replaceable></filename>
specifies the source of the packages. The argument
<literal>'*'</literal> shows all installable packages. (The quotes are
necessary to prevent shell expansion.) You can also select specific
packages by name:
<screen>
$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> gcc
gcc-3.4.6
gcc-4.0.3
gcc-4.1.1</screen>
</para>
<para>It is also possible to see the <emphasis>status</emphasis> of
available packages, i.e., whether they are installed into the user
environment and/or present in the system:
<screen>
$ nix-env -qasf nixpkgs-<replaceable>version</replaceable> '*'
...
-PS bash-3.0
--S binutils-2.15
IPS bison-1.875d
...</screen>
The first character (<literal>I</literal>) indicates whether the
package is installed in your current user environment. The second
(<literal>P</literal>) indicates whether it is present on your system
(in which case installing it into your user environment would be a
very quick operation). The last one (<literal>S</literal>) indicates
whether there is a so-called <emphasis>substitute</emphasis> for the
package, which is Nix’s mechanism for doing binary deployment. It
just means that Nix knows that it can fetch a pre-built package from
somewhere (typically a network server) instead of building it
locally.</para>
<para>So now that we have a set of Nix expressions we can build the
packages contained in them. This is done using <literal>nix-env
-i</literal>. For instance,
<screen>
$ nix-env -f nixpkgs-<replaceable>version</replaceable> -i subversion</screen>
will install the package called <literal>subversion</literal> (which
is, of course, the <link
xlink:href='http://subversion.tigris.org/'>Subversion version
management system</link>).</para>
<para>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
<command>nix-pull</command> command, which must be supplied with a URL
containing a <emphasis>manifest</emphasis> 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 <link
xlink:href='http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x'
/>, then you should do:
<screen>
$ nix-pull http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x/MANIFEST</screen>
If you then issue the installation command, it should start
downloading binaries from <systemitem
class='fqdomainname'>nixos.org</systemitem>, 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.</para>
<para>Naturally, packages can also be uninstalled:
<screen>
$ nix-env -e subversion</screen>
</para>
<para>Upgrading to a new version is just as easy. If you have a new
release of Nix Packages, you can do:
<screen>
$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u subversion</screen>
This will <emphasis>only</emphasis> upgrade Subversion if there is a
“newer” version in the new set of Nix expressions, as
defined by some pretty arbitrary rules regarding ordering of version
numbers (which generally do what you’d expect of them). To just
unconditionally replace Subversion with whatever version is in the Nix
expressions, use <parameter>-i</parameter> instead of
<parameter>-u</parameter>; <parameter>-i</parameter> will remove
whatever version is already installed.</para>
<para>You can also upgrade all packages for which there are newer
versions:
<screen>
$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u '*'</screen>
</para>
<para>Sometimes it’s useful to be able to ask what
<command>nix-env</command> would do, without actually doing it. For
instance, to find out what packages would be upgraded by
<literal>nix-env -u '*'</literal>, you can do
<screen>
$ nix-env ... -u '*' --dry-run
(dry run; not doing anything)
upgrading `libxslt-1.1.0' to `libxslt-1.1.10'
upgrading `graphviz-1.10' to `graphviz-1.12'
upgrading `coreutils-5.0' to `coreutils-5.2.1'</screen>
</para>
</section>
<section xml:id="sec-profiles"><title>Profiles</title>
<para>Profiles and user environments are Nix’s mechanism for
implementing the ability to allow different users to have different
configurations, and to do atomic upgrades and rollbacks. To
understand how they work, it’s useful to know a bit about how Nix
works. In Nix, packages are stored in unique locations in the
<emphasis>Nix store</emphasis> (typically,
<filename>/nix/store</filename>). For instance, a particular version
of the Subversion package might be stored in a directory
<filename>/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/</filename>,
while another version might be stored in
<filename>/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2</filename>.
The long strings prefixed to the directory names are cryptographic
hashes<footnote><para>160-bit truncations of SHA-256 hashes encoded in
a base-32 notation, to be precise.</para></footnote> of
<emphasis>all</emphasis> inputs involved in building the package —
sources, dependencies, compiler flags, and so on. So if two
packages differ in any way, they end up in different locations in
the file system, so they don’t interfere with each other. <xref
linkend='fig-user-environments' /> shows a part of a typical Nix
store.</para>
<figure xml:id='fig-user-environments'><title>User environments</title>
<mediaobject>
<imageobject>
<imagedata fileref='figures/user-environments.png' format='PNG' />
</imageobject>
</mediaobject>
</figure>
<para>Of course, you wouldn’t want to type
<screen>
$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn</screen>
every time you want to run Subversion. Of course we could set up the
<envar>PATH</envar> environment variable to include the
<filename>bin</filename> directory of every package we want to use,
but this is not very convenient since changing <envar>PATH</envar>
doesn’t take effect for already existing processes. The solution Nix
uses is to create directory trees of symlinks to
<emphasis>activated</emphasis> packages. These are called
<emphasis>user environments</emphasis> and they are packages
themselves (though automatically generated by
<command>nix-env</command>), so they too reside in the Nix store. For
instance, in <xref linkend='fig-user-environments' /> the user
environment <filename>/nix/store/0c1p5z4kda11...-user-env</filename>
contains a symlink to just Subversion 1.1.2 (arrows in the figure
indicate symlinks). This would be what we would obtain if we had done
<screen>
$ nix-env -i subversion</screen>
on a set of Nix expressions that contained Subversion 1.1.2.</para>
<para>This doesn’t in itself solve the problem, of course; you
wouldn’t want to type
<filename>/nix/store/0c1p5z4kda11...-user-env/bin/svn</filename>
either. That’s why there are symlinks outside of the store that point
to the user environments in the store; for instance, the symlinks
<filename>default-42-link</filename> and
<filename>default-43-link</filename> in the example. These are called
<emphasis>generations</emphasis> since every time you perform a
<command>nix-env</command> operation, a new user environment is
generated based on the current one. For instance, generation 43 was
created from generation 42 when we did
<screen>
$ nix-env -i subversion mozilla</screen>
on a set of Nix expressions that contained Mozilla and a new version
of Subversion.</para>
<para>Generations are grouped together into
<emphasis>profiles</emphasis> so that different users don’t interfere
with each other if they don’t want to. For example:
<screen>
$ ls -l /nix/var/nix/profiles/
...
lrwxrwxrwx 1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env
lrwxrwxrwx 1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env
lrwxrwxrwx 1 eelco ... default -> default-43-link</screen>
This shows a profile called <filename>default</filename>. The file
<filename>default</filename> itself is actually a symlink that points
to the current generation. When we do a <command>nix-env</command>
operation, a new user environment and generation link are created
based on the current one, and finally the <filename>default</filename>
symlink is made to point at the new generation. This last step is
atomic on Unix, which explains how we can do atomic upgrades. (Note
that the building/installing of new packages doesn’t interfere in
any way with old packages, since they are stored in different
locations in the Nix store.)</para>
<para>If you find that you want to undo a <command>nix-env</command>
operation, you can just do
<screen>
$ nix-env --rollback</screen>
which will just make the current generation link point at the previous
link. E.g., <filename>default</filename> would be made to point at
<filename>default-42-link</filename>. You can also switch to a
specific generation:
<screen>
$ nix-env --switch-generation 43</screen>
which in this example would roll forward to generation 43 again. You
can also see all available generations:
<screen>
$ nix-env --list-generations</screen></para>
<para>Actually, there is another level of indirection not shown in the
figure above. You generally wouldn’t have
<filename>/nix/var/nix/profiles/<replaceable>some-profile</replaceable>/bin</filename>
in your <envar>PATH</envar>. Rather, there is a symlink
<filename>~/.nix-profile</filename> that points to your current
profile. This means that you should put
<filename>~/.nix-profile/bin</filename> in your <envar>PATH</envar>
(and indeed, that’s what the initialisation script
<filename>/nix/etc/profile.d/nix.sh</filename> does). This makes it
easier to switch to a different profile. You can do that using the
command <command>nix-env --switch-profile</command>:
<screen>
$ nix-env --switch-profile /nix/var/nix/profiles/my-profile
$ nix-env --switch-profile /nix/var/nix/profiles/default</screen>
These commands switch to the <filename>my-profile</filename> and
default profile, respectively. If the profile doesn’t exist, it will
be created automatically. You should be careful about storing a
profile in another location than the <filename>profiles</filename>
directory, since otherwise it might not be used as a root of the
garbage collector (see <xref linkend='sec-garbage-collection'
/>).</para>
<para>All <command>nix-env</command> operations work on the profile
pointed to by <command>~/.nix-profile</command>, but you can override
this using the <option>--profile</option> option (abbreviation
<option>-p</option>):
<screen>
$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion</screen>
This will <emphasis>not</emphasis> change the
<command>~/.nix-profile</command> symlink.</para>
</section>
<section xml:id='sec-garbage-collection'><title>Garbage collection</title>
<para><command>nix-env</command> operations such as upgrades
(<option>-u</option>) and uninstall (<option>-e</option>) never
actually delete packages from the system. All they do (as shown
above) is to create a new user environment that no longer contains
symlinks to the “deleted” packages.</para>
<para>Of course, since disk space is not infinite, unused packages
should be removed at some point. You can do this by running the Nix
garbage collector. It will remove from the Nix store any package
not used (directly or indirectly) by any generation of any
profile.</para>
<para>Note however that as long as old generations reference a
package, it will not be deleted. After all, we wouldn’t be able to
do a rollback otherwise. So in order for garbage collection to be
effective, you should also delete (some) old generations. Of course,
this should only be done if you are certain that you will not need to
roll back.</para>
<para>To delete all old (non-current) generations of your current
profile:
<screen>
$ nix-env --delete-generations old</screen>
Instead of <literal>old</literal> you can also specify a list of
generations, e.g.,
<screen>
$ nix-env --delete-generations 10 11 14</screen>
</para>
<para>After removing appropriate old generations you can run the
garbage collector as follows:
<screen>
$ nix-store --gc</screen>
If you are feeling uncertain, you can also first view what files would
be deleted:
<screen>
$ nix-store --gc --print-dead</screen>
Likewise, the option <option>--print-live</option> will show the paths
that <emphasis>won’t</emphasis> be deleted.</para>
<para>There is also a convenient little utility
<command>nix-collect-garbage</command>, which when invoked with the
<option>-d</option> (<option>--delete-old</option>) switch deletes all
old generations of all profiles in
<filename>/nix/var/nix/profiles</filename>. So
<screen>
$ nix-collect-garbage -d</screen>
is a quick and easy way to clean up your system.</para>
<section xml:id="ssec-gc-roots"><title>Garbage collector roots</title>
<para>The roots of the garbage collector are all store paths to which
there are symlinks in the directory
<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>.
For instance, the following command makes the path
<filename>/nix/store/d718ef...-foo</filename> a root of the collector:
<screen>
$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar</screen>
That is, after this command, the garbage collector will not remove
<filename>/nix/store/d718ef...-foo</filename> or any of its
dependencies.</para>
<para>Subdirectories of
<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>
are also searched for symlinks. Symlinks to non-store paths are
followed and searched for roots, but symlinks to non-store paths
<emphasis>inside</emphasis> the paths reached in that way are not
followed to prevent infinite recursion.</para>
</section>
</section>
<section xml:id="sec-channels"><title>Channels</title>
<para>If you want to stay up to date with a set of packages, it’s not
very convenient to manually download the latest set of Nix expressions
for those packages, use <command>nix-pull</command> to register
pre-built binaries (if available), and upgrade using
<command>nix-env</command>. Fortunately, there’s a better way:
<emphasis>Nix channels</emphasis>.</para>
<para>A Nix channel is just a URL that points to a place that contains
a set of Nix expressions and a manifest. Using the command <link
linkend="sec-nix-channel"><command>nix-channel</command></link> you
can automatically stay up to date with whatever is available at that
URL.</para>
<para>You can “subscribe” to a channel using
<command>nix-channel --add</command>, e.g.,
<screen>
$ nix-channel --add http://nixos.org/channels/nixpkgs-unstable</screen>
subscribes you to a channel that always contains that latest version
of the Nix Packages collection. (Instead of
<literal>nixpkgs-unstable</literal> you could also subscribe to
<literal>nixpkgs-stable</literal>, 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
<filename>~/.nix-channels</filename>. Right now there is no command
to “unsubscribe”; you should just edit that file manually
and delete the offending URL.</para>
<para>To obtain the latest Nix expressions available in a channel, do
<screen>
$ nix-channel --update</screen>
This downloads the Nix expressions in every channel (downloaded from
<literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal>)
and registers any available pre-built binaries in every channel
(by <command>nix-pull</command>ing
<literal><replaceable>url</replaceable>/MANIFEST</literal>). It also
makes the union of each channel’s Nix expressions the default for
<command>nix-env</command> operations. Consequently, you can then say
<screen>
$ nix-env -u '*'</screen>
to upgrade all packages in your profile to the latest versions
available in the subscribed channels.</para>
</section>
<section xml:id="sec-one-click"><title>One-click installs</title>
<para>Often, when you want to install a specific package (e.g., from
the <link
xlink:href="http://nixos.org/nixpkgs/">Nix
Packages collection</link>), 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 <emphasis>one-click installs</emphasis> 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.</para>
<para>For instance, you can go to <link
xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
/> and click on any link for the individual packages for your
platform. The first time you do this, your browser will ask what to
do with <literal>application/nix-package</literal> files. You should
open them with <filename>/nix/bin/nix-install-package</filename>.
This will open a window that asks you to confirm that you want to
install the package. When you answer <literal>Y</literal>, 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.</para>
<para>You can also install <literal>application/nix-package</literal>
files from the command line directly. See <xref
linkend='sec-nix-install-package' /> for details.</para>
</section>
<section xml:id="sec-sharing-packages"><title>Sharing packages between machines</title>
<para>Sometimes you want to copy a package from one machine to
another. Or, you want to install some packages and you know that
another machine already has some or all of those packages or their
dependencies. In that case there are mechanisms to quickly copy
packages between machines.</para>
<para>The command <command
linkend="sec-nix-copy-closure">nix-copy-closure</command> copies a Nix
store path along with all its dependencies to or from another machine
via the SSH protocol. It doesn’t copy store paths that are already
present on the target machine. For example, the following command
copies Firefox with all its dependencies:
<screen>
$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)</screen>
See <xref linkend='sec-nix-copy-closure' /> for details.</para>
<para>With <command linkend='refsec-nix-store-export'>nix-store
--export</command> and <command
linkend='refsec-nix-store-import'>nix-store --import</command> you can
write the closure of a store path (that is, the path and all its
dependencies) to a file, and then unpack that file into another Nix
store. For example,
<screen>
$ nix-store --export $(nix-store -qR $(type -p firefox)) > firefox.closure</screen>
writes the closure of Firefox to a file. You can then copy this file
to another machine and install the closure:
<screen>
$ nix-store --import &lt; firefox.closure</screen>
Any store paths in the closure that are already present in the target
store are ignored. It is also possible to pipe the export into
another command, e.g. to copy and install a closure directly to/on
another machine:
<screen>
$ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \
ssh alice@itchy.example.org "bunzip2 | nix-store --import"</screen>
But note that <command>nix-copy-closure</command> is generally more
efficient in this example because it only copies paths that are not
already present in the target Nix store.</para>
<para>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 <emphasis>on demand</emphasis>. For instance,
suppose that you mount a remote machine containing a Nix store via
<command
xlink:href="http://fuse.sourceforge.net/sshfs.html">sshfs</command>:
<screen>
$ sshfs alice@itchy.example.org:/ /mnt</screen>
You should then set the <envar>NIX_OTHER_STORES</envar> environment
variable to tell Nix about this remote Nix store:
<screen>
$ export NIX_OTHER_STORES=/mnt/nix</screen>
Then if you do any Nix operation, e.g.
<screen>
$ nix-env -i firefox</screen>
and Nix has to build a path that it sees is already present in
<filename>/mnt/nix</filename>, then it will just copy from there
instead of building it from source.</para>
</section>
</chapter>

170
doc/manual/packages/basic-package-mgmt.xml Normal file
View file

@ -0,0 +1,170 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-basic-package-mgmt">
<title>Basic Package Management</title>
<para>The main command for package management is <link
linkend="sec-nix-env"><command>nix-env</command></link>. You can use
it to install, upgrade, and erase packages, and to query what
packages are installed or are available for installation.</para>
<para>In Nix, different users can have different “views”
on the set of installed applications. That is, there might be lots of
applications present on the system (possibly in many different
versions), but users can have a specific selection of those active —
where “active” just means that it appears in a directory
in the user’s <envar>PATH</envar>. Such a view on the set of
installed applications is called a <emphasis>user
environment</emphasis>, which is just a directory tree consisting of
symlinks to the files of the active applications. </para>
<para>Components are installed from a set of <emphasis>Nix
expressions</emphasis> that tell Nix how to build those packages,
including, if necessary, their dependencies. There is a collection of
Nix expressions called the 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 <link
xlink:href='http://nixos.org/nixpkgs/download.html' />.</para>
<para>Assuming that you have downloaded and unpacked a release of Nix
Packages, you can view the set of available packages in the release:
<screen>
$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> '*'
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
...</screen>
where <literal>nixpkgs-<replaceable>version</replaceable></literal> is
where you’ve unpacked the release. The flag <option>-q</option>
specifies a query operation; <option>-a</option> means that you want
to show the “available” (i.e., installable) packages, as opposed to
the installed packages; and <option>-f</option>
<filename>nixpkgs-<replaceable>version</replaceable></filename>
specifies the source of the packages. The argument
<literal>'*'</literal> shows all installable packages. (The quotes are
necessary to prevent shell expansion.) You can also select specific
packages by name:
<screen>
$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> gcc
gcc-3.4.6
gcc-4.0.3
gcc-4.1.1</screen>
</para>
<para>It is also possible to see the <emphasis>status</emphasis> of
available packages, i.e., whether they are installed into the user
environment and/or present in the system:
<screen>
$ nix-env -qasf nixpkgs-<replaceable>version</replaceable> '*'
...
-PS bash-3.0
--S binutils-2.15
IPS bison-1.875d
...</screen>
The first character (<literal>I</literal>) indicates whether the
package is installed in your current user environment. The second
(<literal>P</literal>) indicates whether it is present on your system
(in which case installing it into your user environment would be a
very quick operation). The last one (<literal>S</literal>) indicates
whether there is a so-called <emphasis>substitute</emphasis> for the
package, which is Nix’s mechanism for doing binary deployment. It
just means that Nix knows that it can fetch a pre-built package from
somewhere (typically a network server) instead of building it
locally.</para>
<para>So now that we have a set of Nix expressions we can build the
packages contained in them. This is done using <literal>nix-env
-i</literal>. For instance,
<screen>
$ nix-env -f nixpkgs-<replaceable>version</replaceable> -i subversion</screen>
will install the package called <literal>subversion</literal> (which
is, of course, the <link
xlink:href='http://subversion.tigris.org/'>Subversion version
management system</link>).</para>
<para>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
<command>nix-pull</command> command, which must be supplied with a URL
containing a <emphasis>manifest</emphasis> 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 <link
xlink:href='http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x'
/>, then you should do:
<screen>
$ nix-pull http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x/MANIFEST</screen>
If you then issue the installation command, it should start
downloading binaries from <systemitem
class='fqdomainname'>nixos.org</systemitem>, 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.</para>
<para>Naturally, packages can also be uninstalled:
<screen>
$ nix-env -e subversion</screen>
</para>
<para>Upgrading to a new version is just as easy. If you have a new
release of Nix Packages, you can do:
<screen>
$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u subversion</screen>
This will <emphasis>only</emphasis> upgrade Subversion if there is a
“newer” version in the new set of Nix expressions, as
defined by some pretty arbitrary rules regarding ordering of version
numbers (which generally do what you’d expect of them). To just
unconditionally replace Subversion with whatever version is in the Nix
expressions, use <parameter>-i</parameter> instead of
<parameter>-u</parameter>; <parameter>-i</parameter> will remove
whatever version is already installed.</para>
<para>You can also upgrade all packages for which there are newer
versions:
<screen>
$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u '*'</screen>
</para>
<para>Sometimes it’s useful to be able to ask what
<command>nix-env</command> would do, without actually doing it. For
instance, to find out what packages would be upgraded by
<literal>nix-env -u '*'</literal>, you can do
<screen>
$ nix-env ... -u '*' --dry-run
(dry run; not doing anything)
upgrading `libxslt-1.1.0' to `libxslt-1.1.10'
upgrading `graphviz-1.10' to `graphviz-1.12'
upgrading `coreutils-5.0' to `coreutils-5.2.1'</screen>
</para>
</chapter>

57
doc/manual/packages/channels.xml Normal file
View file

@ -0,0 +1,57 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-channels">
<title>Channels</title>
<para>If you want to stay up to date with a set of packages, it’s not
very convenient to manually download the latest set of Nix expressions
for those packages, use <command>nix-pull</command> to register
pre-built binaries (if available), and upgrade using
<command>nix-env</command>. Fortunately, there’s a better way:
<emphasis>Nix channels</emphasis>.</para>
<para>A Nix channel is just a URL that points to a place that contains
a set of Nix expressions and a manifest. Using the command <link
linkend="sec-nix-channel"><command>nix-channel</command></link> you
can automatically stay up to date with whatever is available at that
URL.</para>
<para>You can “subscribe” to a channel using
<command>nix-channel --add</command>, e.g.,
<screen>
$ nix-channel --add http://nixos.org/channels/nixpkgs-unstable</screen>
subscribes you to a channel that always contains that latest version
of the Nix Packages collection. (Instead of
<literal>nixpkgs-unstable</literal> you could also subscribe to
<literal>nixpkgs-stable</literal>, 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
<filename>~/.nix-channels</filename>. Right now there is no command
to “unsubscribe”; you should just edit that file manually
and delete the offending URL.</para>
<para>To obtain the latest Nix expressions available in a channel, do
<screen>
$ nix-channel --update</screen>
This downloads the Nix expressions in every channel (downloaded from
<literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal>)
and registers any available pre-built binaries in every channel
(by <command>nix-pull</command>ing
<literal><replaceable>url</replaceable>/MANIFEST</literal>). It also
makes the union of each channel’s Nix expressions the default for
<command>nix-env</command> operations. Consequently, you can then say
<screen>
$ nix-env -u '*'</screen>
to upgrade all packages in your profile to the latest versions
available in the subscribed channels.</para>
</chapter>

70
doc/manual/packages/garbage-collection.xml Normal file
View file

@ -0,0 +1,70 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='sec-garbage-collection'>
<title>Garbage Collection</title>
<para><command>nix-env</command> operations such as upgrades
(<option>-u</option>) and uninstall (<option>-e</option>) never
actually delete packages from the system. All they do (as shown
above) is to create a new user environment that no longer contains
symlinks to the “deleted” packages.</para>
<para>Of course, since disk space is not infinite, unused packages
should be removed at some point. You can do this by running the Nix
garbage collector. It will remove from the Nix store any package
not used (directly or indirectly) by any generation of any
profile.</para>
<para>Note however that as long as old generations reference a
package, it will not be deleted. After all, we wouldn’t be able to
do a rollback otherwise. So in order for garbage collection to be
effective, you should also delete (some) old generations. Of course,
this should only be done if you are certain that you will not need to
roll back.</para>
<para>To delete all old (non-current) generations of your current
profile:
<screen>
$ nix-env --delete-generations old</screen>
Instead of <literal>old</literal> you can also specify a list of
generations, e.g.,
<screen>
$ nix-env --delete-generations 10 11 14</screen>
</para>
<para>After removing appropriate old generations you can run the
garbage collector as follows:
<screen>
$ nix-store --gc</screen>
If you are feeling uncertain, you can also first view what files would
be deleted:
<screen>
$ nix-store --gc --print-dead</screen>
Likewise, the option <option>--print-live</option> will show the paths
that <emphasis>won’t</emphasis> be deleted.</para>
<para>There is also a convenient little utility
<command>nix-collect-garbage</command>, which when invoked with the
<option>-d</option> (<option>--delete-old</option>) switch deletes all
old generations of all profiles in
<filename>/nix/var/nix/profiles</filename>. So
<screen>
$ nix-collect-garbage -d</screen>
is a quick and easy way to clean up your system.</para>
<xi:include href="garbage-collector-roots.xml" />
</chapter>

29
doc/manual/packages/garbage-collector-roots.xml Normal file
View file

@ -0,0 +1,29 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-gc-roots">
<title>Garbage Collector Roots</title>
<para>The roots of the garbage collector are all store paths to which
there are symlinks in the directory
<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>.
For instance, the following command makes the path
<filename>/nix/store/d718ef...-foo</filename> a root of the collector:
<screen>
$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar</screen>
That is, after this command, the garbage collector will not remove
<filename>/nix/store/d718ef...-foo</filename> or any of its
dependencies.</para>
<para>Subdirectories of
<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>
are also searched for symlinks. Symlinks to non-store paths are
followed and searched for roots, but symlinks to non-store paths
<emphasis>inside</emphasis> the paths reached in that way are not
followed to prevent infinite recursion.</para>
</section>

37
doc/manual/packages/one-click.xml Normal file
View file

@ -0,0 +1,37 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-one-click">
<title>One-Click Installation</title>
<para>Often, when you want to install a specific package (e.g., from
the <link
xlink:href="http://nixos.org/nixpkgs/">Nix
Packages collection</link>), 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 <emphasis>one-click installs</emphasis> 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.</para>
<para>For instance, you can go to <link
xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
/> and click on any link for the individual packages for your
platform. The first time you do this, your browser will ask what to
do with <literal>application/nix-package</literal> files. You should
open them with <filename>/nix/bin/nix-install-package</filename>.
This will open a window that asks you to confirm that you want to
install the package. When you answer <literal>Y</literal>, 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.</para>
<para>You can also install <literal>application/nix-package</literal>
files from the command line directly. See <xref
linkend='sec-nix-install-package' /> for details.</para>
</chapter>

24
doc/manual/packages/package-management.xml Normal file
View file

@ -0,0 +1,24 @@
<part xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id='chap-package-management'>
<title>Package Management</title>
<partintro>
<para>This chapter discusses how to do package management with Nix,
i.e., how to obtain, install, upgrade, and erase packages. This is
the “user’s” perspective of the Nix system — people
who want to <emphasis>create</emphasis> packages should consult
<xref linkend='chap-writing-nix-expressions' />.</para>
</partintro>
<xi:include href="basic-package-mgmt.xml" />
<xi:include href="profiles.xml" />
<xi:include href="garbage-collection.xml" />
<xi:include href="channels.xml" />
<xi:include href="one-click.xml" />
<xi:include href="sharing-packages.xml" />
</part>

159
doc/manual/packages/profiles.xml Normal file
View file

@ -0,0 +1,159 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-profiles">
<title>Profiles</title>
<para>Profiles and user environments are Nix’s mechanism for
implementing the ability to allow different users to have different
configurations, and to do atomic upgrades and rollbacks. To
understand how they work, it’s useful to know a bit about how Nix
works. In Nix, packages are stored in unique locations in the
<emphasis>Nix store</emphasis> (typically,
<filename>/nix/store</filename>). For instance, a particular version
of the Subversion package might be stored in a directory
<filename>/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/</filename>,
while another version might be stored in
<filename>/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2</filename>.
The long strings prefixed to the directory names are cryptographic
hashes<footnote><para>160-bit truncations of SHA-256 hashes encoded in
a base-32 notation, to be precise.</para></footnote> of
<emphasis>all</emphasis> inputs involved in building the package —
sources, dependencies, compiler flags, and so on. So if two
packages differ in any way, they end up in different locations in
the file system, so they don’t interfere with each other. <xref
linkend='fig-user-environments' /> shows a part of a typical Nix
store.</para>
<figure xml:id='fig-user-environments'><title>User environments</title>
<mediaobject>
<imageobject>
<imagedata fileref='figures/user-environments.png' format='PNG' />
</imageobject>
</mediaobject>
</figure>
<para>Of course, you wouldn’t want to type
<screen>
$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn</screen>
every time you want to run Subversion. Of course we could set up the
<envar>PATH</envar> environment variable to include the
<filename>bin</filename> directory of every package we want to use,
but this is not very convenient since changing <envar>PATH</envar>
doesn’t take effect for already existing processes. The solution Nix
uses is to create directory trees of symlinks to
<emphasis>activated</emphasis> packages. These are called
<emphasis>user environments</emphasis> and they are packages
themselves (though automatically generated by
<command>nix-env</command>), so they too reside in the Nix store. For
instance, in <xref linkend='fig-user-environments' /> the user
environment <filename>/nix/store/0c1p5z4kda11...-user-env</filename>
contains a symlink to just Subversion 1.1.2 (arrows in the figure
indicate symlinks). This would be what we would obtain if we had done
<screen>
$ nix-env -i subversion</screen>
on a set of Nix expressions that contained Subversion 1.1.2.</para>
<para>This doesn’t in itself solve the problem, of course; you
wouldn’t want to type
<filename>/nix/store/0c1p5z4kda11...-user-env/bin/svn</filename>
either. That’s why there are symlinks outside of the store that point
to the user environments in the store; for instance, the symlinks
<filename>default-42-link</filename> and
<filename>default-43-link</filename> in the example. These are called
<emphasis>generations</emphasis> since every time you perform a
<command>nix-env</command> operation, a new user environment is
generated based on the current one. For instance, generation 43 was
created from generation 42 when we did
<screen>
$ nix-env -i subversion mozilla</screen>
on a set of Nix expressions that contained Mozilla and a new version
of Subversion.</para>
<para>Generations are grouped together into
<emphasis>profiles</emphasis> so that different users don’t interfere
with each other if they don’t want to. For example:
<screen>
$ ls -l /nix/var/nix/profiles/
...
lrwxrwxrwx 1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env
lrwxrwxrwx 1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env
lrwxrwxrwx 1 eelco ... default -> default-43-link</screen>
This shows a profile called <filename>default</filename>. The file
<filename>default</filename> itself is actually a symlink that points
to the current generation. When we do a <command>nix-env</command>
operation, a new user environment and generation link are created
based on the current one, and finally the <filename>default</filename>
symlink is made to point at the new generation. This last step is
atomic on Unix, which explains how we can do atomic upgrades. (Note
that the building/installing of new packages doesn’t interfere in
any way with old packages, since they are stored in different
locations in the Nix store.)</para>
<para>If you find that you want to undo a <command>nix-env</command>
operation, you can just do
<screen>
$ nix-env --rollback</screen>
which will just make the current generation link point at the previous
link. E.g., <filename>default</filename> would be made to point at
<filename>default-42-link</filename>. You can also switch to a
specific generation:
<screen>
$ nix-env --switch-generation 43</screen>
which in this example would roll forward to generation 43 again. You
can also see all available generations:
<screen>
$ nix-env --list-generations</screen></para>
<para>Actually, there is another level of indirection not shown in the
figure above. You generally wouldn’t have
<filename>/nix/var/nix/profiles/<replaceable>some-profile</replaceable>/bin</filename>
in your <envar>PATH</envar>. Rather, there is a symlink
<filename>~/.nix-profile</filename> that points to your current
profile. This means that you should put
<filename>~/.nix-profile/bin</filename> in your <envar>PATH</envar>
(and indeed, that’s what the initialisation script
<filename>/nix/etc/profile.d/nix.sh</filename> does). This makes it
easier to switch to a different profile. You can do that using the
command <command>nix-env --switch-profile</command>:
<screen>
$ nix-env --switch-profile /nix/var/nix/profiles/my-profile
$ nix-env --switch-profile /nix/var/nix/profiles/default</screen>
These commands switch to the <filename>my-profile</filename> and
default profile, respectively. If the profile doesn’t exist, it will
be created automatically. You should be careful about storing a
profile in another location than the <filename>profiles</filename>
directory, since otherwise it might not be used as a root of the
garbage collector (see <xref linkend='sec-garbage-collection'
/>).</para>
<para>All <command>nix-env</command> operations work on the profile
pointed to by <command>~/.nix-profile</command>, but you can override
this using the <option>--profile</option> option (abbreviation
<option>-p</option>):
<screen>
$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion</screen>
This will <emphasis>not</emphasis> change the
<command>~/.nix-profile</command> symlink.</para>
</chapter>

82
doc/manual/packages/sharing-packages.xml Normal file
View file

@ -0,0 +1,82 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-sharing-packages">
<title>Sharing Packages Between Machines</title>
<para>Sometimes you want to copy a package from one machine to
another. Or, you want to install some packages and you know that
another machine already has some or all of those packages or their
dependencies. In that case there are mechanisms to quickly copy
packages between machines.</para>
<para>The command <command
linkend="sec-nix-copy-closure">nix-copy-closure</command> copies a Nix
store path along with all its dependencies to or from another machine
via the SSH protocol. It doesn’t copy store paths that are already
present on the target machine. For example, the following command
copies Firefox with all its dependencies:
<screen>
$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)</screen>
See <xref linkend='sec-nix-copy-closure' /> for details.</para>
<para>With <command linkend='refsec-nix-store-export'>nix-store
--export</command> and <command
linkend='refsec-nix-store-import'>nix-store --import</command> you can
write the closure of a store path (that is, the path and all its
dependencies) to a file, and then unpack that file into another Nix
store. For example,
<screen>
$ nix-store --export $(nix-store -qR $(type -p firefox)) > firefox.closure</screen>
writes the closure of Firefox to a file. You can then copy this file
to another machine and install the closure:
<screen>
$ nix-store --import &lt; firefox.closure</screen>
Any store paths in the closure that are already present in the target
store are ignored. It is also possible to pipe the export into
another command, e.g. to copy and install a closure directly to/on
another machine:
<screen>
$ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \
ssh alice@itchy.example.org "bunzip2 | nix-store --import"</screen>
But note that <command>nix-copy-closure</command> is generally more
efficient in this example because it only copies paths that are not
already present in the target Nix store.</para>
<para>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 <emphasis>on demand</emphasis>. For instance,
suppose that you mount a remote machine containing a Nix store via
<command
xlink:href="http://fuse.sourceforge.net/sshfs.html">sshfs</command>:
<screen>
$ sshfs alice@itchy.example.org:/ /mnt</screen>
You should then set the <envar>NIX_OTHER_STORES</envar> environment
variable to tell Nix about this remote Nix store:
<screen>
$ export NIX_OTHER_STORES=/mnt/nix</screen>
Then if you do any Nix operation, e.g.
<screen>
$ nix-env -i firefox</screen>
and Nix has to build a path that it sees is already present in
<filename>/mnt/nix</filename>, then it will just copy from there
instead of building it from source.</para>
</chapter>

52
doc/manual/quick-start.xml → doc/manual/quick-start/getting-started.xml
View file

@ -1,17 +1,15 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id="chap-quick-start">
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-getting-started-nix">
<title>Quick Start</title>
<title>Getting Started with Nix</title>
<para>This tutorial takes you through the basic tasks you might perform when you start using Nix.</para>
<procedure>
<para>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.</para>
<orderedlist>
<listitem><para>Install Nix by running the following:
<step><para>Install Nix by running the following:
<screen>
$ bash &lt;(curl https://nixos.org/nix/install)
@ -20,9 +18,9 @@ $ bash &lt;(curl https://nixos.org/nix/install)
This will install Nix in <filename>/nix</filename>. The install script
will create <filename>/nix</filename> using <command>sudo</command>,
so make sure you have sufficient rights. (For other installation
methods, see <xref linkend="chap-installation"/>.)</para></listitem>
methods, see <xref linkend="chap-installation"/>.)</para></step>
<listitem><para>See what installable packages are currently available
<step><para>See what installable packages are currently available
in the channel:
<screen>
@ -33,17 +31,17 @@ hello-2.1.1
libxslt-1.1.0
<replaceable>...</replaceable></screen>
</para></listitem>
</para></step>
<listitem><para>Install some packages from the channel:
<step><para>Install some packages from the channel:
<screen>
$ nix-env -i hello <replaceable>...</replaceable> </screen>
This should download pre-built packages; it should not build them
locally (if it does, something went wrong).</para></listitem>
locally (if it does, something went wrong).</para></step>
<listitem><para>Test that they work:
<step><para>Test that they work:
<screen>
$ which hello
@ -52,16 +50,16 @@ $ hello
Hello, world!
</screen>
</para></listitem>
</para></step>
<listitem><para>Uninstall a package:
<step><para>Uninstall a package:
<screen>
$ nix-env -e hello</screen>
</para></listitem>
</para></step>
<listitem><para>To keep up-to-date with the channel, do:
<step><para>To keep up-to-date with the channel, do:
<screen>
$ nix-channel --update nixpkgs
@ -69,9 +67,9 @@ $ nix-env -u '*'</screen>
The latter command will upgrade each installed package for which there
is a “newer” version (as determined by comparing the version
numbers).</para></listitem>
numbers).</para></step>
<listitem><para>You can also install specific packages directly from
<step><para>You can also install specific packages directly from
your web browser. For instance, you can go to <link
xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
/> and click on any link for the individual packages for your
@ -79,18 +77,18 @@ platform. Associate <literal>application/nix-package</literal> with
the program <command>nix-install-package</command>. A window should
appear asking you whether it’s okay to install the package. Say
<literal>Y</literal>. The package and all its dependencies will be
installed.</para></listitem>
installed.</para></step>
<listitem><para>If you're unhappy with the result of a
<step><para>If you're unhappy with the result of a
<command>nix-env</command> action (e.g., an upgraded package turned
out not to work properly), you can go back:
<screen>
$ nix-env --rollback</screen>
</para></listitem>
</para></step>
<listitem><para>You should periodically run the Nix garbage collector
<step><para>You should periodically run the Nix garbage collector
to get rid of unused packages, since uninstalls or upgrades don't
actually delete them:
@ -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.-->
</para></listitem>
</para></step>
</orderedlist>
</procedure>
</chapter>

17
doc/manual/quick-start/quick-start.xml Normal file
View file

@ -0,0 +1,17 @@
<part xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="chap-quick-start">
<title>Quick-Start</title>
<partintro>
<para>This section is for impatient people who don't like reading
documentation. For more in-depth information you are kindly referred
to subsequent chapters.</para>
</partintro>
<xi:include href="getting-started.xml" />
</part>

2521
doc/manual/release-notes.xml
View file

File diff suppressed because it is too large Load diff

43
doc/manual/release-notes/release-notes.xml Normal file
View file

@ -0,0 +1,43 @@
<part xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-relnotes">
<title>Nix Release Notes</title>
<partintro>
<para>This section lists the release notes for each stable version of Nix.</para>
</partintro>
<!-- TODO
<xi:include href="rl-18.xml" />
-->
<xi:include href="rl-17.xml" />
<xi:include href="rl-161.xml" />
<xi:include href="rl-16.xml" />
<xi:include href="rl-152.xml" />
<xi:include href="rl-15.xml" />
<xi:include href="rl-14.xml" />
<xi:include href="rl-13.xml" />
<xi:include href="rl-12.xml" />
<xi:include href="rl-11.xml" />
<xi:include href="rl-10.xml" />
<xi:include href="rl-016.xml" />
<xi:include href="rl-015.xml" />
<xi:include href="rl-014.xml" />
<xi:include href="rl-013.xml" />
<xi:include href="rl-012.xml" />
<xi:include href="rl-011.xml" />
<xi:include href="rl-0101.xml" />
<xi:include href="rl-010.xml" />
<xi:include href="rl-092.xml" />
<xi:include href="rl-091.xml" />
<xi:include href="rl-09.xml" />
<xi:include href="rl-081.xml" />
<xi:include href="rl-08.xml" />
<xi:include href="rl-07.xml" />
<xi:include href="rl-06.xml" />
<xi:include href="rl-05.xml" />
</part>

323
doc/manual/release-notes/rl-010.xml Normal file
View file

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

13
doc/manual/release-notes/rl-0101.xml Normal file
View file

@ -0,0 +1,13 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-relnotes-0.10.1">
<title>Release 0.10.1 (October 11, 2006)</title>
<para>This release fixes two somewhat obscure bugs that occur when
evaluating Nix expressions that are stored inside the Nix store
(<literal>NIX-67</literal>). These do not affect most users.</para>
</chapter>

261
doc/manual/release-notes/rl-011.xml Normal file
View file

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

175
doc/manual/release-notes/rl-012.xml Normal file
View file

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

106
doc/manual/release-notes/rl-013.xml Normal file
View file

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

44
doc/manual/release-notes/rl-014.xml Normal file
View file

@ -0,0 +1,44 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-relnotes-0.14"><title>Release 0.14 (February 4, 2010)</title>
<para>This release has the following improvements:</para>
<itemizedlist>
<listitem>
<para>The garbage collector now starts deleting garbage much
faster than before. It no longer determines liveness of all paths
in the store, but does so on demand.</para>
</listitem>
<listitem>
<para>Added a new operation, <command>nix-store --query
--roots</command>, that shows the garbage collector roots that
directly or indirectly point to the given store paths.</para>
</listitem>
<listitem>
<para>Removed support for converting Berkeley DB-based Nix
databases to the new schema.</para>
</listitem>
<listitem>
<para>Removed the <option>--use-atime</option> and
<option>--max-atime</option> garbage collector options. They were
not very useful in practice.</para>
</listitem>
<listitem>
<para>On Windows, Nix now requires Cygwin 1.7.x.</para>
</listitem>
<listitem>
<para>A few bug fixes.</para>
</listitem>
</itemizedlist>
</chapter>

14
doc/manual/release-notes/rl-015.xml Normal file
View file

@ -0,0 +1,14 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-relnotes-0.15">
<title>Release 0.15 (March 17, 2010)</title>
<para>This is a bug-fix release. Among other things, it fixes
building on Mac OS X (Snow Leopard), and improves the contents of
<filename>/etc/passwd</filename> and <filename>/etc/group</filename>
in <literal>chroot</literal> builds.</para>
</chapter>

55
doc/manual/release-notes/rl-016.xml Normal file
View file

@ -0,0 +1,55 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-relnotes-0.16">
<title>Release 0.16 (August 17, 2010)</title>
<para>This release has the following improvements:</para>
<itemizedlist>
<listitem>
<para>The Nix expression evaluator is now much faster in most
cases: typically, <link
xlink:href="http://www.mail-archive.com/nix-dev@cs.uu.nl/msg04113.html">3
to 8 times compared to the old implementation</link>. It also
uses less memory. It no longer depends on the ATerm
library.</para>
</listitem>
<listitem>
<para>
Support for configurable parallelism inside builders. Build
scripts have always had the ability to perform multiple build
actions in parallel (for instance, by running <command>make -j
2</command>), but this was not desirable because the number of
actions to be performed in parallel was not configurable. Nix
now has an option <option>--cores
<replaceable>N</replaceable></option> as well as a configuration
setting <varname>build-cores =
<replaceable>N</replaceable></varname> that causes the
environment variable <envar>NIX_BUILD_CORES</envar> to be set to
<replaceable>N</replaceable> when the builder is invoked. The
builder can use this at its discretion to perform a parallel
build, e.g., by calling <command>make -j
<replaceable>N</replaceable></command>. In Nixpkgs, this can be
enabled on a per-package basis by setting the derivation
attribute <varname>enableParallelBuilding</varname> to
<literal>true</literal>.
</para>
</listitem>
<listitem>
<para><command>nix-store -q</command> now supports XML output
through the <option>--xml</option> flag.</para>
</listitem>
<listitem>
<para>Several bug fixes.</para>
</listitem>
</itemizedlist>
</chapter>

11
doc/manual/release-notes/rl-05.xml Normal file
View file

@ -0,0 +1,11 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-relnotes-0.5">
<title>Release 0.5 and earlier</title>
<para>Please refer to the Subversion commit log messages.</para>
</chapter>

122
doc/manual/release-notes/rl-06.xml Normal file
View file

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

35
doc/manual/release-notes/rl-07.xml Normal file
View file

@ -0,0 +1,35 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-relnotes-0.7">
<title>Release 0.7 (January 12, 2005)</title>
<itemizedlist>
<listitem><para>Binary patching. When upgrading components using
pre-built binaries (through nix-pull / nix-channel), Nix can
automatically download and apply binary patches to already installed
components instead of full downloads. Patching is “smart”: if there
is a <emphasis>sequence</emphasis> of patches to an installed
component, Nix will use it. Patches are currently generated
automatically between Nixpkgs (pre-)releases.</para></listitem>
<listitem><para>Simplifications to the substitute
mechanism.</para></listitem>
<listitem><para>Nix-pull now stores downloaded manifests in
<filename>/nix/var/nix/manifests</filename>.</para></listitem>
<listitem><para>Metadata on files in the Nix store is canonicalised
after builds: the last-modified timestamp is set to 0 (00:00:00
1/1/1970), the mode is set to 0444 or 0555 (readable and possibly
executable by all; setuid/setgid bits are dropped), and the group is
set to the default. This ensures that the result of a build and an
installation through a substitute is the same; and that timestamp
dependencies are revealed.</para></listitem>
</itemizedlist>
</chapter>

246
doc/manual/release-notes/rl-08.xml Normal file
View file

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

21
doc/manual/release-notes/rl-081.xml Normal file
View file

@ -0,0 +1,21 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-relnotes-0.8.1">
<title>Release 0.8.1 (April 13, 2005)</title>
<para>This is a bug fix release.</para>
<itemizedlist>
<listitem><para>Patch downloading was broken.</para></listitem>
<listitem><para>The garbage collector would not delete paths that
had references from invalid (but substitutable)
paths.</para></listitem>
</itemizedlist>
</chapter>

98
doc/manual/release-notes/rl-09.xml Normal file
View file

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

13
doc/manual/release-notes/rl-091.xml Normal file
View file

@ -0,0 +1,13 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-relnotes-0.9.1">
<title>Release 0.9.1 (September 20, 2005)</title>
<para>This bug fix release addresses a problem with the ATerm library
when the <option>--with-aterm</option> flag in
<command>configure</command> was <emphasis>not</emphasis> used.</para>
</chapter>

28
doc/manual/release-notes/rl-092.xml Normal file
View file

@ -0,0 +1,28 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-relnotes-0.9.2">
<title>Release 0.9.2 (September 21, 2005)</title>
<para>This bug fix release fixes two problems on Mac OS X:
<itemizedlist>
<listitem><para>If Nix was linked against statically linked versions
of the ATerm or Berkeley DB library, there would be dynamic link
errors at runtime.</para></listitem>
<listitem><para><command>nix-pull</command> and
<command>nix-push</command> intermittently failed due to race
conditions involving pipes and child processes with error messages
such as <literal>open2: open(GLOB(0x180b2e4), >&amp;=9) failed: Bad
file descriptor at /nix/bin/nix-pull line 77</literal> (issue
<literal>NIX-14</literal>).</para></listitem>
</itemizedlist>
</para>
</chapter>

119
doc/manual/release-notes/rl-10.xml Normal file
View file

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

100
doc/manual/release-notes/rl-11.xml Normal file
View file

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

157
doc/manual/release-notes/rl-12.xml Normal file
View file

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

19
doc/manual/release-notes/rl-13.xml Normal file
View file

@ -0,0 +1,19 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-relnotes-1.3">
<title>Release 1.3 (January 4, 2013)</title>
<para>This is primarily a bug fix release. When this version is first
run on Linux, it removes any immutable bits from the Nix store and
increases the schema version of the Nix store. (The previous release
removed support for setting the immutable bit; this release clears any
remaining immutable bits to make certain operations more
efficient.)</para>
<para>This release has contributions from Eelco Dolstra and Stuart
Pernsteiner.</para>
</chapter>

39
doc/manual/release-notes/rl-14.xml Normal file
View file

@ -0,0 +1,39 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-relnotes-1.4">
<title>Release 1.4 (February 26, 2013)</title>
<para>This release fixes a security bug in multi-user operation. It
was possible for derivations to cause the mode of files outside of the
Nix store to be changed to 444 (read-only but world-readable) by
creating hard links to those files (<link
xlink:href="https://github.com/NixOS/nix/commit/5526a282b5b44e9296e61e07d7d2626a79141ac4">details</link>).</para>
<para>There are also the following improvements:</para>
<itemizedlist>
<listitem><para>New built-in function:
<function>builtins.hashString</function>.</para></listitem>
<listitem><para>Build logs are now stored in
<filename>/nix/var/log/nix/drvs/<replaceable>XX</replaceable>/</filename>,
where <replaceable>XX</replaceable> is the first two characters of
the derivation. This is useful on machines that keep a lot of build
logs (such as Hydra servers).</para></listitem>
<listitem><para>The function <function>corepkgs/fetchurl</function>
can now make the downloaded file executable. This will allow
getting rid of all bootstrap binaries in the Nixpkgs source
tree.</para></listitem>
<listitem><para>Language change: The expression <literal>"${./path}
..."</literal> now evaluates to a string instead of a
path.</para></listitem>
</itemizedlist>
</chapter>

12
doc/manual/release-notes/rl-15.xml Normal file
View file

@ -0,0 +1,12 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-relnotes-1.5">
<title>Release 1.5 (February 27, 2013)</title>
<para>This is a brown paper bag release to fix a regression introduced
by the hard link security fix in 1.4.</para>
</chapter>

12
doc/manual/release-notes/rl-151.xml Normal file
View file

@ -0,0 +1,12 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-relnotes-1.5.1">
<title>Release 1.5.1 (February 28, 2013)</title>
<para>The bug fix to the bug fix had a bug itself, of course. But
this time it will work for sure!</para>
</chapter>

12
doc/manual/release-notes/rl-152.xml Normal file
View file

@ -0,0 +1,12 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-relnotes-1.5.2">
<title>Release 1.5.2 (May 13, 2013)</title>
<para>This is primarily a bug fix release. It has contributions from
Eelco Dolstra, Lluís Batlle i Rossell and Shea Levy.</para>
</chapter>

127
doc/manual/release-notes/rl-16.xml Normal file
View file

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

69
doc/manual/release-notes/rl-161.xml Normal file
View file

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

Some files were not shown because too many files have changed in this diff Show more