Home Explore Blog CI



nixpkgs

2nd chunk of `nixos/doc/manual/development/writing-modules.chapter.md`
a668cc4c5b3366eb1ab63472483720a3d2356d60b54ec28600000001000008c0
    `pkgs` and `config` inside the module.

-   This `imports` list enumerates the paths to other NixOS modules that
    should be included in the evaluation of the system configuration. A
    default set of modules is defined in the file `modules/module-list.nix`.
    These don't need to be added in the import list.

-   The attribute `options` is a nested set of *option declarations*
    (described below).

-   The attribute `config` is a nested set of *option definitions* (also
    described below).

[Example: NixOS Module for the "locate" Service](#locate-example)
shows a module that handles the regular update of the "locate" database,
an index of all files in the file system. This module declares two
options that can be defined by other modules (typically the user's
`configuration.nix`): `services.locate.enable` (whether the database should
be updated) and `services.locate.interval` (when the update should be done).
It implements its functionality by defining two options declared by other
modules: `systemd.services` (the set of all systemd services) and
`systemd.timers` (the list of commands to be executed periodically by
`systemd`).

Care must be taken when writing systemd services using `Exec*` directives. By
default systemd performs substitution on `%<char>` specifiers in these
directives, expands environment variables from `$FOO` and `${FOO}`, splits
arguments on whitespace, and splits commands on `;`. All of these must be escaped
to avoid unexpected substitution or splitting when interpolating into an `Exec*`
directive, e.g. when using an `extraArgs` option to pass additional arguments to
the service. The functions `utils.escapeSystemdExecArg` and
`utils.escapeSystemdExecArgs` are provided for this, see [Example: Escaping in
Exec directives](#exec-escaping-example) for an example. When using these
functions system environment substitution should *not* be disabled explicitly.

::: {#locate-example .example}
### NixOS Module for the "locate" Service
```nix
{ config, lib, pkgs, ... }:

let
  inherit (lib) concatStringsSep mkIf mkOption optionalString types;
  cfg = config.services.locate;
in {
  options.services.locate = {
    enable = mkOption {
      type = types.bool;
      default = false;

Title: Details of NixOS Module Structure and an Example
Summary
A NixOS module function can omit the `pkgs` and `config` parameters if they are not used. The `imports` list includes paths to other modules, with a default set defined in `modules/module-list.nix`. The `options` attribute contains option declarations, while the `config` attribute contains option definitions. An example module for the 'locate' service demonstrates declaring options like `services.locate.enable` and `services.locate.interval`, and implementing functionality by defining options for systemd services and timers. When writing systemd services, it's crucial to escape special characters in `Exec*` directives using `utils.escapeSystemdExecArg` and `utils.escapeSystemdExecArgs`.