mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-21 13:10:33 +00:00
Merge pull request #47430 from roberth/nixpkgs-extend
pkgs.extend for adding overlays
This commit is contained in:
John Ericson
GitHub
commit
b71389aefb
|
|
@ -6,8 +6,14 @@
|
|||
|
||||
<para>
|
||||
Sometimes one wants to override parts of <literal>nixpkgs</literal>, e.g.
|
||||
derivation attributes, the results of derivations or even the whole package
|
||||
set.
|
||||
derivation attributes, the results of derivations.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
These functions are used to make changes to packages, returning only single
|
||||
packages. <link xlink:href="#chap-overlays">Overlays</link>, 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">
|
||||
|
|
@ -25,6 +31,9 @@
|
|||
<para>
|
||||
Example usages:
|
||||
<programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting>
|
||||
<!-- TODO: move below programlisting to a new section about extending and overlays
|
||||
and reference it
|
||||
-->
|
||||
<programlisting>
|
||||
import pkgs.path { overlays = [ (self: super: {
|
||||
foo = super.foo.override { barSupport = true ; };
|
||||
|
|
|
|||
191
doc/overlays.xml
191
doc/overlays.xml
|
|
@ -17,91 +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 nipxkgs, for example
|
||||
<literal>import <nixpkgs> { overlays = [ overlay1 overlay2 ];
|
||||
}</literal>.
|
||||
</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">
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@
|
|||
, # A list of overlays (Additional `self: super: { .. }` customization
|
||||
# functions) to be fixed together in the produced package set
|
||||
overlays
|
||||
}:
|
||||
} @args:
|
||||
|
||||
let
|
||||
stdenvAdapters = self: super:
|
||||
|
|
@ -159,6 +159,19 @@ let
|
|||
};
|
||||
};
|
||||
};
|
||||
|
||||
# Extend the package set with zero or more overlays. This preserves
|
||||
# preexisting overlays. Prefer to initialize with the right overlays
|
||||
# in one go when calling Nixpkgs, for performance and simplicity.
|
||||
appendOverlays = extraOverlays:
|
||||
import ./stage.nix (args // { overlays = args.overlays ++ extraOverlays; });
|
||||
|
||||
# Extend the package set with a single overlay. This preserves
|
||||
# preexisting overlays. Prefer to initialize with the right overlays
|
||||
# in one go when calling Nixpkgs, for performance and simplicity.
|
||||
# Prefer appendOverlays if used repeatedly.
|
||||
extend = f: self.appendOverlays [f];
|
||||
|
||||
};
|
||||
|
||||
# The complete chain of package set builders, applied from top to bottom.
|
||||
|
|
|
|||
Loading…
Reference in a new issue