Modules

Here is a fizzbuzz flake from Perch modules end-to-end tests:

{
  inputs = {
    home-manager.url = "github:nix-community/home-manager?rev=fdec8815a86db36f42fc9c8cb2931cd8485f5aed";
    deploy-rs.url = "github:serokell/deploy-rs?rev=d5eff7f948535b9c723d60cd8239f8f11ddc90fa";
    rumor.url = "github:haras-unicorn/rumor?rev=f945357feec3b6cb9caf12ca8084606e8396c706";
  };

  outputs =
    {
      perch,
      perch-modules,
      home-manager,
      deploy-rs,
      rumor,
      ...
    }@inputs:
    perch.lib.flake.make {
      inherit inputs;
      selfModules.fizzbuzz =
        {
          self,
          pkgs,
          lib,
          config,
          specialArgs,
          perch-modules,
          nixosModule,
          ...
        }:
        {
          defaultPackage = true;
          packageNixpkgs.system = [
            "x86_64-linux"
            "x86_64-darwin"
          ];
          package = pkgs.writeShellApplication {
            name = "fizzbuzz";
            text = ''
              for i in {1..100}; do
                if (( i % 15 == 0 )); then
                  echo "FizzBuzz"
                elif (( i % 3 == 0 )); then
                  echo "Fizz"
                elif (( i % 5 == 0 )); then
                  echo "Buzz"
                else
                  echo "$i"
                fi
              done
            '';
          };

          defaultNixosModule = true;
          nixosModule = {
            options.programs.fizzbuzz = {
              enable = lib.mkEnableOption "fizzbuzz";
            };
            config = lib.mkIf config.programs.fizzbuzz.enable {
              environment.systemPackages = [
                self.packages.${pkgs.system}.default
              ];
            };
          };

          nixosModuleTestNixpkgs.system = [ "x86_64-linux" ];
          nixosModuleTest = pkgs.testers.runNixOSTest {
            name = "${nixosModule.name}-${pkgs.system}";
            nodes = {
              ${nixosModule.name} = {
                imports = [
                  nixosModule.value
                ];

                config.programs.fizzbuzz.enable = true;
              };
            };
            testScript = ''
              start_all()
              node = machines[0]
              node.succeed("fizzbuzz")
            '';
          };

          defaultHomeManagerModule = true;
          homeManagerModule = {
            options.programs.fizzbuzz = {
              enable = lib.mkEnableOption "fizzbuzz";
            };
            config = lib.mkIf config.programs.fizzbuzz.enable {
              home.packages = [
                self.packages.${pkgs.system}.default
              ];
            };
          };

          nixosConfigurationNixpkgs.system = "x86_64-linux";
          nixosConfiguration = {
            imports = [
              self.nixosModules.default
              home-manager.nixosModules.default
              perch-modules.nixosModules."flake-deployRs"
              perch-modules.nixosModules."flake-rumor"
            ];
            fileSystems."/" = {
              device = "/dev/disk/by-label/NIXROOT";
              fsType = "ext4";
            };
            deploy.node = {
              hostname = "example.com";
              sshUser = "haras";
            };
            rumor.sops.keys = [ "secret" ];
            rumor.sops.path = "../sops.yaml";
            rumor.specification.generations = [
              {
                generator = "text";
                arguments = {
                  name = "secret";
                  text = "hello :)";
                };
              }
            ];
            boot.loader.grub.device = "nodev";
            programs.fizzbuzz.enable = true;
            users.users.haras.isNormalUser = true;
            home-manager.extraSpecialArgs = specialArgs;
            home-manager.users.haras = {
              imports = [
                self.homeManagerModules.default
              ];
              programs.fizzbuzz.enable = true;
              home.stateVersion = "25.11";
            };
            system.stateVersion = "25.11";
          };
        };
    };
}

In the example we see a call to perch.lib.flake.make with one fizzbuzz module. The module defines:

a default and named package called fizzbuzz by the name of the module for the abovementioned systems like so:

{
  packages = {
    "systems..." = {
      default = "<<derivation>>";
      fizzbuzz = "<<derivation>>";
    };
  };
}

a default and named NixOS module using the beforementioned package called fizzbuzz by the name of the module like so:
```
{
  nixosModules = {
    default = "<<module>>";
    fizzbuzz = "<<module>>";
  };
}
```

a named NixOS module test inside checks using the beforementioned NixOS module like so:

{
  checks = {
    ${system} = {
      fizzbuzz-test = "<<derivation>>";
    };
  };
}

a default and named Home manager module using the beforementioned package called fizzbuzz by the name of the module like so:
```
{
  homeManagerModule = {
    default = "<<module>>";
    fizzbuzz = "<<module>>";
  };
}
```
a NixOS configuration using the beforementioned NixOS module named fizzbuzz-${system} where the system is the abovementioned system
```
{
  nixosConfigurations = {
    "fizzbuzz-${system}" = "<<nixos configuration>>";
  };
}
```

a deploy.nodes flake output to be used with deploy-rs along with checks for the deploy.nodes flake output schema

{
  deploy.nodes = {
    "fizzbuzz-${system}" = {
      hostname = "example.com";
      sshUser = "haras";
      user = "root";
      profiles.system = "<<derivation>>";
    };
  };
  checks = {
    ${system} = {
      deploy-activate = "<<derivation>>";
      deploy-schema = "<<derivation>>";
    };
  };
}

a rumor flake output to be used with rumor along with checks for the rumor flake output schema

{
  rumor = {
    "fizzbuzz-${system}" = {
      generations = [{
        {
          generator = "text";
          arguments = {
            name = "secret";
            text = "hello :)";
          };
        }

        {
          generator = "age";
          arguments = {
            private = "age-private";
            public = "age-public";
          };
        }
        {
          generator = "sops";
          arguments = {
            renew = true;
            age = "age-public";
            private = "sops-private";
            public = "sops-public";
            secrets = {
              "test" = "test"
            };
          };
        }
      ];
      exports = [{
        exporter = "copy";
        arguments = {
          from = "sops-public";
          to = "../sops.yaml";
        };
      }];
    };
  };
  checks = {
    ${system} = {
      rumor-fizzbuzz-${system}-schema = "<<derivation>>";
    };
  };
}

The generated age key and sops file are here to ease use with sops-nix

Special arguments

nixosModule - in the NixOS module test evaluation context, it will be set to the NixOS module that is defined in the same flake module if the flake module defines one.

Options

Home manager modules

defaultHomeManagerModule: bool = false - whether this module defines the default Home manager module
homeManagerModule: raw - the Home manager module for this module

Deploy-rs

nixosConfigurationsAsDeployNodes: bool = true - converts all NixOS configurations with deploy.node configuration into deploy nodes

perch-modules provides a NixOS module perch-modules.nixosModules."flake-deployRs" which you can use to define a deploy.node in your NixOS configuration

NixOS module tests

nixosModuleTest: raw - the NixOS module test for this module
nixosModuleTestNixpkgs: nixpkgs config - the nixpkgs configuration for this NixOS module test pkgs

Rumor

nixosConfigurationsAsRumor: bool = true - converts all NixOS configurations with rumor configuration into rumor specifications

perch-modules provides a NixOS module perch-modules.nixosModules."flake-rumor" which you can use to define a rumor specification in your NixOS configuration

Keyboard shortcuts