nathan/nixpkgs
1
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2026-06-05 21:03:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

lib/services: improve configure function documentation

Browse Source 
Expand the doc comment with a structured description, type signature,
properly formatted parameter docs, and an example showing how to
implement modular services for a new containing system.
This commit is contained in:
cinereal
2026-04-09 09:09:47 +02:00
parent f557638126
commit fb3b7c0b19
1 changed files with 51 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
lib/services/lib.nix
View File

@@ -37,17 +37,63 @@ rec {
);
/**
This is the entrypoint for the portable part of modular services.
Entrypoint for integrating modular services into a containing module system.
It provides the various options that are consumed by service manager implementations.
Each containing system (NixOS, ...) calls `configure` to
obtain a `serviceSubmodule` type for its services option. The returned submodule
includes the portable service base and any service-manager-specific modules
passed via `extraRootModules`.
**Implementing for a new system** (e.g. home-manager, nix-darwin):
```nix
# darwin/modules/services/system.nix
{ lib, config, pkgs, ... }:
let
portable-lib = import <nixpkgs/lib/services/lib.nix> { inherit lib; };
modularServiceConfiguration = portable-lib.configure {
serviceManagerPkgs = pkgs;
extraRootModules = [
./launchd-service.nix # launchd-specific options (plist generation, etc.)
];
};
in
{
options.services = lib.mkOption {
type = lib.types.attrsOf modularServiceConfiguration.serviceSubmodule;
default = { };
};
config = {
# Convert service tree -> launchd plists, assertions, etc.
# (analogous to how NixOS converts to systemd units)
launchd.agents = ...;
assertions = ...;
warnings = ...;
};
}
```
lib.services.configure :: AttrSet -> { serviceSubmodule :: SubmoduleType }
# Inputs
`serviceManagerPkgs`: A Nixpkgs instance which will be used for built-in logic such as converting `configData.<path>.text` to a store path.
`serviceManagerPkgs`
`extraRootModules`: Modules to be loaded into the "root" service submodule, but not into its sub-`services`. That's the modules' own responsibility.
: 1\. A Nixpkgs instance used for built-in logic such as converting
`configData.<path>.text` to a store path.
`extraRootSpecialArgs`: Fixed module arguments that are provided in a similar manner to `extraRootModules`.
`extraRootModules`
: 2\. Modules to be loaded into the "root" service submodule, but not
into its sub-`services`. That's the modules' own responsibility.
Typically contains service-manager-specific option modules
(e.g. systemd unit options, launchd plist options).
`extraRootSpecialArgs`
: 3\. Fixed module arguments provided alongside `extraRootModules`.
# Output