• Stars
    star
    1,043
  • Rank 43,008 (Top 0.9 %)
  • Language
    Nix
  • License
    MIT License
  • Created about 4 years ago
  • Updated 27 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Pure Nix flake utility functions [maintainer=@zimbatm]

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>]

The list of systems to use in eachDefaultSystem and simpleFlake.

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 the systems input of this flake.

Eg (in your flake.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 version
  inputs.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 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;
        };
      }
    );
}

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

Meld merges subflakes using common inputs. Useful when you want to split up a large flake with many different components into more manageable 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 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;
    };
}

Commercial support

Looking for help or customization?

Get in touch with Numtide to get a quote. We make it easy for companies to work with Open Source projects: https://numtide.com/contact

More Repositories

1

devshell

Per project developer environments
Nix
1,140
star
2

system-manager

Manage system config using nix on any distro
Rust
574
star
3

treefmt

one CLI to format your repo
Go
500
star
4

treefmt-nix

treefmt nix configuration
Nix
185
star
5

nix-filter

a small self-contained source filtering lib
Nix
182
star
6

nixpkgs-unfree

nixpkgs with the unfree bits enabled
Nix
84
star
7

nits

Nix & NATS
Go
76
star
8

nix-gl-host

Run OpenGL/Cuda programs built with Nix, on all Linux distributions.
Python
64
star
9

systemd-vaultd

Provide access to vault secrets to systemd services
Nix
61
star
10

nar-serve

Unpack and serve NAR file content on the fly
Go
30
star
11

prj-spec

Project Base Directory Specification
Shell
28
star
12

nix-vm-test

Re-use the NixOS VM test infrastructure to test Ubuntu, Debian, and Fedora machines.
Nix
28
star
13

terraform-provider-linuxbox

Configure Linux machines with Terraform
Go
27
star
14

bld

Build nix targets based on git repository directories
Go
27
star
15

deploykit

Execute commands remote via ssh and locally in parallel with python
Python
25
star
16

nix-stdlib

experimental nix prelude
Nix
24
star
17

action-cli

GitHub Actions without JavaScript
Rust
18
star
18

nix-eval-cache

Skips build/evaluation based on modification date of nix files.
Rust
17
star
19

software-consulting-documents

Software Consulting Legal Documents
16
star
20

blueprint

Nix without the glue code
Nix
15
star
21

github-deploy

Track deployments on GitHub PRs
Go
12
star
22

clean-git-action

Leave no build artifacts behind
Shell
10
star
23

serve-go

Like vercel/serve but for production. Serve SPA apps quickly.
Go
9
star
24

build-go-cache

buildGoCache speeds up nix's buildGoModule by pre-compiling imported go modules
Nix
8
star
25

nix-gitignore

filterSource using .gitignore (experiment)
Go
7
star
26

numtide-github-runner

the best self-hosted github runners on the market
Nix
7
star
27

terraform-deploy-nixos-flakes

Shell
5
star
28

nixos-rke2

NixOS modules for RKE2
Nix
5
star
29

terraform-upload-ami

Upload and import the AMI from a VHD
HCL
5
star
30

harvest-invoice-calculator

A little tool that helps generating invoices from Harvest data
Python
4
star
31

terraform-nixos-install

HCL
3
star
32

generate-terraform-provider-shim

Handle third-party Terraform providers
Go
3
star
33

nixpkgs-terraform

terraform-related packages with Nix
Nix
3
star
34

terraform-nix-build

Build Nix with the external provider
Python
2
star
35

nix-vm-test-demo

Dump of the code used in the nix-vm-test demo
Nix
2
star
36

yarnlock2json

Convert `yarn.lock` files to JSON
JavaScript
1
star
37

kartusche

Go
1
star
38

terraform-linuxbox-traefik

HCL
1
star
39

terraform-linuxbox-monitorpack

Seed DevOps monitoring module
HCL
1
star
40

activate

A small resource converger tool
Nix
1
star
41

gh-v6.com

GitHub downloads, with IPv6
HTML
1
star
42

configure-nix-action

Configures Nix on GitHub Actions
Shell
1
star
43

mkdocs-numtide

Our own mkdocs template, based on the material design
Nix
1
star
44

docker-host-forwarder

Docker image that will forward udp/tcp to docker host
Shell
1
star
45

terraform-nixos-amis

Fork of https://github.com/tweag/terraform-nixos/tree/master/aws_image_nixos
HCL
1
star
46

nixionary.org

HTML
1
star