I’ve been searching for days now on information about what overlays are, why they’re useful, and how they work, but I’m coming up largely empty.
Starting with the wiki page Overlays - NixOS Wiki
Overlays provide a method to extend and change nixpkgs. They replace constructs like
packageOverride
andoverridePackages
.
Okaay… I don’t know what those are either.
Consider a simple example of setting the default proxy in Google Chrome:
Which is doing … what, exactly? And why? And how?
The data flow around overlays, especially regarding super and self arguments can be a bit confusing if you are not familiar with how overlays work. This graph shows the data flow:
Actually, it doesn’t. I don’t know what the diagram here signifies.
Here the main package set is extended with two overlays, ext-1 and ext-2. x // y is represented by a // box with x coming in from the left and y from above.
y? x? Where are these? There’s no such symbol in the diagram. What are “x // y” and “a // box”?
As you can see, self is the same for every stage, but super comes from only the stage before. So when you define an attribute foo in the set to override it, within that overlay self.foo will be it’s version, and super.foo will be the non-overriden version. This is why you see patterns like foo = super.foo.override { … }.
Uhh…
final: prev: { f = final.firefox; }
would work, but
final: prev: { f = prev.firefox; }
would make more sense.
Why would it make more sense? What is this doing?
When writing standalone nix code, for example a
shell.nix
for a project, one usually starts by importing nixpkgs:let pkgs = import <nixpkgs> {}
. To use an overlay in this context, replace that by:
import { overlays = [ overlay1 overlay2 ]; }
OK, so there’s some “overlays” keyword I guess? Where do “overlay1” and “overlay2” come from? And what are they?
nixpkgs.overlays = [ (self: super: / overlay goes here /) ];
OK cool, but WHAT is this overlay that goes “here”, and HOW do I define one?
Examples of overlays
Ahh good, some examples!
Overriding a version …
Adding patches …
Compilation options …
Overriding a package inside a scope …
But none of these have overlays in them! Or maybe they do and they just don’t need the overlay keyword? What are overlays again?
Here is an example of Python packages overlay. The trick is to also override python itself with
packageOverrides
.
I see… Actually, no I don’t. At all.
So what exactly are overlays? What are they used for? How do I make them? How do I use them? What would be some simple examples?