The DOs and DON'Ts of nixpkgs overlays
One presentation at NixCon 2017 that especially drew my attention was Nicolas Pierron’s talk about Nixpkgs overlays (video, slides). I’d like to give a quick summary here for future reference. All the credits go to Nicolas, of course.
What are overlays?
Overlays are the new standard mechanism to customize nixpkgs. They replace
constructs like packageOverride
and overridePackages
.
How do I use overlays?
Put your overlays into ~/.config/nixpkgs/overlays/. All overlays share a basic structure:
Arguments:
- self is the result of the fix point calculation. Use it to access packages which could be modified somewhere else in the overlay stack.
- super one overlay down in the stack (and base nixpkgs for the first overlay). Use it to access the package recipes you want to customize, and for library functions.
Good examples
Add default proxy to Google Chrome
From Alexandre Peyroux.
Fudge Nix store location
From Yann Hodique.
Add custom package
From Mozilla.
Bad examples
Recursive attrset
Two issues:
- Use
super
to access library functions. - Overlays should not be recursive. Use
self
.
Surplus arguments
The issue:
- Overlays should depend just on
self
andsuper
in order to be composable.
Awkward nixpkgs import
Two issues:
- Unnecessary double-import of nixpkgs. This might break cross-system builds.
- requirements.nix should use
self
notpkgs
.
Improved version
shell.nix:
default.nix:
Incorrectly referenced dependencies
The issue:
- Other packages should be taken from
self
notsuper
. This way they can be overridden by other overlays.
Overridden attrset
The issue:
- Other attributes present in
lib
andlatest
from down the overlay stack are erased.
Improved version
Always extend attrsets in overlays:
Summary
I hope this condensed guide helps you to write better overlays. For in-depth discussion, please go watch Nicolas’ talk and read the Nixpkgs manual. Many thanks to Nicolas for putting this together!