reply to https://www.reddit.com/r/NixOS/comments/1hcotxi/a_little_help_with_flake_structure_for_global/

I recommend using nix-starter-configs as a starting point. I use the "standard" template. It helps you set up some of these details, like overlays.

For structure I have a separate module for each nixos configuration, and each home manager configuration. Those don't contain a whole lot by themselves. Then I have a "common" module for nixos and for home manager for global configuration - I import that in each of the configuration-specific modules. Then I have lots of stuff split into small "feature" modules. Those I import either in the "common" modules, or on the configuration-specific modules.

External dependencies and overlays

Since you asked about setting up an external flake dependency I'll give an example I use. I use a window manager, niri, that I get from an external flake. I include the flake reference in inputs in flake.nix (source):

niri = {
  url = "github:sodiboo/niri-flake";
  inputs.nixpkgs.follows = "nixpkgs"; # this is optional
};

Nix-starter-configs is preconfigured to load overlays from a file, overlays/default.nix. There are a couple of pieces to make that work. overlays/default.nix exports a function that accepts the entire flake inputs attribute set as an argument. The function returns an attribute set (a dictionary) with overlays as values. Here's mine, simplified a bit (source):

{ inputs, ... }:
let
  patch = pkg: patches: pkg.overrideAttrs (oldAttrs: {
    patches = (oldAttrs.patches or [ ]) ++ patches;
  });
in
rec {
  # This one brings our custom packages from the 'pkgs' directory
  additions = final: _prev: import ../pkgs { inherit inputs; pkgs = final; };

  modifications = final: prev: {
    neovide = patch prev.neovide [ ./neovide-font-customization.patch ];
  };

  # When applied, the unstable nixpkgs set (declared in the flake inputs) will
  # be accessible through 'pkgs.unstable'
  unstable-packages = final: _prev: {
    unstable = import inputs.nixpkgs-unstable {
      # Apply the same system, config, and overlays to 'pkgs.unstable' that are
      # applied to 'pkgs'
      localSystem = final.buildPlatform.system;
      crossSystem = final.hostPlatform.system;
      config = final.config;
      overlays = [ additions modifications ];
    };
  };

  niri = inputs.niri.overlays.niri;
}

You can see that an overlay is a function that takes two arguments, final and prev, and returns an attribute set that gets merged with the overlayed package set. prev is an alias for pkgs before the overlay applies so for example here I modify an existing neovide package which I reference as prev.neovide. final also references the package set, but it references packages after all overlays are applied (which works thanks to lazy evaluation). Use final to reference packages you aren't modifying to avoid order dependencies between overlays.

Anyway, back to niri. The niri flake exports its own overlay that adds a package called niri to a package set. So I add it to my own set of overlays by including it in the output attribute set in overlays/default.nix. If I were starting fresh nix-starter-configs the only change I would need to make to that file would be to add that niri line at the end.

Those overlays are brought into my flake.nix by a line that adds overlays to my outputs (source):

outputs = { self, nixpkgs, home-manager, systems, ... }@inputs:
  let
    # ...
  in
  {
    # ...
    overlays = import ./overlays { inherit inputs; };
  }

import ./overlays { inherit inputs; }; is something you see a lot that takes some learning to understand. I can put parenthesis in to show more clearly how this is evaluated:

  (import ./overlays) { inherit inputs; };
# ------------------- -------------------
#     ^                        ^
# import a function     call the imported function
# from  another file    with this argument

When you import a directory you implicitly import a file named default.nix in that directory. So import ./overlays is equivalent to import ./overlays/default.nix.

{ inherit inputs; } is roughly equivalent to { inputs = inputs; }. See how all of the flake inputs are assigned to a variable called inputs because of the @inputs part of the argument-destructuring pattern in the outputs function? Because I have the niri flake in my flake inputs that makes an attribute, inputs.niri. Passing inputs to the function in overlay/default.nix lets me reference the flake input there.

Putting overlays in my flake outputs lets me reference them elsewhere in the flake as self.overlays because self is a self-reference to your own flake's outputs.

Overlays need to be applied to your package set. You can do that using either import nixpkgs or nixpkgs.legacyPackages; I find import nixpkgs easier to use when you're doing something non-trivial. So I have a function that defines a package set for a given system ((source)[https://github.com/hallettj/home.nix/blob/231e3e30ace28422282061489a59a0f6f97710e5/flake.nix#L51]):

  pkgs = system: import nixpkgs {
    inherit system;
    overlays = builtins.attrValues self.overlays;
  };

Like before this syntax imports a function from nixpkgs, and calls it with an argument, an attribute set with attributes named system and overlays.

But wait, nixpkgs is a flake input! What does it mean to import a flake input? When you use an external flake as an input you get two things merged into one value:

an attribute set that is returned from the external flake's output function
a derivation for the external flake's source tree

A derivation is a nix value with self-contained instructions for building a store path - a file or directory in /nix/store/. Most of the attributes in pkgs are derivations. Importing a derivation is a lot like importing a directory: nix looks in the derivation's store path (building it first if necessary) for a file called default.nix, and imports that. Nixpkgs has a file called default.nix that exports a function that initializes a package set.

Remember that my overlays output is an attribute set of named overlays. builtins.attrValues turns an attribute set into a list of values, ignoring the attribute names (the keys). This is the part that connects my overlays to the package set that I give to my nixos and home manager configurations.

So if I had skipped all of that silly indirection with overlays/default.nix and an overlays flake output I could have skipped straight to a much simpler way of doing this which would be,

  pkgs = system: import nixpkgs {
    inherit system;
    overlays = [niri.overlays.niri];
  };

Or I could have done something like,

  pkgs = system: import nixpkgs {
    inherit system;
    overlays = [
      (final: prev: {
        niri = inputs.niri.packages.${system}.niri;
      })
    ];
  };

hallettj/comment.md

External dependencies and overlays