numtide/flake-utilsPublic

NotificationsYou must be signed in to change notification settings
Fork84
Star1.5k

Pure Nix flake utility functions [maintainer=@zimbatm]

License

MIT license

1.5k stars 84 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 102 Commits
.github		.github
examples		examples
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
allSystems.nix		allSystems.nix
check-utils.nix		check-utils.nix
default.nix		default.nix
filterPackages.nix		filterPackages.nix
flake-utils.svg		flake-utils.svg
flake.lock		flake.lock
flake.nix		flake.nix
flattenTree.nix		flattenTree.nix
lib.nix		lib.nix
simpleFlake.nix		simpleFlake.nix

Repository files navigation

flake-utils

Pure Nix flake utility functions.

Anumtide project.

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

Usage

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

A map from system to system built fromallSystems:

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

It's mainly useful todetect typos and auto-complete if you usernix-lsp.

Eg: instead of typing"x86_64-linux", usesystem.x86_64-linux.

`allSystems :: [<system>]`

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

`defaultSystems :: [<system>]`

The list of systems to use ineachDefaultSystem andsimpleFlake.

The default values are["x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin"].

It's possible to override and control that list by changing thesystems input of this flake.

Eg (in yourflake.nix):

{# 1. Defined a "systems" inputs that maps to only ["x86_64-linux"]inputs.systems.url="github:nix-systems/x86_64-linux";inputs.flake-utils.url="github:numtide/flake-utils";# 2. Override the flake-utils default to your versioninputs.flake-utils.inputs.systems.follows="systems";outputs={self,flake-utils, ...}:# Now eachDefaultSystem is only using ["x86_64-linux"], but this list can also# further be changed by users of your flake.flake-utils.lib.eachDefaultSystem(system:{# ...});}

For more details in this pattern, see:https://github.com/nix-systems/nix-systems.

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

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

Eg:

eachSystem[system.x86_64-linux](system:{hello=42;})# => { hello = { x86_64-linux = 42; }; }eachSystemallSystems(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}

`eachSystemPassThrough :: [<system>] -> (<system> -> attrs)`

UnlikeeachSystem, this function does not inject the${system} key by merelyproviding the system argument to the function.

`eachDefaultSystem :: (<system> -> attrs)`

eachSystem pre-populated withdefaultSystems.

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:letpkgs=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;};});}

`eachDefaultSystemPassThrough :: (<system> -> attrs)`

eachSystemPassThrough pre-populated withdefaultSystems.

Example

inputs.flake-utils.lib.eachDefaultSystem(system:{checks./*<SYSTEM>.*/"<CHECK>"=/* ... */;devShells./*<SYSTEM>.*/"<DEV_SHELL>"=/* ... */;packages./*<SYSTEM>.*/"<PACKAGE>"=/* ... */;})//inputs.flake-utils.lib.eachDefaultSystemPassThrough(system:{homeConfigurations."<HOME_CONFIGURATION>"=/* ... */;nixosConfigurations."<NIXOS_CONFIGURATION>"=/* ... */;})

`meld :: attrs -> [ path ] -> attrs`

Meld merges subflakes using common inputs. Useful when you want tosplit up a large flake with many different components into moremanageable parts.

`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 specialapps anddefaultApp prefixes.

`flattenTree :: attrs -> attrs`

Nix flakes insists on having a flat attribute set of derivations invarious places like thepackages andchecks attributes.

This function traverses a tree of attributes (by respectingrecurseIntoAttrs) and only returns their derivations, with a flattenedkey-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 asimple flake that builds a package. It takes nixpkgs and a bunch of otherparameters and outputs a value that is compatible as a flake output.

Input:

{# pass an instance of selfself,# pass an instance of the nixpkgs flakenixpkgs,# 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 configconfig ?{},# pass either a function or a fileoverlay ?null,# use this to load other flakes overlays to supplement nixpkgspreOverlays ?[],# maps to the devShell output. Pass in a shell.nix file or function.shell ?null,# pass the list of supported systemssystems ?["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{inheritselfnixpkgs;name="simple-flake";overlay=./overlay.nix;shell=./shell.nix;};}