feat(all-formats.nix): add readme section and test

Author: DavHau

README.md

@@ -147,6 +147,63 @@ For more details on configuring `binfmt`, have a look at:
 Once you've run `nixos-rebuild` with these options,
 you can use the `--system` option to create images for other architectures.
 
+## Using as a nixos-module
+
+`nixos-generators` can be included as a `NixOS module` into your existing `configuration.nix` making all available formats available through `config.formats` and configurable through `config.formatConfigs`. New formats can be defined by adding a new entry like `config.formatConfigs.my-new-format = {config, ...}: {}`.
+
+An example `flake.nix` demonstrating this approach is below. `vmware` or
+`my-custom-format` images can be built from the same `configuration.nix` by running:
+
+- `nix build .#vmware` or
+- `nix build .#my-custom-format`
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "nixpkgs/nixos-unstable";
+    nixos-generators = {
+      url = "github:nix-community/nixos-generators";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+  outputs = { self, nixpkgs, nixos-generators, ... }: {
+
+    # A single nixos config outputting multiple formats.
+    # Alternatively put this in a configuration.nix.
+    nixosModules.my-machine = {config, ...}: {
+      imports = [
+        nixos-generators.nixosModules.all-formats
+      ];
+
+      nixpkgs.hostPlatform = "x86_64-linux";
+
+      # customize an existing format
+      formatConfigs.vmware = {config, ...}: {
+        services.openssh.enable = true;
+      };
+
+      # define a new format
+      formatConfigs.my-custom-format = {config, modulesPath, ...}: {
+        imports = ["${toString modulesPath}/installer/cd-dvd/installation-cd-base.nix"];
+        formatAttr = "isoImage";
+        filename = "*.iso";
+        networking.wireless.networks = {
+          # ...
+        };
+      };
+
+    # the evaluated machine
+    nixosConfigurations.my-machine = nixpkgs.lib.nixosSystem {
+      modules = [self.nixosModules.my-machine];
+    };
+
+    # optionally re-expose all formats as packages
+    packages.x86_64-linux =
+      self.nixosConfigurations.my-machine.config.formats;
+  };
+}
+```
+
 ## Using in a Flake
 
 `nixos-generators` can be included as a `Flake` input and provides

checks/test-all-formats-flake/flake.nix

@@ -0,0 +1,50 @@
+/*
+Tests using the all-formats module through a flake.
+- Tests if foramts can be customized.
+- Tests if new foramts can be added
+*/
+{
+  inputs = {
+    nixpkgs.url = "nixpkgs/nixos-unstable";
+    nixos-generators = {
+      url = "github:nix-community/nixos-generators";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+  outputs = { self, nixpkgs, nixos-generators, ... }: {
+
+    nixosModules.my-machine = {config, ...}: {
+      imports = [
+        nixos-generators.nixosModules.all-formats
+      ];
+
+      nixpkgs.hostPlatform = "x86_64-linux";
+
+      # customize an existing format
+      formatConfigs.vmware = {config, ...}: {
+        services.openssh.enable = false;
+      };
+
+      # define a new format
+      formatConfigs.my-custom-format = {config, modulesPath, ...}: {
+        imports = ["${toString modulesPath}/installer/cd-dvd/installation-cd-base.nix"];
+        formatAttr = "isoImage";
+        filename = "*.iso";
+        networking.wireless.networks = {
+          # ...
+        };
+      };
+    };
+
+    nixosConfigurations.my-machine = nixpkgs.lib.nixosSystem {
+      modules = [self.nixosModules.my-machine];
+    };
+
+    checks.x86_64-linux = {
+      test-flake_vmware =
+        self.nixosConfigurations.my-machine.config.formats.vmware;
+      test-flake_my-custom-format =
+        self.nixosConfigurations.my-machine.config.formats.my-custom-format;
+    };
+  };
+}

flake.nix

@@ -11,9 +11,19 @@
     self,
     nixpkgs,
     nixlib,
-  }: let
+  } @ inputs: let
     lib = nixpkgs.lib;
 
+    callFlake = flake: let
+      args =
+        inputs
+        // {
+          nixos-generators = self;
+          self = subFlake;
+        };
+      subFlake = (import flake).outputs args;
+    in subFlake;
+
     # Ensures a derivation's name can be accessed without evaluating it deeply.
     # Prevents `nix flake show` from being very slow.
     makeLazyDrv = name: drv: {
@@ -30,11 +40,15 @@
     # Library modules (depend on nixlib)
     {
       # export all generator formats in ./formats
-      nixosModules = nixlib.lib.mapAttrs' (file: _: {
-        name = nixlib.lib.removeSuffix ".nix" file;
-        # The exported module should include the internal format* options
-        value.imports = [(./formats + "/${file}") ./format-module.nix];
-      }) (builtins.readDir ./formats);
+      nixosModules =
+        {
+          all-formats = ./all-formats.nix;
+        }
+        // (nixlib.lib.mapAttrs' (file: _: {
+          name = nixlib.lib.removeSuffix ".nix" file;
+          # The exported module should include the internal format* options
+          value.imports = [(./formats + "/${file}") ./format-module.nix];
+        }) (builtins.readDir ./formats));
 
       # example usage in flakes:
       #   outputs = { self, nixpkgs, nixos-generators, ...}: {
@@ -124,31 +138,35 @@
         });
 
         checks =
-          lib.genAttrs ["x86_64-linux" "aarch64-linux"]
+          lib.recursiveUpdate
+          (callFlake ./checks/test-all-formats-flake/flake.nix).checks
           (
-            system: let
-              allFormats = import ./checks/test-all-formats.nix {
-                inherit nixpkgs system;
-              };
-              test-customize-format = import ./checks/test-customize-format.nix {
-                inherit nixpkgs system;
-              };
-            in
-              lib.mapAttrs makeLazyDrv (
-                {
-                  inherit
-                    (self.packages.${system})
-                    nixos-generate
-                    ;
-
-                  inherit test-customize-format;
-
-                  is-formatted = import ./checks/is-formatted.nix {
-                    pkgs = nixpkgs.legacyPackages.${system};
-                  };
-                }
-                // allFormats
-              )
+            lib.genAttrs ["x86_64-linux" "aarch64-linux"]
+            (
+              system: let
+                allFormats = import ./checks/test-all-formats.nix {
+                  inherit nixpkgs system;
+                };
+                test-customize-format = import ./checks/test-customize-format.nix {
+                  inherit nixpkgs system;
+                };
+              in
+                lib.mapAttrs makeLazyDrv (
+                  {
+                    inherit
+                      (self.packages.${system})
+                      nixos-generate
+                      ;
+
+                    inherit test-customize-format;
+
+                    is-formatted = import ./checks/is-formatted.nix {
+                      pkgs = nixpkgs.legacyPackages.${system};
+                    };
+                  }
+                  // allFormats
+                )
+            )
           );
 
         devShells = forAllSystems (system: let