docs(nix): define assembly file ownership

This commit is contained in:
2026-08-28 11:01:39 -04:00
parent d0b00ada96
commit 3f24669f78

View File

@@ -11,7 +11,7 @@ Read this document with `docs/dictionary.md`.
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.
Use `dotfiles.mk<Name>` for assembly functions passed through module arguments.
Avoid:
@@ -39,13 +39,13 @@ This keeps data-only functions separate from functions that carry flake context.
Avoid:
```nix
dotfiles.lib.mkHost { hostName = "neogaia"; }
dotfiles.lib.mkGuest { name = "sample"; }
```
Use:
```nix
dotfiles.mkHost { hostName = "neogaia"; }
dotfiles.mkGuest { name = "sample"; }
```
## File Placement
@@ -54,7 +54,7 @@ dotfiles.mkHost { hostName = "neogaia"; }
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 library files under `lib/`.
Put modules under `modules/`.
Put host configurations under `hosts/<name>/`.
Put host-side guest wiring under `guests/`.
@@ -101,7 +101,30 @@ Use:
```text
flake/default.nix # imports ./hosts.nix
flake/hosts.nix # defines mkHost
flake/hosts.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 the concept has one.
Name that constructor `mk<Concept>`.
Avoid:
```nix
{
inherit collectNixFiles mkHost mkHosts;
}
```
Use:
```nix
{
inherit mkHosts;
}
```
## Function Arguments