+127 -346

README.md

··· 18 18 19 19 <img width="300" height="300" alt="den" src="https://github.com/user-attachments/assets/af9c9bca-ab8b-4682-8678-31a70d510bbb" /> 20 20 21 21 - - Dendritic: Same concern over different classes. 21 21 + - Dendritic: same concern, different classes and context-aware. 22 22 23 23 - - Small and [DRY](modules/aspects/provides/unfree.nix)<br> 24 24 - [`class` generic](modules/aspects/provides/primary-user.nix) Nix configurations. 23 23 + - Small, [DRY](modules/aspects/provides/unfree.nix) & [`class`-generic](modules/aspects/provides/primary-user.nix) modules. 25 24 26 26 - - Context-Aware aspects.<br>[Parametric](modules/aspects/provides/define-user.nix) over `host`/`home`/`user`. 25 25 + - [Parametric](modules/aspects/provides/define-user.nix) over `host`/`home`/`user`. 27 26 28 28 - - Stop copying and **share**(tm)<br> 29 29 - aspects across systems and Dendritic repos. 27 27 + - [Share](templates/default/modules/_profile/namespace.nix) aspects across systems & repos. 30 28 31 31 - - Bidirectional [configurations](modules/aspects/dependencies.nix).<br> 32 32 - Users can contribute to their Host configuration and the other way around. 33 33 - 34 34 - - Custom factories and output attributes.<br> 35 35 - Support any new `class` of Nix configurations. 29 29 + - Bidirectional [dependencies](modules/aspects/dependencies.nix): user/host contributions. 36 30 37 37 - - Use your `stable`/`unstable` input channels. 31 31 + - Custom factories for any Nix `class`. 38 32 39 39 - - _Freeform_ `host`/`user`/`home` [schemas](modules/_types.nix).<br> 40 40 - Avoid the need for using `specialArgs`. 33 33 + - Use `stable`/`unstable` channels per config. 41 34 42 42 - - Multi-platform, Multi-tenant hosts. 35 35 + - Freeform `host`/`user`/`home` [schemas](modules/_types.nix) (no `specialArgs`). 43 36 44 44 - - Reuse aspects across hosts, OS, homes. 37 37 + - Multi-platform, multi-tenant hosts. 45 38 46 46 - - [Batteries Included](modules/aspects/provides/)<br> 47 47 - Opt-in and replaceable. 39 39 + - [Batteries](modules/aspects/provides/): Opt-in, replaceable aspects. 48 40 49 49 - - [Well tested](templates/default/modules/_example/ci.nix)<br> 50 50 - Suite exercises all [features with examples](templates/default/modules/). 41 41 + - [Well-tested](templates/default/modules/_example/ci.nix) with an [example suite](templates/default/modules/). 51 42 52 43 Need more batteries? See [vic/denful](https://github.com/vic/denful). 53 44 54 54 - Join the community [discussion](https://github.com/vic/den/discussions). Ask questions, share how you use `den`. 45 45 + Join our [community discussion](https://github.com/vic/den/discussions). 55 46 56 47 </div> 57 48 </td> 58 49 <td> 59 50 60 60 - 🏠 Concise definitions of 61 61 - [Hosts, Users](templates/default/modules/_example/hosts.nix) and [Standalone-Homes](templates/default/modules/_example/homes.nix). 51 51 + 🏠 Define [Hosts, Users](templates/default/modules/_example/hosts.nix) & [Homes](templates/default/modules/_example/homes.nix) concisely. 62 52 63 63 - See [\_types.nix](modules/_types.nix) for complete schema. 53 53 + See schema in [`_types.nix`](modules/_types.nix). 64 54 65 55 ```nix 66 56 # modules/hosts.nix 57 57 + # OS & standalone homes share 'vic' aspect. 58 58 + # $ nixos-rebuild switch --flake .#my-laptop 59 59 + # $ home-manager switch --flake .#vic 67 60 { 68 68 - # This example defines the following aspects: 69 69 - # den.aspects.my-laptop and den.aspects.vic 70 70 - # standalone-hm and nixos-hm share vic aspect 71 71 - 72 72 - # $ nixos-rebuild switch --flake .#my-laptop 73 73 - den.hosts.x86-64-linux.my-laptop.users.vic = {}; 74 74 - # $ home-manager switch --flake .#vic 75 75 - den.homes.aarch64-darwin.vic = { }; 76 76 - 77 77 - # That's it! Now lets attach configs via aspects 61 61 + den.hosts.x86-64-linux.laptop.users.vic = {}; 62 62 + den.homes.aarch64-darwin.vic = {}; 78 63 } 79 64 ``` 80 65 81 81 - 🧩 [Aspect-oriented](https://github.com/vic/flake-aspects) configurations. ([example](templates/default/modules/_example/aspects.nix)) 66 66 + 🧩 [Aspect-oriented](https://github.com/vic/flake-aspects) incremental features. ([example](templates/default/modules/_example/aspects.nix)) 67 67 + 68 68 + Any module can contribute configurations to aspects. 82 69 83 70 ```nix 84 84 - # modules/my-laptop.nix -- Attach behaviour to host 85 85 - { den, ... }: 86 86 - { 71 71 + # modules/my-laptop.nix 72 72 + { den, ... }: { 87 73 den.aspects.my-laptop = { 88 88 - # dependency graph on other shared aspects 89 74 includes = [ 90 90 - # my parametric { host } => aspect 91 91 - den.aspects.vpn # setups firewall/daemons 92 92 - # opt-in, replaceable batteries included 93 93 - den._.home-manager 75 75 + den.aspects.vpn # { host } => config 76 76 + den._.home-manager # battery 94 77 ]; 95 95 - # provide same features at any OS/platform 96 96 - nixos = ...; # (see nixos options) 97 97 - darwin = ...; # (see nix-darwin options) 98 98 - # contrib hm-config to all my-laptop users 78 78 + nixos = { /* NixOS options */ }; 79 79 + darwin = { /* nix-darwin options */ }; 80 80 + # For all users of my-laptop 99 81 homeManager.programs.vim.enable = true; 100 82 }; 101 83 } 102 84 103 103 - # modules/vic.nix -- Reused in OS/standalone HM 104 104 - { den, ... }: 105 105 - { 85 85 + # modules/vic.nix 86 86 + { den, ... }: { 106 87 den.aspects.vic = { 107 107 - homeManager = ...; # (see home-manager options) 108 108 - # user can contrib to hosts where it lives 109 109 - nixos.users.users.vic.description = "oeiuwq"; 88 88 + homeManager = { /* ... */ }; 89 89 + # User contribs to host 90 90 + nixos.users.users = { 91 91 + vic.description = "oeiuwq"; 92 92 + } 110 93 includes = [ 111 94 den.aspects.tiling-wm 112 112 - # parametric { user, host } => aspect 113 113 - den._.primary-user # vic is admin 95 95 + den._.primary-user 114 96 ]; 115 97 }; 116 98 } 117 99 ``` 118 100 119 119 - For real-world examples, see [`vic/vix`](https://github.com/vic/vix/tree/den) 120 120 - or try this [GH search](https://github.com/search?q=vic%2Fden+language%3ANix&type=code). 101 101 + For real-world examples, see [`vic/vix`](https://github.com/vic/vix/tree/den) or this [GH search](https://github.com/search?q=vic%2Fden+language%3ANix&type=code). 121 102 122 122 - **❄️ Try it now! Launch our template VM:** 103 103 + **❄️ Try it now!** 123 104 105 105 + Launch our template VM: 124 106 ```console 125 107 nix run github:vic/den 126 108 ``` 127 109 128 128 - Or clone it and run the VM as you edit 110 110 + Or, initialize a project: 129 111 130 112 ```console 131 113 nix flake init -t github:vic/den ··· 133 115 nix run .#vm 134 116 ``` 135 117 136 136 - Our [default template](templates/default) provides a [layout](templates/default/modules/_profile/) for quickstart. 118 118 + Our [default template](templates/default) provides a [profile-based layout](templates/default/modules/_profile/) for a quick start. 137 119 138 120 </td> 139 121 </tr> 140 122 </table> 141 123 142 142 - You are done! You know everything there is to know about `den` for creating configurations with it. 124 124 + You are done! You know everything to start creating configurations with `den`. 125 125 + 126 126 + Feel free to to __explore__ the codebase, particularly our [included batteries](modules/aspects/provides) and [tests](templates/default/modules/_example). 143 127 144 144 - However, if you want to learn more about how it works, I have tried to document some other topics in collapsible sections to avoid distraction from the introduction. 128 128 + # Learn More 129 129 + 130 130 + If you want to learn how `den` works, the following sections detail its concepts and patterns. 145 131 146 132 <details> 147 133 <summary> 148 134 149 149 - # Basic Concepts and Patterns. 135 135 + ### Basic Concepts 150 136 151 151 - > Learn about aspects, static and parametric. Default aspects and dependencies. 137 137 + > Learn about static vs. parametric aspects, the default aspect, and dependencies. 152 138 153 139 </summary> 154 140 155 155 - There are two fundamental types of aspects in `den`, _static_ and _parametric_. 141 141 + `den` has two fundamental types of aspects: _static_ and _parametric_. 156 142 157 143 <table> 158 144 <tr> 159 145 <td> 160 146 161 161 - #### **Static** aspects are just attribute sets 147 147 + #### **Static** aspects are attribute sets. 148 148 + 149 149 + An aspect is a set of modules for different `classes`, configuring a single concern across them. 162 150 163 151 ```nix 164 164 - # An aspect is a collection of many 165 165 - # Nix configuration modules, each having 166 166 - # a different `class`. 167 152 den.aspects.my-laptop = { 168 168 - nixos = { }; 169 169 - darwin = { }; 170 170 - homeManager = { }; 153 153 + nixos = { /* ... */ }; 154 154 + darwin = { /* ... */ }; 171 155 172 172 - # aspects can be nested via `_` (`provides`) 173 173 - # forming a tree structure. 156 156 + # Nested aspects via `_` 157 157 + # (alias for `provides`) 174 158 _.gaming = { 175 175 - nixos = { }; 176 176 - 177 177 - # aspects can also `include` others 178 178 - # forming a graph of dependencies 179 179 - includes = [ 180 180 - # gaming.nixos module will mixin 181 181 - # nvidia-gpu.nixos module if any. 182 182 - den.aspects.nvidia-gpu 183 183 - ]; 159 159 + nixos = { /* ... */ }; 160 160 + # Dependency graph via `includes` 161 161 + includes = [ den.aspects.nvidia-gpu ]; 184 162 }; 185 185 - 186 163 }; 187 164 ``` 188 165 189 189 - > **TIP** 190 190 - > **`_`** is an alias for `provides`. In many examples you will see `foo._.bar._.baz` instead of `foo.provides.bar.provides.baz`. 191 191 - 192 166 </td> 193 167 <td> 194 168 195 195 - #### **Parametric** aspects are just functions. 169 169 + #### **Parametric** aspects are functions. 170 170 + 171 171 + They take a `context` and return a configuration. 196 172 197 173 ```nix 198 198 - # The convention is to always use named args. 199 199 - # These required args is the **context** the 200 200 - # aspect needs to provide configuration. 201 201 - hostParametric = { host }: { 174 174 + # A `{ host, gaming }` contextual aspect. 175 175 + hostFunction = { host, gaming }: { 202 176 nixos.networking.hostName = host.hostName; 203 203 - 204 204 - # A parametric aspect can also ask other 205 205 - # aspects for context-aware configurations. 206 206 - # Here, we ask two other parametric aspects 207 207 - # given the `{ host, gaming }` context. 208 208 - includes = let 209 209 - context.host = host; 210 210 - context.gaming.emulators = [ "nes" ]; 211 211 - in map (f: f context) [ 212 212 - den.default 213 213 - den.aspects.gaming-platform 214 214 - ]; 215 177 }; 216 216 - ``` 217 178 218 218 - #### Important **context** variants in `den`. 219 219 - 220 220 - Den uses the following contexts by default. 221 221 - 222 222 - The aspect system is not limited to these,<br> 223 223 - but these are used to describe [dependencies](modules/aspects/dependencies.nix)<br> 224 224 - between hosts/users, homes and default configs. 225 225 - 226 226 - - `{ host }` - For host _OS_ level configs. 227 227 - - `{ user, host }` - For user _Home_ level configs. 228 228 - - `{ home }` - For standalone _Home_ configs. 179 179 + # A parametric aspect can request context-aware 180 180 + # configurations from other aspects. 181 181 + hostParametric = { host }: { 182 182 + __functor = den.lib.parametric { 183 183 + inherit host; 184 184 + gaming.emulators = [ "nes" ]; 185 185 + }; 186 186 + includes = [ hostFunction den.default ]; 187 187 + } 188 188 + ``` 229 189 230 190 </td> 231 191 </tr> 232 192 </table> 233 193 234 234 - ### The Default aspect and default Dependencies 235 235 - 236 236 - Den has an special aspect at `den.default` that serves for global configuration. `den.default` is **included by default** in all *Hosts*, *Users* and *Homes*. For example a Home configuration invokes `den.default { inherit home; }`, to obtain the aggregated defaults for home contexts. 194 194 + `den` uses several default contexts to manage [dependencies](modules/aspects/dependencies.nix): 237 195 238 238 - <table> 239 239 - <tr> 240 240 - <td> 241 241 - 242 242 - #### Registering defaults values 243 243 - 244 244 - ```nix 245 245 - { 246 246 - # you can assign static values directly. 247 247 - den.default.nixos = { 248 248 - system.stateVersion = "25.11"; 249 249 - }; 250 250 - 251 251 - # you can also include other aspects 252 252 - den.default.includes = [ 253 253 - { darwin.system.stateVersion = 6; } 254 254 - ] 255 255 - } 256 256 - ``` 257 257 - 258 258 - It is possible to also register context-aware parametric aspects in `den.defaults`. This is how you can provide a default to all hosts or users that match a condition. 259 259 - 260 260 - ```nix 261 261 - # This example is split to aid reading. 262 262 - let 263 263 - hasOneUser = host: 264 264 - length (attrNames host.users) == 1; 265 265 - hasUser = host: user: 266 266 - hasAttr user.name host.users; 267 267 - makeAdmin = user: { 268 268 - nixos.users.users.${user.name} = { 269 269 - extraGroups = [ "wheel" ]; 270 270 - }; 271 271 - }; 272 272 - 273 273 - # IFF host has ONE user, make it admin 274 274 - single-user-is-admin = { host, user }: 275 275 - if hasOneUser host && hasUser host user 276 276 - then makeAdmin user else { }; 277 277 - in 278 278 - { 279 279 - den.default.includes = [ 280 280 - # will be called *ONLY* on when the 281 281 - # `{ host, user }` context is used. 282 282 - single-user-is-admin 283 283 - ]; 284 284 - } 285 285 - ``` 286 286 - 287 287 - #### Custom parametric providers. 288 288 - 289 289 - The following is the code for how `den.default` is 290 290 - defined. 291 291 - 292 292 - ```nix 293 293 - { den, ... }: { 294 294 - den.default.__functor = den.lib.parametric true; 295 295 - } 296 296 - ``` 297 297 - 298 298 - You can do the very same for other aspects of you 299 299 - that can have context-aware aspects in their `.includes`. 300 300 - 301 301 - ```nix 302 302 - { den, ...}: { 303 303 - den.aspects.gaming.__functor = den.lib.parametric true; 304 304 - 305 305 - # any other file can register gaming aspects 306 306 - den.aspects.gaming.includes = [ 307 307 - ({ emulation }: { 308 308 - nixos = ...; 309 309 - includes = [ den.aspects.steam ]; 310 310 - }) 311 311 - 312 312 - { nixos = ...; } # always included 313 313 - ({ gpu }: { }) # non-match on my-laptop 314 314 - ]; 315 315 - 316 316 - # then you can depend on the gaming aspect: 317 317 - den.aspects.my-laptop.includes = [ 318 318 - (den.aspects.gaming { emulation = "neogeo"; }) 319 319 - ]; 320 320 - 321 321 - } 322 322 - ``` 323 323 - 324 324 - For more examples on parametric aspects explore our [batteries](modules/aspects/provides/). 325 325 - 326 326 - > Use the source, Luke! 196 196 + - `{ host }`, `{ user, host }`, `{ home }` 197 197 + - `{ fromUser, toHost }`, `{ fromHost, toUser }` 327 198 328 199 </td> 329 329 - 330 330 - <td> 331 331 - 332 332 - #### Aspect dependencies 333 333 - 334 334 - Accessing an aspect module causes `flake-aspects` to resolve it 335 335 - by including the aspect's own class module and the same-class module 336 336 - of all its transitive includes. 337 337 - 338 338 - Additional to this, `den` registers some special [dependencies](modules/aspects/dependencies.nix) 339 339 - designed to aid on Den particular use case: Host/Users, Homes. 340 340 - 341 341 - ###### Host dependencies 342 342 - 343 343 - Host also include `den.aspects.<host> { inherit host; }` meaning 344 344 - all included parametric aspects have an opportunity to produce 345 345 - aditional configurations for the host. 346 346 - 347 347 - Also for each user, `den.aspects.<user> { inherit host user; }` 348 348 - is called. So `den.aspects.alice.nixos` can provide config to 349 349 - all hosts where alice lives. And also has the opportunity to 350 350 - register parametric aspects on `alice.provides` that inspect 351 351 - the host attribute to contionally produce other aspects. 200 200 + </tr> 201 201 + </table> 352 202 353 353 - ###### User dependencies 203 203 + ### The Default Aspect and Dependencies 354 204 355 355 - User modules are read from [os-home](modules/aspects/provides/home-manager.nix) configurations. 205 205 + `den` features a special aspect, `den.default`, which applies global configurations. It is automatically included in all hosts, users, and homes, receiving the appropriate context (e.g., `den.default { inherit home; }`). 356 206 357 357 - It basically invokes `den.aspects.<user> { inherit host user; }` but 358 358 - this time the host also contributes back generic configs to the users. 359 359 - If you are wondering how this is not recursive, the answer is by using 360 360 - our _contexts_, user-to-host dependencies start with a `{ host }` context, 361 361 - while host-to-user dependencies start with a `{ user, host }` context, and 362 362 - even when both are given to `den.aspects.<user> ctx` the results are 363 363 - non recursive. 207 207 + You can register static values or context-aware parametric aspects within `den.default`. This allows you to define defaults that apply conditionally to all hosts or users. 364 208 365 365 - A user also depends on `den.default { inherit host user; }`. 366 366 - 367 367 - ###### Home dependencies 368 368 - 369 369 - Home just uses its own module, its includes, and invokes `den.default { inherit home; }`. 370 370 - 371 371 - </td> 372 372 - 373 373 - </tr> 374 374 - </table> 209 209 + A key feature of `den` is its management of aspect dependencies. When an aspect is resolved, `flake-aspects` includes its class-specific module along with those of its transitive `includes`. `den` extends this by registering special [dependencies](modules/aspects/dependencies.nix) to link hosts and users. For instance, a host's configuration includes contributions from each of its users' aspects, and a user's home configuration includes contributions from its host's aspect, creating a bidirectional flow of settings. This is achieved without recursion by using distinct contexts for each direction. 375 210 376 211 </details> 377 212 378 213 <details> 379 214 <summary> 380 215 381 381 - # Aspect Organization Patterns 216 216 + ### Organization Patterns 382 217 383 383 - > Learn about organizing patterns for reuse. 218 218 + > Learn patterns for organizing and reusing aspects. 384 219 385 220 </summary> 386 221 387 387 - No two nix configurations are the same. We all tend to organize things as we feel better. 388 388 - This section will try to outline some hints on possible ways to organize aspects, none 389 389 - of this is mandatory, and indeed you are encouraged to explore and [share](https://github.com/vic/den/discussions) your own patterns and insights. 222 222 + While `den` is unopinionated about organization, these patterns can help structure your aspects for clarity and reuse. 390 223 391 391 - #### Having a _namespace_ of aspects. 392 392 - 393 393 - The first principle is using `.provides.` (aka [`._.`](https://github.com/vic/den/discussions/34)) to nest your aspects as they make sense for you. 394 394 - 395 395 - Unlike normal flake-parts, where modules are _flat_ and people tend to use names like `flake.modules.nixos."host/my-laptop"` or `nixos."feature/gaming"` to avoid collission, in `den` you have a proper tree structure. 396 396 - 397 397 - I (_vic_), use an aspect `vix` for all _features_ on my system, and from there I create sub-aspects. 398 398 - 399 399 - Because writing `den.aspects.vix._.gaming._.emulation` tends to be repetitive, I use the following `vix` alias as module argument. 400 400 - 401 401 - > This pattern is also shown in the default template, under [`_profile`](templates/default/modules/_profile/). 224 224 + #### Aspect Namespaces 402 225 403 403 - > **NOTE**: 404 404 - > `den` provides an [__angle brackets__](https://fzakaria.com/2025/08/10/angle-brackets-in-a-nix-flake-world) **experimental feature** that allows even shorter syntax for deep `.provides.` access. 405 405 - > See [import-non-dendritic.nix](templates/default/modules/_example/import-non-dendritic.nix) for an example usage. 226 226 + Group related aspects under a single top-level aspect and alias it as a module argument for easier access. The `den.namespace` function streamlines this. 406 227 407 228 <table> 408 229 <tr> 409 230 <td> 410 231 232 232 + #### Using local and remote namespaces 233 233 + 411 234 ```nix 412 235 # modules/namespace.nix 413 413 - { config, ... }: 236 236 + { inputs, ... }: 414 237 { 415 415 - den.aspects.vix = { }; 416 416 - _module.args.vix = config.den.aspects.vix._; 238 238 + imports = [ 239 239 + # create local `pro` namespace 240 240 + (inputs.den.namespace "pro" true) 241 241 + # mixin remote `pro` from input 242 242 + (inputs.den.namespace "pro" inputs.foo) 243 243 + ]; 417 244 } 418 245 ``` 419 246 420 247 </td> 421 248 <td> 422 249 250 250 + #### Directly read and write to namespace 251 251 + 423 252 ```nix 424 253 # modules/my-laptop.nix 425 425 - { vix, ... }: 254 254 + { pro, ... }: 426 255 { 427 427 - vix.gaming = { 428 428 - _.steam.includes = [ 429 429 - vix.gpu 430 430 - vix.performance-profile 431 431 - ]; 432 432 - }; 256 256 + pro.gaming.includes = [ pro.gpu ]; 433 257 } 434 258 ``` 435 259 436 436 - See [real-life example from vic/vix](https://github.com/vic/vix/blob/den/modules/hosts/nargun.nix) 437 437 - 438 260 </td> 439 261 </tr> 440 262 </table> 441 263 442 442 - #### Using parametric aspects to route configurations. 264 264 + #### Angle-Bracket Syntax 443 265 444 444 - The following example routes configurations into the `vix` namespace. 445 445 - This is just an example of using parametric aspects to depend on other 446 446 - aspects in any part of the tree. 266 266 + For deeply nested aspects, `den` offers an experimental feature to shorten access paths. By bringing `den.lib.__findFile` into scope, you can use angle brackets to reference aspects more concisely. 447 267 448 448 - <table> 449 449 - <tr> 450 450 - <td> 268 268 + - `<my-laptop>` resolves to `den.aspects.my-laptop` 269 269 + - `<my-laptop/gaming>` resolves to `den.aspects.my-laptop.provides.gaming` 270 270 + - `<den/import-tree/host>` resolves to `den.provides.import-tree.provides.home` 271 271 + - `<vix/foo/bar>` namespace aware: `den.ful.vix.foo.provides.bar` 451 272 452 452 - ```nix 453 453 - # modules/routes.nix 454 454 - { den, ... }: 455 455 - let 456 456 - noop = _: { }; 273 273 + This feature is powered by a custom [`__findFile`](nix/den-brackets.nix) implementation. See the [profile example](templates/default/modules/_profile/den-brackets.nix) to learn how to enable it. 457 274 458 458 - by-platform-config = { host }: 459 459 - vix.${host.system} or noop; 460 460 - 461 461 - user-provides-host-config = { user, host }: 462 462 - vix.${user.aspect}._.${host.aspect} or noop; 463 463 - 464 464 - host-provides-user-config = { user, host }: 465 465 - vix.${host.aspect}._.${user.aspect} or noop; 466 466 - 467 467 - route = locator: { user, host }@ctx: 468 468 - (locator ctx) ctx; 469 469 - in 470 470 - { 471 471 - den.aspects.routes.__functor = 472 472 - den.lib.parametric true; 473 473 - den.aspects.routes.includes = 474 474 - map route [ 475 475 - user-provides-host-config 476 476 - host-provides-user-config 477 477 - by-platform-config 478 478 - ]; 479 479 - } 480 480 - ``` 275 275 + #### Parametric Routing 481 276 482 482 - </td> 483 483 - <td> 277 277 + You can use parametric aspects to create routing logic that dynamically includes other aspects based on context. This pattern allows you to build a flexible and declarative dependency tree. 484 278 485 279 ```nix 280 280 + # modules/routes.nix 281 281 + { den, pro, ... }: 282 282 + let 283 283 + # Route to a platform-specific profile 284 284 + by-platform = { host }: pro.${host.system} or { }; 285 285 + in 486 286 { 487 487 - # for all darwin hardware 488 488 - vix.aarch64-darwin = { host }: { 489 489 - darwin = ...; 490 490 - }; 491 491 - 492 492 - # config bound to vic user 493 493 - # on my-laptop host. 494 494 - vix.vic.provides.my-laptop = 495 495 - { host, user }: { 496 496 - nixos = ...; 497 497 - }; 287 287 + # Apply routes globally 288 288 + den.default.includes = [ by-platform ]; 498 289 } 499 290 ``` 500 291 501 501 - Use your imagination, come up with 502 502 - an awesome Dendritic setup that suits you. 503 503 - 504 504 - </td> 505 505 - </tr> 506 506 - </table> 507 507 - 508 508 - > You made it to the end!, thanks for reading to this point. 509 509 - > I hope you enjoy using `den` as much as I have done writing it and have put dedication 510 510 - > on it for being high quality-nix for you. \<3. 511 511 - > I feel like den is now feature complete, and it will not likely change. 292 292 + > You made it to the end! Thanks for reading. I hope you enjoy using `den`. It is feature-complete and unlikely to change. 512 293 513 294 </details> 514 295 515 515 - ### Contributing. 296 296 + ### Contributing 516 297 517 517 - Yes, please, anything!. From fixing my bad english and typos, to sharing your ideas and experience with `den` in our discussion forums. Feel free to participate and be nice with everyone. 298 298 + Contributions are welcome! Feel free to fix typos, improve documentation, or share ideas in our [discussions](https://github.com/vic/den/discussions). 518 299 519 519 - PRs are more than welcome, the CI runs some checks that verify nothing (known) is broken. Any new feature needs a test in `_example/ci.nix`. 300 300 + All PRs are checked against the CI. New features should include a test in `_example/ci.nix`. 520 301 521 521 - If you need to run the test suite locally: 302 302 + To run tests locally: 522 303 523 304 ```console 524 524 - $ nix flake check ./checkmate --override-input target . 525 525 - $ cd templates/default && nix flake check --override-input den ../.. 305 305 + nix flake check ./checkmate --override-input target . 306 306 + cd templates/default && nix flake check --override-input den ../.. 526 307 ```

+7 -2

checkmate/tests/aspect-functor.nix

··· 1 1 - { lib, inputs, ... }: 1 1 + { 2 2 + lib, 3 3 + inputs, 4 4 + config, 5 5 + ... 6 6 + }: 2 7 let 3 3 - __functor = (inputs.target.lib lib inputs).parametric true; 8 8 + __functor = (inputs.target.lib { inherit lib inputs config; }).parametric true; 4 9 5 10 aspect-example = { 6 11 inherit __functor;

+40

checkmate/tests/den-brackets.nix

··· 1 1 + { ... }@top: 2 2 + let 3 3 + lib = top.inputs.nixpkgs.lib; 4 4 + 5 5 + # deadnix: skip 6 6 + __findFile = 7 7 + if true then 8 8 + import "${top.inputs.target}/nix/den-brackets.nix" { inherit lib config inputs; } 9 9 + else 10 10 + __findFile; 11 11 + 12 12 + inputs = { 13 13 + 14 14 + }; 15 15 + 16 16 + config.den = { 17 17 + default.foo = 1; 18 18 + 19 19 + provides.foo.a = 2; 20 20 + provides.foo.provides.bar.b = 3; 21 21 + provides.foo.provides.c = 4; 22 22 + 23 23 + d = 5; 24 24 + 25 25 + aspects.foo.a = 6; 26 26 + aspects.foo.provides.bar.b = 7; 27 27 + aspects.foo.provides.c = 8; 28 28 + 29 29 + }; 30 30 + in 31 31 + { 32 32 + flake.tests."<den.default>" = 33 33 + let 34 34 + expr = <den.default>; 35 35 + expected.foo = 2; 36 36 + in 37 37 + { 38 38 + inherit expr expected; 39 39 + }; 40 40 + }

+7 -2

checkmate/tests/function_can_take.nix

··· 1 1 - { lib, inputs, ... }: 1 1 + { 2 2 + lib, 3 3 + inputs, 4 4 + config, 5 5 + ... 6 6 + }: 2 7 let 3 3 - takes = (inputs.target.lib lib inputs).canTake; 8 8 + takes = (inputs.target.lib { inherit inputs lib config; }).canTake; 4 9 5 10 flake.tests."test function with no named arguments can take anything" = { 6 11 expr = takes { } (x: x);

+2 -1

flake.nix

··· 1 1 { 2 2 - outputs = _inputs: { 2 2 + outputs = _: { 3 3 flakeModule = ./nix/flakeModule.nix; 4 4 templates.default = { 5 5 path = ./templates/default; 6 6 description = "Minimal nixos configuration"; 7 7 }; 8 8 packages = import ./nix/template-packages.nix; 9 9 + namespace = import ./nix/namespace.nix; 9 10 lib = import ./nix/lib.nix; 10 11 }; 11 12 }

+2 -1

modules/lib.nix

··· 1 1 { 2 2 lib, 3 3 inputs, 4 4 + config, 4 5 ... 5 6 }: 6 7 { 7 7 - config.den.lib = inputs.den.lib lib inputs; 8 8 + config.den.lib = inputs.den.lib { inherit inputs lib config; }; 8 9 options.den.lib = lib.mkOption { 9 10 internal = true; 10 11 visible = false;

+49

nix/den-brackets.nix

··· 1 1 + # __findFile implementation to resolve deep aspects. 2 2 + # inspired by https://fzakaria.com/2025/08/10/angle-brackets-in-a-nix-flake-world 3 3 + # 4 4 + # For user facing documentation, see: 5 5 + # See templates/default/_profile/den-brackets.nix 6 6 + # See templates/default/_profile/namespace.nix 7 7 + { 8 8 + lib, 9 9 + config, 10 10 + ... 11 11 + }: 12 12 + _nixPath: name: 13 13 + let 14 14 + 15 15 + findAspect = 16 16 + path: 17 17 + let 18 18 + head = lib.head path; 19 19 + tail = lib.tail path; 20 20 + 21 21 + notFound = "Aspect not found: ${lib.concatStringsSep "." path}"; 22 22 + 23 23 + headIsDen = head == "den"; 24 24 + readFromDen = lib.getAttrFromPath tail config.den; 25 25 + 26 26 + headIsAspect = builtins.hasAttr head config.den.aspects; 27 27 + readFromAspects = lib.getAttrFromPath path config.den.aspects; 28 28 + 29 29 + headIsDenful = lib.hasAttrByPath [ "ful" head ] config.den; 30 30 + readFromDenful = lib.getAttrFromPath tail config.den.ful; 31 31 + 32 32 + found = 33 33 + if headIsDen then 34 34 + readFromDen 35 35 + else if headIsAspect then 36 36 + readFromAspects 37 37 + else if headIsDenful then 38 38 + readFromDenful 39 39 + else 40 40 + throw notFound; 41 41 + in 42 42 + found; 43 43 + 44 44 + in 45 45 + lib.pipe name [ 46 46 + (lib.strings.replaceStrings [ "/" ] [ ".provides." ]) 47 47 + (lib.strings.splitString ".") 48 48 + (findAspect) 49 49 + ]

+8 -13

nix/lib.nix

··· 1 1 - lib: inputs: 1 1 + { 2 2 + inputs, 3 3 + lib, 4 4 + config, 5 5 + ... 6 6 + }: 2 7 let 3 8 isFn = f: (builtins.isFunction f) || (f ? __functor); 4 9 canTake = import ./fn-can-take.nix lib; ··· 55 60 56 61 aspects = inputs.flake-aspects.lib lib; 57 62 58 58 - # EXPERIMENTAL. __findFile to resolve deep aspects. 59 59 - # __findFile = angleBrackets den.aspects; 60 60 - # <foo/bar/baz> => den.aspects.foo.provides.bar.provides.baz 61 61 - # inspired by https://fzakaria.com/2025/08/10/angle-brackets-in-a-nix-flake-world 62 62 - angleBrackets = 63 63 - den-ns: _nixPath: name: 64 64 - lib.pipe name [ 65 65 - (lib.replaceString "/" ".provides.") 66 66 - (lib.splitString ".") 67 67 - (path: lib.getAttrFromPath path den-ns) 68 68 - ]; 63 63 + __findFile = import ./den-brackets.nix { inherit lib config; }; 69 64 70 65 den-lib = { 71 66 inherit 72 67 parametric 73 68 aspects 74 74 - angleBrackets 69 69 + __findFile 75 70 statics 76 71 owned 77 72 isFn

+29

nix/namespace.nix

··· 1 1 + name: input: 2 2 + { config, lib, ... }: 3 3 + let 4 4 + isLocal = !builtins.isAttrs input; 5 5 + isOutput = isLocal && input == true; 6 6 + 7 7 + aliasModule = lib.mkAliasOptionModule [ name ] [ "den" "ful" name ]; 8 8 + 9 9 + type = lib.types.attrsOf config.den.lib.aspects.types.providerType; 10 10 + 11 11 + source = if isLocal then { } else input.denful.${name}; 12 12 + output = 13 13 + if isOutput then 14 14 + { 15 15 + config.flake.denful.${name} = config.den.ful.${name}; 16 16 + options.flake.denful.${name} = lib.mkOption { inherit type; }; 17 17 + } 18 18 + else 19 19 + { }; 20 20 + in 21 21 + { 22 22 + imports = [ 23 23 + aliasModule 24 24 + output 25 25 + ]; 26 26 + config._module.args.${name} = config.den.ful.${name}; 27 27 + config.den.ful.${name} = source; 28 28 + options.den.ful.${name} = lib.mkOption { inherit type; }; 29 29 + }

+6 -9

templates/default/flake.lock

··· 22 22 }, 23 23 "den": { 24 24 "locked": { 25 25 - "lastModified": 1762483837, 26 26 - "narHash": "sha256-4rFMMbyZdzxPduljpUB2eEB4VHNLcF2pM2K6KxWK37k=", 27 27 - "owner": "vic", 28 28 - "repo": "den", 29 29 - "rev": "c1a0d345c4484faba4a146d60c746b12c5fce9e6", 30 30 - "type": "github" 25 25 + "lastModified": 1762501715, 26 26 + "narHash": "sha256-ynnkGe7wBqQLZM+R4mwh/N7nFn5mh870wRe6tyiZfQY=", 27 27 + "path": "/home/vic/hk/den", 28 28 + "type": "path" 31 29 }, 32 30 "original": { 33 33 - "owner": "vic", 34 34 - "repo": "den", 35 35 - "type": "github" 31 31 + "path": "/home/vic/hk/den", 32 32 + "type": "path" 36 33 } 37 34 }, 38 35 "flake-aspects": {

+1 -1

templates/default/flake.nix

··· 14 14 url = "github:nix-darwin/nix-darwin"; 15 15 }; 16 16 den = { 17 17 - url = "github:vic/den"; 17 17 + url = "path:/home/vic/hk/den"; 18 18 }; 19 19 flake-aspects = { 20 20 url = "github:vic/flake-aspects";

+9 -12

templates/default/modules/_example/import-non-dendritic.nix

··· 1 1 # configures class-automatic module auto imports for hosts/users/homes. 2 2 # See documentation at modules/aspects/provides/import-tree.nix 3 3 - { den, ... }: 4 4 - let 5 5 - # EXPERIMENTAL FEATURE: __findFile enables angle brackets 6 6 - # <import-tree/host> resolves to: den.provides.import-tree.provides.host 7 7 - # See lib.nix and https://fzakaria.com/2025/08/10/angle-brackets-in-a-nix-flake-world 8 8 - # deadnix: skip # this weird if is for my nixf-diagnose to skip unused __findFile. 9 9 - __findFile = if true then den.lib.angleBrackets den.provides else __findFile; 10 10 - in 3 3 + { 4 4 + # deadnix: skip # see _profile/den-brackets.nix 5 5 + __findFile ? __findFile, 6 6 + ... 7 7 + }: 11 8 { 12 9 13 10 # alice imports non-dendritic <class> modules from _non_dendritic/alice/_<class>/*.nix 14 14 - den.aspects.alice.includes = [ (<import-tree> ./_non_dendritic/alice) ]; 11 11 + den.aspects.alice.includes = [ (<den/import-tree> ./_non_dendritic/alice) ]; 15 12 16 13 # See the documentation at batteries/import-tree.nix 17 14 den.default.includes = [ 18 18 - (<import-tree/host> ./_non_dendritic/hosts) 19 19 - (<import-tree/user> ./_non_dendritic/users) 20 20 - (<import-tree/home> ./_non_dendritic/homes) 15 15 + (<den/import-tree/host> ./_non_dendritic/hosts) 16 16 + (<den/import-tree/user> ./_non_dendritic/users) 17 17 + (<den/import-tree/home> ./_non_dendritic/homes) 21 18 ]; 22 19 23 20 }

+36

templates/default/modules/_profile/den-brackets.nix

··· 1 1 + # This enables den's angle brackets opt-in feature. 2 2 + # Remove this file to opt-out. 3 3 + # 4 4 + # When den.lib.__findFile is in scope, you can do: 5 5 + # 6 6 + # <pro/foo/bar> and it will resolve to: 7 7 + # den.aspects.pro.provides.foo.provides.bar 8 8 + # 9 9 + # <pro/foo.includes> resolves to: 10 10 + # den.aspects.pro.provides.foo.includes 11 11 + # 12 12 + # <den/import-tree/home> resolves to: 13 13 + # den.provides.import-tree.provides.home 14 14 + # 15 15 + # <den.default> resolves to den.default 16 16 + # 17 17 + # When the vix remote namespace is enabled 18 18 + # <vix/foo> resolves to: den.ful.vix.provides.foo 19 19 + # 20 20 + # Usage: 21 21 + # 22 22 + # Bring `__findFile` into scope from module args: 23 23 + # 24 24 + # { __findFile, ... }: 25 25 + # den.default.includes = [ <den/home-manager> ]; 26 26 + # } 27 27 + # 28 28 + # IF you are using nixf-diagnose, it will complain 29 29 + # about __findFile not being used, trick it with: 30 30 + # 31 31 + # { __findFile ? __findFile, ... } 32 32 + # 33 33 + { den, ... }: 34 34 + { 35 35 + _module.args.__findFile = den.lib.__findFile; 36 36 + }

+8 -7

templates/default/modules/_profile/hosts/bones/common-user-env.nix

··· 4 4 # private aspects can be let-bindings 5 5 # more re-usable ones are better defined inside the `pro` namespace. 6 6 host-contrib-to-user = 7 7 - # { host, user }: # uncomment if needed 8 8 - { 9 9 - homeManager.programs.vim.enable = true; 10 10 - }; 7 7 + { fromHost, toUser }: 8 8 + if fromHost.name == "bones" || toUser.name == "fido" then 9 9 + { 10 10 + homeManager.programs.vim.enable = true; 11 11 + } 12 12 + else 13 13 + { }; 11 14 in 12 15 { 13 13 - den.aspects.bones.provides.user.includes = [ 14 14 - # add other aspects of yours that use host, user 15 15 - # to conditionally add behaviour. 16 16 + den.default.includes = [ 16 17 host-contrib-to-user 17 18 ]; 18 19 }

+62 -19

templates/default/modules/_profile/namespace.nix

··· 1 1 - # creates a `pro` aspect namespace. 1 1 + # This module creates an aspect namespace. 2 2 + # 3 3 + # Just add the following import: 4 4 + # 5 5 + # # define local namespace. enable flake output. 6 6 + # imports = [ (inputs.den.namespace "vix" true) ]; 7 7 + # 8 8 + # # you can use remote namespaces and they will merge 9 9 + # imports = [ (inputs.den.namespace "vix" inputs.dendrix) ]; 10 10 + # 11 11 + # Internally, a namespace is just a `provides` branch: 12 12 + # 13 13 + # # den.ful is the social-convention for namespaces. 14 14 + # den.ful.<name> 15 15 + # 16 16 + # Having an aspect namespace is not required but helps a lot 17 17 + # with organization and conventient access to your aspects. 18 18 + # 19 19 + # The following examples use the `vix` namespace, 20 20 + # inspired by github:vic/vix own namespace pattern. 21 21 + # 22 22 + # By using an aspect namespace you can: 23 23 + # 24 24 + # - Directly write to aspects in your namespace. 25 25 + # 26 26 + # { 27 27 + # vix.gaming.nixos = ...; 28 28 + # 29 29 + # # instead of: 30 30 + # # den.ful.vix.gaming.nixos = ...; 31 31 + # } 32 32 + # 33 33 + # - Directly read aspects from your namespace. 34 34 + # 35 35 + # # Access the namespace from module args 36 36 + # { vix, ... }: 37 37 + # { 38 38 + # den.default.includes = [ vix.security ]; 39 39 + # 40 40 + # # instead of: 41 41 + # # den.default.includes = [ den.ful.vix.security ]; 42 42 + # } 2 43 # 3 3 - # this is not required but helps you avoid writing 4 4 - # `den.aspects.profile.provides` all the time 5 5 - # and use your namespace instead. 6 6 - # This is inspired by vic's vix namespae. 44 44 + # - Share and re-use aspects between Dendritic flakes 7 45 # 8 8 - # User TODO: rename `pro` to something else on your project. 9 9 - # The namespace is accesible via the module args 10 10 - # and also writable as an option at module root. 46 46 + # # Aspects opt-in exposed as flake.denful.<name> 47 47 + # { imports = [( inputs.den.namespace "vix" true)] } 11 48 # 12 12 - { config, lib, ... }: 49 49 + # # Many flakes can expose to the same namespace and we 50 50 + # # can merge them, accessing aspects in a uniform way. 51 51 + # { imports = [( inputs.den.namespace "vix" inputs.dendrix )] } 52 52 + # 53 53 + # - Use angle-brackets to access deeply nested trees 54 54 + # 55 55 + # # Be sure to read _profile/den-brackets.nix 56 56 + # { __findFile, ... }: 57 57 + # den.aspects.my-laptop.includes = [ <vix/gaming/retro> ]; 58 58 + # } 59 59 + # 60 60 + # 61 61 + # You can of course choose to not have any of the above. 62 62 + # USER TODO: Remove this file for not using a namespace. 63 63 + # USER TODO: Replace `pro` and update other files using it. 64 64 + { inputs, ... }: 13 65 { 14 14 - # create a sub-tree of provided aspects. 15 15 - # the `profile` name is generic, use your own 16 16 - # as deep as you like, only that it ends in a provides tree. 17 17 - den.aspects.profile.provides = { }; 18 18 - # setup for write 19 19 - imports = [ (lib.mkAliasOptionModule [ "pro" ] [ "den" "aspects" "profile" "provides" ]) ]; 20 20 - # setup for read 21 21 - _module.args.pro = config.den.aspects.profile.provides; 22 22 - # optionally expose outside your flake. 23 23 - # flake.pro = config.den.aspects.profile.provides; 66 66 + imports = [ (inputs.den.namespace "pro" true) ]; 24 67 }

+9 -52

templates/default/modules/_profile/profiles.nix

··· 1 1 # Profiles are just aspects whose only job is to include other aspects 2 2 # based on the properties (context) of the host/user they are included in. 3 3 - { pro, ... }: 3 3 + { pro, den, ... }: 4 4 { 5 5 6 6 # install profiles as parametric aspects on all hosts/users 7 7 den.default.includes = [ 8 8 - pro.by-host 9 9 - pro.by-user 8 8 + pro.profiles 10 9 ]; 11 10 12 12 - # `by-host { host }` 13 13 - # 14 14 - # den automatically includes `den.aspects.${host.name}`, besides that 15 15 - # this profile adds the following aspects if they exist: 16 16 - # 17 17 - # - `den.aspects.profile._.${system}` eg, an aspect per host hardware platform. 18 18 - # 19 19 - # since the `host` type is a freeform (see types.nix) you can add 20 20 - # custom attributes to your hosts and use them to dispatch for 21 21 - # common aspects. eg, by host network, etc. 22 22 - # 23 23 - # Also, remember that aspects can form a tree structure by using their 24 24 - # `provides` attribute, not all aspects need to exist at same level. 25 25 - pro.by-host = 26 26 - { host, ... }: 27 27 - { 28 28 - includes = [ 29 29 - (pro.${host.system} or { }) 30 30 - ]; 31 31 - }; 32 32 - 33 33 - # `by-user { host, user }` 34 34 - # 35 35 - # den automatically includes `den.aspects.${user.name}`. 36 36 - # a user can contribute modules to the host is part of, and also 37 37 - # define its own home-level configs. 38 38 - # 39 39 - # - `den.aspects.<host>._.user { host, user }`: included on each user of a host. 40 40 - # - `den.aspects.<user>._.host { host, user }`: included on each host where a user exists. 41 41 - # 42 42 - # this profile adds the following aspects if they exist: 43 43 - # 44 44 - # - `den.aspects.profile._.single-user-is-admin { host, user }` 45 45 - # 46 46 - # Since both host and user types are freeforms, you might add custom attributes 47 47 - # to them and your parametric aspects can use those attributes to conditionally add 48 48 - # features into the host or user level. 49 49 - pro.by-user = 50 50 - { host, user }: 51 51 - { 52 52 - includes = 53 53 - let 54 54 - apply = f: f { inherit host user; }; 55 55 - in 56 56 - map apply [ 57 57 - pro.single-user-is-admin 58 58 - # TODO: add 59 59 - ]; 60 60 - }; 11 11 + pro.profiles = { 12 12 + __functor = den.lib.parametric true; 13 13 + includes = [ 14 14 + ({ host }: pro.${host.system} or { }) 15 15 + # add other routes according to context. 16 16 + ]; 17 17 + }; 61 18 62 19 }

+5 -5

templates/default/modules/_profile/profiles/single-user-is-admin.nix

··· 3 3 4 4 # When a host includes *ONLY* one user, make that user the admin. 5 5 pro.single-user-is-admin = 6 6 - { host, user }: 6 6 + { fromUser, toHost }@context: 7 7 let 8 8 - one-user = 1 == builtins.length (builtins.attrValues host.users); 9 9 - is-admin = one-user && builtins.hasAttr user.name host.users; 10 10 - admin = lib.optionals is-admin [ den._.primary-user ]; 8 8 + single = 1 == builtins.length (builtins.attrValues toHost.users); 9 9 + exists = single && builtins.hasAttr fromUser.name toHost.users; 10 10 + admin = lib.optionals exists [ den._.primary-user ]; 11 11 define = [ den._.define-user ]; 12 12 in 13 13 { 14 14 - includes = map (f: f { inherit user host; }) (define ++ admin); 14 14 + includes = map (f: f context) (define ++ admin); 15 15 }; 16 16 }

+9 -13

templates/default/modules/_profile/users/fido/common-host-env.nix

··· 1 1 # An aspect that contributes to any operating system where fido is a user. 2 2 - { ... }: 2 2 + # hooks itself into any host. 3 3 + { pro, ... }: 3 4 let 4 4 - # private aspects can be in variables 5 5 - # more re-usable ones are better defined inside the `pro` namespace. 6 6 - user-contrib-to-host = 7 7 - # { user, host }: # uncomment if needed 8 8 - { 9 9 - nixos = { }; 10 10 - darwin = { }; 11 11 - }; 5 5 + fido-at-host = 6 6 + { fromUser, toHost }: if fromUser.name != "fido" then { } else pro.fido._.${toHost.name}; 12 7 in 13 8 { 14 14 - den.aspects.fido.provides.host.includes = [ 15 15 - # add other aspects of yours that use host, user 16 16 - # to conditionally add behaviour. 17 17 - user-contrib-to-host 9 9 + den.default.includes = [ 10 10 + fido-at-host 18 11 ]; 12 12 + 13 13 + # fido on bones host. 14 14 + pro.fido._.bones.nixos = { }; 19 15 }

+1 -1

templates/default/modules/den.nix

··· 8 8 (inputs.import-tree ./_example) 9 9 10 10 # The _profile directory contains a minimal profile-based layout. 11 11 - # (inputs.import-tree ./_profile) # Disabled, working on #45 11 11 + (inputs.import-tree ./_profile) 12 12 ]; 13 13 }