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