How to determine intended use of nix flakes outputs

I’m getting started with flakes and have some confusion about the intended use of each output. This page helpfully lists the outputs, but does not describe all of them. Is there documentation somewhere that does? For instance, I imagine overlays is a list of overlays. But, what then is overlay? Is this meant to extend a package set whereas overlays is meant to modify existing packages?

Thanks!

1 Like

The overlay(s) are mostly a convention right now that are supposed to contain either a single or a list of overlays. They are useful when a flake wants to extend nixpkgs with their own overrides.

Then on the consumer side you would do something like this:

{
  description = "Flake utils demo";

  inputs.flake-utils.url = "github:numtide/flake-utils";
  # assuming that this flake exports an overlay attribute
  inputs.someflake.url = "foo.com/bar";

  outputs = { self, nixpkgs, flake-utils, someflake }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs {
          overlays = [ someflake.overlay ];
        };
      in
      # and here is the core of the consumer flake
      {
        defaultPackage = pkgs.hello;
      }
    );
}

Thanks for such a prompt reply! It sounds like the use of overlay vs overlays is fairly open-ended. For instance, I could define all my flake overlays separately and then reference them as a list or individually in the consumer flake. Or, I could put a number of modifications in a single final: prev and then the consumer flake would be required to use none or all of them. I guess there are use case specific tradeoffs here (e.g. codependent overlays) that maybe describe why both of these are available. But please correct me if that’s wrong.

Is this “convention” described anywhere? For instance, maybe in code comments in a nix branch? Or, its really just in people’s heads at the moment?

Indeed, there are many ways to compose flakes, and we are just figuring these out at the moment. That “convention” is my own interpretation based on what I know of Eelco and having used flakes for a bit longer.

All of this is still fairly unstable and might still change completely in a few months.

1 Like