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

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

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

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:

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

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
+    # Inventory options are already included under the clan attribute
-    # We just omitted them in the buildClan docs, because we want a separate output for the inventory model
+    # 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
+    # Inventory options are already included under the clan attribute
-    # We just omitted them in the buildClan docs, because we want a separate output for the inventory model
+    # 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)
 

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" ];

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

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

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" = {

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";

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" = {};

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";
     };

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";

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).
+Machines can be added via [`clan.inventory.machines`](../guides/inventory.md) or in `clan.machines`, which allows for defining NixOS options.
-
-!!! Note
-    It is possible to use `inventory` and `buildClan` together at the same time.
 
 === "**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";
                 };
             };
         };

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
 
 ---
 

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;

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

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;

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.