doc: Improve overrides and overlays documentation
This commit is contained in:
Robert Hensing
+111
-86
@@ -17,97 +17,122 @@
|
||||
<title>Installing overlays</title>
|
||||
|
||||
<para>
|
||||
The list of overlays is determined as follows.
|
||||
The list of overlays can be set either explicitly in a Nix expression, or
|
||||
through <literal><nixpkgs-overlays></literal> or user configuration
|
||||
files.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If the <varname>overlays</varname> argument is not provided explicitly, we
|
||||
look for overlays in a path. The path 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.
|
||||
</para>
|
||||
<para>
|
||||
This 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>
|
||||
</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>
|
||||
<section xml:id="sec-overlays-argument">
|
||||
<title>Set overlays in NixOS or Nix expressions</title>
|
||||
|
||||
<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>
|
||||
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>
|
||||
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 looked 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>
|
||||
The <filename>overlays.nix</filename> option therefore 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>
|
||||
<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">
|
||||
|
||||
Reference in New Issue
Block a user