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

Merge pull request #47430 from roberth/nixpkgs-extend

Browse Source 
pkgs.extend for adding overlays
This commit is contained in:
John Ericson 2018-10-23 20:21:48 -04:00 committed by GitHub
commit b71389aefb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 136 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
doc/functions/overrides.xml
View File

@ -6,8 +6,14 @@
<para> <para>
Sometimes one wants to override parts of <literal>nixpkgs</literal>, e.g. Sometimes one wants to override parts of <literal>nixpkgs</literal>, e.g.
derivation attributes, the results of derivations or even the whole package derivation attributes, the results of derivations.
set. </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> </para>
<section xml:id="sec-pkg-override"> <section xml:id="sec-pkg-override">
@ -25,6 +31,9 @@
<para> <para>
Example usages: Example usages:
<programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting> <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> <programlisting>
import pkgs.path { overlays = [ (self: super: { import pkgs.path { overlays = [ (self: super: {
foo = super.foo.override { barSupport = true ; }; foo = super.foo.override { barSupport = true ; };

191
doc/overlays.xml
View File

@ -17,91 +17,122 @@
<title>Installing overlays</title> <title>Installing overlays</title>
<para> <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>&lt;nixpkgs-overlays></literal> or user configuration
files.
</para> </para>
<para> <section xml:id="sec-overlays-argument">
If the <varname>overlays</varname> argument is not provided explicitly, we <title>Set overlays in NixOS or Nix expressions</title>
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 &lt;nixpkgs> { overlays = [ overlay1 overlay2 ];
}</literal>.
</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.
</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>&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.
</para>
</listitem>
</orderedlist>
</para>
<para> <para>
If we are looking for overlays at a path, then there are two cases: On a NixOS system the value of the <literal>nixpkgs.overlays</literal>
<itemizedlist> option, if present, is passed to the system Nixpkgs directly as an
<listitem> argument. Note that this does not affect the overlays for non-NixOS
<para> operations (e.g. <literal>nix-env</literal>), which are
If the path is a file, then the file is imported as a Nix expression and <link xlink:href="#sec-overlays-lookup">looked</link> up independently.
used as the list of overlays. </para>
</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> <para>
On a NixOS system the value of the <literal>nixpkgs.overlays</literal> The list of overlays can be passed explicitly when importing nixpkgs, for
option, if present, is passed to the system Nixpkgs directly as an argument. example <literal>import &lt;nixpkgs> { overlays = [ overlay1 overlay2 ];
Note that this does not affect the overlays for non-NixOS operations (e.g. }</literal>.
<literal>nix-env</literal>), which are looked up independently. </para>
</para>
<para> <para>
The <filename>overlays.nix</filename> option therefore provides a convenient Further overlays can be added by calling the <literal>pkgs.extend</literal>
way to use the same overlays for a NixOS system configuration and user or <literal>pkgs.appendOverlays</literal>, although it is often preferable
configuration: the same file can be used as to avoid these functions, because they recompute the Nixpkgs fixpoint,
<filename>overlays.nix</filename> and imported as the value of which is somewhat expensive to do.
<literal>nixpkgs.overlays</literal>. </para>
</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>&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
<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.
</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>
<!--============================================================--> <!--============================================================-->
<section xml:id="sec-overlays-definition"> <section xml:id="sec-overlays-definition">

15
pkgs/top-level/stage.nix
View File

@ -56,7 +56,7 @@
, # A list of overlays (Additional `self: super: { .. }` customization , # A list of overlays (Additional `self: super: { .. }` customization
# functions) to be fixed together in the produced package set # functions) to be fixed together in the produced package set
overlays overlays
}: } @args:
let let
stdenvAdapters = self: super: 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. # The complete chain of package set builders, applied from top to bottom.