Restructuring the Nix manual
This commit is contained in:
Mikey Ariel
parent
3f0a4bf0e7
commit
8901acc976
22
doc/manual/builds/build-farm.xml
Normal file
22
doc/manual/builds/build-farm.xml
Normal 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>
|
||||||
|
|
@ -1,17 +1,10 @@
|
||||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
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>
|
<title>Enabling 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>
|
|
||||||
|
|
||||||
<para>You can enable distributed builds by setting the environment
|
<para>You can enable distributed builds by setting the environment
|
||||||
variable <envar>NIX_BUILD_HOOK</envar> to point to a program that Nix
|
variable <envar>NIX_BUILD_HOOK</envar> to point to a program that Nix
|
||||||
20
doc/manual/command-ref/command-ref.xml
Normal file
20
doc/manual/command-ref/command-ref.xml
Normal 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>
|
||||||
|
|
@ -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:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-common-env">
|
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>
|
<para>Most Nix commands interpret the following environment variables:</para>
|
||||||
|
|
@ -335,4 +337,4 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
|
|
||||||
|
|
||||||
</section>
|
</chapter>
|
||||||
14
doc/manual/command-ref/files.xml
Normal file
14
doc/manual/command-ref/files.xml
Normal 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
17
doc/manual/command-ref/main-commands.xml
Normal 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,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-build">
|
xml:id="sec-nix-build">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-channel">
|
xml:id="sec-nix-channel">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-collect-garbage">
|
xml:id="sec-nix-collect-garbage">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-daemon">
|
xml:id="sec-nix-daemon">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-env">
|
xml:id="sec-nix-env">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-hash">
|
xml:id="sec-nix-hash">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-install-package">
|
xml:id="sec-nix-install-package">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-instantiate">
|
xml:id="sec-nix-instantiate">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-prefetch-url">
|
xml:id="sec-nix-prefetch-url">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-pull">
|
xml:id="sec-nix-pull">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-push">
|
xml:id="sec-nix-push">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-shell">
|
xml:id="sec-nix-shell">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -1,6 +1,7 @@
|
||||||
<refentry xmlns="http://docbook.org/ns/docbook"
|
<refentry xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id="sec-nix-store">
|
xml:id="sec-nix-store">
|
||||||
|
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
|
@ -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>
|
<para>Most Nix commands accept the following command-line options:</para>
|
||||||
|
|
@ -386,4 +386,4 @@
|
||||||
</variablelist>
|
</variablelist>
|
||||||
|
|
||||||
|
|
||||||
</section>
|
</chapter>
|
||||||
23
doc/manual/command-ref/utilities.xml
Normal file
23
doc/manual/command-ref/utilities.xml
Normal 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
243
doc/manual/expressions/advanced-attributes.xml
Normal 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
121
doc/manual/expressions/arguments-variables.xml
Normal 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
119
doc/manual/expressions/build-script.xml
Normal 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
119
doc/manual/expressions/builder-syntax.xml
Normal 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>
|
||||||
|
|
@ -1,9 +1,10 @@
|
||||||
<section xmlns="http://docbook.org/ns/docbook"
|
<section xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
version="5.0"
|
||||||
xml:id='ssec-builtins'>
|
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
|
<para>This section lists the functions and constants built into the
|
||||||
Nix expression evaluator. (The built-in function
|
Nix expression evaluator. (The built-in function
|
||||||
26
doc/manual/expressions/custom-builder.xml
Normal file
26
doc/manual/expressions/custom-builder.xml
Normal 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
33
doc/manual/expressions/debug-build.xml
Normal 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
211
doc/manual/expressions/derivations.xml
Normal 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
30
doc/manual/expressions/expression-language.xml
Normal 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
148
doc/manual/expressions/expression-syntax.xml
Normal 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
98
doc/manual/expressions/generic-builder.xml
Normal 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
344
doc/manual/expressions/language-constructs.xml
Normal 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 && httpd.expat == expat; <co xml:id='ex-subversion-nix-co-2' />
|
||||||
|
assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); <co xml:id='ex-subversion-nix-co-3' />
|
||||||
|
assert pythonBindings -> swig != null && swig.pythonSupport;
|
||||||
|
assert javaSwigBindings -> swig != null && swig.javaSupport;
|
||||||
|
assert javahlBindings -> j2sdk != null;
|
||||||
|
|
||||||
|
stdenv.mkDerivation {
|
||||||
|
name = "subversion-1.1.1";
|
||||||
|
...
|
||||||
|
openssl = if sslSupport then openssl else null; <co xml:id='ex-subversion-nix-co-4' />
|
||||||
|
...
|
||||||
|
}</programlisting>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
<para><xref linkend='ex-subversion-nix' /> show how assertions are
|
||||||
|
used in the Nix expression for Subversion.</para>
|
||||||
|
|
||||||
|
<calloutlist>
|
||||||
|
|
||||||
|
<callout arearefs='ex-subversion-nix-co-1'>
|
||||||
|
<para>This assertion states that if Subversion is to have support
|
||||||
|
for local repositories, then Berkeley DB is needed. So if the
|
||||||
|
Subversion function is called with the
|
||||||
|
<varname>localServer</varname> argument set to
|
||||||
|
<literal>true</literal> but the <varname>db4</varname> argument
|
||||||
|
set to <literal>null</literal>, then the evaluation fails.</para>
|
||||||
|
</callout>
|
||||||
|
|
||||||
|
<callout arearefs='ex-subversion-nix-co-2'>
|
||||||
|
<para>This is a more subtle condition: if Subversion is built with
|
||||||
|
Apache (<literal>httpServer</literal>) support, then the Expat
|
||||||
|
library (an XML library) used by Subversion should be same as the
|
||||||
|
one used by Apache. This is because in this configuration
|
||||||
|
Subversion code ends up being linked with Apache code, and if the
|
||||||
|
Expat libraries do not match, a build- or runtime link error or
|
||||||
|
incompatibility might occur.</para>
|
||||||
|
</callout>
|
||||||
|
|
||||||
|
<callout arearefs='ex-subversion-nix-co-3'>
|
||||||
|
<para>This assertion says that in order for Subversion to have SSL
|
||||||
|
support (so that it can access <literal>https</literal> URLs), an
|
||||||
|
OpenSSL library must be passed. Additionally, it says that
|
||||||
|
<emphasis>if</emphasis> Apache support is enabled, then Apache's
|
||||||
|
OpenSSL should match Subversion's. (Note that if Apache support
|
||||||
|
is not enabled, we don't care about Apache's OpenSSL.)</para>
|
||||||
|
</callout>
|
||||||
|
|
||||||
|
<callout arearefs='ex-subversion-nix-co-4'>
|
||||||
|
<para>The conditional here is not really related to assertions,
|
||||||
|
but is worth pointing out: it ensures that if SSL support is
|
||||||
|
disabled, then the Subversion derivation is not dependent on
|
||||||
|
OpenSSL, even if a non-<literal>null</literal> value was passed.
|
||||||
|
This prevents an unnecessary rebuild of Subversion if OpenSSL
|
||||||
|
changes.</para>
|
||||||
|
</callout>
|
||||||
|
|
||||||
|
</calloutlist>
|
||||||
|
|
||||||
|
</simplesect>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<simplesect><title>With-expressions</title>
|
||||||
|
|
||||||
|
<para>A <emphasis>with-expression</emphasis>,
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
with <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting>
|
||||||
|
|
||||||
|
introduces the set <replaceable>e1</replaceable> into the lexical
|
||||||
|
scope of the expression <replaceable>e2</replaceable>. For instance,
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
let as = { x = "foo"; y = "bar"; };
|
||||||
|
in with as; x + y</programlisting>
|
||||||
|
|
||||||
|
evaluates to <literal>"foobar"</literal> since the
|
||||||
|
<literal>with</literal> adds the <varname>x</varname> and
|
||||||
|
<varname>y</varname> attributes of <varname>as</varname> to the
|
||||||
|
lexical scope in the expression <literal>x + y</literal>. The most
|
||||||
|
common use of <literal>with</literal> is in conjunction with the
|
||||||
|
<function>import</function> function. E.g.,
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
with (import ./definitions.nix); ...</programlisting>
|
||||||
|
|
||||||
|
makes all attributes defined in the file
|
||||||
|
<filename>definitions.nix</filename> available as if they were defined
|
||||||
|
locally in a <literal>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
113
doc/manual/expressions/language-operators.xml
Normal 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>&&</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
268
doc/manual/expressions/language-values.xml
Normal 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
86
doc/manual/expressions/simple-building-testing.xml
Normal 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
47
doc/manual/expressions/simple-expression.xml
Normal 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
60
doc/manual/expressions/standard-env.xml
Normal 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
27
doc/manual/expressions/writing-nix-expressions.xml
Normal 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>
|
||||||
|
|
@ -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 <(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
57
doc/manual/installation/building-source.xml
Normal 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
24
doc/manual/installation/env-variables.xml
Normal 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
34
doc/manual/installation/installation.xml
Normal 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
81
doc/manual/installation/installing-binary.xml
Normal 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 <(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
17
doc/manual/installation/installing-source.xml
Normal 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
106
doc/manual/installation/multi-user.xml
Normal 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
27
doc/manual/installation/nix-security.xml
Normal 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
30
doc/manual/installation/obtaining-source.xml
Normal 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
73
doc/manual/installation/prerequisites-source.xml
Normal 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
21
doc/manual/installation/single-user.xml
Normal 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
38
doc/manual/installation/supported-platforms.xml
Normal 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>
|
||||||
|
|
@ -1,11 +1,10 @@
|
||||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
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>
|
<title>About Nix</title>
|
||||||
|
|
||||||
|
|
||||||
<section><title>About Nix</title>
|
|
||||||
|
|
||||||
<para>Nix is a <emphasis>purely functional package manager</emphasis>.
|
<para>Nix is a <emphasis>purely functional package manager</emphasis>.
|
||||||
This means that it treats packages like values in purely functional
|
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>
|
</chapter>
|
||||||
16
doc/manual/introduction/introduction.xml
Normal file
16
doc/manual/introduction/introduction.xml
Normal 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
20
doc/manual/introduction/nix-license.xml
Normal 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>
|
||||||
|
|
@ -1,9 +1,12 @@
|
||||||
<book xmlns="http://docbook.org/ns/docbook"
|
<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>
|
<info>
|
||||||
|
|
||||||
<title>Nix User's Guide</title>
|
<title>Nix Package Manager Guide</title>
|
||||||
|
|
||||||
<edition>Version <xi:include href="version.txt" parse="text" /></edition>
|
<edition>Version <xi:include href="version.txt" parse="text" /></edition>
|
||||||
|
|
||||||
|
|
@ -27,58 +30,30 @@
|
||||||
|
|
||||||
</info>
|
</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="introduction/introduction.xml" />
|
||||||
<xi:include href="quick-start.xml" />
|
<xi:include href="quicks-start/quick-start.xml" />
|
||||||
<xi:include href="installation.xml" />
|
<xi:include href="installation/installation.xml" />
|
||||||
<xi:include href="package-management.xml" />
|
<xi:include href="packages/package-management.xml" />
|
||||||
<xi:include href="writing-nix-expressions.xml" />
|
<xi:include href="expressions/writing-nix-expressions.xml" />
|
||||||
<xi:include href="build-farm.xml" />
|
<xi:include href="builds/build-farm.xml" />
|
||||||
|
<xi:include href="command-ref/command-ref.xml" />
|
||||||
|
<xi:include href="troubleshooting/troubleshooting.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="bugs.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="hacking.xml" />
|
||||||
|
<xi:include href="release-notes/release-notes.xml" />
|
||||||
|
|
||||||
|
<!--
|
||||||
<appendix>
|
<appendix>
|
||||||
<title>Nix Release Notes</title>
|
<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)" />
|
xpointer="xmlns(x=http://docbook.org/ns/docbook)xpointer(x:article/x:section)" />
|
||||||
</appendix>
|
</appendix>
|
||||||
|
-->
|
||||||
|
|
||||||
</book>
|
</book>
|
||||||
|
|
|
||||||
|
|
@ -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 < 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
170
doc/manual/packages/basic-package-mgmt.xml
Normal 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
57
doc/manual/packages/channels.xml
Normal 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
70
doc/manual/packages/garbage-collection.xml
Normal 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
29
doc/manual/packages/garbage-collector-roots.xml
Normal 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
37
doc/manual/packages/one-click.xml
Normal 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
24
doc/manual/packages/package-management.xml
Normal 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
159
doc/manual/packages/profiles.xml
Normal 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
82
doc/manual/packages/sharing-packages.xml
Normal 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 < 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>
|
||||||
|
|
@ -1,17 +1,15 @@
|
||||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
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
|
<step><para>Install Nix by running the following:
|
||||||
documentation. For more in-depth information you are kindly referred
|
|
||||||
to the following chapters.</para>
|
|
||||||
|
|
||||||
<orderedlist>
|
|
||||||
|
|
||||||
<listitem><para>Install Nix by running the following:
|
|
||||||
|
|
||||||
<screen>
|
<screen>
|
||||||
$ bash <(curl https://nixos.org/nix/install)
|
$ bash <(curl https://nixos.org/nix/install)
|
||||||
|
|
@ -20,9 +18,9 @@ $ bash <(curl https://nixos.org/nix/install)
|
||||||
This will install Nix in <filename>/nix</filename>. The install script
|
This will install Nix in <filename>/nix</filename>. The install script
|
||||||
will create <filename>/nix</filename> using <command>sudo</command>,
|
will create <filename>/nix</filename> using <command>sudo</command>,
|
||||||
so make sure you have sufficient rights. (For other installation
|
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:
|
in the channel:
|
||||||
|
|
||||||
<screen>
|
<screen>
|
||||||
|
|
@ -33,17 +31,17 @@ hello-2.1.1
|
||||||
libxslt-1.1.0
|
libxslt-1.1.0
|
||||||
<replaceable>...</replaceable></screen>
|
<replaceable>...</replaceable></screen>
|
||||||
|
|
||||||
</para></listitem>
|
</para></step>
|
||||||
|
|
||||||
<listitem><para>Install some packages from the channel:
|
<step><para>Install some packages from the channel:
|
||||||
|
|
||||||
<screen>
|
<screen>
|
||||||
$ nix-env -i hello <replaceable>...</replaceable> </screen>
|
$ nix-env -i hello <replaceable>...</replaceable> </screen>
|
||||||
|
|
||||||
This should download pre-built packages; it should not build them
|
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>
|
<screen>
|
||||||
$ which hello
|
$ which hello
|
||||||
|
|
@ -52,16 +50,16 @@ $ hello
|
||||||
Hello, world!
|
Hello, world!
|
||||||
</screen>
|
</screen>
|
||||||
|
|
||||||
</para></listitem>
|
</para></step>
|
||||||
|
|
||||||
<listitem><para>Uninstall a package:
|
<step><para>Uninstall a package:
|
||||||
|
|
||||||
<screen>
|
<screen>
|
||||||
$ nix-env -e hello</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>
|
<screen>
|
||||||
$ nix-channel --update nixpkgs
|
$ nix-channel --update nixpkgs
|
||||||
|
|
@ -69,9 +67,9 @@ $ nix-env -u '*'</screen>
|
||||||
|
|
||||||
The latter command will upgrade each installed package for which there
|
The latter command will upgrade each installed package for which there
|
||||||
is a “newer” version (as determined by comparing the version
|
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
|
your web browser. For instance, you can go to <link
|
||||||
xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
|
xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
|
||||||
/> and click on any link for the individual packages for your
|
/> 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
|
the program <command>nix-install-package</command>. A window should
|
||||||
appear asking you whether it’s okay to install the package. Say
|
appear asking you whether it’s okay to install the package. Say
|
||||||
<literal>Y</literal>. The package and all its dependencies will be
|
<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
|
<command>nix-env</command> action (e.g., an upgraded package turned
|
||||||
out not to work properly), you can go back:
|
out not to work properly), you can go back:
|
||||||
|
|
||||||
<screen>
|
<screen>
|
||||||
$ nix-env --rollback</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
|
to get rid of unused packages, since uninstalls or upgrades don't
|
||||||
actually delete them:
|
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
|
generations available for garbage collection), while the second
|
||||||
command actually deletes them.-->
|
command actually deletes them.-->
|
||||||
|
|
||||||
</para></listitem>
|
</para></step>
|
||||||
|
|
||||||
</orderedlist>
|
</procedure>
|
||||||
|
|
||||||
</chapter>
|
</chapter>
|
||||||
17
doc/manual/quick-start/quick-start.xml
Normal file
17
doc/manual/quick-start/quick-start.xml
Normal 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>
|
||||||
File diff suppressed because it is too large
Load diff
43
doc/manual/release-notes/release-notes.xml
Normal file
43
doc/manual/release-notes/release-notes.xml
Normal 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
323
doc/manual/release-notes/rl-010.xml
Normal 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
13
doc/manual/release-notes/rl-0101.xml
Normal 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
261
doc/manual/release-notes/rl-011.xml
Normal 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
175
doc/manual/release-notes/rl-012.xml
Normal 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 <
|
||||||
|
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
106
doc/manual/release-notes/rl-013.xml
Normal 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
44
doc/manual/release-notes/rl-014.xml
Normal 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
14
doc/manual/release-notes/rl-015.xml
Normal 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
55
doc/manual/release-notes/rl-016.xml
Normal 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
11
doc/manual/release-notes/rl-05.xml
Normal 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
122
doc/manual/release-notes/rl-06.xml
Normal 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
35
doc/manual/release-notes/rl-07.xml
Normal 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
246
doc/manual/release-notes/rl-08.xml
Normal 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 <= 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
21
doc/manual/release-notes/rl-081.xml
Normal 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
98
doc/manual/release-notes/rl-09.xml
Normal 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];
|
||||||
|
};
|
||||||
|
 
|
||||||
|
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
13
doc/manual/release-notes/rl-091.xml
Normal 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
28
doc/manual/release-notes/rl-092.xml
Normal 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), >&=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
119
doc/manual/release-notes/rl-10.xml
Normal 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><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
100
doc/manual/release-notes/rl-11.xml
Normal 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 <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
157
doc/manual/release-notes/rl-12.xml
Normal 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
19
doc/manual/release-notes/rl-13.xml
Normal 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
39
doc/manual/release-notes/rl-14.xml
Normal 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
12
doc/manual/release-notes/rl-15.xml
Normal 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
12
doc/manual/release-notes/rl-151.xml
Normal 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
12
doc/manual/release-notes/rl-152.xml
Normal 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
127
doc/manual/release-notes/rl-16.xml
Normal 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 <nixpkgs> {};
|
||||||
|
[ thunderbird
|
||||||
|
geeqie
|
||||||
|
...
|
||||||
|
]
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
then after any change to this file, you can run:
|
||||||
|
|
||||||
|
<screen>
|
||||||
|
$ nix-env -f my-packages.nix -ir
|
||||||
|
</screen>
|
||||||
|
|
||||||
|
to update your profile to match the specification.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>The ‘<literal>with</literal>’ language construct is now more
|
||||||
|
lazy. It only evaluates its argument if a variable might actually
|
||||||
|
refer to an attribute in the argument. For instance, this now
|
||||||
|
works:
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
let
|
||||||
|
pkgs = with pkgs; { foo = "old"; bar = foo; } // overrides;
|
||||||
|
overrides = { foo = "new"; };
|
||||||
|
in pkgs.bar
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
This evaluates to <literal>"new"</literal>, while previously it
|
||||||
|
gave an “infinite recursion” error.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>Nix now has proper integer arithmetic operators. For
|
||||||
|
instance, you can write <literal>x + y</literal> instead of
|
||||||
|
<literal>builtins.add x y</literal>, or <literal>x <
|
||||||
|
y</literal> instead of <literal>builtins.lessThan x y</literal>.
|
||||||
|
The comparison operators also work on strings.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>On 64-bit systems, Nix integers are now 64 bits rather than
|
||||||
|
32 bits.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>When using the Nix daemon, the <command>nix-daemon</command>
|
||||||
|
worker process now runs on the same CPU as the client, on systems
|
||||||
|
that support setting CPU affinity. This gives a significant speedup
|
||||||
|
on some systems.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>If a stack overflow occurs in the Nix evaluator, you now get
|
||||||
|
a proper error message (rather than “Segmentation fault”) on some
|
||||||
|
systems.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>In addition to directories, you can now bind-mount regular
|
||||||
|
files in chroots through the (now misnamed) option
|
||||||
|
<option>build-chroot-dirs</option>.</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>This release has contributions from Domen Kožar, Eelco Dolstra,
|
||||||
|
Florian Friesdorf, Gergely Risko, Ivan Kozik, Ludovic Courtès and Shea
|
||||||
|
Levy.</para>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
69
doc/manual/release-notes/rl-161.xml
Normal file
69
doc/manual/release-notes/rl-161.xml
Normal 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
Loading…
Reference in a new issue