196 lines
6.7 KiB
XML
196 lines
6.7 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xml:id="chap-overlays">
|
|
<title>Overlays</title>
|
|
<para>
|
|
This chapter describes how to extend and change Nixpkgs using overlays.
|
|
Overlays are used to add layers in the fixed-point used by Nixpkgs to compose
|
|
the set of all packages.
|
|
</para>
|
|
<para>
|
|
Nixpkgs can be configured with a list of overlays, which are applied in
|
|
order. This means that the order of the overlays can be significant if
|
|
multiple layers override the same package.
|
|
</para>
|
|
<!--============================================================-->
|
|
<section xml:id="sec-overlays-install">
|
|
<title>Installing overlays</title>
|
|
|
|
<para>
|
|
The list of overlays can be set either explicitly in a Nix expression, or
|
|
through <literal><nixpkgs-overlays></literal> or user configuration
|
|
files.
|
|
</para>
|
|
|
|
<section xml:id="sec-overlays-argument">
|
|
<title>Set overlays in NixOS or Nix expressions</title>
|
|
|
|
<para>
|
|
On a NixOS system the value of the <literal>nixpkgs.overlays</literal>
|
|
option, if present, is passed to the system Nixpkgs directly as an
|
|
argument. Note that this does not affect the overlays for non-NixOS
|
|
operations (e.g. <literal>nix-env</literal>), which are
|
|
<link xlink:href="#sec-overlays-lookup">looked</link> up independently.
|
|
</para>
|
|
|
|
<para>
|
|
The list of overlays can be passed explicitly when importing nixpkgs, for
|
|
example <literal>import <nixpkgs> { overlays = [ overlay1 overlay2 ];
|
|
}</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
Further overlays can be added by calling the <literal>pkgs.extend</literal>
|
|
or <literal>pkgs.appendOverlays</literal>, although it is often preferable
|
|
to avoid these functions, because they recompute the Nixpkgs fixpoint,
|
|
which is somewhat expensive to do.
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="sec-overlays-lookup">
|
|
<title>Install overlays via configuration lookup</title>
|
|
|
|
<para>
|
|
The list of overlays is determined as follows.
|
|
</para>
|
|
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
First, if an
|
|
<link xlink:href="#sec-overlays-argument"><varname>overlays</varname>
|
|
argument</link> to the Nixpkgs function itself is given, then that is
|
|
used and no path lookup will be performed.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Otherwise, if the Nix path entry
|
|
<literal><nixpkgs-overlays></literal> exists, we look for overlays at
|
|
that path, as described below.
|
|
</para>
|
|
<para>
|
|
See the section on <literal>NIX_PATH</literal> in the Nix manual for
|
|
more details on how to set a value for
|
|
<literal><nixpkgs-overlays>.</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If one of <filename>~/.config/nixpkgs/overlays.nix</filename> and
|
|
<filename>~/.config/nixpkgs/overlays/</filename> exists, then we look
|
|
for overlays at that path, as described below. It is an error if both
|
|
exist.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>
|
|
If we are looking for overlays at a path, then there are two cases:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If the path is a file, then the file is imported as a Nix expression and
|
|
used as the list of overlays.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If the path is a directory, then we take the content of the directory,
|
|
order it lexicographically, and attempt to interpret each as an overlay
|
|
by:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Importing the file, if it is a <literal>.nix</literal> file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Importing a top-level <filename>default.nix</filename> file, if it is
|
|
a directory.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Because overlays that are set in NixOS configuration do not affect
|
|
non-NixOS operations such as <literal>nix-env</literal>, the
|
|
<filename>overlays.nix</filename> option provides a convenient way to use
|
|
the same overlays for a NixOS system configuration and user configuration:
|
|
the same file can be used as <filename>overlays.nix</filename> and imported
|
|
as the value of <literal>nixpkgs.overlays</literal>.
|
|
</para>
|
|
|
|
<!-- TODO: Example of sharing overlays between NixOS configuration
|
|
and configuration lookup. Also reference the example
|
|
from the sec-overlays-argument paragraph about NixOS.
|
|
-->
|
|
</section>
|
|
</section>
|
|
<!--============================================================-->
|
|
<section xml:id="sec-overlays-definition">
|
|
<title>Defining overlays</title>
|
|
|
|
<para>
|
|
Overlays are Nix functions which accept two arguments, conventionally called
|
|
<varname>self</varname> and <varname>super</varname>, and return a set of
|
|
packages. For example, the following is a valid overlay.
|
|
</para>
|
|
|
|
<programlisting>
|
|
self: super:
|
|
|
|
{
|
|
boost = super.boost.override {
|
|
python = self.python3;
|
|
};
|
|
rr = super.callPackage ./pkgs/rr {
|
|
stdenv = self.stdenv_32bit;
|
|
};
|
|
}
|
|
</programlisting>
|
|
|
|
<para>
|
|
The first argument (<varname>self</varname>) corresponds to the final
|
|
package set. You should use this set for the dependencies of all packages
|
|
specified in your overlay. For example, all the dependencies of
|
|
<varname>rr</varname> in the example above come from
|
|
<varname>self</varname>, as well as the overridden dependencies used in the
|
|
<varname>boost</varname> override.
|
|
</para>
|
|
|
|
<para>
|
|
The second argument (<varname>super</varname>) corresponds to the result of
|
|
the evaluation of the previous stages of Nixpkgs. It does not contain any of
|
|
the packages added by the current overlay, nor any of the following
|
|
overlays. This set should be used either to refer to packages you wish to
|
|
override, or to access functions defined in Nixpkgs. For example, the
|
|
original recipe of <varname>boost</varname> in the above example, comes from
|
|
<varname>super</varname>, as well as the <varname>callPackage</varname>
|
|
function.
|
|
</para>
|
|
|
|
<para>
|
|
The value returned by this function should be a set similar to
|
|
<filename>pkgs/top-level/all-packages.nix</filename>, containing overridden
|
|
and/or new packages.
|
|
</para>
|
|
|
|
<para>
|
|
Overlays are similar to other methods for customizing Nixpkgs, in particular
|
|
the <literal>packageOverrides</literal> attribute described in
|
|
<xref linkend="sec-modify-via-packageOverrides"/>. Indeed,
|
|
<literal>packageOverrides</literal> acts as an overlay with only the
|
|
<varname>super</varname> argument. It is therefore appropriate for basic
|
|
use, but overlays are more powerful and easier to distribute.
|
|
</para>
|
|
</section>
|
|
</chapter>
|