New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add overlays mechanism to Nixpkgs. #21243
Changes from 7 commits
b28d698
3490df6
4e3c511
0d5a8e4
4eb8d9c
9cedda5
4205b8a
7fda136
5b9131c
120a603
17efce4
8798264
97e75f2
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,99 @@ | ||
<chapter xmlns="http://docbook.org/ns/docbook" | ||
xmlns:xlink="http://www.w3.org/1999/xlink" | ||
xml:id="chap-overlays"> | ||
|
||
<title>Overlays</title> | ||
|
||
<para>This chapter describes how to extend and change Nixpkgs packages using | ||
overlays. Overlays are used to add layers in the fix-point used by Nixpkgs | ||
to compose the set of all packages.</para> | ||
|
||
<!--============================================================--> | ||
|
||
<section xml:id="sec-overlays-install"> | ||
<title>Installing Overlays</title> | ||
|
||
<para>The set of overlays is looked for in the following places. The | ||
first one present is considered, and all the rest are ignored: | ||
|
||
<orderedlist> | ||
|
||
<listitem> | ||
|
||
<para>As an argument of the imported attribute set. When importing Nixpkgs, | ||
the <varname>overlays</varname> attribute argument can be set to a list of | ||
functions, which is described in <xref linkend="sec-overlays-layout"/>.</para> | ||
|
||
</listitem> | ||
|
||
<listitem> | ||
|
||
<para>In the directory pointed by the environment variable | ||
<varname>NIXPKGS_OVERLAYS</varname>. | ||
</listitem> | ||
|
||
<listitem> | ||
|
||
<para>In the directory <filename>~/.nixpkgs/overlays/</filename>. | ||
</listitem> | ||
|
||
</orderedlist> | ||
</para> | ||
|
||
<para>For the second and third option, the directory should contain Nix expressions defining the | ||
overlays. Each overlay can be a file, a directory containing a | ||
<filename>default.nix</filename>, or a symlink to one of those. The expressions should follow | ||
the syntax described in <xref linkend="sec-overlays-layout"/>.</para> | ||
|
||
<para>The order of the overlay layers can influence the recipe of packages if multiple layers override | ||
the same recipe. In the case where overlays are loaded from a directory, these are loaded in | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
alphabetical order.</para> | ||
|
||
<para>To install an overlay using the last option, you can clone the overlay's repository and add | ||
a symbolic link to in the <filename>~/.nixpkgs/overlays/</filename> directory.</para> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
|
||
</section> | ||
|
||
<!--============================================================--> | ||
|
||
<section xml:id="sec-overlays-layout"> | ||
<title>Overlays Layout</title> | ||
|
||
<para>Overlays are expressed as Nix functions which accept 2 arguments and return a set of | ||
packages</para> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Needs a period or colon at the end. |
||
|
||
<programlisting> | ||
self: super: | ||
|
||
{ | ||
boost = super.boost.override { | ||
python = self.python3; | ||
}; | ||
rr = super.callPackage ./pkgs/rr { | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why is this There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. E.g. I would think we need to provide a custom There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Technically you could use both, but this would get some extra meaning in the futur (security-update branch), because Note that I documented it as functions should be taken from Also note that this way, we make it syntactically verifiable, as anything which comes around the dependencies uses There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. That sounds reasonable, but can you explain how functions already capture
How does the second There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. OK, I tried it out and looked at the implementation and I now understand why this works, albeit the current behavior is slightly surprising to me. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. self: super:
{
callWithSelf = f: f self;
} Any layer defined after could then do: self: super:
{
mySelfClone = super.callWithSelf (x: x);
} |
||
stdenv = self.stdenv_32bit; | ||
}; | ||
} | ||
</programlisting> | ||
|
||
<para>The first argument, usually named <varname>self</varname>, corresponds to the final package | ||
set. You should use this set for the dependencies of all packages specified in your | ||
overlay. For example, all the dependencies of <varname>rr</varname> in the example above come | ||
from <varname>self</varname>, as well as the overriden dependencies used in the | ||
<varname>boost</varname> override.</para> | ||
|
||
<para>The second argument, usually named <varname>super</varname>, | ||
corresponds to the result of the evaluation of the previous stages of | ||
Nixpkgs. It does not contain any of the packages added by the current | ||
overlay nor any of the following overlays. This set should be used either | ||
to refer to packages you wish to override, or to access functions defined | ||
in Nixpkgs. For example, the original recipe of <varname>boost</varname> | ||
in the above example, comes from <varname>super</varname>, as well as the | ||
<varname>callPackage</varname> function.</para> | ||
|
||
<para>The value returned by this function should be a set similar to | ||
<filename>pkgs/top-level/all-packages.nix</filename>, which contains | ||
overridden and/or new packages.</para> | ||
|
||
</section> | ||
|
||
</chapter> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
grammar: options