nix-playgraound/notes/016-overlays.md

Overlays

This note covers 13-overlay/, which defines overlays.default and then imports nixpkgs with that overlay to expose the overlaid package as a normal flake output.

---

1. What an Overlay Is

An overlay is a function:

final: prev: {
  ...
}

It receives:

• prev: the package set before your changes, and
• final: the package set after all overlays are applied.

The result is an attrset of additions or overrides.

This example writes the first argument as _ because it only needs prev:

overlay = _: prev: {
  ...
};

---

2. The Smallest Useful Pattern

This example adds one package:

overlay = _: prev: {
  hello-overlay = prev.writeShellScriptBin "hello-overlay" ''
    echo "hello from an overlay"
  '';
};

Then it imports nixpkgs with that overlay:

pkgs = import nixpkgs {
  inherit system;
  overlays = [ overlay ];
};

That is the key mechanic. The overlay itself is just a function. It does nothing until you import a package set with it.

---

3. Why the Flake Exposes Both

The example exposes:

• overlays.default, so other flakes can reuse the overlay, and
• packages.<system>.default, so the same flake is easy to build and run locally.

That makes the example useful both as a teaching flake and as a reusable overlay source.

---

4. Commands to Try

cd 13-overlay

nix build
./result/bin/hello-overlay

nix run
nix flake show
nix flake check