271 lines
4.7 KiB
Markdown
271 lines
4.7 KiB
Markdown
# Nix Conventions
|
|
|
|
This document records local Nix style and design conventions.
|
|
Use these conventions when changing this flake.
|
|
Read this document with `docs/dictionary.md`.
|
|
|
|
## Names
|
|
|
|
### Reserve `lib` for `nixpkgs.lib`
|
|
|
|
Use `lib` only for the base `nixpkgs.lib` value.
|
|
Do not use `lib` for project functions.
|
|
Use `util` for library functions passed through module arguments.
|
|
Use `flake.mk<Name>` for assembly functions used by flake outputs.
|
|
|
|
Avoid:
|
|
|
|
```nix
|
|
specialArgs = {
|
|
lib = util;
|
|
};
|
|
```
|
|
|
|
Use:
|
|
|
|
```nix
|
|
specialArgs = {
|
|
inherit util;
|
|
};
|
|
```
|
|
|
|
Then call library functions through `util` inside modules:
|
|
|
|
```nix
|
|
{
|
|
lib,
|
|
util,
|
|
...
|
|
}:
|
|
{
|
|
networking.networkmanager.unmanaged = [ "interface-name:${util.bridgeName 10}" ];
|
|
}
|
|
```
|
|
|
|
### Name project function namespaces by role
|
|
|
|
Put pure project functions under `util`.
|
|
Put functions that create systems or output values under `flake`.
|
|
This keeps data-only functions separate from functions that carry flake context.
|
|
|
|
Avoid:
|
|
|
|
```nix
|
|
util.mkHosts { root = self + "/hosts"; }
|
|
```
|
|
|
|
Use:
|
|
|
|
```nix
|
|
flake.mkHosts { root = self + "/hosts"; }
|
|
```
|
|
|
|
## File Placement
|
|
|
|
### Put files in the directory that owns their role
|
|
|
|
Choose the file location before writing a Nix file.
|
|
Put assembly files under `flake/`.
|
|
Put library files under `lib/`.
|
|
Put modules under `modules/`.
|
|
Put host configurations under `hosts/<name>/`.
|
|
Put host-side guest wiring under `guests/`.
|
|
Put registry definitions under `registry/`.
|
|
Keep `flake.nix` focused on inputs and output wiring.
|
|
Do not add root-level Nix files other than `flake.nix`.
|
|
|
|
A module is self-contained configuration under `modules/`.
|
|
A module configures one program, service, or subsystem.
|
|
Files under `hosts/`, `guests/`, and `modules/` return NixOS modules.
|
|
|
|
### Use `default.nix` for module directories with support files
|
|
|
|
Use `default.nix` as the primary module when a module directory owns support files.
|
|
Keep sibling files for data or code read by that primary module.
|
|
|
|
Avoid:
|
|
|
|
```text
|
|
modules/shell/fish/fish.nix
|
|
modules/shell/fish/config.fish
|
|
```
|
|
|
|
Use:
|
|
|
|
```text
|
|
modules/shell/fish/default.nix
|
|
modules/shell/fish/config.fish
|
|
```
|
|
|
|
### Use non-module `default.nix` files only for directory assembly
|
|
|
|
Outside `modules/`, use `default.nix` to connect files in its directory.
|
|
Do not define primary assembly functions in `default.nix`.
|
|
Put primary assembly functions in named files.
|
|
|
|
Avoid:
|
|
|
|
```text
|
|
flake/default.nix # defines mkHost
|
|
```
|
|
|
|
Use:
|
|
|
|
```text
|
|
flake/default.nix # imports ./host.nix
|
|
flake/host.nix # defines mkHosts
|
|
```
|
|
|
|
### Keep assembly files focused on one concept
|
|
|
|
Give each assembly file under `flake/` one top-level concept.
|
|
Keep helper functions private to that file when no other file needs them.
|
|
Export the constructor for the concept when another assembly file needs it.
|
|
Name that constructor `mk<Concept>`.
|
|
|
|
Avoid:
|
|
|
|
```nix
|
|
{
|
|
inherit collectNixFiles mkHost mkHosts;
|
|
}
|
|
```
|
|
|
|
Use:
|
|
|
|
```nix
|
|
{
|
|
inherit mkHosts;
|
|
}
|
|
```
|
|
|
|
## Function Arguments
|
|
|
|
### Use closed interfaces for assembly files and library files
|
|
|
|
Use exact function argument patterns for assembly files and library files.
|
|
The caller owns the argument set for these files.
|
|
The imported file names each accepted attribute.
|
|
The imported file rejects stale or accidental extra attributes.
|
|
|
|
Avoid:
|
|
|
|
```nix
|
|
{
|
|
inputs,
|
|
lib,
|
|
self,
|
|
...
|
|
}:
|
|
```
|
|
|
|
Use:
|
|
|
|
```nix
|
|
{
|
|
inputs,
|
|
lib,
|
|
self,
|
|
}:
|
|
```
|
|
|
|
### Pass function arguments explicitly
|
|
|
|
Pass only the values an assembly file or library file needs.
|
|
Bind `lib` to the base `nixpkgs.lib` value at the call site.
|
|
Use `inherit` only for values that keep the same name.
|
|
|
|
Avoid:
|
|
|
|
```nix
|
|
import ./flake inputs
|
|
```
|
|
|
|
Use:
|
|
|
|
```nix
|
|
let
|
|
inherit (nixpkgs) lib;
|
|
in
|
|
import ./flake { inherit lib inputs self; }
|
|
```
|
|
|
|
### Keep NixOS module interfaces open
|
|
|
|
Files under `hosts/`, `guests/`, and `modules/` return NixOS modules.
|
|
`nixosSystem` owns their argument shape.
|
|
Name each argument the module uses.
|
|
Keep `...` so the module accepts standard arguments and special arguments.
|
|
|
|
Avoid:
|
|
|
|
```nix
|
|
{
|
|
config,
|
|
lib,
|
|
pkgs,
|
|
registry,
|
|
}:
|
|
```
|
|
|
|
Use:
|
|
|
|
```nix
|
|
{
|
|
config,
|
|
lib,
|
|
pkgs,
|
|
registry,
|
|
...
|
|
}:
|
|
```
|
|
|
|
## `let` Bindings
|
|
|
|
### Use role-specific binding names
|
|
|
|
A `let` binding name must explain the value's role in the expression.
|
|
Avoid names that describe only the value's type.
|
|
|
|
Avoid:
|
|
|
|
```nix
|
|
let
|
|
names = lib.attrNames hosts;
|
|
in
|
|
lib.genAttrs names mkHost
|
|
```
|
|
|
|
Use:
|
|
|
|
```nix
|
|
let
|
|
hostNames = lib.attrNames hosts;
|
|
in
|
|
lib.genAttrs hostNames mkHost
|
|
```
|
|
|
|
## Standard Library Calls
|
|
|
|
### Qualify standard library calls in flake assembly
|
|
|
|
Use qualified standard library calls inside assembly files.
|
|
Use `lib.mapAttrs` instead of inheriting `mapAttrs` from `lib`.
|
|
This keeps the source of each function visible.
|
|
|
|
Avoid:
|
|
|
|
```nix
|
|
let
|
|
inherit (lib) mapAttrs;
|
|
in
|
|
mapAttrs f attrs
|
|
```
|
|
|
|
Use:
|
|
|
|
```nix
|
|
lib.mapAttrs f attrs
|
|
```
|
|
|