forked from mirrors/nixpkgs
109 lines
4.4 KiB
XML
109 lines
4.4 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 packages using
|
|
overlays. Overlays are used to add layers in the fix-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 is determined as follows:
|
|
|
|
<orderedlist>
|
|
|
|
<listitem>
|
|
<para>First, if an <varname>overlays</varname> argument to the nixpkgs function itself is given,
|
|
then that is used. This can be passed explicitly when importing nipxkgs, for example
|
|
<literal>import <nixpkgs> { overlays = [ overlay1 overlay2 ] }</literal>.</para>
|
|
|
|
<para>On a NixOS system the value of the <literal>nixpkgs.overlays</literal> option, if present,
|
|
is passed to the system Nixpkgs in this way. Note that this does not affect the overlays for
|
|
non-NixOS operations (e.g. <literal>nix-env</literal>), which are looked up independently.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Otherwise, if the Nix path entry <literal><nixpkgs-overlays></literal> exists and is a
|
|
directory, then the result is the set of overlays found in that directory, ordered lexicographically.</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>Otherwise, if <filename>~/.config/nixpkgs/overlays/</filename> exists and is a directory, then
|
|
the result is the set of overlays found in that directory, ordered lexicographically.</para>
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>For the second and third options overlays can be provided as files,
|
|
directories containing a <filename>default.nix</filename>, or symlinks to one of those.</para>
|
|
|
|
<para>The last option provides a convenient way to install an overlay from a repository,
|
|
by cloning the overlay's repository and adding a symbolic link to it in
|
|
<filename>~/.config/nixpkgs/overlays/</filename>.</para>
|
|
|
|
</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>
|