Merge pull request #304 from Pacman99/update-docs

docs: general updates
This commit is contained in:
Pacman99 2021-06-05 10:13:06 -07:00 committed by GitHub
commit fb41643ed6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 227 additions and 170 deletions

View file

@ -1,5 +1,8 @@
# Pull Requests # 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 relevant docs. Each directory contains its own README.md, which will
automatically be pulled into the [mdbook](https://devos.divnix.com). The book is 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. rendered on every change, so the docs should always be up to date.

View file

@ -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 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. 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 As an example, a file `hosts/system.nix` or `hosts/system/default.nix` will
output `nixosConfigurations.system`. You can have as many hosts as you want be available via the flake output `nixosConfigurations.system`. You can have
and all of them will be automatically imported based on their name. 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` For each host, the configuration automatically sets the `networking.hostName`
attribute to the name of the file minus the _.nix_ extension. This is for attribute to the folder name or name of the file minus the _.nix_ extension. This
convenience, since `nixos-rebuild` automatically searches for a configuration is for convenience, since `nixos-rebuild` automatically searches for a configuration
matching the current systems hostname if one is not specified explicitly. 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 You can set channels, systems, and add extra modules to each host by editing the

View file

@ -8,34 +8,29 @@ separation of concerns.
If you need guidance, a community [branch](https://github.com/divnix/devos/tree/community/profiles) 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. is maintained to help get up to speed on their usage.
## Constraints ## Creation
For the sake of consistency, a profile should always be defined in a Profiles are created with the `rakeLeaves` function which recursively collects
___default.nix___ containing a [nixos module config][config]. `.nix` files from within a folder. The recursion stops at folders with a `default.nix`
A profile's directory is used for quick modularization of in them. You end up with an attribute set with leaves(paths to profiles) or
[interelated bits](./profiles.md#subprofiles). nodes(attrsets leading to more nodes or leaves).
A profile is used for quick modularization of [interelated bits](./profiles.md#subprofiles).
> ##### _Notes:_ > ##### _Notes:_
> * For _declaring_ module options, there's the [modules](../outputs/modules.md) directory. > * For _declaring_ module options, there's the [modules](../outputs/modules.md) directory.
> * This directory takes inspiration from > * This directory takes inspiration from
> [upstream](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules/profiles) > [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 ### Nested profiles
Profiles can also define subprofiles. They follow the same constraints outlined Profiles can be nested in attribute sets due to the recursive nature of `rakeLeaves`.
above. A good top level profile should be a high level concern, such as your This can be useful to have a set of profiles created for a specific purpose. It is
personal development environment while the subprofiles should be more focused sometimes useful to have a `common` profile that has high level concerns related
program configurations such as your text editor, and shell configs. This way, to all its sister profiles.
you can either pull in the whole development profile, or pick and choose
individual programs.
### Example ### Example
profiles/develop/default.nix: profiles/develop/common.nix:
```nix ```nix
{ {
imports = [ ./zsh ]; imports = [ ./zsh ];
@ -43,7 +38,7 @@ profiles/develop/default.nix:
} }
``` ```
profiles/develop/zsh/default.nix: profiles/develop/zsh.nix:
```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 ## Conclusion
Profiles are the most important concept in DevOS. They allow us to keep our 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 Nix expressions self contained and modular. This way we can maximize reuse

View file

@ -1,19 +1,13 @@
# Suites # Suites
Suites provide a mechanism for users to easily combine and name collecitons of 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 profiles. For good examples, check out the suites defined in the community branch.
[branch](https://github.com/divnix/devos/blob/community/suites/default.nix).
In the future, we will use suites as a mechanism for deploying various machine `suites` are a special case of an `importable` which get passed as a special
types which don't depend on hardware, such as vm's and containers. 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. 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 ## Definition
```nix ```nix
rec { rec {

View file

@ -23,11 +23,23 @@ your users. For a fully fleshed out example, check out the developers personal
``` ```
## Home Manager ## 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 All modules defined in [user modules][modules-list] will be imported to
Home Manager. All profiles are availabe in [suites][suites] as userProfiles. Home Manager.
The `userSuites` output will be available in your Home Manager Configuration as User profiles can be collected in a similar fashion as system ones into a `suites`
the special argument, `suites`. argument that gets passed to your home-manager users.
### Example
```nix
{
home-manager.users.nixos = { suites, ... }: {
imports = suites.base;
};
}
```
## External Usage ## External Usage
You can easily use the defined home-manager configurations outside of NixOS 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 [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/users/modules/module-list.nix
[modules-list]: https://github.com/divnix/devos/tree/core/modules/module-list.nix

View file

@ -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

View file

@ -40,7 +40,7 @@ nix flake
*_Default_* *_Default_*
``` ```
"inputs.<name>" "self.inputs.<name>"
``` ```
@ -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 ## home
hosts, modules, suites, and profiles for home-manager hosts, modules, suites, and profiles for home-manager
@ -103,7 +153,7 @@ meant importing modules from external flakes
*_Type_*: *_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_* *_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 ## home.modules
modules to include in all hosts and export to homeModules output 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 ## home.profiles
profile folders that can be collected into suites WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
the name of the argument passed to suites is based both with the importables option. `rakeLeaves` can be used to create profiles and
on the folder name. by passing a module or `rec` set to `importables`, suites can access profiles.
[ ./profiles ] => { 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_*: *_Type_*:
@ -150,31 +235,23 @@ list of paths
## home.suites ## home.suites
Function that takes profiles and returns suites for this config system WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
These can be accessed through the 'suites' special argument. 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_*: *_Type_*:
function that evaluates to a(n) attrs or path convertible to it function that evaluates to a(n) attrs or path convertible to it
*_Default_*
```
"<function>"
```
## 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_*: *_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_* *_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 ## nixos.profiles
profile folders that can be collected into suites WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
the name of the argument passed to suites is based both with the importables option. `rakeLeaves` can be used to create profiles and
on the folder name. by passing a module or `rec` set to `importables`, suites can access profiles.
[ ./profiles ] => { 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_*: *_Type_*:
@ -363,17 +475,39 @@ list of paths
## nixos.suites ## nixos.suites
Function that takes profiles and returns suites for this config system WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
These can be accessed through the 'suites' special argument. 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_*: *_Type_*:
function that evaluates to a(n) attrs or path convertible to it 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_* *_Default_*
``` ```
"<function>" "channels: { }"
``` ```

View file

@ -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, `all-packages.nix`, you just add it the the _default.nix_ in this directory,
which is defined as a simple overlay. which is defined as a simple overlay.
This overlay is set as the default `overlay` output attribute for the flake. All the packages are exported via `packages.<system>.<pkg-name>`, for all
And all the packages are exported via `packages.<system>.<pkg-name>`, for all
the supported systems listed in the package's `meta.platforms` attribute. 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 And, as usual, every package in the overlay is also available to any NixOS

View file

@ -5,22 +5,19 @@ NixOS offers some incredibly powerful tools to write tests for your
configuration, and, optionally, run them in configuration, and, optionally, run them in
[CI](./integrations/hercules.md). [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
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 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 packages during their [check phase][check]. All packages and their tests will
be built during CI. be built during CI.
## Integration Tests ## 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, 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! 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 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 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, already great resources for learning how to use these tests effectively,