update doc to match new template format and logic
This commit is contained in:
parent
2a7d9e7109
commit
ffe4836e35
7 changed files with 80 additions and 71 deletions
|
@ -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.
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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
|
||||||
|
|
Loading…
Reference in a new issue