Merge #276

276: Update core r=blaggacao a=Pacman99 Core is starting to get pretty stale. All the changes in `develop` are pretty stable and I think we should encourage updating to them. As most future updates can be done through [devlib](https://github.com/divnix/devlib), so once you switch to this version of the template. Updating to new changes will be much simpler (ie #91). Co-authored-by: Pacman99 <[email protected]> Co-authored-by: Pacman99 <[email protected]> Co-authored-by: David Arnold <[email protected]>
divnix · May 15, 2021 · 4df3d8c · 4df3d8c
2 parents 82b73cf + 2f474e3
commit 4df3d8c
Show file tree

Hide file tree

Showing 51 changed files with 821 additions and 1,362 deletions.
diff --git 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 ];
 }
 ```
+Upon exporting overlays, these overlays will be automatically filtered out 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:
+> To avoid declaring "external" modules separately, which is obvious since they come from `inputs`, 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
@@ -15,27 +15,41 @@ 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.
 
+You can set channels, systems, and add extra modules to each host by editing the
+`nixos.hosts` argument in flake.nix. This is the perfect place to import
+host specific modules from external sources, such as the
+[nixos-hardware][nixos-hardware] repository.
+
 It is recommended that the host modules only contain configuration information
 specific to a particular piece of hardware. Anything reusable across machines
 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.
 
 ## Example
 
+flake.nix:
+```nix
+{
+  nixos.hosts = mkMerge [
+    (devos.lib.importHosts ./hosts)
+    {
+      librem = {
+        channelName = "latest";
+        modules = [ hardware.purism-librem-13v3 ];
+      };
+    }
+  ];
+}
+```
+
 hosts/librem.nix:
 ```nix
-{ suites, hardware, ... }:
+{ suites, ... }:
 {
-  imports = suites.laptop ++ [ hardware.purism-librem-13v3 ];
+  imports = suites.laptop;
 
   boot.loader.systemd-boot.enable = true;
   boot.loader.efi.canTouchEfiVariables = true;

diff --git a/doc/concepts/overrides.md b/doc/concepts/overrides.md
@@ -1,47 +1,41 @@
 # 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.
+## Packages
+You can make use of `overlays/overrides.nix` to override specific packages in the
+default channel to be pulled from other channels. That file is simply an example
+of how any overlay can get `channels` as their first argument.
 
-They are defined in the `extern/overrides.nix` file.
+You can add overlays to any channel to override packages from other channels.
 
-## 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.
-
-Pulling the manix package from the override flake:
+Pulling the manix package from the `latest` channel:
 ```nix
-{
-  packages = pkgs: final: prev: {
-    inherit (pkgs) manix;
-  };
+channels: final: prev: {
+  __dontExport = true;
+  inherit (pkgs.latest) manix;
 }
 ```
 
-### Modules
+It is recommended to set the `__dontExport` property for override specific
+overlays. `overlays/overrides.nix` is the best place to consolidate all package
+overrides and the property is already set for you.
+
+## 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` channel:
 ```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
@@ -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/lib.md b/doc/lib.md
@@ -3,8 +3,7 @@ The lib directory mirrors the upstream concepts of [`nixpkgs:./lib`][nixpkgs-lib
 [`nixpkgs:./nixos/lib`][nixpkgs-nixos-lib] and [`nixpkgs:./pkgs/pkgs-lib`][nixpkgs-pkgs-lib],
 but also occasionally [`nixpkgs:./pkgs/build-support`][nixpkgs-pkgs-build-support].
 
-It comes with functions necesary to declutter `devos` itself, but you are
-welcome to extend it to your needs.
+All functions defined in lib can be accessed in modules and packages as `ourlib`.
 
 For example: