feat(modules): support nixos & home-manager's stable branches (#182)

* chore(modules): add mkVersionedOpts to lib

* ci: test against stable nixos/home-manager

* feat(modules): support nixos & home-manager's stable branches

* docs: add version support information

.github/workflows/ci.yml

@@ -36,6 +36,10 @@ jobs:
     name: Test Modules
     runs-on: ubuntu-latest
 
+    strategy:
+      matrix:
+        test: [unstable, stable]
+
     steps:
       - uses: actions/checkout@v4
 
@@ -46,5 +50,10 @@ jobs:
         uses: DeterminateSystems/magic-nix-cache-action@v6
 
       - name: Run VM
+        env:
+          TEST: ${{ matrix.test }}
         run: |
-          nix build --print-build-logs --show-trace ./dev#checks.x86_64-linux.module-vm-test
+          nix build \
+            --print-build-logs \
+            --show-trace \
+            "./dev#checks.x86_64-linux.module-test-$TEST"

README.md

@@ -154,6 +154,10 @@ For [standalone installations](https://nix-community.github.io/home-manager/inde
   A: You can find programs supported through home-manager [here](https://github.com/catppuccin/nix/tree/main/modules/home-manager),
   and NixOS modules [here](https://github.com/catppuccin/nix/tree/main/modules/nixos)
 
+- Q: **"What versions of NixOS and home-manager are supported?"**\
+  A: We primarily support the `unstable` branch, but try our best to support the current stable release.
+  You can check if your stable release is currently supported at [status.nixos.org](https://status.nixos.org/)
+
 ## 💝 Thanks to
 
 - [Stonks3141](https://github.com/Stonks3141)

dev/flake.lock

@@ -20,6 +20,27 @@
         "type": "github"
       }
     },
+    "home-manager-stable": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs-stable"
+        ]
+      },
+      "locked": {
+        "lastModified": 1715381426,
+        "narHash": "sha256-wPuqrAQGdv3ISs74nJfGb+Yprm23U/rFpcHFFNWgM94=",
+        "owner": "nix-community",
+        "repo": "home-manager",
+        "rev": "ab5542e9dbd13d0100f8baae2bc2d68af901f4b4",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "ref": "release-23.11",
+        "repo": "home-manager",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
       "locked": {
         "lastModified": 1715787315,
@@ -35,10 +56,27 @@
         "type": "indirect"
       }
     },
+    "nixpkgs-stable": {
+      "locked": {
+        "lastModified": 1716239187,
+        "narHash": "sha256-5oyOV5ZlqXYQ8RB6lvVrKxVBeBPE/ZsLY+qQKqSJLZM=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "f88df4bf25b729d78712c441fb0910f7085e9395",
+        "type": "github"
+      },
+      "original": {
+        "id": "nixpkgs",
+        "ref": "release-23.11",
+        "type": "indirect"
+      }
+    },
     "root": {
       "inputs": {
         "home-manager": "home-manager",
-        "nixpkgs": "nixpkgs"
+        "home-manager-stable": "home-manager-stable",
+        "nixpkgs": "nixpkgs",
+        "nixpkgs-stable": "nixpkgs-stable"
       }
     }
   },

dev/flake.nix

@@ -3,14 +3,20 @@
 
   inputs = {
     nixpkgs.url = "nixpkgs/nixos-unstable";
+    nixpkgs-stable.url = "nixpkgs/release-23.11";
 
     home-manager = {
       url = "github:nix-community/home-manager";
       inputs.nixpkgs.follows = "nixpkgs";
     };
+
+    home-manager-stable = {
+      url = "github:nix-community/home-manager/release-23.11";
+      inputs.nixpkgs.follows = "nixpkgs-stable";
+    };
   };
 
-  outputs = { self, nixpkgs, home-manager }:
+  outputs = { self, nixpkgs, nixpkgs-stable, home-manager, home-manager-stable }:
     let
       systems = [
         "x86_64-linux"
@@ -19,7 +25,12 @@
         "aarch64-darwin"
       ];
 
-      forAllSystems = fn: nixpkgs.lib.genAttrs systems (system: fn nixpkgs.legacyPackages.${system});
+      nixpkgsFor = nixpkgs.lib.genAttrs systems (system: {
+        unstable = nixpkgs.legacyPackages.${system};
+        stable = nixpkgs-stable.legacyPackages.${system};
+      });
+
+      forAllSystems = fn: nixpkgs.lib.genAttrs systems (system: fn nixpkgsFor.${system}.unstable);
     in
     {
       apps = forAllSystems ({ lib, pkgs, ... }: {
@@ -40,8 +51,11 @@
         };
       });
 
-      checks = forAllSystems ({ lib, pkgs, ... }: lib.optionalAttrs pkgs.stdenv.isLinux {
+      checks = forAllSystems ({ lib, pkgs, system, ... }: lib.optionalAttrs pkgs.stdenv.isLinux {
-        module-vm-test = pkgs.callPackage ../test.nix { inherit home-manager; };
+        module-test-unstable = pkgs.callPackage ../test.nix { inherit home-manager; };
+        module-test-stable = nixpkgsFor.${system}.stable.callPackage ../test.nix {
+          home-manager = home-manager-stable;
+        };
       });
 
       formatter = forAllSystems (pkgs: pkgs.nixpkgs-fmt);

modules/home-manager/tofi.nix

@@ -6,10 +6,15 @@ let
   inherit (config.catppuccin) sources;
   cfg = config.programs.tofi.catppuccin;
   enable = cfg.enable && config.programs.tofi.enable;
+
+  # `programs.tofi` was added in 24.05 and not backported
+  # TODO: remove when 24.05 is stable
+  minVersion = "24.05";
 in
 {
-  options.programs.tofi.catppuccin =
+  options.programs.tofi = lib.ctp.mkVersionedOpts minVersion {
-    lib.ctp.mkCatppuccinOpt "tofi";
+    catppuccin = lib.ctp.mkCatppuccinOpt "tofi";
+  };
 
   config.programs.tofi = lib.mkIf enable {
     settings = lib.ctp.fromINI (sources.tofi + /catppuccin-${cfg.flavour});

modules/lib/default.nix

@@ -116,4 +116,15 @@ in
   # by default enums cannot be merged, but they keep their passed value in `functor.payload`.
   # `functor.binOp` can merge those values
   mergeEnums = a: b: lib.types.enum (a.functor.binOp a.functor.payload b.functor.payload);
+
+  # string
+  # returns the current release version of nixos or home-manager. throws an evaluation error if neither are
+  # found
+  getModuleRelease = config.home.version.release or config.system.nixos.release or (throw "Couldn't determine release version!");
+
+  # string -> a -> a
+  # if the current module release is less than `minVersion`, all options are made no-ops with
+  # `lib.mkSinkUndeclaredOptions`
+  mkVersionedOpts = minVersion: option:
+    if lib.versionAtLeast ctp.getModuleRelease minVersion then option else lib.mkSinkUndeclaredOptions { };
 }

modules/nixos/sddm.nix

@@ -4,48 +4,54 @@
 , ...
 }:
 let
+  inherit (lib) mkIf ctp types mkOption versionAtLeast;
   cfg = config.services.displayManager.sddm.catppuccin;
   enable = cfg.enable && config.services.displayManager.sddm.enable;
 
-  inherit (lib) mkIf ctp types mkOption;
+  # versions >= 24.05 renamed `services.xserver.displayManager` to `services.displayManager`
+  # TODO: remove when 24.05 is stable
+  minVersion = "24.05";
 in
 {
-  options.services.displayManager.sddm.catppuccin =
+  options.services.displayManager = ctp.mkVersionedOpts minVersion {
-    ctp.mkCatppuccinOpt "sddm"
+    sddm.catppuccin =
-    // {
+      ctp.mkCatppuccinOpt "sddm"
-      font = mkOption {
+      // {
-        type = types.str;
+        font = mkOption {
-        default = "Noto Sans";
+          type = types.str;
-        description = "Font to use for the login screen";
+          default = "Noto Sans";
-      };
+          description = "Font to use for the login screen";
+        };
 
-      fontSize = mkOption {
+        fontSize = mkOption {
-        type = types.str;
+          type = types.str;
-        default = "9";
+          default = "9";
-        description = "Font size to use for the login screen";
+          description = "Font size to use for the login screen";
-      };
+        };
 
-      background = mkOption {
+        background = mkOption {
-        type = with types; (either path str);
+          type = with types; (either path str);
-        default = "";
+          default = "";
-        description = "Background image to use for the login screen";
+          description = "Background image to use for the login screen";
-      };
+        };
 
-      loginBackground = mkOption {
+        loginBackground = mkOption {
-        type = types.bool;
+          type = types.bool;
-        default = true;
+          default = true;
-        description = "Add an additonal background layer to the login panel";
+          description = "Add an additional background layer to the login panel";
+        };
       };
-    };
+  };
 
-  config = mkIf enable {
+  config = mkIf enable
+    {
+      environment.systemPackages = [
+        (pkgs.catppuccin-sddm.override {
+          flavor = cfg.flavour;
+          inherit (cfg) font fontSize background loginBackground;
+        })
+      ];
+    } // mkIf (enable && versionAtLeast ctp.getModuleRelease minVersion) {
     services.displayManager.sddm.theme = "catppuccin-${cfg.flavour}";
-
-    environment.systemPackages = [
-      (pkgs.catppuccin-sddm.override {
-        flavor = cfg.flavour;
-        inherit (cfg) font fontSize background loginBackground;
-      })
-    ];
   };
 }