Unverified Commit fb3b7c0b authored by cinereal's avatar cinereal
Browse files

lib/services: improve configure function documentation 

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.
parent f5576381

lib/services/lib.nix

+51 −5
Original line number Diff line number Diff line
@@ -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`



    : 1\. A Nixpkgs instance used for built-in logic such as converting

    `configData.<path>.text` to a store path.



    `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).



    `extraRootModules`: Modules to be loaded into the "root" service submodule, but not into its sub-`services`. That's the modules' own responsibility.

    `extraRootSpecialArgs`



    `extraRootSpecialArgs`: Fixed module arguments that are provided in a similar manner to `extraRootModules`.

    : 3\. Fixed module arguments provided alongside `extraRootModules`.



    # Output