How to apply overlays

Nix overlays are a method of overriding or extending the Nixpkgs package set by passing it thru layers of functions. See the overlays chapter of the Nixpkgs manual for more information.

Overlaying within a Nix shell

In the case of creating a Nix shell environment with the Sycl Tcl library present it is necessary to apply the sampkgs overlay to make the Sycl package available.


# shell.nix
let
  sampkgsRepo = builtins.fetchGit { url = "https://git.syndicate-lang.org/ehmry/sampkgs"; };
  sampkgsOverlayFunc = import "${sampkgsRepo}/overlay.nix";

  nixpkgsFunc = import <nixpkgs>;

  pkgs = nixpkgsFunc {
    overlays = [ sampkgsOverlayFunc ];
  };
  # pkgs contains alt.sam after overlaying.
in
pkgs.mkShell {
  packages = [
    pkgs.pkg-config
    pkgs.alt.sam.tcl9Packages.tcl
    pkgs.alt.sam.tcl9Packages.tcllib
    pkgs.alt.sam.tcl9Packages.tk
    pkgs.alt.sam.tcl9Packages.sycl
  ];
}

Why overlays

Resolving a Nix package can be thought of as happening by two different methods:

  • Importing a self-contained package expression that includes a pinned version of the Nixpkgs repository.
  • Importing a locally relevant checkout of the Nixpkgs repository and applying a package function.

The former is the flake way of doing things. It is more deterministic (all other things being equal) but also less efficient and breakage with the present world of assumptions takes longer to manifest.

The latter method promotes packages that continue to build after dependency and toolchain updates. It also eliminates the introduction of multiple build of the same version of a dependency due to superficial differences in build environments.

Having choosen the later, more distinctions can be made:

  • Realising a package by modifications within Nixpkgs.
  • Realising a package by addition within Nixpkgs.
  • Realising a package independently as a function taking Nixpkgs as input.

The first and second can be achieved using overlays, and the third can always be achieved by the second, so for the sake of consistency, please use overlays.

Between the first and second distinctions, the second is preferable but the first is sometimes necessary. Prefer addition to modification because the order in which modifications are applied is significant whereas additions to a package scope are eventually consistent.

Further reading