Manual: Describe NixOS package management styles
This commit is contained in:
Eelco Dolstra
parent
1ff7584a30
commit
81eebecd15
|
|
@ -11,6 +11,300 @@ NixOS machine through the configuration file
|
||||||
effect after you run <command>nixos-rebuild</command>.</para>
|
effect after you run <command>nixos-rebuild</command>.</para>
|
||||||
|
|
||||||
|
|
||||||
|
<!--===============================================================-->
|
||||||
|
|
||||||
|
<section><title>Package management</title>
|
||||||
|
|
||||||
|
<para>This section describes how to add additional packages to your
|
||||||
|
system. NixOS has two distinct styles of package management:
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
|
||||||
|
<listitem><para><emphasis>Declarative</emphasis>, where you declare
|
||||||
|
what packages you want in your
|
||||||
|
<filename>configuration.nix</filename>. Every time you run
|
||||||
|
<command>nixos-rebuild</command>, NixOS will ensure that you get a
|
||||||
|
consistent set of binaries corresponding to your
|
||||||
|
specification.</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para><emphasis>Ad hoc</emphasis>, where you install,
|
||||||
|
upgrade and uninstall packages via the <command>nix-env</command>
|
||||||
|
command. This style allows mixing packages from different Nixpkgs
|
||||||
|
versions. It’s the only choice for non-root
|
||||||
|
users.</para></listitem>
|
||||||
|
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>The next two sections describe these two styles.</para>
|
||||||
|
|
||||||
|
|
||||||
|
<section><title>Declarative package management</title>
|
||||||
|
|
||||||
|
<para>With declarative package management, you specify which packages
|
||||||
|
you want on your system by setting the option
|
||||||
|
<option>environment.systemPackages</option>. For instance, adding the
|
||||||
|
following line to <filename>configuration.nix</filename> enables the
|
||||||
|
Mozilla Thunderbird email application:
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
environment.systemPackages = [ pkgs.thunderbird ];
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
The effect of this specification is that the Thunderbird package from
|
||||||
|
Nixpkgs will be built or downloaded as part of the system when you run
|
||||||
|
<command>nixos-rebuild switch</command>.</para>
|
||||||
|
|
||||||
|
<para>You can get a list of the available packages as follows:
|
||||||
|
<screen>
|
||||||
|
$ nix-env -qaP '*' --description
|
||||||
|
nixos.pkgs.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
|
||||||
|
<replaceable>...</replaceable>
|
||||||
|
</screen>
|
||||||
|
|
||||||
|
The first column in the output is the <emphasis>attribute
|
||||||
|
name</emphasis>, such as
|
||||||
|
<literal>nixos.pkgs.thunderbird</literal>. (The
|
||||||
|
<literal>nixos</literal> prefix allows distinguishing between
|
||||||
|
different channels that you might have.)</para>
|
||||||
|
|
||||||
|
<para>To “uninstall” a package, simply remove it from
|
||||||
|
<option>environment.systemPackages</option> and run
|
||||||
|
<command>nixos-rebuild switch</command>.</para>
|
||||||
|
|
||||||
|
|
||||||
|
<section><title>Customising packages</title>
|
||||||
|
|
||||||
|
<para>Some packages in Nixpkgs have options to enable or disable
|
||||||
|
optional functionality or change other aspects of the package. For
|
||||||
|
instance, the Firefox wrapper package (which provides Firefox with a
|
||||||
|
set of plugins such as the Adobe Flash player) has an option to enable
|
||||||
|
the Google Talk plugin. It can be set in
|
||||||
|
<filename>configuration.nix</filename> as follows:
|
||||||
|
|
||||||
|
<filename>
|
||||||
|
nixpkgs.config.firefox.enableGoogleTalkPlugin = true;
|
||||||
|
</filename>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<warning><para>Unfortunately, Nixpkgs currently lacks a way to query
|
||||||
|
available configuration options.</para></warning>
|
||||||
|
|
||||||
|
<para>Apart from high-level options, it’s possible to tweak a package
|
||||||
|
in almost arbitrary ways, such as changing or disabling dependencies
|
||||||
|
of a package. For instance, the Emacs package in Nixpkgs by default
|
||||||
|
has a dependency on GTK+ 2. If you want to build it against GTK+ 3,
|
||||||
|
you can specify that as follows:
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
The function <varname>override</varname> performs the call to the Nix
|
||||||
|
function that produces Emacs, with the original arguments amended by
|
||||||
|
the set of arguments specified by you. So here the function argument
|
||||||
|
<varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>,
|
||||||
|
causing Emacs to depend on GTK+ 3. (The parentheses are necessary
|
||||||
|
because in Nix, function application binds more weakly than list
|
||||||
|
construction, so without them,
|
||||||
|
<literal>environment.systemPackages</literal> would be a list with two
|
||||||
|
elements.)</para>
|
||||||
|
|
||||||
|
<para>Even greater customisation is possible using the function
|
||||||
|
<varname>overrideDerivation</varname>. While the
|
||||||
|
<varname>override</varname> mechanism above overrides the arguments of
|
||||||
|
a package function, <varname>overrideDerivation</varname> allows
|
||||||
|
changing the <emphasis>result</emphasis> of the function. This
|
||||||
|
permits changing any aspect of the package, such as the source code.
|
||||||
|
For instance, if you want to override the source code of Emacs, you
|
||||||
|
can say:
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
environment.systemPackages =
|
||||||
|
[ (pkgs.lib.overrideDerivation pkgs.emacs (attrs: {
|
||||||
|
name = "emacs-25.0-pre";
|
||||||
|
src = /path/to/my/emacs/tree;
|
||||||
|
}))
|
||||||
|
];
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
Here, <varname>overrideDerivation</varname> takes the Nix derivation
|
||||||
|
specified by <varname>pkgs.emacs</varname> and produces a new
|
||||||
|
derivation in which the original’s <literal>name</literal> and
|
||||||
|
<literal>src</literal> attribute have been replaced by the given
|
||||||
|
values. The original attributes are accessible via
|
||||||
|
<varname>attrs</varname>.</para>
|
||||||
|
|
||||||
|
<para>The overrides shown above are not global. They do not affect
|
||||||
|
the original package; other packages in Nixpkgs continue to depend on
|
||||||
|
the original rather than the customised package. This means that if
|
||||||
|
another package in your system depends on the original package, you
|
||||||
|
end up with two instances of the package. If you want to have
|
||||||
|
everything depend on your customised instance, you can apply a
|
||||||
|
<emphasis>global</emphasis> override as follows:
|
||||||
|
|
||||||
|
<screen>
|
||||||
|
nixpkgs.config.packageOverrides = pkgs:
|
||||||
|
{ emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
|
||||||
|
};
|
||||||
|
</screen>
|
||||||
|
|
||||||
|
The effect of this definition is essentially equivalent to modifying
|
||||||
|
the <literal>emacs</literal> attribute in the Nixpkgs source tree.
|
||||||
|
Any package in Nixpkgs that depends on <literal>emacs</literal> will
|
||||||
|
be passed your customised instance. (However, the value
|
||||||
|
<literal>pkgs.emacs</literal> in
|
||||||
|
<varname>nixpkgs.config.packageOverrides</varname> refers to the
|
||||||
|
original rather than overriden instance, to prevent an infinite
|
||||||
|
recursion.)</para>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section><title>Adding custom packages</title>
|
||||||
|
|
||||||
|
<para>It’s possible that a package you need is not available in NixOS.
|
||||||
|
In that case, you can do two things. First, you can clone the Nixpkgs
|
||||||
|
repository, add the package to your clone, and (optionally) submit a
|
||||||
|
patch or pull request to have it accepted into the main Nixpkgs
|
||||||
|
repository. This is described in detail in the <link
|
||||||
|
xlink:href="http://hydra.nixos.org/job/nixpkgs/trunk/tarball/latest/download-by-type/doc/manual">Nixpkgs
|
||||||
|
manual</link>. In short, you clone Nixpkgs:
|
||||||
|
|
||||||
|
<screen>
|
||||||
|
$ git clone git://github.com/NixOS/nixpkgs.git
|
||||||
|
$ cd nixpkgs
|
||||||
|
</screen>
|
||||||
|
|
||||||
|
Then you write and test the package as described in the Nixpkgs
|
||||||
|
manual. Finally, you add it to
|
||||||
|
<literal>environment.systemPackages</literal>, e.g.
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
environment.systemPackages = [ pkgs.my-package ];
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
and you run <command>nixos-rebuild</command>, specifying your own
|
||||||
|
Nixpkgs tree:
|
||||||
|
|
||||||
|
<screen>
|
||||||
|
$ nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
|
||||||
|
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>The second possibility is to add the package outside of the
|
||||||
|
Nixpkgs tree. For instance, here is how you specify a build of the
|
||||||
|
<link xlink:href="http://www.gnu.org/software/hello/">GNU Hello</link>
|
||||||
|
package directly in <filename>configuration.nix</filename>:
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
environment.systemPackages =
|
||||||
|
let
|
||||||
|
my-hello = with pkgs; stdenv.mkDerivation rec {
|
||||||
|
name = "hello-2.8";
|
||||||
|
src = fetchurl {
|
||||||
|
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||||
|
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
in
|
||||||
|
[ my-hello ];
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
Of course, you can also move the definition of
|
||||||
|
<literal>my-hello</literal> into a separate Nix expression, e.g.
|
||||||
|
<programlisting>
|
||||||
|
environment.systemPackages = [ (import ./my-hello.nix) ];
|
||||||
|
</programlisting>
|
||||||
|
where <filename>my-hello.nix</filename> contains:
|
||||||
|
<programlisting>
|
||||||
|
with <nixpkgs> {}; # bring all of Nixpkgs into scope
|
||||||
|
|
||||||
|
stdenv.mkDerivation rec {
|
||||||
|
name = "hello-2.8";
|
||||||
|
src = fetchurl {
|
||||||
|
url = "mirror://gnu/hello/${name}.tar.gz";
|
||||||
|
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
|
||||||
|
};
|
||||||
|
}
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
This allows testing the package easily:
|
||||||
|
<screen>
|
||||||
|
$ nix-build my-hello.nix
|
||||||
|
$ ./result/bin/hello
|
||||||
|
Hello, world!
|
||||||
|
</screen>
|
||||||
|
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
|
||||||
|
<section><title>Ad hoc package management</title>
|
||||||
|
|
||||||
|
<para>With the command <command>nix-env</command>, you can install and
|
||||||
|
uninstall packages from the command line. For instance, to install
|
||||||
|
Mozilla Thunderbird:
|
||||||
|
|
||||||
|
<screen>
|
||||||
|
$ nix-env -iA nixos.pkgs.thunderbird</screen>
|
||||||
|
|
||||||
|
If you invoke this as root, the package is installed in the Nix
|
||||||
|
profile <filename>/nix/var/nix/profiles/default</filename> and visible
|
||||||
|
to all users of the system; otherwise, the package ends up in
|
||||||
|
<filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename>
|
||||||
|
and is not visible to other users. The <option>-A</option> flag
|
||||||
|
specifies the package by its attribute name; without it, the package
|
||||||
|
is installed by matching against its package name
|
||||||
|
(e.g. <literal>thunderbird</literal>). The latter is slower because
|
||||||
|
it requires matching against all available Nix packages, and is
|
||||||
|
ambiguous if there are multiple matching packages.</para>
|
||||||
|
|
||||||
|
<para>Packages come from the NixOS channel. You typically upgrade a
|
||||||
|
package by updating to the latest version of the NixOS channel:
|
||||||
|
<screen>
|
||||||
|
$ nix-channel --update nixos
|
||||||
|
</screen>
|
||||||
|
and then running <literal>nix-env -i</literal> again. Other packages
|
||||||
|
in the profile are <emphasis>not</emphasis> affected; this is the
|
||||||
|
crucial difference with the declarative style of package management,
|
||||||
|
where running <command>nixos-rebuild switch</command> causes all
|
||||||
|
packages to be updated to their current versions in the NixOS channel.
|
||||||
|
You can however upgrade all packages for which there is a newer
|
||||||
|
version by doing:
|
||||||
|
<screen>
|
||||||
|
$ nix-env -u '*'
|
||||||
|
</screen>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>A package can be unstalled using the <option>-e</option>
|
||||||
|
flag:
|
||||||
|
<screen>
|
||||||
|
$ nix-env -e thunderbird
|
||||||
|
</screen>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Finally, you can roll back an undesirable
|
||||||
|
<command>nix-env</command> action:
|
||||||
|
<screen>
|
||||||
|
$ nix-env --rollback
|
||||||
|
</screen>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para><command>nix-env</command> has many more flags. For details,
|
||||||
|
see the
|
||||||
|
<citerefentry><refentrytitle>nix-env</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||||
|
manpage or the Nix manual.</para>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
|
||||||
<!--===============================================================-->
|
<!--===============================================================-->
|
||||||
|
|
||||||
<section><title>Networking</title>
|
<section><title>Networking</title>
|
||||||
|
|
|
||||||
|
|
@ -307,7 +307,7 @@ available.</para>
|
||||||
|
|
||||||
<!--===============================================================-->
|
<!--===============================================================-->
|
||||||
|
|
||||||
<section>
|
<section xml:id="sec-upgrading">
|
||||||
|
|
||||||
<title>Upgrading NixOS</title>
|
<title>Upgrading NixOS</title>
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue