doc: Improve overlays section #255132
doc: Improve overlays section #255132
Conversation
ofborg
bot
added
the
2.status: merge conflict
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-09-14-documentation-team-meeting-notes-80/33033/1 |
doc/using/overlays.chapter.md
Outdated
| See the section on `NIX_PATH` in the Nix manual for more details on how to set a value for `<nixpkgs-overlays>.` | ||
| If you already have an imported Nixpkgs, you can apply further overlays on top using: | ||
| ```nix | ||
| pkgs.appendOverlays [ |
There was a problem hiding this comment.
does this need to be pkgs = pkgs.appendOverlays or does it really stand alone?
There was a problem hiding this comment.
I think that would be a bit confusing then. I just used pkgs = in the beginning to signal that it's an imported Nixpkgs.
Maybe we could do something like this to make it clearer though:
pkgsModified = pkgs.appendOverlays [ ... ]
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-09-21-documentation-team-meeting-notes-81/33490/1 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-09-28-documentation-team-meeting-notes-83/33599/1 |
infinisil
force-pushed
the
doc-overlays-rewrite
branch
from
bc8804c
to
de2b045
Compare
asymmetric
added
the
6.topic: documentation
There was a problem hiding this comment.
I'd suggest to call the arguments
final and prev (super is a new term, if you know lib.fix already)
final is also often used in fixed point functions and kind of self explaining if you are familiar with that concept alread.
prev is also kind of self explaining, since the word stems from previous.
|
|
||
| The list of overlays can be passed explicitly when importing nixpkgs, for example `import <nixpkgs> { overlays = [ overlay1 overlay2 ]; }`. | ||
| The first argument (`self`) 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 `rr` in the example above come from `self`, as well as the overridden dependencies used in the `boost` override. |
There was a problem hiding this comment.
| The first argument (`self`) 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 `rr` in the example above come from `self`, as well as the overridden dependencies used in the `boost` override. | |
| The first argument (`final`) corresponds to the final package set after all overlays have been applied. You should use this set for the dependencies of all packages specified in your overlay. For example, all the dependencies of `rr` in the example above come from `final`, as well as the overridden dependencies used in the `boost` override. |
|
|
||
| NOTE: DO NOT USE THIS in nixpkgs. Further overlays can be added by calling the `pkgs.extend` or `pkgs.appendOverlays`, although it is often preferable to avoid these functions, because they recompute the Nixpkgs fixpoint, which is somewhat expensive to do. | ||
| The second argument (`super`) 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 `boost` in the above example, comes from `super`, as well as the `callPackage` function. |
There was a problem hiding this comment.
| The second argument (`super`) 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 `boost` in the above example, comes from `super`, as well as the `callPackage` function. | |
| The second argument (`prev`) corresponds to the result of the evaluation of all previous overlays. 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, to access functions defined in Nixpkgs, or simply if the addition made needs the original unmodified value. For example, the original recipe of `boost` in the above example, comes from `prev`, as well as the `callPackage` function. |
wegank
added
the
2.status: stale
|
@infinisil also see my approach of the api documentation The implementation uses. It should be consistent, and the code was refactored long ago to be consistent in that style. |
stale
bot
removed
the
2.status: stale
|
|
||
| ## Installing overlays {#sec-overlays-install} | ||
| ## What are overlays {#sec-overlays-definition} |
There was a problem hiding this comment.
I think the important question is "what can i do with overlays". The technical correct definition is not as important in the first sentence.
| ## What are overlays {#sec-overlays-definition} | |
| ## What are overlays {#sec-overlays-definition} | |
| Overlays can be used in general to extend or change existing attribute sets. Common applications are: | |
| - Adding/extending packages to a locally imported version of nixpkgs | |
| - Overriding packages | |
| - Overriding packageSets | |
| - Extending fixedPoint packageSets such as nixpkgs. (We should maybe explain somewhere what those fixed point package sets are.) | |
Description of changes
Done in a split off from the docs team meeting, with @henrik-ch tagging along. Not done yet.
Things done
sandbox = trueset innix.conf? (See Nix manual)nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/)