Merge pull request 'modules: add explizit class to clan module' (#4115) from hsjobeki/buildClan into main

Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4115
2025-06-27 08:13:54 +00:00
parent f3134b93e1 731de62876
commit 382fe7181b
19 changed files with 56 additions and 73 deletions
--- a/clanServices/hello-world/tests/eval-tests.nix
+++ b/clanServices/hello-world/tests/eval-tests.nix
@@ -6,7 +6,7 @@
 let
  testFlake = clanLib.buildClan {
    # Point to the folder of the module
-    # TODO: make this optional in buildClan
+    # TODO: make this optional
    directory = ./..;

    # Create some test machines
--- a/clanServices/wifi/tests/eval-tests.nix
+++ b/clanServices/wifi/tests/eval-tests.nix
@@ -6,7 +6,7 @@
 let
  testFlake = clanLib.buildClan {
    # Point to the folder of the module
-    # TODO: make this optional in buildClan
+    # TODO: make this optional
    directory = ./..;

    # Create some test machines
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -168,7 +168,7 @@ nav:
              - reference/clan.core/state.md
              - reference/clan.core/vars.md
      - Nix API:
-          - buildClan: reference/nix-api/buildclan.md
+          - clan: reference/nix-api/clan.md
          - Inventory: reference/nix-api/inventory.md
      - Glossary: reference/glossary.md
      - Decisions:
--- a/docs/nix/flake-module.nix
+++ b/docs/nix/flake-module.nix
@@ -97,7 +97,6 @@
            # Frontmatter format for clanModules
            export CLAN_MODULES_FRONTMATTER_DOCS=${clanModulesFrontmatter}/share/doc/nixos/options.json

-            # buildClan options
            export BUILD_CLAN_PATH=${buildClanOptions}/share/doc/nixos/options.json

            mkdir $out
--- a/docs/nix/render_options/init.py
+++ b/docs/nix/render_options/init.py
@@ -383,15 +383,8 @@ For more information, see the [inventory guide](../../guides/inventory.md).

    `clan.admin.allowedkeys`

-    This means there are two equivalent ways to set the `allowedkeys` option.
-    Either via a nixos module or via the inventory interface.
-    **But it is recommended to keep together `imports` and `config` to preserve
-    locality of the module configuration.**
-
-    === "Inventory"
-
    ```nix
-        clan-core.lib.buildClan {
+    clan-core.lib.clan {
        inventory.services = {
            admin.me = {
                roles.default.machines = [ "jon" ];
@@ -400,19 +393,6 @@ For more information, see the [inventory guide](../../guides/inventory.md).
        };
    };
    ```
-
-    === "NixOS"
-
-        ```nix
-        clan-core.lib.buildClan {
-            machines = {
-                jon = {
-                    clan.admin.allowedkeys = [ "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD..." ];
-                    imports = [ clanModules.admin ];
-                };
-            };
-        };
-        ```
 """
        )
    return ""
@@ -708,18 +688,18 @@ def produce_build_clan_docs() -> None:
        msg = f"Environment variables are not set correctly: $out={OUT}"
        raise ClanError(msg)

-    output = """# BuildClan
+    output = """# Clan

 This provides an overview of the available arguments of the `clan` interface.

 Each attribute is documented below

- **buildClan**: A function that takes an attribute set.`.
+- **clan-core.lib.clan**: A function that takes an attribute set.

-    ??? example "buildClan Example"
+    ??? example "clan Example"

        ```nix
-        buildClan {
+        clan {
            self = self;
            machines = {
                jon = { };
@@ -728,7 +708,13 @@ Each attribute is documented below
        };
        ```

- **flake-parts**: Each attribute can be defined via `clan.<attribute name>`. See our [flake-parts](../../guides/flake-parts.md) guide.
+- **clan with flake-parts**: Import the FlakeModule
+
+    After importing the FlakeModule you can define your `clan` as a flake attribute
+
+    All attribute can be defined via `clan.*`
+
+    Further information see: [flake-parts](../../guides/flake-parts.md) guide.

    ??? example "flake-parts Example"

@@ -767,7 +753,7 @@ Each attribute is documented below
            for option in root.suboptions:
                output += options_docs_from_tree(option, init_level=2)

-    outfile = Path(OUT) / "nix-api/buildclan.md"
+    outfile = Path(OUT) / "nix-api/clan.md"
    outfile.parent.mkdir(parents=True, exist_ok=True)
    with Path.open(outfile, "w") as of:
        of.write(output)
@@ -821,8 +807,8 @@ Typically needed by module authors to define roles, behavior and metadata for di

    See: [clanService Authoring Guide](../../guides/authoring/clanServices/index.md)
 """
-    # Inventory options are already included under the buildClan attribute
-    # We just omitted them in the buildClan docs, because we want a separate output for the inventory model
+    # Inventory options are already included under the clan attribute
+    # We just omitted them in the clan docs, because we want a separate output for the inventory model
    with Path(CLAN_SERVICE_INTERFACE).open() as f:
        options: dict[str, dict[str, Any]] = json.load(f)

@@ -860,11 +846,11 @@ def produce_inventory_docs() -> None:
    output = """# Inventory
 This provides an overview of the available attributes of the `inventory` model.

-It can be set via the `inventory` attribute of the [`buildClan`](./buildclan.md#inventory) function, or via the [`clan.inventory`](./buildclan.md#inventory) attribute of flake-parts.
+It can be set via the `inventory` attribute of the [`clan`](./clan.md#inventory) function, or via the [`clan.inventory`](./clan.md#inventory) attribute of flake-parts.

 """
-    # Inventory options are already included under the buildClan attribute
-    # We just omitted them in the buildClan docs, because we want a separate output for the inventory model
+    # Inventory options are already included under the clan attribute
+    # We just omitted them in the clan docs, because we want a separate output for the inventory model
    with Path(BUILD_CLAN_PATH).open() as f:
        options: dict[str, dict[str, Any]] = json.load(f)

--- a/docs/site/guides/authoring/clanModules/index.md
+++ b/docs/site/guides/authoring/clanModules/index.md
@@ -52,7 +52,7 @@ clanModules/borgbackup

    ```nix title="flake.nix"
    # ...
-    buildClan {
+    clan-core.lib.clan {
        # 1. Add the module to the available clanModules with inventory support
        inventory.modules = {
            custom-module = ./modules/my_module;
@@ -175,7 +175,7 @@ The following shows how to add options to your module.
    Configuration can be set as follows.

    ```nix title="flake.nix"
-    buildClan {
+    clan-core.lib.clan {
        inventory.services = {
            custom-module.instance_1 = {
                roles.default.machines = [ "machineA" ];
--- a/docs/site/guides/flake-parts.md
+++ b/docs/site/guides/flake-parts.md
@@ -27,7 +27,7 @@ inputs = {

 ## 2. Import the Clan flake-parts Module

-After updating your flake inputs, the next step is to import the Clan flake-parts module. This will make the [Clan options](../reference/nix-api/buildclan.md) available within `mkFlake`.
+After updating your flake inputs, the next step is to import the Clan flake-parts module. This will make the [Clan options](../reference/nix-api/clan.md) available within `mkFlake`.

 ```nix
 {
@@ -62,7 +62,7 @@ Next you'll need to configure Clan wide settings and define machines, here's an
      ];

      # Define your Clan
-      # See: https://docs.clan.lol/reference/nix-api/buildclan/
+      # See: https://docs.clan.lol/reference/nix-api/clan/
      clan = {
        # Clan wide settings
        meta.name = ""; # This is required and must be unique
--- a/docs/site/guides/getting-started/add-machines.md
+++ b/docs/site/guides/getting-started/add-machines.md
@@ -8,7 +8,7 @@ Clan currently offers the following methods to configure machines:

 !!! Success "Recommended for advanced Nix users"

-    - flake.nix (i.e. via `buildClan`)
+    - flake.nix (i.e. via `clan-core.lib.clan`)
        - `machine` argument
        - `inventory` argument

@@ -30,7 +30,7 @@ In the `flake.nix` file:
 === "**normal flake template**"

    ```nix title="flake.nix" hl_lines="3"
-    buildClan {
+    clan-core.lib.clan {
        # Set a unique name
        meta.name = "Lobsters";
        # Necessary for importing external Clan services
--- a/docs/site/guides/getting-started/deploy.md
+++ b/docs/site/guides/getting-started/deploy.md
@@ -175,7 +175,7 @@ During an update, the CLI will SSH into the build host and run `nixos-rebuild` f


 ```{.nix hl_lines="5" .no-copy}
-buildClan {
+clan {
    # ...
    machines = {
        "jon" = {
@@ -191,7 +191,7 @@ To exclude machines from being updated when running `clan machines update` witho
 one can set the `clan.deployment.requireExplicitUpdate` option to true:

 ```{.nix hl_lines="5" .no-copy}
-buildClan {
+clan {
    # ...
    machines = {
        "jon" = {
--- a/docs/site/guides/getting-started/secrets.md
+++ b/docs/site/guides/getting-started/secrets.md
@@ -82,7 +82,7 @@ are loaded when using Clan:
  outputs =
    { self, clan-core, ... }:
    let
-      clan = clan-core.clanLib.buildClan {
+      clan = clan-core.clanLib.clan {
        inherit self;

        meta.name = "myclan";
--- a/docs/site/guides/inventory.md
+++ b/docs/site/guides/inventory.md
@@ -47,7 +47,7 @@ Each service can still be customized and configured according to the modules opt
    See also: [Multiple Service Instances](#multiple-service-instances)

    ```{.nix hl_lines="6-7"}
-    buildClan {
+    clan-core.lib.clan {
        inventory = {
            services = {
                borgbackup.instance_1 = {
@@ -69,7 +69,7 @@ It is possible to add services to multiple machines via tags as shown
 !!! Example "Tags Example"

    ```{.nix hl_lines="5 8 14"}
-    buildClan {
+    clan-core.lib.clan {
        inventory = {
            machines = {
                "jon" = {
@@ -101,7 +101,7 @@ It is possible to add services to multiple machines via tags as shown
    In this example `backup_server` has role `client` and `server` in different instances.

    ```{.nix hl_lines="11 14"}
-    buildClan {
+    clan-core.lib.clan {
        inventory = {
            machines = {
                "jon" = {};
--- a/docs/site/guides/macos.md
+++ b/docs/site/guides/macos.md
@@ -13,10 +13,10 @@ Currently, Clan supports the following features for macOS:

 In this example, we'll name the machine `yourmachine`. Replace this with your preferred machine name.

-=== "**If using core.lib.buildClan**"
+=== "**If using clan-core.lib.clan**"

 ```nix
-buildClan {
+clan-core.lib.clan {
    inventory = {
        machines.yourmachine.machineClass = "darwin";
    };
--- a/docs/site/guides/migrations/migration-guide.md
+++ b/docs/site/guides/migrations/migration-guide.md
@@ -68,7 +68,7 @@ output parameters.

 The existing `nixosConfigurations` output of your flake will be created by
 clan. In addition, a new `clanInternals` output will be added. Since both of
-these are provided by the output of `lib.buildClan`, a common syntax is to use a
+these are provided by the output of `clan-core.lib.clan`, a common syntax is to use a
 `let...in` statement to create your clan and access it's parameters in the flake
 outputs.

@@ -85,7 +85,7 @@ For the provide flake example, your flake should now look like this:

  outputs = { self, nixpkgs, clan-core, ... }:
  let
-    clan = clan-core.lib.buildClan {
+    clan = clan-core.lib.clan {
      self = self; # this needs to point at the repository root
      specialArgs = {};
      meta.name = throw "Change me to something unique";
--- a/docs/site/guides/more-machines.md
+++ b/docs/site/guides/more-machines.md
@@ -17,19 +17,14 @@ Every folder `machines/{machineName}` will be registered automatically as a Clan
    - [x] `machines/{machineName}/facter.json` Automatically configured, for further information see [nixos-facter](https://clan.lol/blog/nixos-facter/)
    - [x] `machines/{machineName}/disko.nix` Automatically loaded, for further information see the [disko docs](https://github.com/nix-community/disko/blob/master/docs/quickstart.md).

-
-
 ## Manual declaration

-Machines can also be added manually under `buildClan`, `clan.*` in flake-parts or via [`inventory`](../guides/inventory.md).
-
-!!! Note
-    It is possible to use `inventory` and `buildClan` together at the same time.
+Machines can be added via [`clan.inventory.machines`](../guides/inventory.md) or in `clan.machines`, which allows for defining NixOS options.

 === "**Individual Machine Configuration**"

    ```{.nix}
-    buildClan {
+    clan-core.lib.clan {
        machines = {
            "jon" = {
                # Any valid nixos config
@@ -41,12 +36,13 @@ Machines can also be added manually under `buildClan`, `clan.*` in flake-parts o
 === "**Inventory Configuration**"

    ```{.nix}
-    buildClan {
+    clan-core.lib.clan {
        inventory = {
            machines = {
                "jon" = {
-                    # Inventory machines can set tags
+                    # Inventory can set tags and other metadata
                    tags = [ "zone1" ];
+                    deploy.targetHost = "root@jon";
                };
            };
        };
--- a/docs/site/reference/index.md
+++ b/docs/site/reference/index.md
@@ -7,7 +7,7 @@ This section of the site provides an overview of available options and commands
 - Learn how to use the [Clan CLI](./cli/index.md)
 - Explore available services and application [modules](./clanModules/index.md)
 - Discover [configuration options](./clan.core/index.md) that manage essential features
- Find descriptions of the [Nix interfaces](./nix-api/buildclan.md) for defining a Clan
+- Find descriptions of the [Nix interfaces](./nix-api/clan.md) for defining a Clan

 ---

--- a/flakeModules/clan.nix
+++ b/flakeModules/clan.nix
@@ -26,6 +26,7 @@ in
      description = "Clan module. Define your clan inside here";
      default = { };
      type = types.submoduleWith {
+        class = "clan";
        specialArgs = {
          inherit self;
          inherit (inputs) nixpkgs nix-darwin;
--- a/lib/modules/default.nix
+++ b/lib/modules/default.nix
@@ -20,6 +20,7 @@ rec {
      nix-darwin = self.inputs.nix-darwin or clan-core.inputs.nix-darwin;
    in
    lib.evalModules {
+      class = "clan";
      specialArgs = {
        inherit
          self
--- a/lib/modules/inventoryClass/interface.nix
+++ b/lib/modules/inventoryClass/interface.nix
@@ -55,7 +55,7 @@ let

      Supported types:

-      - **Strings**: Interpreted relative to the 'directory' passed to buildClan.
+      - **Strings**: Interpreted relative to the 'directory' passed to `lib.clan`.
      - **Paths**: should be relative to the current file.
      - **Any**: Nix expression must be serializable to JSON.

@@ -146,7 +146,7 @@ in

        ???+ example
            ```nix
-            buildClan {
+            clan-core.lib.clan {
                # 1. Add the module to the available inventory modules
                inventory.modules = {
                  custom-module = ./modules/my_module;
--- a/lib/modules/inventoryClass/roles-interface.nix
+++ b/lib/modules/inventoryClass/roles-interface.nix
@@ -44,7 +44,7 @@ in

        Supported types:

-        - **Strings**: Interpreted relative to the 'directory' passed to buildClan.
+        - **Strings**: Interpreted relative to the 'directory' passed to `lib.clan`.
        - **Paths**: should be relative to the current file.
        - **Any**: Nix expression must be serializable to JSON.