From ffe4836e35e8b4a1ef2d99292c1ea4a3df6ad821 Mon Sep 17 00:00:00 2001 From: Pacman99 Date: Mon, 26 Apr 2021 18:29:05 -0700 Subject: [PATCH] update doc to match new template format and logic --- doc/concepts/extern.md | 47 ++++++++++++++++++--------------------- doc/concepts/hosts.md | 38 ++++++++++++++++++------------- doc/concepts/overrides.md | 42 ++++++++++++++-------------------- doc/concepts/suites.md | 8 ++++++- doc/outputs/overlays.md | 2 +- doc/start/from-nixos.md | 12 ++++++++-- doc/tests.md | 2 +- 7 files changed, 80 insertions(+), 71 deletions(-) diff --git a/doc/concepts/extern.md b/doc/concepts/extern.md index 3b26912..171d8c5 100644 --- a/doc/concepts/extern.md +++ b/doc/concepts/extern.md @@ -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. diff --git a/doc/concepts/hosts.md b/doc/concepts/hosts.md index 0a74dd1..770fa51 100644 --- a/doc/concepts/hosts.md +++ b/doc/concepts/hosts.md @@ -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 diff --git a/doc/concepts/overrides.md b/doc/concepts/overrides.md index 28194cd..78b50fd 100644 --- a/doc/concepts/overrides.md +++ b/doc/concepts/overrides.md @@ -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 `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 diff --git a/doc/concepts/suites.md b/doc/concepts/suites.md index e6a8bff..5c0d590 100644 --- a/doc/concepts/suites.md +++ b/doc/concepts/suites.md @@ -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 diff --git a/doc/outputs/overlays.md b/doc/outputs/overlays.md index d71b459..f463d1a 100644 --- a/doc/outputs/overlays.md +++ b/doc/outputs/overlays.md @@ -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.` _as well as_ +exported via `overlays./` _as well as_ `packages..` (for valid systems), so all you have to do is write it. diff --git a/doc/start/from-nixos.md b/doc/start/from-nixos.md index bbb0e55..9b0b3f5 100644 --- a/doc/start/from-nixos.md +++ b/doc/start/from-nixos.md @@ -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. diff --git a/doc/tests.md b/doc/tests.md index 033d75a..f6fd7fe 100644 --- a/doc/tests.md +++ b/doc/tests.md @@ -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