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

disassembler · 2017-10-30T10:41:03Z

Motivation for this change

confusion of what self and super represent in overlays, since this is something users can set and isn't hard coded, making this change to the docs should help.

@nbp

Things done

Tested using sandboxing (nix.useSandbox on NixOS, or option build-use-sandbox in nix.conf on non-NixOS)
Built on platform(s)
- NixOS
- macOS
- other Linux distributions
Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
Tested compilation of all pkgs that depend on this change using nix-shell -p nox --run "nox-review wip"
Tested execution of all binary files (usually in ./result/bin/)
Fits CONTRIBUTING.md.

nbp

There is a renaming issue: previous <-> final

nbp · 2017-10-30T10:45:51Z

doc/overlays.xml

  };
 }
 </programlisting>

-<para>The first argument (<varname>self</varname>) corresponds to the final package
+<para>The first argument (<varname>final</varname>) corresponds to the previous package


Bad rewrite again :/

nbp · 2017-10-30T10:56:35Z

doc/overlays.xml

-corresponds to the result of the evaluation of the previous stages of
+<para>The second argument (<varname>previous</varname>)
+corresponds to the result of the evaluation of <literal>Nixpkgs</literal> with the
+overlays applied that are called prior to the application of the current overlay.


nit: s/that are called/

nbp

Last nits before merging.

nbp · 2017-10-30T11:26:52Z

doc/overlays.xml

  };
 }
 </programlisting>

-<para>The first argument (<varname>self</varname>) corresponds to the final package
+<para>The first argument (<varname>final</varname>) corresponds to the resulting
+package set after all the overlays are applied.
 set. You should use this set for the dependencies of all packages specified in your


nit: "… applied. set. You …"

nbp · 2017-10-30T11:28:03Z

doc/overlays.xml

-corresponds to the result of the evaluation of the previous stages of
+<para>The second argument (<varname>previous</varname>)
+corresponds to the result of 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


nit: "… current overlay. Nixpkgs. It …"

grahamc · 2017-10-30T12:45:32Z

doc/overlays.xml

-  rr = super.callPackage ./pkgs/rr {
-    stdenv = self.stdenv_32bit;
+  rr = previous.callPackage ./pkgs/rr {
+    stdenv = final.stdenv_32bit;


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

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).

@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.

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

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

nbp · 2017-10-31T09:45:09Z

doc/overlays.xml

  };
-  rr = super.callPackage ./pkgs/rr {
-    stdenv = self.stdenv_32bit;
+  rr = final.callPackage ./pkgs/rr {


callPackage is a function, which it-self captures self to provide the packages to the package, and using it through self will go through the fix-point twice.

This does not make sense to me. For the interpreter the fix point is not a loop, and there is no such thing as the count of goes through the fix point. (Here is an accurate enough model of the internal states of a straightforward interpreter of the nix language that illustrates this: https://gist.github.com/orivej/5fddcf792dfa37a5bfa16d9a95fe70fa .) Using final is in no way less computationally efficient than using previous. When callPackage is not overridden in a future overlay, final.callPackage is exactly the same as previous.callPackage, but the choice of the former is more obvious.

@orivej Today there is not, but the reason the documentation is that way, is to make sure that we make the code written by user future-proof. Doing the opposite would become a problem for automatic grafting.

As you mentioned, there is no difference today, but doing it as currently mentioned in the documentation will prevent the addition of issues that would have to be fixed later.

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

Could you explain why functions should come from previous? I am fairly certain that in practice this is a stylistic choice until someone wants to override some functions (and final looks better), that we should use final if they do, and it should not concern us if the referenced value is a derivation or a function . The only concern is if we can just use the final value, or if we need the previous value to implement our override of it.

@nbp Could you detail the future plans? What is automatic grafting?

From the name of it I guess the automatic grafting is deep merging of attribute sets, but that does not seem to cause any issues with using functions from final.

@orivej The automatic grafting described in #10851 , which is coming slowly, depends on the fact that we can peel off the fix-point and watch the number of hops through the fix-point. Using a function which captures self, from self, implies that we go twice through self, and miss this dependency.

disassembler · 2017-10-31T09:49:09Z

@nbp ok, reverted. Look good now?

nbp · 2017-10-31T09:55:13Z

doc/overlays.xml

-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


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

Mic92 · 2017-11-25T16:08:38Z

any updates?

dtzWill · 2018-03-01T13:52:34Z

Beep boop, is this ready?

disassembler · 2018-10-27T09:23:13Z

I'm going to close this. self: super everyone is comfortable with now and I think it would just confuse people if we changed the names at this point.

nbp suggested changes Oct 30, 2017

View reviewed changes

disassembler force-pushed the overlay-self-super-rename branch from e94fd38 to 7fb4800 Compare October 30, 2017 10:44

nbp suggested changes Oct 30, 2017

View reviewed changes

disassembler force-pushed the overlay-self-super-rename branch from 7fb4800 to 4ad8a3e Compare October 30, 2017 10:54

disassembler changed the title ~~overlay: doc update for self/super -> previous/final~~ overlay: doc update for self/super -> final/previous Oct 30, 2017

nbp approved these changes Oct 30, 2017

View reviewed changes

disassembler force-pushed the overlay-self-super-rename branch 2 times, most recently from b05f34a to b0fab62 Compare October 30, 2017 11:25

nbp approved these changes Oct 30, 2017

View reviewed changes

grahamc reviewed Oct 30, 2017

View reviewed changes

disassembler force-pushed the overlay-self-super-rename branch 3 times, most recently from fbc1979 to b1b6b06 Compare October 30, 2017 21:46

nbp suggested changes Oct 31, 2017

View reviewed changes

docs: overlay update for self/super -> final/previous

5d5927f

disassembler force-pushed the overlay-self-super-rename branch from b1b6b06 to 5d5927f Compare October 31, 2017 09:48

nbp suggested changes Oct 31, 2017

View reviewed changes

disassembler closed this Oct 27, 2018

spikespaz mentioned this pull request Feb 7, 2024

nix: overlay polish for prev parameter hyprwm/Hyprland#4558

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

disassembler commented Oct 30, 2017

nbp left a comment

nbp Oct 30, 2017

nbp Oct 30, 2017

nbp left a comment

nbp Oct 30, 2017

nbp Oct 30, 2017

grahamc Oct 30, 2017

orivej Oct 30, 2017

nbp Oct 30, 2017

disassembler Oct 30, 2017

nbp Oct 31, 2017

nbp Oct 31, 2017

orivej Oct 31, 2017

nbp Oct 31, 2017

orivej Oct 31, 2017 •

edited

orivej Oct 31, 2017

orivej Oct 31, 2017

nbp Oct 31, 2017

disassembler commented Oct 31, 2017

nbp Oct 31, 2017

Mic92 commented Nov 25, 2017

dtzWill commented Mar 1, 2018

disassembler commented Oct 27, 2018

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

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

Conversation

disassembler commented Oct 30, 2017

Motivation for this change

Things done

nbp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nbp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

orivej Oct 31, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

disassembler commented Oct 31, 2017

Choose a reason for hiding this comment

Mic92 commented Nov 25, 2017

dtzWill commented Mar 1, 2018

disassembler commented Oct 27, 2018

orivej Oct 31, 2017 •

edited