yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: rename all references from 'buildClan' to 'lib.clan'

Browse Source
This commit is contained in:
Johannes Kirschbauer
2025-06-27 09:54:23 +02:00
parent 35d50489bb
commit 731de62876
17 changed files with 54 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
clanServices/hello-world/tests/eval-tests.nix
View File

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

2
clanServices/wifi/tests/eval-tests.nix
View File

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

2
docs/mkdocs.yml
View File

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

1
docs/nix/flake-module.nix
View File

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

64
docs/nix/render_options/__init__.py
View File

@@ -383,36 +383,16 @@ 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 {
inventory.services = {
admin.me = {
roles.default.machines = [ "jon" ];
config.allowedkeys = [ "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD..." ];
};
```nix
clan-core.lib.clan {
inventory.services = {
admin.me = {
roles.default.machines = [ "jon" ];
config.allowedkeys = [ "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD..." ];
};
};
```
=== "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)

4
docs/site/guides/authoring/clanModules/index.md
View File

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

4
docs/site/guides/flake-parts.md
View File

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

4
docs/site/guides/getting-started/add-machines.md
View File

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

4
docs/site/guides/getting-started/deploy.md
View File

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

2
docs/site/guides/getting-started/secrets.md
View File

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

6
docs/site/guides/inventory.md
View File

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

4
docs/site/guides/macos.md
View File

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

4
docs/site/guides/migrations/migration-guide.md
View File

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

14
docs/site/guides/more-machines.md
View File

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

2
docs/site/reference/index.md
View File

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

4
lib/modules/inventoryClass/interface.nix
View File

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

2
lib/modules/inventoryClass/roles-interface.nix
View File

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