198 lines
3.5 KiB
Markdown
198 lines
3.5 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 `dotfiles.lib` for library functions passed through module arguments.
|
|
Use `dotfiles.<name>` for assembly functions passed through module arguments.
|
|
|
|
Avoid:
|
|
|
|
```nix
|
|
{
|
|
lib = dotfilesFunctions;
|
|
}
|
|
```
|
|
|
|
Use:
|
|
|
|
```nix
|
|
{
|
|
lib = nixpkgs.lib;
|
|
dotfiles.lib = dotfilesFunctions;
|
|
}
|
|
```
|
|
|
|
### Name project function namespaces by role
|
|
|
|
Put pure project functions under `dotfiles.lib`.
|
|
Put functions that create modules, systems, or assembly values under `dotfiles`.
|
|
This keeps data-only functions separate from functions that carry flake context.
|
|
|
|
Avoid:
|
|
|
|
```nix
|
|
dotfiles.lib.mkHost { hostName = "neogaia"; }
|
|
```
|
|
|
|
Use:
|
|
|
|
```nix
|
|
dotfiles.mkHost { hostName = "neogaia"; }
|
|
```
|
|
|
|
## 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/`.
|
|
Do not add library files until this repository has a library directory.
|
|
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.
|
|
|
|
## 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
|
|
```
|
|
|