update doc to match new template format and logic
This commit is contained in:
Pacman99
parent
2a7d9e7109
commit
ffe4836e35
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user