From fe3a624930d35a7278001a5d05629959c5a42d4d Mon Sep 17 00:00:00 2001 From: Pacman99 Date: Thu, 3 Jun 2021 12:25:06 -0700 Subject: [PATCH] docs: general updates --- doc/CONTRIBUTING.md | 5 +- doc/concepts/hosts.md | 11 ++- doc/concepts/profiles.md | 43 +++++---- doc/concepts/suites.md | 14 +-- doc/concepts/users.md | 23 +++-- doc/lib.md | 87 ----------------- doc/mkFlakeOptions.md | 200 ++++++++++++++++++++++++++++++++------- doc/outputs/pkgs.md | 3 +- doc/tests.md | 11 +-- 9 files changed, 227 insertions(+), 170 deletions(-) delete mode 100644 doc/lib.md diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index bb480ae..f721069 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -1,5 +1,8 @@ # Pull Requests -If making a change to core, or adding a feature, please be sure to update the +All development is done in the `develop` branch. Only minor bug-fixes and release +PRs should target `master`. + +If making a change to the template, or adding a feature, please be sure to update the relevant docs. Each directory contains its own README.md, which will automatically be pulled into the [mdbook](https://devos.divnix.com). The book is rendered on every change, so the docs should always be up to date. diff --git a/doc/concepts/hosts.md b/doc/concepts/hosts.md index 37130f3..1c3c3fa 100644 --- a/doc/concepts/hosts.md +++ b/doc/concepts/hosts.md @@ -6,13 +6,14 @@ of these hosts, devos automatically imports every _.nix_ file inside this directory to the mentioned attribute set, applying the projects defaults to each. The only hard requirement is that the file contain a valid NixOS module. -As an example, a file `hosts/system.nix` will be available via the flake -output `nixosConfigurations.system`. You can have as many hosts as you want -and all of them will be automatically imported based on their name. +As an example, a file `hosts/system.nix` or `hosts/system/default.nix` will +be available via the flake output `nixosConfigurations.system`. You can have +as many hosts as you want and all of them will be automatically imported based +on their name. For each host, the configuration automatically sets the `networking.hostName` -attribute to the name of the file minus the _.nix_ extension. This is for -convenience, since `nixos-rebuild` automatically searches for a configuration +attribute to the folder name or name of the file minus the _.nix_ extension. This +is for convenience, since `nixos-rebuild` automatically searches for a configuration matching the current systems hostname if one is not specified explicitly. You can set channels, systems, and add extra modules to each host by editing the diff --git a/doc/concepts/profiles.md b/doc/concepts/profiles.md index 1c8f416..b4ff0a1 100644 --- a/doc/concepts/profiles.md +++ b/doc/concepts/profiles.md @@ -8,34 +8,29 @@ separation of concerns. If you need guidance, a community [branch](https://github.com/divnix/devos/tree/community/profiles) is maintained to help get up to speed on their usage. -## Constraints -For the sake of consistency, a profile should always be defined in a -___default.nix___ containing a [nixos module config][config]. -A profile's directory is used for quick modularization of -[interelated bits](./profiles.md#subprofiles). +## Creation +Profiles are created with the `rakeLeaves` function which recursively collects +`.nix` files from within a folder. The recursion stops at folders with a `default.nix` +in them. You end up with an attribute set with leaves(paths to profiles) or +nodes(attrsets leading to more nodes or leaves). + +A profile is used for quick modularization of [interelated bits](./profiles.md#subprofiles). > ##### _Notes:_ > * For _declaring_ module options, there's the [modules](../outputs/modules.md) directory. > * This directory takes inspiration from > [upstream](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules/profiles) > . -> * Sticking to a simple [spec][spec] has refreshing advantages. -> [hercules-ci](../integrations/hercules.md) expects all profiles to be -> defined in a ___default.nix___, allowing them to be built automatically when -> added. Congruently, [suites](suites.md) expect ___default.nix___ to avoid -> having to manage their paths manually. -## Subprofiles -Profiles can also define subprofiles. They follow the same constraints outlined -above. A good top level profile should be a high level concern, such as your -personal development environment while the subprofiles should be more focused -program configurations such as your text editor, and shell configs. This way, -you can either pull in the whole development profile, or pick and choose -individual programs. +### Nested profiles +Profiles can be nested in attribute sets due to the recursive nature of `rakeLeaves`. +This can be useful to have a set of profiles created for a specific purpose. It is +sometimes useful to have a `common` profile that has high level concerns related +to all its sister profiles. ### Example -profiles/develop/default.nix: +profiles/develop/common.nix: ```nix { imports = [ ./zsh ]; @@ -43,7 +38,7 @@ profiles/develop/default.nix: } ``` -profiles/develop/zsh/default.nix: +profiles/develop/zsh.nix: ```nix { ... }: { @@ -52,6 +47,16 @@ profiles/develop/zsh/default.nix: } ``` +The examples above will end up with a profiles set like this: +```nix +{ + develop = { + common = ./profiles/develop/common.nix; + zsh = ./profiles/develop/zsh.nix; + }; +} +``` + ## Conclusion Profiles are the most important concept in DevOS. They allow us to keep our Nix expressions self contained and modular. This way we can maximize reuse diff --git a/doc/concepts/suites.md b/doc/concepts/suites.md index 5c0d590..0182d9b 100644 --- a/doc/concepts/suites.md +++ b/doc/concepts/suites.md @@ -1,19 +1,13 @@ # Suites Suites provide a mechanism for users to easily combine and name collecitons of -profiles. For good examples, check out the suites defined in the community -[branch](https://github.com/divnix/devos/blob/community/suites/default.nix). +profiles. For good examples, check out the suites defined in the community branch. -In the future, we will use suites as a mechanism for deploying various machine -types which don't depend on hardware, such as vm's and containers. +`suites` are a special case of an `importable` which get passed as a special +argument (one that can be use in an `imports` line) to your hosts. -They are defined with the `suites` argument in either `home` or `nixos` namespace. +They are defined with the `suites` argument in either the `home` or `nixos` namespace. Suites should be passed as a function that take profiles as an argument. -The profiles are passed based on the folder names and list passed to the relevant -`profiles` argument. In the template's flake.nix `profiles` is set as -`[ ./profiles ./users ]` and that corresponds to the `{ profiles, users }` argument -pattern. - ## Definition ```nix rec { diff --git a/doc/concepts/users.md b/doc/concepts/users.md index 235884a..20f371d 100644 --- a/doc/concepts/users.md +++ b/doc/concepts/users.md @@ -23,11 +23,23 @@ your users. For a fully fleshed out example, check out the developers personal ``` ## Home Manager -Home Manager support follows the same principles as regular nixos configurations. +Home Manager support follows the same principles as regular nixos configurations, +it even gets its own namespace in your `flake.nix` as `home`. + All modules defined in [user modules][modules-list] will be imported to -Home Manager. All profiles are availabe in [suites][suites] as userProfiles. -The `userSuites` output will be available in your Home Manager Configuration as -the special argument, `suites`. +Home Manager. +User profiles can be collected in a similar fashion as system ones into a `suites` +argument that gets passed to your home-manager users. + +### Example +```nix +{ + home-manager.users.nixos = { suites, ... }: { + imports = suites.base; + }; +} +``` + ## External Usage You can easily use the defined home-manager configurations outside of NixOS @@ -56,5 +68,4 @@ nix build "github:divnix/devos#homeConfigurations.nixos@NixOS.home.activationPac ``` [home-manager]: https://nix-community.github.io/home-manager -[suites]: https://github.com/divnix/devos/tree/core/suites/default.nix -[modules-list]: https://github.com/divnix/devos/tree/core/modules/module-list.nix +[modules-list]: https://github.com/divnix/devos/tree/core/users/modules/module-list.nix diff --git a/doc/lib.md b/doc/lib.md deleted file mode 100644 index ee402eb..0000000 --- a/doc/lib.md +++ /dev/null @@ -1,87 +0,0 @@ -# Lib -The lib directory mirrors the upstream concepts of [`nixpkgs:./lib`][nixpkgs-lib], -[`nixpkgs:./nixos/lib`][nixpkgs-nixos-lib] and [`nixpkgs:./pkgs/pkgs-lib`][nixpkgs-pkgs-lib], -but also occasionally [`nixpkgs:./pkgs/build-support`][nixpkgs-pkgs-build-support]. - -All functions defined in lib can be accessed in modules and packages as `ourlib`. - -For example: - -- you want to add a library function that depends on some packages -and use it throughout your devos environment: place it into `./lib` -as if you would place it into [`nixpkgs:./pkgs/pkgs-lib`][nixpkgs-pkgs-lib]. - -- you want to add library functions that don't depend on `pkgs`: place -them into `./lib` as if you would place them into [`nixpkgs:./lib`][nixpkgs-lib]. - -- need to try out a newish custom build support: place it here before -upstreaming into [`nixpkgs:./pkgs/build-support`][nixpkgs-pkgs-build-support]. - -- you want to reutilize certain module configuration functions or helpers: -place them into `./lib` as if you would place them into [`nixpkgs:./nixos/lib`][nixpkgs-nixos-lib]. - -Once your library grows, we recoomend you start organizing them into subfolders -analogous `nixpkgs`: - -| `nixpkgs` | `devos` | -| ---------------------- | ------------------ | -| `./lib` | `./lib` | -| `./pkgs/pkgs-lib` | `./lib/pkgs-lib` | -| `./nixos/lib` | `./lib/nixos-lib` | -| `./pkgs/build-support` | `./lib/pkgs-build` | - - -## Example -lib/nixos-lib/mkCustomI3BindSym/default.nix: -```nix -{ pkgs, writers, ... }: -{ name, cmd, workspace, baseKey }: -let - isWorkspaceEmpty = writers.writePython3 "is-workspace-empty" { - libraries = [ pkgs.python3Packages.i3ipc ]; - } (builtins.readFile ./is-workspace-empty.py); - - ws = builtins.toString workspace; -in -'' - - # ${name} - #bindsym ${baseKey}+${ws} workspace ${ws}; exec ${cmd} - bindsym ${baseKey}+${ws} workspace ${ws}; exec bash -c "${isWorkspaceEmpty} && ${cmd}" -'' -``` - -lib/nixos-lib/mkCustomI3BindSym/is-workspace-empty.py: -```python -# returns 0/1 if current workspace is empty/non-empty - -import i3ipc - -i3 = i3ipc.Connection() -tree = i3.get_tree() - - -def current_workspace(): - return tree.find_focused().workspace() - - -if current_workspace().leaves(): - print("Error current workspace is not empty") - exit(1) -exit(0) -``` - -lib/default.nix: -```nix -{ nixos, pkgs, ... }: -# ... -{ - # ... - mkCustomI3BindSym = pkgs.callPackage ./nixos-lib/mkCustomI3BindSym { }; -} -``` - -[nixpkgs-lib]: https://github.com/NixOS/nixpkgs/tree/master/lib -[nixpkgs-pkgs-lib]: https://github.com/NixOS/nixpkgs/tree/master/pkgs/pkgs-lib -[nixpkgs-pkgs-build-support]: https://github.com/NixOS/nixpkgs/tree/master/pkgs/build-support -[nixpkgs-nixos-lib]: https://github.com/NixOS/nixpkgs/tree/master/nixos/lib diff --git a/doc/mkFlakeOptions.md b/doc/mkFlakeOptions.md index 90719ba..dbc7abc 100644 --- a/doc/mkFlakeOptions.md +++ b/doc/mkFlakeOptions.md @@ -40,7 +40,7 @@ nix flake *_Default_* ``` -"inputs." +"self.inputs." ``` @@ -81,6 +81,56 @@ attribute set or path convertible to it +## devshell +Modules to include in your devos shell. the `modules` argument +will be exported under the `devshellModules` output + + +*_Type_*: +submodule + + +*_Default_* +``` +{} +``` + + + + +## devshell.externalModules +modules to include that won't be exported +meant importing modules from external flakes + + +*_Type_*: +list of valid module or path convertible to its or anything convertible to it + + +*_Default_* +``` +[] +``` + + + + +## devshell.modules +modules to include in all hosts and export to devshellModules output + + +*_Type_*: +list of path to a modules or anything convertible to it or path convertible to it + + +*_Default_* +``` +[] +``` + + + + ## home hosts, modules, suites, and profiles for home-manager @@ -103,7 +153,7 @@ meant importing modules from external flakes *_Type_*: -list of valid module or path convertible to its +list of valid module or path convertible to its or anything convertible to it *_Default_* @@ -114,6 +164,34 @@ list of valid module or path convertible to its +## home.importables +Packages of paths to be passed to modules as `specialArgs`. + + +*_Type_*: +attribute set + + +*_Default_* +``` +{} +``` + + + + +## home.importables.suites +collections of profiles + + +*_Type_*: +attribute set of list of paths or anything convertible to its + + + + + + ## home.modules modules to include in all hosts and export to homeModules output @@ -131,10 +209,17 @@ list of path to a modules or anything convertible to it or path convertible to i ## home.profiles -profile folders that can be collected into suites -the name of the argument passed to suites is based -on the folder name. -[ ./profiles ] => { profiles }: +WARNING: The 'suites' and `profiles` options have been deprecated, you can now create +both with the importables option. `rakeLeaves` can be used to create profiles and +by passing a module or `rec` set to `importables`, suites can access profiles. +Example: +``` +importables = rec { + profiles = digga.lib.importers.rakeLeaves ./profiles; + suites = with profiles; { }; +} +``` +See https://github.com/divnix/digga/pull/30 for more details *_Type_*: @@ -150,31 +235,23 @@ list of paths ## home.suites -Function that takes profiles and returns suites for this config system -These can be accessed through the 'suites' special argument. +WARNING: The 'suites' and `profiles` options have been deprecated, you can now create +both with the importables option. `rakeLeaves` can be used to create profiles and +by passing a module or `rec` set to `importables`, suites can access profiles. +Example: +``` +importables = rec { + profiles = digga.lib.importers.rakeLeaves ./profiles; + suites = with profiles; { }; +} +``` +See https://github.com/divnix/digga/pull/30 for more details *_Type_*: function that evaluates to a(n) attrs or path convertible to it -*_Default_* -``` -"" -``` - - - - -## inputs -inputs for this flake -used to set channel defaults and create registry - - -*_Type_*: -attribute set of nix flakes - - @@ -236,7 +313,7 @@ meant importing modules from external flakes *_Type_*: -list of valid module or path convertible to its +list of valid module or path convertible to its or anything convertible to it *_Default_* @@ -343,11 +420,46 @@ null +## nixos.importables +Packages of paths to be passed to modules as `specialArgs`. + + +*_Type_*: +attribute set + + +*_Default_* +``` +{} +``` + + + + +## nixos.importables.suites +collections of profiles + + +*_Type_*: +attribute set of list of paths or anything convertible to its + + + + + + ## nixos.profiles -profile folders that can be collected into suites -the name of the argument passed to suites is based -on the folder name. -[ ./profiles ] => { profiles }: +WARNING: The 'suites' and `profiles` options have been deprecated, you can now create +both with the importables option. `rakeLeaves` can be used to create profiles and +by passing a module or `rec` set to `importables`, suites can access profiles. +Example: +``` +importables = rec { + profiles = digga.lib.importers.rakeLeaves ./profiles; + suites = with profiles; { }; +} +``` +See https://github.com/divnix/digga/pull/30 for more details *_Type_*: @@ -363,17 +475,39 @@ list of paths ## nixos.suites -Function that takes profiles and returns suites for this config system -These can be accessed through the 'suites' special argument. +WARNING: The 'suites' and `profiles` options have been deprecated, you can now create +both with the importables option. `rakeLeaves` can be used to create profiles and +by passing a module or `rec` set to `importables`, suites can access profiles. +Example: +``` +importables = rec { + profiles = digga.lib.importers.rakeLeaves ./profiles; + suites = with profiles; { }; +} +``` +See https://github.com/divnix/digga/pull/30 for more details *_Type_*: function that evaluates to a(n) attrs or path convertible to it + + + + +## outputsBuilder +builder for flake system-spaced outputs +The builder gets passed an attrset of all channels + + +*_Type_*: +function that evaluates to a(n) attrs + + *_Default_* ``` -"" +"channels: { }" ``` diff --git a/doc/outputs/pkgs.md b/doc/outputs/pkgs.md index 99684b5..58ce52b 100644 --- a/doc/outputs/pkgs.md +++ b/doc/outputs/pkgs.md @@ -7,8 +7,7 @@ The only minor difference is that, instead of adding the `callPackage` call to `all-packages.nix`, you just add it the the _default.nix_ in this directory, which is defined as a simple overlay. -This overlay is set as the default `overlay` output attribute for the flake. -And all the packages are exported via `packages..`, for all +All the packages are exported via `packages..`, for all the supported systems listed in the package's `meta.platforms` attribute. And, as usual, every package in the overlay is also available to any NixOS diff --git a/doc/tests.md b/doc/tests.md index f6fd7fe..1d7b65e 100644 --- a/doc/tests.md +++ b/doc/tests.md @@ -5,22 +5,19 @@ NixOS offers some incredibly powerful tools to write tests for your configuration, and, optionally, run them in [CI](./integrations/hercules.md). -## Lib Tests -You can easily write tests for your own library functions in the -lib/___tests/lib.nix___ file and they will be run on every `nix flake check` or -during a CI run. - ## Unit Tests -Unit tests are can be created from regular derivations, and they can do +Unit tests can be created from regular derivations, and they can do almost anything you can imagine. By convention, it is best to test your packages during their [check phase][check]. All packages and their tests will be built during CI. ## Integration Tests +All your profiles defined in suites will be tested in a NixOS VM. + You can write integration tests for one or more NixOS VMs that can, optionally, be networked together, and yes, it's as awesome as it sounds! -Be sure to use the `mkTest` function, in the [___tests/default.nix___][default] +Be sure to use the `mkTest` function from digga, `digga.lib.pkgs-lib.mkTest` which wraps the official [testing-python][testing-python] function to ensure that the system is setup exactly as it is for a bare DevOS system. There are already great resources for learning how to use these tests effectively,