Digga — slangy German for "good friend" — is a flake utility library that helps you declaratively craft and manage all three layers of your system environment within a single nix flakes repository:

development shells (via numtide/devshell),
home environments (via nix-community/home-manager), and
host configurations (via NixOS/nixpkgs/nixos).

This library is based on flake-utils-plus.

Usage

The best way to make use of library is with the Official template.

You can also have a look at the different examples.

Philosophy

In it's lib.mkFlake function, Digga implements a well-specified API interface comprising four API containers that allow you to:

configure nixpkgs channels including internal and external overlays,
define NixOS hosts including internal and external NixOS modules as well as host defaults that apply to all hosts in the environment,
specify user home environments including internal and external home-manager modules, and
setup & combine a series of devshells that you like to have available in your projects.

Modules, Profiles & Suites

For NixOS- & home-manager-modules, Digga allows you to distinguish between modules, profiles and suites.

Modules are abstract configurations that, while holding the implementation, do not set any system state.
Profiles are concrete configurations that set system state within the profile domain.
Suites are a composable, clean and discoverable mechanism for profile aggregation.

Overlays and modules can be defined internally coming from your repo or externally coming from an upstream flake. This distinction serves the library to only export your own work as the public flake output.

Downstream consumers of your flake can now more easily tell your art apart from other upstream art.

Contributing

We encourage contributions of any kind. The simplest way to get involved is to join the chat or report problems and ideas on the issue thread.

To craft well thought out APIs we need all the thoughts regarding new ideas.

Pull Requests are just as amazing.

License

Digga is licensed under the MIT License.

Top Level API

digga's top level API. API Containers are documented in their respective sub-chapter:

channelsConfig

nixpkgs config for all channels

Type: attribute set or path convertible to it

Default

{}

inputs

The flake's inputs

Type: attribute set of nix flakes

outputsBuilder

builder for flake system-spaced outputs The builder gets passed an attrset of all channels

Type: function that evaluates to a(n) attrs or path convertible to it

Default

"channels: { }"

self

The flake to create the DevOS outputs for

Type: nix flake

supportedSystems

The systems supported by this flake

Type: list of strings

Default

["aarch64-linux","aarch64-darwin","i686-linux","x86_64-darwin","x86_64-linux"]

Channels API Container

Configure your channels that you can use throughout your configurations.

⚠ Gotcha ⚠

Devshell & (non-host-specific) Home-Manager pkgs instances are rendered off the nixos.hostDefaults.channelName (default) channel.

channels

nixpkgs channels to create

Type: attribute set of submodules or path convertible to it

Default

{}

channels.<name>.config

nixpkgs config for this channel

Type: attribute set or path convertible to it

Default

{}

channels.<name>.input

nixpkgs flake input to use for this channel

Type: nix flake

Default

"self.inputs.<name>"

channels.<name>.overlays

overlays to apply to this channel these will get exported under the 'overlays' flake output as <channel>/<name> and any overlay pulled from ${inputs} will be filtered out

Type: list of valid Nixpkgs overlay or path convertible to its or anything convertible to it or path convertible to it

Default

[]

Home-Manager API Container

Configure your home manager modules, profiles & suites.

home

hosts, modules, suites, and profiles for home-manager

Type: submodule or path convertible to it

Default

{}

home.exportedModules

modules to include in all hosts and export to homeModules output

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

home.externalModules

The externalModules option has been removed. Any modules that should be exported should be defined with the exportedModules option and all other modules should just go into the modules option.

Type: list of valid modules or anything convertible to it

Default

[]

home.importables

Packages of paths to be passed to modules as specialArgs.

Type: attribute set

Default

{}

home.importables.suites

collections of profiles

Type: null or attribute set of list of paths or anything convertible to its or path convertible to it

Default

null

home.modules

modules to include that won't be exported meant importing modules from external flakes

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

home.profiles

WARNING: The 'suites' and profiles options have been deprecated, you can now create both with the importables option. rakeLeaves can be used to create profiles and by passing a module or rec set to importables, suites can access profiles. Example:

importables = rec {
  profiles = digga.lib.rakeLeaves ./profiles;
  suites = with profiles; { };
}

See https://github.com/divnix/digga/pull/30 for more details

Type: list of paths or path convertible to it

Default

[]

home.suites

importables = rec {
  profiles = digga.lib.rakeLeaves ./profiles;
  suites = with profiles; { };
}

See https://github.com/divnix/digga/pull/30 for more details

Type: function that evaluates to a(n) attrs or path convertible to it

home.users

HM users that can be deployed portably without a host.

Type: attribute set of HM user configs

Default

{}

Devshell API Container

Configure your devshell module collections of your environment.

devshell

Modules to include in your DevOS shell. the modules argument will be exported under the devshellModules output

Type: submodule or path convertible to it

Default

{}

devshell.exportedModules

modules to include in all hosts and export to devshellModules output

Type: list of valid module or path convertible to its or anything convertible to it

Default

[]

devshell.externalModules

The externalModules option has been removed. Any modules that should be exported should be defined with the exportedModules option and all other modules should just go into the modules option.

Type: list of valid modules or anything convertible to it

Default

[]

devshell.modules

modules to include that won't be exported meant importing modules from external flakes

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

NixOS API Container

Configure your nixos modules, profiles & suites.

nixos

hosts, modules, suites, and profiles for NixOS

Type: submodule or path convertible to it

Default

{}

nixos.hostDefaults

Defaults for all hosts. the modules passed under hostDefaults will be exported to the 'nixosModules' flake output. They will also be added to all hosts.

Type: submodule

Default

{}

nixos.hostDefaults.channelName

Channel this host should follow

Type: channel defined in channels

nixos.hostDefaults.exportedModules

modules to include in all hosts and export to nixosModules output

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

nixos.hostDefaults.externalModules

The externalModules option has been removed. Any modules that should be exported should be defined with the exportedModules option and all other modules should just go into the modules option.

Type: list of valid modules or anything convertible to it

Default

[]

nixos.hostDefaults.modules

modules to include that won't be exported meant importing modules from external flakes

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

nixos.hostDefaults.system

system for this host

Type: null or system defined in supportedSystems

Default

null

nixos.hosts

configurations to include in the nixosConfigurations output

Type: attribute set of submodules

Default

{}

nixos.hosts.<name>.channelName

Channel this host should follow

Type: null or channel defined in channels

Default

null

nixos.hosts.<name>.modules

modules to include

Type: list of valid modules or anything convertible to it or path convertible to it

Default

[]

nixos.hosts.<name>.system

system for this host

Type: null or system defined in supportedSystems

Default

null

nixos.hosts.<name>.tests

tests to run

Type: list of valid NixOS test or path convertible to its or anything convertible to it

Default

[]

Example

{"_type":"literalExpression","text":"[\n  {\n    name = \"testname1\";\n    machine = { ... };\n    testScript = ''\n      # ...\n    '';\n  }\n  ({ corutils, writers, ... }: {\n    name = \"testname2\";\n    machine = { ... };\n    testScript = ''\n      # ...\n    '';\n  })\n  ./path/to/test.nix\n];\n"}

nixos.importables

Packages of paths to be passed to modules as specialArgs.

Type: attribute set

Default

{}

nixos.importables.suites

collections of profiles

Type: null or attribute set of list of paths or anything convertible to its or path convertible to it

Default

null

nixos.profiles

importables = rec {
  profiles = digga.lib.rakeLeaves ./profiles;
  suites = with profiles; { };
}

See https://github.com/divnix/digga/pull/30 for more details

Type: list of paths or path convertible to it

Default

[]

nixos.suites

importables = rec {
  profiles = digga.lib.rakeLeaves ./profiles;
  suites = with profiles; { };
}

See https://github.com/divnix/digga/pull/30 for more details

Type: function that evaluates to a(n) attrs or path convertible to it

TL;DR;

Target Branch: main
Merge Policy: bors is always right (→ bors try)
Docs: every change set is expected to contain doc updates
Commit Msg: be a poet! Comprehensive and explanatory commit messages should cover the motivation and use case in an easily understandable manner even when read after a few months.
Test Driven Development: please default to test driven development you can make use of the ./examples & ./e2e and wire test up in the devshell.

Within the Devshell (`nix develop`)

Hooks: please git commit within the devshell
Fail Early: please run check-all from within the devshell on your local machine

Digga Library Docs