init

README.md

···
+# Easy Hosts
+
+This is a nix flake module, this means that it is intended to be used alongside [flake-parts](https://flake.parts).
+
+You can find some examples of how to use this module in the [examples](./examples) directory.
+
+## Why use this?
+
+We provide you with the following attributes `self'` and `inputs'` that can be used to make your configuration shorter going from writing `inputs.input-name.packages.${pkgs.system}.package-name` to `inputs'.input-name.packages.package-name`.
+
+We also can auto construct your hosts based on your file structure. Whilst providing you with a nice api which will allow you to add more settings to your hosts at a later date or consume another flake-module that can work alongside this flake.
+
+## Explaination of the module
+
+- `easyHosts.autoConstruct`: If set to true, the module will automatically construct the hosts for you from the directory structure of `easyHosts.path`.
+
+- `easyHosts.path`: The directory to where the hosts are stored, this *must* be set.
+
+- `easyHosts.onlySystem`: If you only have 1 system type like `aarch64-darwin` then you can use this setting to prevent nesting your directories.
+
+- `easyHosts.shared`: The shared options for all the hosts.
+  - `modules`: A list of modules that will be included in all the hosts.
+  - `specialArgs`: A list of special arguments that will be passed to all the hosts.
+
+- `easyHosts.perClass`: This provides you with the `class` argument such that you can specify what classes get which modules.
+  - `modules`: A list of modules that will be included in all the hosts of the given class.
+  - `specialArgs`: A list of special arguments that will be passed to all the hosts of the given class.
+
+- `easyHosts.hosts.<host>`: The options for the given host.
+  - `path`: the path to the host, this is not strictly needed if you have a flat directory called `hosts` or `systems`.
+  - `arch`: The architecture of the host.
+  - `modules`: A list of modules that will be included in the host.
+  - `class`: the class of the host, this can be one of [ "nixos", "darwin", "iso" ].
+  - `specialArgs`: A list of special arguments that will be passed to the host.
+  - `deployable`: this was added for people who may want to consume a deploy-rs or colonma flakeModule.
+
+## Similar projects
+
+- [ez-configs](https://github.com/ehllie/ez-configs)
+
+## Real world examples
+
+- [isabelroses/dotfiles](https://github.com/isabelroses/dotfiles)

examples/multi-specialised/flake.lock

···
+{
+  "nodes": {
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1735774679,
+        "narHash": "sha256-soePLBazJk0qQdDVhdbM98vYdssfs3WFedcq+raipRI=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "f2f7418ce0ab4a5309a4596161d154cfc877af66",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1735471104,
+        "narHash": "sha256-0q9NGQySwDQc7RhAV2ukfnu7Gxa5/ybJ2ANT8DQrQrs=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "88195a94f390381c6afcdaa933c2f6ff93959cb4",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

examples/multi-specialised/flake.nix

···
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+    flake-parts = {
+      url = "github:hercules-ci/flake-parts";
+      inputs.nixpkgs-lib.follows = "nixpkgs";
+    };
+
+    easy-hosts.url = "github:isabelroses/easy-hosts";
+  };
+
+  outputs =
+    inputs:
+    inputs.flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [ inputs.easy-hosts.flakeModule ];
+
+      systems = [
+        "x86_64-linux"
+        "aarch64-darwin"
+      ];
+
+      easyHosts = {
+        autoConstruct = true;
+        path = ./hosts;
+
+        perClass = class: {
+          # only nixos systems will get this module
+          modules = inputs.nixpkgs.lib.optionals (class == "nixos") [
+            ./modules/nixos.nix
+          ];
+        };
+      };
+    };
+}

examples/multi-specialised/hosts/aarch64-darwin/default.nix

···
+{ }

examples/multi-specialised/hosts/x86_64-iso/test2/default.nix

···
+{ }

examples/multi-specialised/hosts/x86_64-nixos/test3/default.nix

···
+{ }

examples/multi-specialised/hosts/x86_64-nixos/test4/default.nix

···
+{ }

examples/multi-specialised/modules/nixos.nix

···
+{ }

examples/multi/flake.lock

···
+{
+  "nodes": {
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1735774679,
+        "narHash": "sha256-soePLBazJk0qQdDVhdbM98vYdssfs3WFedcq+raipRI=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "f2f7418ce0ab4a5309a4596161d154cfc877af66",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1735471104,
+        "narHash": "sha256-0q9NGQySwDQc7RhAV2ukfnu7Gxa5/ybJ2ANT8DQrQrs=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "88195a94f390381c6afcdaa933c2f6ff93959cb4",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

examples/multi/flake.nix

···
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+    flake-parts = {
+      url = "github:hercules-ci/flake-parts";
+      inputs.nixpkgs-lib.follows = "nixpkgs";
+    };
+
+    easy-hosts.url = "github:isabelroses/easy-hosts";
+  };
+
+  outputs =
+    inputs:
+    inputs.flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [ inputs.easy-hosts.flakeModule ];
+
+      systems = [ "x86_64-linux" ];
+
+      easyHosts = {
+        autoConstruct = true;
+        path = ./hosts;
+      };
+    };
+}

examples/multi/hosts/aarch64-darwin/test/default.nix

···
+{ }

examples/multi/hosts/aarch64-linux/test2/default.nix

···
+{ }

examples/multi/hosts/x86_64-linux/test3/default.nix

···
+{ }

examples/multi/hosts/x86_64-linux/test4/default.nix

···
+{ }

examples/not-auto/flake.nix

···
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+    flake-parts = {
+      url = "github:hercules-ci/flake-parts";
+      inputs.nixpkgs-lib.follows = "nixpkgs";
+    };
+
+    easy-hosts.url = "github:isabelroses/easy-hosts";
+  };
+
+  outputs =
+    inputs:
+    inputs.flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [ inputs.easy-hosts.flakeModule ];
+
+      systems = [
+        "x86_64-nixos"
+        "aarch64-darwin"
+      ];
+
+      easyHosts.hosts = {
+        test = {
+          arch = "x86_64";
+          class = "nixos";
+        };
+
+        test2 = {
+          arch = "x86_64";
+          class = "darwin";
+        };
+      };
+    };
+}

examples/not-auto/hosts/test/default.nix

···
+{ }

examples/not-auto/hosts/test2/default.nix

···
+{ }

examples/only/flake.nix

···
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+    flake-parts = {
+      url = "github:hercules-ci/flake-parts";
+      inputs.nixpkgs-lib.follows = "nixpkgs";
+    };
+
+    easy-hosts.url = "github:isabelroses/easy-hosts";
+  };
+
+  outputs =
+    inputs:
+    inputs.flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [ inputs.easy-hosts.flakeModule ];
+
+      systems = [ "aarch64-darwin" ];
+
+      easyHosts = {
+        autoConstruct = true;
+        path = ./hosts;
+        onlySystem = "aarch64-darwin";
+      };
+    };
+}

examples/only/hosts/test1/default.nix

···
+{ }

examples/only/hosts/test2/default.nix

···
+{ }

flake-module.nix

···
+{
+  lib,
+  inputs,
+  config,
+  withSystem,
+  ...
+}:
+let
+  inherit (lib.options) mkOption literalExpression;
+  inherit (lib) types;
+
+  inherit (import ./lib.nix { inherit lib inputs withSystem; })
+    constructSystem
+    mkHosts
+    buildHosts
+    ;
+
+  cfg = config.easyHosts;
+in
+{
+  options = {
+    easyHosts = {
+      autoConstruct = lib.mkEnableOption "Automatically construct hosts";
+
+      path = mkOption {
+        type = types.nullOr types.path;
+        default = null;
+        example = literalExpression "./hosts";
+      };
+
+      onlySystem = mkOption {
+        type = types.nullOr types.str;
+        default = null;
+        example = literalExpression "aarch64-darwin";
+      };
+
+      shared = {
+        modules = mkOption {
+          # we really expect a list of paths but i want to accept lists of lists of lists and so on
+          # since they will be flattened in the final function that applies the settings
+          type = types.listOf types.anything;
+          default = [ ];
+        };
+
+        specialArgs = mkOption {
+          type = types.attrs;
+          default = { };
+        };
+      };
+
+      perClass = mkOption {
+        default = _: {
+          modules = [ ];
+          specialArgs = { };
+        };
+
+        type = types.functionTo (
+          types.submodule {
+            options = {
+              modules = mkOption {
+                type = types.listOf types.anything;
+                default = [ ];
+              };
+
+              specialArgs = mkOption {
+                type = types.attrs;
+                default = { };
+              };
+            };
+          }
+        );
+      };
+
+      hosts = mkOption {
+        default = { };
+        type = types.attrsOf (
+          types.submodule (
+            { name, ... }:
+            let
+              self = cfg.hosts.${name};
+            in
+            {
+              options = {
+                arch = mkOption {
+                  type = types.str;
+                  default = "x86_64";
+                };
+
+                class = mkOption {
+                  type = types.str;
+                  default = "nixos";
+                };
+
+                system = mkOption {
+                  type = types.str;
+                  default = constructSystem self.class self.arch;
+                };
+
+                path = mkOption {
+                  type = types.nullOr types.path;
+                  default = null;
+                  example = literalExpression "./hosts/myhost";
+                };
+
+                deployable = mkOption {
+                  type = types.bool;
+                  default = false;
+                };
+
+                modules = mkOption {
+                  type = types.listOf types.anything;
+                  default = [ ];
+                };
+
+                specialArgs = mkOption {
+                  type = types.attrs;
+                  default = { };
+                };
+              };
+            }
+          )
+        );
+      };
+    };
+  };
+
+  config = {
+    # if the user has made it such that they want the hosts to be constructed automatically
+    # i.e. from the file paths then we will do that
+    easyHosts.hosts = lib.mkIf cfg.autoConstruct (buildHosts cfg);
+
+    flake = mkHosts cfg;
+  };
+}

flake.nix

···
+{
+  inputs = { };
+
+  outputs = _: {
+    flakeModule = ./flake-module.nix;
+
+    templates = {
+      multi = {
+        path = ./templates/multi;
+        description = "A multi-system flake with auto construction enabled, but only using x86_64-linux.";
+      };
+
+      multi-specialised = {
+        path = ./templates/multi-specialised;
+        description = "A multi-system flake with auto construction enabled, using the custom class system of easy-hosts";
+      };
+
+      not-auto = {
+        path = ./templates/not-auto;
+        description = "A flake with auto construction disabled, using only the `easyHosts.hosts` attribute.";
+      };
+
+      only = {
+        path = ./templates/only;
+        description = "A flake with auto construction enabled, with only one class and a more 'flat' structure.";
+      };
+    };
+  };
+}

lib.nix

···
+{
+  lib,
+  inputs,
+  withSystem,
+  ...
+}:
+let
+  inherit (inputs) self;
+
+  constructSystem =
+    target: arch:
+    if (target == "iso" || target == "nixos") then "${arch}-linux" else "${arch}-${target}";
+
+  inherit (builtins)
+    readDir
+    elemAt
+    filter
+    pathExists
+    ;
+  inherit (lib.lists) optionals singleton flatten;
+  inherit (lib.attrsets)
+    recursiveUpdate
+    foldAttrs
+    attrValues
+    mapAttrs
+    filterAttrs
+    ;
+  inherit (lib.modules) mkDefault evalModules;
+
+  /**
+    mkHost is a function that uses withSystem to give us inputs' and self'
+    it also assumes the the system type either nixos or darwin and uses the appropriate
+
+    # Type
+
+    ```
+    mkHost :: AttrSet -> AttrSet
+    ```
+
+    # Example
+
+    ```nix
+      mkHost {
+        name = "myhost";
+        path = "/path/to/host";
+        system = "x86_64-linux";
+        class = "nixos";
+        modules = [ ./module.nix ];
+        specialArgs = { foo = "bar"; };
+      }
+    ```
+  */
+  mkHost =
+    {
+      name,
+      path,
+      class ? "nixos",
+      system ? "x86_64-linux",
+      modules ? [ ],
+      specialArgs ? { },
+      ...
+    }:
+    withSystem system (
+      { self', inputs', ... }:
+      let
+        eval = evalModules {
+          # we use recursiveUpdate such that users can "override" the specialArgs
+          #
+          # This should only be used for special arguments that need to be evaluated
+          # when resolving module structure (like in imports).
+          specialArgs = recursiveUpdate {
+            # create the modulesPath based on the system, we need
+            modulesPath =
+              if class == "darwin" then "${inputs.darwin}/modules" else "${inputs.nixpkgs}/nixos/modules";
+
+            # laying it out this way is completely arbitrary, however it looks nice i guess
+            inherit lib;
+            inherit self self';
+            inherit inputs inputs';
+          } specialArgs;
+
+          # A nominal type for modules. When set and non-null, this adds a check to
+          # make sure that only compatible modules are imported.
+          class = if class == "iso" then "nixos" else class;
+
+          modules = flatten [
+            # import our host system paths
+            (
+              if path != null then
+                path
+              else
+                (filter pathExists [
+                  # if the previous path does not exist then we will try to import some paths with some assumptions
+                  "${self}/hosts/${name}/default.nix"
+                  "${self}/systems/${name}/default.nix"
+                ])
+            )
+
+            # get an installer profile from nixpkgs to base the Isos off of
+            # this is useful because it makes things alot easier
+            (optionals (class == "iso") [
+              "${inputs.nixpkgs}/nixos/modules/installer/cd-dvd/installation-cd-minimal-new-kernel.nix"
+            ])
+
+            # we need to import the module list for our system
+            # this is either the nixos modules list provided by nixpkgs
+            # or the darwin modules list provided by nix darwin
+            (import (
+              if class == "darwin" then
+                "${inputs.darwin}/modules/module-list.nix"
+              else
+                "${inputs.nixpkgs}/nixos/modules/module-list.nix"
+            ))
+
+            (singleton {
+              # TODO: learn what this means and why its needed to build the iso
+              _module.args.modules = [ ];
+
+              # we set the systems hostname based on the host value
+              # which should be a string that is the hostname of the system
+              networking.hostName = name;
+
+              nixpkgs = {
+                # you can also do this as `inherit system;` with the normal `lib.nixosSystem`
+                # however for evalModules this will not work, so we do this instead
+                hostPlatform = mkDefault system;
+
+                # The path to the nixpkgs sources used to build the system.
+                # This is automatically set up to be the store path of the nixpkgs flake used to build
+                # the system if using lib.nixosSystem, and is otherwise null by default.
+                # so that means that we should set it to our nixpkgs flake output path
+                flake.source = inputs.nixpkgs.outPath;
+              };
+            })
+
+            # if we are on darwin we need to import the nixpkgs source, its used in some
+            # modules, if this is not set then you will get an error
+            (optionals (class == "darwin") (singleton {
+              # without supplying an upstream nixpkgs source, nix-darwin will not be able to build
+              # and will complain and log an error demanding that you must set this value
+              nixpkgs.source = mkDefault inputs.nixpkgs;
+
+              system = {
+                # i don't quite know why this is set but upstream does it so i will too
+                checks.verifyNixPath = false;
+
+                # we use these values to keep track of what upstream revision we are on, this also
+                # prevents us from recreating docs for the same configuration build if nothing has changed
+                darwinVersionSuffix = ".${inputs.darwin.shortRev or inputs.darwin.dirtyShortRev or "dirty"}";
+                darwinRevision = inputs.darwin.rev or inputs.darwin.dirtyRev or "dirty";
+              };
+            }))
+
+            # import any additional modules that the user has provided
+            modules
+          ];
+        };
+      in
+      if (class == "nixos" || class == "iso") then
+        { nixosConfigurations.${name} = eval; }
+      else
+        {
+          darwinConfigurations.${name} = eval // {
+            system = eval.config.system.build.toplevel;
+          };
+        }
+    );
+
+  foldAttrsReccursive = builtins.foldl' (acc: attrs: recursiveUpdate acc attrs) { };
+
+  mkHosts =
+    makeHostsConfig:
+    foldAttrs (host: acc: host // acc) { } (
+      attrValues (
+        mapAttrs (
+          name: cfg:
+          mkHost {
+            inherit name;
+
+            inherit (cfg) class system path;
+
+            # merging is handled later
+            modules = [
+              (cfg.modules or [ ])
+              (makeHostsConfig.shared.modules or [ ])
+              ((makeHostsConfig.perClass cfg.class).modules or [ ])
+            ];
+
+            specialArgs = foldAttrsReccursive [
+              (cfg.specialArgs or { })
+              (makeHostsConfig.shared.specialArgs or { })
+              ((makeHostsConfig.perClass cfg.class).specialArgs or { })
+            ];
+          }
+        ) makeHostsConfig.hosts
+      )
+    );
+
+  onlyDirs = filterAttrs (_: type: type == "directory");
+
+  splitSystem =
+    system:
+    let
+      sp = builtins.split "-" system;
+      arch = elemAt sp 0;
+      class = if ((elemAt sp 2) == "linux") then "nixos" else elemAt sp 2;
+    in
+    {
+      inherit arch class;
+    };
+
+  normaliseHosts =
+    cfg: hosts:
+    if (cfg.onlySystem == null) then
+      foldAttrs (acc: host: acc // host) { } (
+        attrValues (
+          mapAttrs (
+            system: hosts':
+            mapAttrs (name: _: {
+              inherit (splitSystem system) arch class;
+              path = "${cfg.path}/${system}/${name}";
+            }) hosts'
+          ) hosts
+        )
+      )
+    else
+      mapAttrs (host: _: {
+        inherit (splitSystem cfg.onlySystem) arch class;
+        path = "${cfg.path}/${host}";
+      }) hosts;
+
+  buildHosts =
+    cfg:
+    let
+      hostsDir = readDir cfg.path;
+
+      hosts =
+        if (cfg.onlySystem != null) then
+          hostsDir
+        else
+          mapAttrs (path: _: readDir "${cfg.path}/${path}") (onlyDirs hostsDir);
+    in
+    normaliseHosts cfg hosts;
+in
+{
+  inherit
+    constructSystem
+    mkHost
+    mkHosts
+    buildHosts
+    ;
+}