Merge pull request #304 from Pacman99/update-docs
docs: general updates
This commit is contained in:
Pacman99
GitHub
commit
fb41643ed6
9 changed files with 227 additions and 170 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
87
doc/lib.md
87
doc/lib.md
|
|
@ -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
|
||||
|
|
@ -40,7 +40,7 @@ nix flake
|
|||
|
||||
*_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
|
||||
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_*
|
||||
```
|
||||
"<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_*:
|
||||
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_*
|
||||
```
|
||||
"<function>"
|
||||
"channels: { }"
|
||||
```
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.<system>.<pkg-name>`, for all
|
||||
All the packages are exported via `packages.<system>.<pkg-name>`, 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
|
||||
|
|
|
|||
11
doc/tests.md
11
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,
|
||||
|
|
|
|||
Loading…
Reference in a new issue