docs(nix): apply writing conventions
This commit is contained in:
24
docs/nix.md
24
docs/nix.md
@@ -1,7 +1,7 @@
|
||||
# Nix Conventions
|
||||
|
||||
This document records local Nix style and design conventions.
|
||||
Prefer these conventions when changing this flake.
|
||||
Use these conventions when changing this flake.
|
||||
|
||||
## Names
|
||||
|
||||
@@ -33,10 +33,10 @@ Use:
|
||||
|
||||
### Use closed interfaces for helper imports
|
||||
|
||||
Use exact function argument patterns when an imported helper file has a closed interface.
|
||||
A helper file has a closed interface when the importer owns the argument set.
|
||||
The imported file must name each accepted attribute.
|
||||
This rejects stale or accidental extra attributes.
|
||||
Use exact function argument patterns for helper imports with closed interfaces.
|
||||
A helper import has a closed interface when the caller owns the argument set.
|
||||
The imported file names each accepted attribute.
|
||||
It rejects stale or accidental extra attributes.
|
||||
|
||||
Avoid:
|
||||
|
||||
@@ -82,7 +82,7 @@ import ./flake {
|
||||
|
||||
### Keep NixOS module interfaces open
|
||||
|
||||
NixOS modules must accept extra arguments because the module system owns their argument shape.
|
||||
NixOS modules accept extra arguments because the module system owns their argument shape.
|
||||
Name the arguments the module uses.
|
||||
Keep `...` so the module accepts standard module arguments and special arguments.
|
||||
|
||||
@@ -111,7 +111,7 @@ Use:
|
||||
|
||||
### Use `@` for forwarding wrappers
|
||||
|
||||
Use `@` when a wrapper must pass the complete argument set to another module function.
|
||||
Use `@` when a wrapper passes the complete argument set to another module function.
|
||||
Name the arguments the wrapper uses before `...`.
|
||||
Forward the bound argument set unchanged.
|
||||
|
||||
@@ -134,7 +134,7 @@ dotfiles.guest { name = "sample"; } args
|
||||
### Use `let` for important intermediate values
|
||||
|
||||
Use a `let` binding when it names an important intermediate value.
|
||||
Use a `let` binding when it avoids repeating a complex expression.
|
||||
Use a `let` binding when it avoids repeated complex expressions.
|
||||
Do not use a `let` binding only to shorten a standard library call.
|
||||
|
||||
Avoid:
|
||||
@@ -156,7 +156,7 @@ lib.mapAttrs f attrs
|
||||
|
||||
### Qualify standard library calls in flake assembly
|
||||
|
||||
Prefer qualified standard library calls inside flake assembly code.
|
||||
Use qualified standard library calls inside flake assembly code.
|
||||
Use `lib.mapAttrs` instead of inheriting `mapAttrs` from `lib`.
|
||||
This keeps the source of helper functions visible.
|
||||
|
||||
@@ -181,9 +181,9 @@ lib.mapAttrs f attrs
|
||||
|
||||
Keep flake assembly code under `flake/`.
|
||||
Keep `flake.nix` focused on inputs and public outputs.
|
||||
A public output is any attribute returned by the flake `outputs` function.
|
||||
Another flake can reference a public output through `inputs.<name>.<output>`.
|
||||
Tools such as `nix flake show` also display public outputs.
|
||||
The `outputs` function returns each public output as an attribute.
|
||||
An external flake reads public outputs through `inputs.<name>.<output>`.
|
||||
`nix flake show` also displays public outputs.
|
||||
|
||||
Avoid:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user