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:

```nix
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`:

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

---

## 2. The Smallest Useful Pattern

This example adds one package:

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

Then it imports `nixpkgs` with that overlay:

```nix
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

```bash
cd 13-overlay

nix build
./result/bin/hello-overlay

nix run
nix flake show
nix flake check
```