nix-overlays.md

Overlays are a feature of Nixpkgs that allow you to:

• Add new packages with new names to the namespace without modifying upstream
  • For example, if there is a package foobar, you might add foobar-1_2_3 to add a specific version for backwards compatibility
• Globally override existing package names, in terms of other packages.
  • For example, if you want to globally override a package to enable a disabled-by-default feature.

First, you need to define a file for the overlay under overlays/, and then import it in flake.nix. There is an example pull request in #14 for this; an overlay typically looks like this:

final: prev: {
    gdal = prev.gdalMinimal;
}

This says "globally override gdal with a different version, named gdalMinimal". In this case gdalMinimal is a build with less features enabled.

The most important part is that there is an equation of the form lhs = rhs; — if the lhs refers to an existing name, it's overwritten. If it refers to a new name, it's introduced. Overwriting an existing name acts as if you changed the files upstream: so the above example globally overrides GDAL for anything that depends on it.

The names final and prev are used to refer to packages in terms of other overlays. For more information about this, see the NixOS Wiki Page for Overlays.