JakeHillion/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Improve overrides and overlays documentation

Browse Source
This commit is contained in:
Robert Hensing 2018-10-18 14:01:06 +02:00
parent 9b7654f6ff
commit 3c2ae189c2
2 changed files with 114 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/functions/overrides.xml
View File

@ -10,12 +10,9 @@
</para>
<para>
These overriding functions let you focus on one part of Nixpkgs and give you
back the requested variation. This is orthogonal but related to overlays and
the extending functions. Those also let you make modifications but return the
whole package set instead of just what you modified. When used together, the
override functions make the changes and overlays or extending functions add
those changes to the package sets.
These functions are used to make changes to packages, returning only single
packages. Overlays, on the other hand, can be used to combine the overridden
packages across the entire package set of Nixpkgs.
</para>
<section xml:id="sec-pkg-override">

89
doc/overlays.xml
View File

@ -16,47 +16,72 @@
<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>&lt;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 &lt;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>
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 &lt;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.
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>&lt;nixpkgs-overlays></literal>
exists, we look for overlays at that path, as described below.
Otherwise, if the Nix path entry
<literal>&lt;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
See the section on <literal>NIX_PATH</literal> in the Nix manual for
more details on how to set a value for
<literal>&lt;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.
<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>
@ -95,19 +120,19 @@
</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.
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>
<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>
<!-- 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">