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 # External Art
When you need to use a module, overlay, or pass a value from one of your inputs 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 ## Overlays
used to extend the arguments passed to all NixOS modules, allowing for External overlays can directly be added to a channel's `overlays` list.
arbitrary values to be passed from flake inputs to the rest of your
configuration.
## Home Manager
There is also an `hmModules` attribute set for pulling home-manager modules in
from the outside world:
### Declare:
flake.nix: flake.nix:
```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 ```nix
with inputs;
{ {
hmModules = { nixos.hostDefaults.externalModules = [ inputs.agenix.nixosModules.age ];
doom-emacs = doom-emacs.hmModule;
};
} }
``` ```
### Use: ## Home Manager
users/nixos/default.nix: Since there isn't a `hosts` concept for home-manager, externalModules is just a
top-level argument in the `home` namespace.
flake.nix:
```nix ```nix
{ hmModules, ... }:
{ {
home-manager.users.nixos = { home.externalModules = [ doom-emacs = doom-emacs.hmModule ];
imports = [ hmModules.doom-emacs ] ;
programs.doom-emacs.enable = true;
};
} }
``` ```
[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 # Hosts
Nix flakes contain an output called `nixosConfigurations` declaring an Nix flakes contain an output called `nixosConfigurations` declaring an
attribute set of valid NixOS systems. To simplify the management and creation attribute set of valid NixOS systems. To create hosts, you can use the
of these hosts, devos automatically imports every _.nix_ file inside this `nixos.hosts` argument and pass `modules` to each host. Host-specific modules
directory to the mentioned attribute set, applying the projects defaults to typically go in the `hosts` folder of the template.
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 Each host should follow a certain channel to define the `pkgs` of that host.
output `nixosConfigurations.system`. You can have as many hosts as you want You can use the `nixos.hostDefaults` to set defaults and global modules for all
and all of them will be automatically imported based on their name. hosts.
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 name of the host. This is for convenience, since `nixos-rebuild`
convenience, since `nixos-rebuild` automatically searches for a configuration automatically searches for a configuration matching the current systems hostname
matching the current systems hostname if one is not specified explicitly. if one is not specified explicitly.
It is recommended that the host modules only contain configuration information It is recommended that the host modules only contain configuration information
specific to a particular piece of hardware. Anything reusable across machines 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), This is a good place to import sets of profiles, called [suites](./suites.md),
that you intend to use on your machine. that you intend to use on your machine.
Additionally, this is the perfect place to import anything you might need from Additionally, you can pass modules from [nixos-hardware][nixos-hardware] in the
the [nixos-hardware][nixos-hardware] repository. `modules` argument for relevant hosts.
> ##### _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.
## Example ## 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 [nixos-hardware]: https://github.com/NixOS/nixos-hardware

View file

@ -1,47 +1,39 @@
# Overrides # Overrides
By default, the NixOS systems are based on unstable. While it is trivial to Each NixOS host follows one channel. But many times it is useful to get packages
change this to a stable release, or any other branch of nixpkgs by or modules from different channels.
changing the flake url, sometimes all we want is a single package from another
branch.
This is what the overrides are for. By default, they are pulled directly from This is what the overrides are for. You can make use of the `overrides.nix` to
nixpkgs/master, but you can change the `override` flake input url to override specific packages to be pulled from other channels. Any overlay may get
nixos-unstable, or even a specific sha revision. `channels` as their first argument.
They are defined in the `extern/overrides.nix` file.
## Example ## Example
### Packages ### Packages
The override packages are defined as a regular overlay with an extra arguement 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 ```nix
{ channels: final: prev: {
packages = pkgs: final: prev: { inherit (pkgs.latest) manix;
inherit (pkgs) manix;
};
} }
``` ```
### Modules ### Modules
You can also pull modules from override. Simply specify their path relative to You can also pull modules from other channels. All modules have access to the
the nixpkgs [modules][nixpkgs-modules] directory. The old version will be added `modulesPath` for each channel as `<channelName>ModulesPath`. And you can use
to `disabledModules` and the new version imported into the configuration. `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 ```nix
{ { latestModulesPath }: {
modules = [ "programs/zsh/zsh.nix" ]; modules = [ "${latestModulesPath}/programs/zsh/zsh.nix" ];
disabledModules = [ "programs/zsh/zsh.nix" ];
} }
``` ```
> ##### _Note:_ > ##### _Note:_
> Sometimes a modules name will change from one branch to another. This is what > Sometimes a modules name will change from one branch to another.
> 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.
[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules [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 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. 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 ## Definition
```nix ```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 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 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 `packages.<system>.<pkgName>` (for valid systems), so all you have to do is
write it. 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 This will make a new file `hosts/up-$(hostname).nix`, which you can edit to
your liking. 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 Make sure your `i18n.defaultLocale` and `time.timeZone` are set properly for
your region. Keep in mind that `networking.hostName` with be automatically 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 set to the name of your host;
hostname `my-host`.
Now might be a good time to read the docs on [suites](../concepts/suites.md) and 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. [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 ## Lib Tests
You can easily write tests for your own library functions in the 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. during a CI run.
## Unit Tests ## Unit Tests