stdenv.mkDerivation: Make self more overlay-like; use self.public

`self` is now arguments, like `super`. The final package is in
`self.public`.

2 files changed, 10 insertions, 7 deletions

diff --git a/doc/stdenv/meta.chapter.md b/doc/stdenv/meta.chapter.md
index 64924dceb717..e57669e261b3 100644
--- a/doc/stdenv/meta.chapter.md
+++ b/doc/stdenv/meta.chapter.md
@@ -187,7 +187,7 @@ all places.
 { stdenv, callPackage }:
 stdenv.mkDerivation (self: {
   # ...
-  passthru.tests.example = callPackage ./example.nix { my-package = self; };
+  passthru.tests.example = callPackage ./example.nix { my-package = self.public; }
 })
 ```
 
diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md
index 2994f7020b19..b54d68cb5ddd 100644
--- a/doc/stdenv/stdenv.chapter.md
+++ b/doc/stdenv/stdenv.chapter.md
@@ -319,7 +319,7 @@ For information about how to run the updates, execute `nix-shell maintainers/scr
 
 ### Recursive attributes in `mkDerivation`
 
-If you pass a function to `mkDerivation`, it will receive as its argument the final output of the same `mkDerivation` call. For example:
+If you pass a function to `mkDerivation`, it will receive as its argument the final arguments, considering use of `overrideAttrs`. For example:
 
 ```nix
 mkDerivation (self: {
@@ -331,9 +331,14 @@ mkDerivation (self: {
 ```
 
 Note that this does not use the `rec` keyword to reuse `withFeature` in `configureFlags`.
+The `rec` keyword works at the syntax level and is unaware of overriding.
+
 Instead, the definition references `self`, allowing users to change `withFeature`
 consistently with `overrideAttrs`.
 
+`self` also contains the attribute `public`, which represents the final package,
+including the output paths, etc.
+
 Let's look at a more elaborate example to understand the differences between
 various bindings:
 
@@ -347,11 +352,11 @@ let pkg =
     packages = [];
 
     # `passthru.tests` is a commonly defined attribute.
-    passthru.tests.simple = f self;
+    passthru.tests.simple = f self.public;
 
     # An example of an attribute containing a function
     passthru.appendPackages = packages':
-      self.overrideAttrs (newSelf: super: {
+      self.public.overrideAttrs (newSelf: super: {
         packages = super.packages ++ packages';
       });
 
@@ -363,9 +368,7 @@ let pkg =
 in pkg
 ```
 
-Unlike the `pkg` binding in the above example, the `self` parameter always references the final package. For instance `(pkg.overrideAttrs(x)).self` is identical to `pkg.overrideAttrs(x)`, whereas `(pkg.overrideAttrs(x)).original` is the same as `pkg`.
-
-This is also different from `mkDerivation rec { ..... }`, which binds the recursive references immediately, so it allows you to reference original _inputs_ only.
+Unlike the `pkg` binding in the above example, the `self` parameter always references the final attributes. For instance `(pkg.overrideAttrs(x)).self.public` is identical to `pkg.overrideAttrs(x)`, whereas `(pkg.overrideAttrs(x)).original` is the same as `pkg`.
 
 See also the section about [`passthru.tests`](#var-meta-tests).