update doc to match new template format and logic

This commit is contained in:
Pacman99 2021-04-26 18:29:05 -07:00
parent 2a7d9e7109
commit ffe4836e35
7 changed files with 80 additions and 71 deletions

View File

@ -1,45 +1,42 @@
# External Art
When you need to use a module, overlay, or pass a value from one of your inputs
to the rest of your NixOS configuration, [extern][extern] is where you do it.
to the rest of your NixOS configuration, you can make use of a couple arguments.
It is encouraged to add external art directly in your `flake.nix` so the file
represents a complete dependency overview of your flake.
Modules and overlays are self explanatory, and the `specialArgs` attribute is
used to extend the arguments passed to all NixOS modules, allowing for
arbitrary values to be passed from flake inputs to the rest of your
configuration.
## Overlays
External overlays can directly be added to a channel's `overlays` list.
## Home Manager
There is also an `hmModules` attribute set for pulling home-manager modules in
from the outside world:
### Declare:
flake.nix:
```nix
{
inputs.doom-emacs.url = "github:vlaci/nix-doom-emacs";
channels.nixos.overlays = [ inputs.agenix.overlay ];
}
```
These overlays will be automatically filtered by inspecting the `inputs` argument.
extern/default.nix:
## Modules
There is a dedicated `nixos.hostDefaults.externalModules` argument for external
modules.
flake.nix:
```nix
with inputs;
{
hmModules = {
doom-emacs = doom-emacs.hmModule;
};
nixos.hostDefaults.externalModules = [ inputs.agenix.nixosModules.age ];
}
```
### Use:
users/nixos/default.nix:
## Home Manager
Since there isn't a `hosts` concept for home-manager, externalModules is just a
top-level argument in the `home` namespace.
flake.nix:
```nix
{ hmModules, ... }:
{
home-manager.users.nixos = {
imports = [ hmModules.doom-emacs ] ;
programs.doom-emacs.enable = true;
};
home.externalModules = [ doom-emacs = doom-emacs.hmModule ];
}
```
[extern]: https://github.com/divnix/devos/tree/core/extern/default.nix
> ##### Note:
> The optimal solution would be to automatically export modules that were created in
> your flake. But this is not possible due to NixOS/nix#4740.

View File

@ -1,19 +1,18 @@
# Hosts
Nix flakes contain an output called `nixosConfigurations` declaring an
attribute set of valid NixOS systems. To simplify the management and creation
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.
attribute set of valid NixOS systems. To create hosts, you can use the
`nixos.hosts` argument and pass `modules` to each host. Host-specific modules
typically go in the `hosts` folder of the template.
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.
Each host should follow a certain channel to define the `pkgs` of that host.
You can use the `nixos.hostDefaults` to set defaults and global modules for all
hosts.
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
matching the current systems hostname if one is not specified explicitly.
attribute to the name of the host. This is for convenience, since `nixos-rebuild`
automatically searches for a configuration matching the current systems hostname
if one is not specified explicitly.
It is recommended that the host modules only contain configuration information
specific to a particular piece of hardware. Anything reusable across machines
@ -22,12 +21,8 @@ is best saved for [profile modules](./profiles.md).
This is a good place to import sets of profiles, called [suites](./suites.md),
that you intend to use on your machine.
Additionally, this is the perfect place to import anything you might need from
the [nixos-hardware][nixos-hardware] repository.
> ##### _Note:_
> Set `nixpkgs.system` to the architecture of this host, default is "x86_64-linux".
> Keep in mind that not all packages are available for all architectures.
Additionally, you can pass modules from [nixos-hardware][nixos-hardware] in the
`modules` argument for relevant hosts.
## Example
@ -44,4 +39,15 @@ hosts/librem.nix:
}
```
flake.nix
```nix
{
nixos.hosts.librem = {
system = "aarch64-linux";
modules = ./hosts/librem.nix;
};
}
```
[nixos-hardware]: https://github.com/NixOS/nixos-hardware

View File

@ -1,47 +1,39 @@
# Overrides
By default, the NixOS systems are based on unstable. While it is trivial to
change this to a stable release, or any other branch of nixpkgs by
changing the flake url, sometimes all we want is a single package from another
branch.
Each NixOS host follows one channel. But many times it is useful to get packages
or modules from different channels.
This is what the overrides are for. By default, they are pulled directly from
nixpkgs/master, but you can change the `override` flake input url to
nixos-unstable, or even a specific sha revision.
They are defined in the `extern/overrides.nix` file.
This is what the overrides are for. You can make use of the `overrides.nix` to
override specific packages to be pulled from other channels. Any overlay may get
`channels` as their first argument.
## Example
### Packages
The override packages are defined as a regular overlay with an extra arguement
`pkgs`. This refers to the packages built from the `override` flake.
`channels`. This refers to all channels defined in `flake.nix`.
Pulling the manix package from the override flake:
Pulling the manix package from the latest flake:
```nix
{
packages = pkgs: final: prev: {
inherit (pkgs) manix;
};
channels: final: prev: {
inherit (pkgs.latest) manix;
}
```
### Modules
You can also pull modules from override. Simply specify their path relative to
the nixpkgs [modules][nixpkgs-modules] directory. The old version will be added
to `disabledModules` and the new version imported into the configuration.
You can also pull modules from other channels. All modules have access to the
`modulesPath` for each channel as `<channelName>ModulesPath`. And you can use
`disabledModules` to remove modules from the current channel.
Pulling the zsh module from the override flake:
Pulling the zsh module from the latest flake:
```nix
{
modules = [ "programs/zsh/zsh.nix" ];
{ latestModulesPath }: {
modules = [ "${latestModulesPath}/programs/zsh/zsh.nix" ];
disabledModules = [ "programs/zsh/zsh.nix" ];
}
```
> ##### _Note:_
> Sometimes a modules name will change from one branch to another. This is what
> the `disabledModules` list is for. If the module name changes, the old
> version will not automatically be disabled, so simply put it's old name in
> this list to disable it.
> Sometimes a modules name will change from one branch to another.
[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules

View File

@ -6,7 +6,13 @@ profiles. For good examples, check out the suites defined in the community
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.
They are defined in `profiles/suites.nix`.
They are defined with the `suites` argument in either `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

View File

@ -4,7 +4,7 @@ we want to keep the process as simple and straightforward as possible.
Any _.nix_ files declared in this directory will be assumed to be a valid
overlay, and will be automatically imported into all [hosts](../concepts/hosts.md), and
exported via `overlays.<file-basename>` _as well as_
exported via `overlays.<channel>/<pkgName>` _as well as_
`packages.<system>.<pkgName>` (for valid systems), so all you have to do is
write it.

View File

@ -10,10 +10,18 @@ flk up
This will make a new file `hosts/up-$(hostname).nix`, which you can edit to
your liking.
You must then add a host to `nixos.hosts` in flake.nix:
```nix
{
nixos.hosts = {
modules = hosts/NixOS.nix;
};
}
```
Make sure your `i18n.defaultLocale` and `time.timeZone` are set properly for
your region. Keep in mind that `networking.hostName` with be automatically
set to the filename of your hosts file, so `hosts/my-host.nix` will have the
hostname `my-host`.
set to the name of your host;
Now might be a good time to read the docs on [suites](../concepts/suites.md) and
[profiles](../concepts/profiles.md) and add or create any that you need.

View File

@ -7,7 +7,7 @@ configuration, and, optionally, run them in
## Lib Tests
You can easily write tests for your own library functions in the
___tests/lib.nix___ file and they will be run on every `nix flake check` or
lib/___tests/lib.nix___ file and they will be run on every `nix flake check` or
during a CI run.
## Unit Tests