132 lines
3.6 KiB
Markdown
132 lines
3.6 KiB
Markdown
# Authoring a clanModule
|
|
|
|
This site will guide you through authoring your first module. Explaining which conventions must be followed, such that others will have an enjoyable experience and the module can be used with minimal effort.
|
|
|
|
:fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier:
|
|
Under construction
|
|
:fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier:
|
|
|
|
## Bootstrapping a `clanModule`
|
|
|
|
A ClanModule is a specific subset of a [NixOS Module](https://nix.dev/tutorials/module-system/index.html), but it has some constraints and might be used via the [Inventory](../manual/inventory.md) interface.
|
|
|
|
Because ClanModules should be configurable via `json` all of its interface (`options`) must be serializable.
|
|
|
|
Currently ClanModules should be contributed to the [clan-core repository](https://git.clan.lol/clan/clan-core). Ad-hoc loading of custom modules is not recommended / supported yet.
|
|
|
|
!!! Tip
|
|
ClanModules interface can be checked by running the json schema converter as follows.
|
|
|
|
`nix build .#legacyPackages.x86_64-linux.schemas.inventory`
|
|
|
|
If the build succeeds the module is compatible.
|
|
|
|
## Directory structure
|
|
|
|
Each module SHOULD be a directory of the following format:
|
|
|
|
```sh
|
|
# Example: borgbackup
|
|
clanModules/borgbackup
|
|
├── README.md
|
|
└── roles
|
|
├── client.nix
|
|
└── server.nix
|
|
```
|
|
|
|
!!! Tip
|
|
This format is strictly required for `features = [ "inventory" ]`.
|
|
Some module authors might decide to opt-out of [inventory](../manual/inventory.md) usage.
|
|
|
|
The next step is to register the module via the `clanModules` attribute.
|
|
|
|
!!! Note
|
|
Currently ClanModules should be contributed to the clan-core repository. Ad-hoc loading modules is not recommended / supported yet.
|
|
|
|
```nix title="clanModules/flake-module.nix"
|
|
--8<-- "clanModules/flake-module.nix:0:6"
|
|
# Register your new module here
|
|
# ...
|
|
```
|
|
|
|
## Readme
|
|
|
|
The `README.md` is a required file. It MUST contain frontmatter in [`toml`]() format.
|
|
|
|
```markdown
|
|
---
|
|
description = "Module A"
|
|
---
|
|
|
|
This is the example module that does xyz.
|
|
```
|
|
|
|
See the [frontmatter reference](#frontmatter-reference) for all supported attributes.
|
|
|
|
## Roles
|
|
|
|
Each `.nix` file in the `roles` directory is added as a role to the service.
|
|
|
|
Other files can be placed alongside the `.nix` files
|
|
|
|
```sh
|
|
└── roles
|
|
├── client.nix
|
|
└── server.nix
|
|
```
|
|
|
|
Adds the roles: `client` and `server`
|
|
|
|
## Organizing the ClanModule
|
|
|
|
Each `{role}.nix` is included into the machine if the machine is declared to have the role.
|
|
|
|
For example
|
|
|
|
```nix
|
|
roles.client.machines = ["MachineA"];
|
|
```
|
|
|
|
Then `roles/client.nix` will be added to the machine `MachineA`.
|
|
|
|
## Frontmatter Reference
|
|
|
|
`description` (**Required** `String`)
|
|
: Short description of the module
|
|
|
|
`categories` (Optional `[ String ]`)
|
|
: default `[ "Uncategorized" ]`
|
|
|
|
Categories are used for Grouping and searching.
|
|
|
|
While initial oriented on [freedesktop](https://specifications.freedesktop.org/menu-spec/latest/category-registry.html) the following categories are allowed
|
|
|
|
- AudioVideo
|
|
- Audio
|
|
- Video
|
|
- Development
|
|
- Education
|
|
- Game
|
|
- Graphics
|
|
- Social
|
|
- Network
|
|
- Office
|
|
- Science
|
|
- System
|
|
- Settings
|
|
- Utility
|
|
- Uncategorized
|
|
|
|
`features` (Optional `[ String ]`)
|
|
: default `[]`
|
|
|
|
Clans Features that the module implements support for.
|
|
|
|
Available feature flags are:
|
|
|
|
- `inventory`
|
|
|
|
!!! warning "Important"
|
|
Every ClanModule, that specifies `features = [ "inventory" ]` MUST have at least one role.
|
|
Many modules use `roles/default.nix` which registers the role `default`
|