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

Overlays: allow overlays to be specified in a file

Browse Source
This commit is contained in:
Michael Peyton Jones
2017-08-17 22:13:39 +00:00
committed by Nicolas B. Pierron
parent 060a41d225
commit 9235ff1259
2 changed files with 70 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/overlays.xml
+41 -15
View File
@@ -17,42 +17,68 @@ 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:
<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. This can be passed explicitly when importing nipxkgs, for example
<literal>import &lt;nixpkgs> { overlays = [ overlay1 overlay2 ] }</literal>.</para>
then that is used.</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>
<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 and is a
directory, then the result is the set of overlays found in that directory, ordered lexicographically.</para>
<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>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>
<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>For the second and third options, overlays are extracted from the given directory as files,
directories containing a <filename>default.nix</filename>, or symlinks to one of those.</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>
<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>
<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 looked up independently.</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>
</section>