From ab8607e01a62ee0465cf4995451c8b913958b1af Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Tue, 23 Sep 2025 16:03:25 +0200 Subject: [PATCH] clan: add nixpkgs version checks --- docs/mkdocs.yml | 1 + docs/site/guides/nixpkgs-flake-input/index.md | 98 +++++++++++++++++++ flakeModules/clan.nix | 47 ++++++--- 3 files changed, 130 insertions(+), 16 deletions(-) create mode 100644 docs/site/guides/nixpkgs-flake-input/index.md diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 083050abb..e88d0c4ee 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -79,6 +79,7 @@ nav: - Networking: - Introduction to Networking: guides/networking/networking.md - Zerotier VPN: guides/networking/mesh-vpn.md + - Nixpkgs Flake Input: guides/nixpkgs-flake-input/index.md - Disko Templates: - Community Disko Templates: guides/disko-templates/community.md - Backups: diff --git a/docs/site/guides/nixpkgs-flake-input/index.md b/docs/site/guides/nixpkgs-flake-input/index.md new file mode 100644 index 000000000..49f7efb21 --- /dev/null +++ b/docs/site/guides/nixpkgs-flake-input/index.md @@ -0,0 +1,98 @@ +**Q**: How should I choose the nixpkgs input for my flake when using clan-core? + +**A**: In general, you should pin your flake to a recent nixpkgs version. +There are two common ways to do this, each with its own trade-offs: + +## Follow clan-core + +- (+) Recommended for most people. +- (+) Verified by our CI and widely used by others +- (-) Coupling to version bumps in clan-core, + - Upstream features and packages may take longer to land. + +```nix +inputs = { + clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz"; + # Uses the nixpkgs version that was locked in clan-core + nixpkgs.follows = "clan-core/nixpkgs"; +} +``` + +## Use your own nixpkgs version + +- (+) Faster access to new upstream features and packages +- (-) Recommended for advanced usage. +- (-) Not covered by our CI — you’re on the frontier + +```nix +inputs = { + # Use your own version here. + nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; + + clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz"; + # Uses the nixpkgs version of your own flake in clan-core + clan-core.inputs.nixpkgs.follows = "nixpkgs"; +} +``` + +## Recommended + +To avoid ambiguity or incompatibility issues, it’s a good idea to check your `flake.lock` for duplicate `nixpkgs` entries. +This usually indicates that one of your flake inputs is missing a `follows` directive. + +If you see something like this, it means you have multiple versions of `nixpkgs`: + +```json + "nixpkgs": { + "locked": { + "lastModified": 315532800, + "narHash": "sha256-1tUpklZsKzMGI3gjo/dWD+hS8cf+5Jji8TF5Cfz7i3I=", + "rev": "08b8f92ac6354983f5382124fef6006cade4a1c1", + "type": "tarball", + "url": "https://releases.nixos.org/nixpkgs/nixpkgs-25.11pre862603.08b8f92ac635/nixexprs.tar.xz" + }, + "original": { + "type": "tarball", + "url": "https://nixos.org/channels/nixpkgs-unstable/nixexprs.tar.xz" + } + }, + "nixpkgs_2": { + "locked": { + "lastModified": 1758346548, + "narHash": "sha256-afXE7AJ7MY6wY1pg/Y6UPHNYPy5GtUKeBkrZZ/gC71E=", + "owner": "nixos", + "repo": "nixpkgs", + "rev": "b2a3852bd078e68dd2b3dfa8c00c67af1f0a7d20", + "type": "github" + }, + "original": { + "owner": "nixos", + "ref": "nixos-25.05", + "repo": "nixpkgs", + "type": "github" + } + }, +``` + +You can grep through your lock file to locate which inputs are referencing the wrong nixpkgs. + +In this example, `home-manager` is pointing to `nixpkgs_2` instead of the main `nixpkgs` + +```json + // ... + "home-manager": { + "inputs": { + "nixpkgs": "nixpkgs_2" + } + // ... +``` + +To fix this add the following line to your flake.nix inputs: + +```nix +home-manager.inputs.nixpkgs.follows = "nixpkgs"; +``` + +Repeat this process until all duplicate `nixpkgs` entries are eliminated. + +This helps prevent cross-version conflicts and ensures all inputs use the same `nixpkgs` source. diff --git a/flakeModules/clan.nix b/flakeModules/clan.nix index 60f47df7d..227ef0f4e 100644 --- a/flakeModules/clan.nix +++ b/flakeModules/clan.nix @@ -22,26 +22,41 @@ in default = config.flake.clan.clanInternals; }; # The clan module - clan = lib.mkOption { - description = "Clan module. Define your clan inside here"; - default = { }; - type = types.submoduleWith { - class = "clan"; - specialArgs = - # TODO: make these explizit options and deduplicate with lib.clan function - let - nixpkgs = inputs.nixpkgs or clan-core.inputs.nixpkgs; - nix-darwin = inputs.nix-darwin or clan-core.inputs.nix-darwin; - in - { + clan = + # TODO: make these explizit options and deduplicate with lib.clan function + let + nixpkgs = inputs.nixpkgs or clan-core.inputs.nixpkgs; + nix-darwin = inputs.nix-darwin or clan-core.inputs.nix-darwin; + in + lib.mkOption { + description = "Clan module. Define your clan inside here"; + default = { }; + type = types.submoduleWith { + class = "clan"; + specialArgs = { inherit self; inherit nixpkgs nix-darwin; }; - modules = [ - clan-core.modules.clan.default - ]; + modules = [ + clan-core.modules.clan.default + ]; + }; + apply = + config: + # TOOD: + # - allow to disable version check? + # - self-incrementing version? + if !lib.versionAtLeast nixpkgs.lib.version "25.11" then + throw '' + Nixpkgs version: ${nixpkgs.lib.version} is incompatible with clan-core. (>= 25.11 is required) + --- + Your version of 'nixpkgs' seems too old for clan-core. + Please read: https://docs.clan.lol/guides/nixpkgs-flake-input + --- + '' + else + config; }; - }; # Mapped flake toplevel outputs darwinConfigurations = lib.mkOption {