Skip to content
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.

Sign up for GitHub

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

overlay: doc update for self/super -> final/previous #30958

Closed
wants to merge 1 commit into from
Closed

overlay: doc update for self/super -> final/previous #30958

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 17 additions & 15 deletions doc/overlays.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,35 +88,37 @@ as <filename>overlays.nix</filename> and imported as the value of <literal>nixpk
<title>Defining overlays</title>

<para>Overlays are Nix functions which accept two arguments,
conventionally called <varname>self</varname> and <varname>super</varname>,
conventionally called <varname>final</varname> and <varname>previous</varname>,
and return a set of packages. For example, the following is a valid overlay.</para>

<programlisting>
self: super:
final: previous:

{
boost = super.boost.override {
python = self.python3;
boost = previous.boost.override {
python = final.python3;
};
rr = super.callPackage ./pkgs/rr {
stdenv = self.stdenv_32bit;
rr = previous.callPackage ./pkgs/rr {
stdenv = final.stdenv_32bit;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it isn't really final though, is it? It can be overlayed on top of later.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

final is the composition of all overlays, including the future ones too.

However, the brevity and clarity of final in this rr example highlights that we should use e.g. final.callPackage, not previous.callPackage for functions, and use previous only when we explicitly want the previous definition (because the current definition will shadow it in the final set).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@grahamc stdenv_32bit is the final, as this is the result which went through the fix-point.
rr is not final yet, it might be overriden, and would be in the previous set of the next overlay.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@orivej that makes sense to me. Updated PR to use final.callPackage unless @nbp disagrees and wants me to change it back.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I disagree, callPackage is a function, and it should come from previous, not final.

};
}
</programlisting>

<para>The first argument (<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 overridden dependencies used in the
<varname>boost</varname> override.</para>
<para>The first argument (<varname>final</varname>) corresponds to the
resulting package set after all the overlays are applied. 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>final</varname>, as well as the overridden dependencies
used in the <varname>boost</varname> override.</para>

<para>The second argument (<varname>super</varname>)
corresponds to the result of the evaluation of the previous stages of
<para>The second argument (<varname>previous</varname>)
corresponds to the the evaluation of <literal>Nixpkgs</literal> with the
overlays applied prior to the application of the current overlay.
Nixpkgs. It does not contain any of the packages added by the current
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: […] current overlay. Nixpkgs. It does […]

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
in the above example, comes from <varname>previous</varname>, as well as the
<varname>callPackage</varname> function.</para>

<para>The value returned by this function should be a set similar to
Expand All @@ -126,7 +128,7 @@ overridden and/or new packages.</para>
<para>Overlays are similar to other methods for customizing Nixpkgs, in particular
the <literal>packageOverrides</literal> attribute described in <xref linkend="sec-modify-via-packageOverrides"/>.
Indeed, <literal>packageOverrides</literal> acts as an overlay with only the
<varname>super</varname> argument. It is therefore appropriate for basic use,
<varname>previous</varname> argument. It is therefore appropriate for basic use,
but overlays are more powerful and easier to distribute.</para>

</section>
Expand Down