Pure Nix flake utility functions
Go to file
zimbatm 575419ad23
split out allSystems.nix
Make it easier to maintain
2023-04-09 12:45:31 +02:00
.github Bump cachix/install-nix-action from 19 to 20 (#89) 2023-04-06 12:21:09 +02:00
examples Update each-system template to use new flake output system (#76) 2022-08-07 15:12:55 +02:00
.gitignore better docs 2020-04-22 17:33:24 +02:00
allSystems.nix split out allSystems.nix 2023-04-09 12:45:31 +02:00
check-utils.nix check-utils: use the same success derivation (#75) 2022-07-04 12:00:14 +02:00
default.nix introduce externally extensible systems (#93) 2023-04-09 12:34:52 +02:00
filterPackages.nix filterPackages: Fix a typo in the comment 2022-06-24 00:32:04 +03:00
flake.lock introduce externally extensible systems (#93) 2023-04-09 12:34:52 +02:00
flake.nix introduce externally extensible systems (#93) 2023-04-09 12:34:52 +02:00
flattenTree.nix flattenTree: use / as the key separator 2020-07-22 11:35:16 +02:00
lib.nix split out allSystems.nix 2023-04-09 12:45:31 +02:00
LICENSE Initial commit 2020-04-11 13:21:35 +00:00
README.md fixup! introduce externally extensible systems (#93) 2023-04-09 12:39:36 +02:00
simpleFlake.nix use defaultSystems in simpleFlake.nix 2022-05-12 18:28:16 +02:00

flake-utils

STATUS: stable

Pure Nix flake utility functions.

The goal of this project is to build a collection of pure Nix functions that don't depend on nixpkgs, and that are useful in the context of writing other Nix flakes.

Usage

system :: { system = system, ... }

A map from system to system built from allSystems:

system = {
  x86_64-linux = "x86_64-linux";
  x86_64-darwin = "x86_64-darwin";
  ...
}

It's mainly useful to detect typos and auto-complete if you use rnix-lsp.

Eg: instead of typing "x86_64-linux", use system.x86_64-linux.

allSystems :: [<system>]

A list of all systems defined in nixpkgs. For a smaller list see defaultSystems.

defaultSystems :: [<system>] (deprecated)

The list of systems passed to the flake-utils systems input.

Use this pattern to pass different systems to your flake: https://github.com/nix-systems/nix-systems.

eachSystem :: [<system>] -> (<system> -> attrs)

A common case is to build the same structure for each system. Instead of building the hierarchy manually or per prefix, iterate over each systems and then re-build the hierarchy.

Eg:

eachSystem [ system.x86_64-linux ] (system: { hello = 42; })
# => { hello = { x86_64-linux = 42; }; }
eachSystem allSystems (system: { hello = 42; })
# => {
   hello.aarch64-darwin = 42,
   hello.aarch64-genode = 42,
   hello.aarch64-linux = 42,
   ...
   hello.x86_64-redox = 42,
   hello.x86_64-solaris = 42,
   hello.x86_64-windows = 42
}

eachDefaultSystem :: (<system> -> attrs)

eachSystem pre-populated with defaultSystems.

Example

$ examples/each-system/flake.nix as nix

{
  description = "Flake utils demo";

  inputs.flake-utils.url = "github:numtide/flake-utils";

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let pkgs = nixpkgs.legacyPackages.${system}; in
      {
        packages = rec {
          hello = pkgs.hello;
          default = hello;
        };
        apps = rec {
          hello = flake-utils.lib.mkApp { drv = self.packages.${system}.hello; };
          default = hello;
        };
      }
    );
}

mkApp { drv, name ? drv.pname or drv.name, exePath ? drv.passthru.exePath or "/bin/${name}"

A small utility that builds the structure expected by the special apps and defaultApp prefixes.

flattenTree :: attrs -> attrs

Nix flakes insists on having a flat attribute set of derivations in various places like the packages and checks attributes.

This function traverses a tree of attributes (by respecting recurseIntoAttrs) and only returns their derivations, with a flattened key-space.

Eg:

flattenTree { hello = pkgs.hello; gitAndTools = pkgs.gitAndTools }

Returns:

{
  hello = «derivation»;
  "gitAndTools/git" = «derivation»;
  "gitAndTools/hub" = «derivation»;
  # ...
}

simpleFlake :: attrs -> attrs

This function should be useful for most common use-cases where you have a simple flake that builds a package. It takes nixpkgs and a bunch of other parameters and outputs a value that is compatible as a flake output.

Input:

{
  # pass an instance of self
  self
, # pass an instance of the nixpkgs flake
  nixpkgs
, # we assume that the name maps to the project name, and also that the
  # overlay has an attribute with the `name` prefix that contains all of the
  # project's packages.
  name
, # nixpkgs config
  config ? { }
, # pass either a function or a file
  overlay ? null
, # use this to load other flakes overlays to supplement nixpkgs
  preOverlays ? [ ]
, # maps to the devShell output. Pass in a shell.nix file or function.
  shell ? null
, # pass the list of supported systems
  systems ? [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ]
}: null

Example

Here is how it looks like in practice:

$ examples/simple-flake/flake.nix as nix

{
  description = "Flake utils demo";

  inputs.flake-utils.url = "github:numtide/flake-utils";

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.simpleFlake {
      inherit self nixpkgs;
      name = "simple-flake";
      overlay = ./overlay.nix;
      shell = ./shell.nix;
    };
}

Known issues

$ nix flake check
warning: unknown flake output 'lib'

nixpkgs is currently having the same issue so I assume that it will be eventually standardized.