commit b8efe91ce225c4413301089d52f47c07f384e38e · pyrox.dev/nixpkgs

+1 -1

nixos/doc/manual/development/development.xml

···

       10
        
         </para>

     

       11
        
        </partintro>

     

       12
        
        <xi:include href="../from_md/development/sources.chapter.xml" />

     

       13
       -
        <xi:include href="writing-modules.xml" />

     

       14
        
        <xi:include href="../from_md/development/building-parts.chapter.xml" />

     

       15
        
        <xi:include href="../from_md/development/writing-documentation.chapter.xml" />

     

       16
        
        <xi:include href="../from_md/development/building-nixos.chapter.xml" />

···

       10
        
         </para>

     

       11
        
        </partintro>

     

       12
        
        <xi:include href="../from_md/development/sources.chapter.xml" />

     

       13
       +
        <xi:include href="../from_md/development/writing-modules.chapter.xml" />

     

       14
        
        <xi:include href="../from_md/development/building-parts.chapter.xml" />

     

       15
        
        <xi:include href="../from_md/development/writing-documentation.chapter.xml" />

     

       16
        
        <xi:include href="../from_md/development/building-nixos.chapter.xml" />

+166

nixos/doc/manual/development/writing-modules.chapter.md

···

       1
       +
       # Writing NixOS Modules {#sec-writing-modules}

     

       2
       +
       

     

       3
       +
       NixOS has a modular system for declarative configuration. This system

     

       4
       +
       combines multiple *modules* to produce the full system configuration.

     

       5
       +
       One of the modules that constitute the configuration is

     

       6
       +
       `/etc/nixos/configuration.nix`. Most of the others live in the

     

       7
       +
       [`nixos/modules`](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules)

     

       8
       +
       subdirectory of the Nixpkgs tree.

     

       9
       +
       

     

       10
       +
       Each NixOS module is a file that handles one logical aspect of the

     

       11
       +
       configuration, such as a specific kind of hardware, a service, or

     

       12
       +
       network settings. A module configuration does not have to handle

     

       13
       +
       everything from scratch; it can use the functionality provided by other

     

       14
       +
       modules for its implementation. Thus a module can *declare* options that

     

       15
       +
       can be used by other modules, and conversely can *define* options

     

       16
       +
       provided by other modules in its own implementation. For example, the

     

       17
       +
       module

     

       18
       +
       [`pam.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix)

     

       19
       +
       declares the option `security.pam.services` that allows other modules (e.g.

     

       20
       +
       [`sshd.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix))

     

       21
       +
       to define PAM services; and it defines the option `environment.etc` (declared by

     

       22
       +
       [`etc.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix))

     

       23
       +
       to cause files to be created in `/etc/pam.d`.

     

       24
       +
       

     

       25
       +
       In [](#sec-configuration-syntax), we saw the following structure of

     

       26
       +
       NixOS modules:

     

       27
       +
       

     

       28
       +
       ```nix

     

       29
       +
       { config, pkgs, ... }:

     

       30
       +
       

     

       31
       +
       { option definitions

     

       32
       +
       }

     

       33
       +
       ```

     

       34
       +
       

     

       35
       +
       This is actually an *abbreviated* form of module that only defines

     

       36
       +
       options, but does not declare any. The structure of full NixOS modules

     

       37
       +
       is shown in [Example: Structure of NixOS Modules](#ex-module-syntax).

     

       38
       +
       

     

       39
       +
       ::: {#ex-module-syntax .example}

     

       40
       +
       ::: {.title}

     

       41
       +
       **Example: Structure of NixOS Modules**

     

       42
       +
       :::

     

       43
       +
       ```nix

     

       44
       +
       { config, pkgs, ... }:

     

       45
       +
       

     

       46
       +
       {

     

       47
       +
         imports =

     

       48
       +
           [ paths of other modules

     

       49
       +
           ];

     

       50
       +
       

     

       51
       +
         options = {

     

       52
       +
           option declarations

     

       53
       +
         };

     

       54
       +
       

     

       55
       +
         config = {

     

       56
       +
           option definitions

     

       57
       +
         };

     

       58
       +
       }

     

       59
       +
       ```

     

       60
       +
       :::

     

       61
       +
       

     

       62
       +
       The meaning of each part is as follows.

     

       63
       +
       

     

       64
       +
       -   The first line makes the current Nix expression a function. The variable

     

       65
       +
           `pkgs` contains Nixpkgs (by default, it takes the `nixpkgs` entry of

     

       66
       +
           `NIX_PATH`, see the [Nix manual](https://nixos.org/manual/nix/stable/#sec-common-env)

     

       67
       +
           for further details), while `config` contains the full system

     

       68
       +
           configuration. This line can be omitted if there is no reference to

     

       69
       +
           `pkgs` and `config` inside the module.

     

       70
       +
       

     

       71
       +
       -   This `imports` list enumerates the paths to other NixOS modules that

     

       72
       +
           should be included in the evaluation of the system configuration. A

     

       73
       +
           default set of modules is defined in the file `modules/module-list.nix`.

     

       74
       +
           These don\'t need to be added in the import list.

     

       75
       +
       

     

       76
       +
       -   The attribute `options` is a nested set of *option declarations*

     

       77
       +
           (described below).

     

       78
       +
       

     

       79
       +
       -   The attribute `config` is a nested set of *option definitions* (also

     

       80
       +
           described below).

     

       81
       +
       

     

       82
       +
       [Example: NixOS Module for the "locate" Service](#locate-example)

     

       83
       +
       shows a module that handles the regular update of the "locate" database,

     

       84
       +
       an index of all files in the file system. This module declares two

     

       85
       +
       options that can be defined by other modules (typically the user's

     

       86
       +
       `configuration.nix`): `services.locate.enable` (whether the database should

     

       87
       +
       be updated) and `services.locate.interval` (when the update should be done).

     

       88
       +
       It implements its functionality by defining two options declared by other

     

       89
       +
       modules: `systemd.services` (the set of all systemd services) and

     

       90
       +
       `systemd.timers` (the list of commands to be executed periodically by

     

       91
       +
       `systemd`).

     

       92
       +
       

     

       93
       +
       ::: {#locate-example .example}

     

       94
       +
       ::: {.title}

     

       95
       +
       **Example: NixOS Module for the "locate" Service**

     

       96
       +
       :::

     

       97
       +
       ```nix

     

       98
       +
       { config, lib, pkgs, ... }:

     

       99
       +
       

     

       100
       +
       with lib;

     

       101
       +
       

     

       102
       +
       let

     

       103
       +
         cfg = config.services.locate;

     

       104
       +
       in {

     

       105
       +
         options.services.locate = {

     

       106
       +
           enable = mkOption {

     

       107
       +
             type = types.bool;

     

       108
       +
             default = false;

     

       109
       +
             description = ''

     

       110
       +
               If enabled, NixOS will periodically update the database of

     

       111
       +
               files used by the locate command.

     

       112
       +
             '';

     

       113
       +
           };

     

       114
       +
       

     

       115
       +
           interval = mkOption {

     

       116
       +
             type = types.str;

     

       117
       +
             default = "02:15";

     

       118
       +
             example = "hourly";

     

       119
       +
             description = ''

     

       120
       +
               Update the locate database at this interval. Updates by

     

       121
       +
               default at 2:15 AM every day.

     

       122
       +
       

     

       123
       +
               The format is described in

     

       124
       +
               systemd.time(7).

     

       125
       +
             '';

     

       126
       +
           };

     

       127
       +
       

     

       128
       +
           # Other options omitted for documentation

     

       129
       +
         };

     

       130
       +
       

     

       131
       +
         config = {

     

       132
       +
           systemd.services.update-locatedb =

     

       133
       +
             { description = "Update Locate Database";

     

       134
       +
               path  = [ pkgs.su ];

     

       135
       +
               script =

     

       136
       +
                 ''

     

       137
       +
                   mkdir -m 0755 -p $(dirname ${toString cfg.output})

     

       138
       +
                   exec updatedb \

     

       139
       +
                     --localuser=${cfg.localuser} \

     

       140
       +
                     ${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \

     

       141
       +
                     --output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags}

     

       142
       +
                 '';

     

       143
       +
             };

     

       144
       +
       

     

       145
       +
           systemd.timers.update-locatedb = mkIf cfg.enable

     

       146
       +
             { description = "Update timer for locate database";

     

       147
       +
               partOf      = [ "update-locatedb.service" ];

     

       148
       +
               wantedBy    = [ "timers.target" ];

     

       149
       +
               timerConfig.OnCalendar = cfg.interval;

     

       150
       +
             };

     

       151
       +
         };

     

       152
       +
       }

     

       153
       +
       ```

     

       154
       +
       :::

     

       155
       +
       

     

       156
       +
       ```{=docbook}

     

       157
       +
       <xi:include href="option-declarations.section.xml" />

     

       158
       +
       <xi:include href="option-types.section.xml" />

     

       159
       +
       <xi:include href="option-def.section.xml" />

     

       160
       +
       <xi:include href="assertions.section.xml" />

     

       161
       +
       <xi:include href="meta-attributes.section.xml" />

     

       162
       +
       <xi:include href="importing-modules.section.xml" />

     

       163
       +
       <xi:include href="replace-modules.section.xml" />

     

       164
       +
       <xi:include href="freeform-modules.section.xml" />

     

       165
       +
       <xi:include href="settings-options.section.xml" />

     

       166
       +
       ```

-191

nixos/doc/manual/development/writing-modules.xml

···

       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       -
               xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       -
               xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       -
               version="5.0"

     

       5
       -
               xml:id="sec-writing-modules">

     

       6
       -
        <title>Writing NixOS Modules</title>

     

       7
       -
        <para>

     

       8
       -
         NixOS has a modular system for declarative configuration. This system

     

       9
       -
         combines multiple <emphasis>modules</emphasis> to produce the full system

     

       10
       -
         configuration. One of the modules that constitute the configuration is

     

       11
       -
         <filename>/etc/nixos/configuration.nix</filename>. Most of the others live in

     

       12
       -
         the

     

       13
       -
         <link

     

       14
       -
       xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><filename>nixos/modules</filename></link>

     

       15
       -
         subdirectory of the Nixpkgs tree.

     

       16
       -
        </para>

     

       17
       -
        <para>

     

       18
       -
         Each NixOS module is a file that handles one logical aspect of the

     

       19
       -
         configuration, such as a specific kind of hardware, a service, or network

     

       20
       -
         settings. A module configuration does not have to handle everything from

     

       21
       -
         scratch; it can use the functionality provided by other modules for its

     

       22
       -
         implementation. Thus a module can <emphasis>declare</emphasis> options that

     

       23
       -
         can be used by other modules, and conversely can <emphasis>define</emphasis>

     

       24
       -
         options provided by other modules in its own implementation. For example, the

     

       25
       -
         module

     

       26
       -
         <link

     

       27
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link>

     

       28
       -
         declares the option <option>security.pam.services</option> that allows other

     

       29
       -
         modules (e.g.

     

       30
       -
         <link

     

       31
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>)

     

       32
       -
         to define PAM services; and it defines the option

     

       33
       -
         <option>environment.etc</option> (declared by

     

       34
       -
         <link

     

       35
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>)

     

       36
       -
         to cause files to be created in <filename>/etc/pam.d</filename>.

     

       37
       -
        </para>

     

       38
       -
        <para xml:id="para-module-syn">

     

       39
       -
         In <xref

     

       40
       -
       linkend="sec-configuration-syntax"/>, we saw the following structure

     

       41
       -
         of NixOS modules:

     

       42
       -
       <programlisting>

     

       43
       -
       { config, pkgs, ... }:

     

       44
       -
       

     

       45
       -
       { <replaceable>option definitions</replaceable>

     

       46
       -
       }

     

       47
       -
       </programlisting>

     

       48
       -
         This is actually an <emphasis>abbreviated</emphasis> form of module that only

     

       49
       -
         defines options, but does not declare any. The structure of full NixOS

     

       50
       -
         modules is shown in <xref linkend='ex-module-syntax' />.

     

       51
       -
        </para>

     

       52
       -
        <example xml:id='ex-module-syntax'>

     

       53
       -
         <title>Structure of NixOS Modules</title>

     

       54
       -
       <programlisting>

     

       55
       -
       { config, pkgs, ... }: <co xml:id='module-syntax-1' />

     

       56
       -
       

     

       57
       -
       {

     

       58
       -
         imports =

     

       59
       -
           [ <replaceable>paths of other modules</replaceable> <co xml:id='module-syntax-2' />

     

       60
       -
           ];

     

       61
       -
       

     

       62
       -
         options = {

     

       63
       -
           <replaceable>option declarations</replaceable> <co xml:id='module-syntax-3' />

     

       64
       -
         };

     

       65
       -
       

     

       66
       -
         config = {

     

       67
       -
           <replaceable>option definitions</replaceable> <co xml:id='module-syntax-4' />

     

       68
       -
         };

     

       69
       -
       }</programlisting>

     

       70
       -
        </example>

     

       71
       -
        <para>

     

       72
       -
         The meaning of each part is as follows.

     

       73
       -
         <calloutlist>

     

       74
       -
          <callout arearefs='module-syntax-1'>

     

       75
       -
           <para>

     

       76
       -
            This line makes the current Nix expression a function. The variable

     

       77
       -
            <varname>pkgs</varname> contains Nixpkgs (by default, it takes the

     

       78
       -
            <varname>nixpkgs</varname> entry of <envar>NIX_PATH</envar>, see the <link

     

       79
       -
            xlink:href="https://nixos.org/manual/nix/stable/#sec-common-env">Nix

     

       80
       -
            manual</link> for further details), while <varname>config</varname>

     

       81
       -
            contains the full system configuration. This line can be omitted if there

     

       82
       -
            is no reference to <varname>pkgs</varname> and <varname>config</varname>

     

       83
       -
            inside the module.

     

       84
       -
           </para>

     

       85
       -
          </callout>

     

       86
       -
          <callout arearefs='module-syntax-2'>

     

       87
       -
           <para>

     

       88
       -
            This list enumerates the paths to other NixOS modules that should be

     

       89
       -
            included in the evaluation of the system configuration. A default set of

     

       90
       -
            modules is defined in the file

     

       91
       -
            <filename>modules/module-list.nix</filename>. These don't need to be added

     

       92
       -
            in the import list.

     

       93
       -
           </para>

     

       94
       -
          </callout>

     

       95
       -
          <callout arearefs='module-syntax-3'>

     

       96
       -
           <para>

     

       97
       -
            The attribute <varname>options</varname> is a nested set of

     

       98
       -
            <emphasis>option declarations</emphasis> (described below).

     

       99
       -
           </para>

     

       100
       -
          </callout>

     

       101
       -
          <callout arearefs='module-syntax-4'>

     

       102
       -
           <para>

     

       103
       -
            The attribute <varname>config</varname> is a nested set of

     

       104
       -
            <emphasis>option definitions</emphasis> (also described below).

     

       105
       -
           </para>

     

       106
       -
          </callout>

     

       107
       -
         </calloutlist>

     

       108
       -
        </para>

     

       109
       -
        <para>

     

       110
       -
         <xref linkend='locate-example' /> shows a module that handles the regular

     

       111
       -
         update of the “locate” database, an index of all files in the file

     

       112
       -
         system. This module declares two options that can be defined by other modules

     

       113
       -
         (typically the user’s <filename>configuration.nix</filename>):

     

       114
       -
         <option>services.locate.enable</option> (whether the database should be

     

       115
       -
         updated) and <option>services.locate.interval</option> (when the update

     

       116
       -
         should be done). It implements its functionality by defining two options

     

       117
       -
         declared by other modules: <option>systemd.services</option> (the set of all

     

       118
       -
         systemd services) and <option>systemd.timers</option> (the list of commands

     

       119
       -
         to be executed periodically by <command>systemd</command>).

     

       120
       -
        </para>

     

       121
       -
        <example xml:id='locate-example'>

     

       122
       -
         <title>NixOS Module for the “locate” Service</title>

     

       123
       -
       <programlisting>

     

       124
       -
       { config, lib, pkgs, ... }:

     

       125
       -
       

     

       126
       -
       with lib;

     

       127
       -
       

     

       128
       -
       let

     

       129
       -
         cfg = config.services.locate;

     

       130
       -
       in {

     

       131
       -
         options.services.locate = {

     

       132
       -
           enable = mkOption {

     

       133
       -
             type = types.bool;

     

       134
       -
             default = false;

     

       135
       -
             description = ''

     

       136
       -
               If enabled, NixOS will periodically update the database of

     

       137
       -
               files used by the <command>locate</command> command.

     

       138
       -
             '';

     

       139
       -
           };

     

       140
       -
       

     

       141
       -
           interval = mkOption {

     

       142
       -
             type = types.str;

     

       143
       -
             default = "02:15";

     

       144
       -
             example = "hourly";

     

       145
       -
             description = ''

     

       146
       -
               Update the locate database at this interval. Updates by

     

       147
       -
               default at 2:15 AM every day.

     

       148
       -
       

     

       149
       -
               The format is described in

     

       150
       -
               <citerefentry><refentrytitle>systemd.time</refentrytitle>

     

       151
       -
               <manvolnum>7</manvolnum></citerefentry>.

     

       152
       -
             '';

     

       153
       -
           };

     

       154
       -
       

     

       155
       -
           # Other options omitted for documentation

     

       156
       -
         };

     

       157
       -
       

     

       158
       -
         config = {

     

       159
       -
           systemd.services.update-locatedb =

     

       160
       -
             { description = "Update Locate Database";

     

       161
       -
               path  = [ pkgs.su ];

     

       162
       -
               script =

     

       163
       -
                 ''

     

       164
       -
                   mkdir -m 0755 -p $(dirname ${toString cfg.output})

     

       165
       -
                   exec updatedb \

     

       166
       -
                     --localuser=${cfg.localuser} \

     

       167
       -
                     ${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \

     

       168
       -
                     --output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags}

     

       169
       -
                 '';

     

       170
       -
             };

     

       171
       -
       

     

       172
       -
           systemd.timers.update-locatedb = mkIf cfg.enable

     

       173
       -
             { description = "Update timer for locate database";

     

       174
       -
               partOf      = [ "update-locatedb.service" ];

     

       175
       -
               wantedBy    = [ "timers.target" ];

     

       176
       -
               timerConfig.OnCalendar = cfg.interval;

     

       177
       -
             };

     

       178
       -
         };

     

       179
       -
       }

     

       180
       -
       </programlisting>

     

       181
       -
        </example>

     

       182
       -
        <xi:include href="../from_md/development/option-declarations.section.xml" />

     

       183
       -
        <xi:include href="../from_md/development/option-types.section.xml" />

     

       184
       -
        <xi:include href="../from_md/development/option-def.section.xml" />

     

       185
       -
        <xi:include href="../from_md/development/assertions.section.xml" />

     

       186
       -
        <xi:include href="../from_md/development/meta-attributes.section.xml" />

     

       187
       -
        <xi:include href="../from_md/development/importing-modules.section.xml" />

     

       188
       -
        <xi:include href="../from_md/development/replace-modules.section.xml" />

     

       189
       -
        <xi:include href="../from_md/development/freeform-modules.section.xml" />

     

       190
       -
        <xi:include href="../from_md/development/settings-options.section.xml" />

     

       191
       -
       </chapter>

+196

nixos/doc/manual/from_md/development/writing-modules.chapter.xml

···

       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook"  xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-writing-modules">

     

       2
       +
         <title>Writing NixOS Modules</title>

     

       3
       +
         <para>

     

       4
       +
           NixOS has a modular system for declarative configuration. This

     

       5
       +
           system combines multiple <emphasis>modules</emphasis> to produce the

     

       6
       +
           full system configuration. One of the modules that constitute the

     

       7
       +
           configuration is <literal>/etc/nixos/configuration.nix</literal>.

     

       8
       +
           Most of the others live in the

     

       9
       +
           <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><literal>nixos/modules</literal></link>

     

       10
       +
           subdirectory of the Nixpkgs tree.

     

       11
       +
         </para>

     

       12
       +
         <para>

     

       13
       +
           Each NixOS module is a file that handles one logical aspect of the

     

       14
       +
           configuration, such as a specific kind of hardware, a service, or

     

       15
       +
           network settings. A module configuration does not have to handle

     

       16
       +
           everything from scratch; it can use the functionality provided by

     

       17
       +
           other modules for its implementation. Thus a module can

     

       18
       +
           <emphasis>declare</emphasis> options that can be used by other

     

       19
       +
           modules, and conversely can <emphasis>define</emphasis> options

     

       20
       +
           provided by other modules in its own implementation. For example,

     

       21
       +
           the module

     

       22
       +
           <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><literal>pam.nix</literal></link>

     

       23
       +
           declares the option <literal>security.pam.services</literal> that

     

       24
       +
           allows other modules (e.g.

     

       25
       +
           <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><literal>sshd.nix</literal></link>)

     

       26
       +
           to define PAM services; and it defines the option

     

       27
       +
           <literal>environment.etc</literal> (declared by

     

       28
       +
           <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><literal>etc.nix</literal></link>)

     

       29
       +
           to cause files to be created in <literal>/etc/pam.d</literal>.

     

       30
       +
         </para>

     

       31
       +
         <para>

     

       32
       +
           In <xref linkend="sec-configuration-syntax" />, we saw the following

     

       33
       +
           structure of NixOS modules:

     

       34
       +
         </para>

     

       35
       +
         <programlisting language="bash">

     

       36
       +
       { config, pkgs, ... }:

     

       37
       +
       

     

       38
       +
       { option definitions

     

       39
       +
       }

     

       40
       +
       </programlisting>

     

       41
       +
         <para>

     

       42
       +
           This is actually an <emphasis>abbreviated</emphasis> form of module

     

       43
       +
           that only defines options, but does not declare any. The structure

     

       44
       +
           of full NixOS modules is shown in

     

       45
       +
           <link linkend="ex-module-syntax">Example: Structure of NixOS

     

       46
       +
           Modules</link>.

     

       47
       +
         </para>

     

       48
       +
         <anchor xml:id="ex-module-syntax" />

     

       49
       +
         <para>

     

       50
       +
           <emphasis role="strong">Example: Structure of NixOS

     

       51
       +
           Modules</emphasis>

     

       52
       +
         </para>

     

       53
       +
         <programlisting language="bash">

     

       54
       +
       { config, pkgs, ... }:

     

       55
       +
       

     

       56
       +
       {

     

       57
       +
         imports =

     

       58
       +
           [ paths of other modules

     

       59
       +
           ];

     

       60
       +
       

     

       61
       +
         options = {

     

       62
       +
           option declarations

     

       63
       +
         };

     

       64
       +
       

     

       65
       +
         config = {

     

       66
       +
           option definitions

     

       67
       +
         };

     

       68
       +
       }

     

       69
       +
       </programlisting>

     

       70
       +
         <para>

     

       71
       +
           The meaning of each part is as follows.

     

       72
       +
         </para>

     

       73
       +
         <itemizedlist>

     

       74
       +
           <listitem>

     

       75
       +
             <para>

     

       76
       +
               The first line makes the current Nix expression a function. The

     

       77
       +
               variable <literal>pkgs</literal> contains Nixpkgs (by default,

     

       78
       +
               it takes the <literal>nixpkgs</literal> entry of

     

       79
       +
               <literal>NIX_PATH</literal>, see the

     

       80
       +
               <link xlink:href="https://nixos.org/manual/nix/stable/#sec-common-env">Nix

     

       81
       +
               manual</link> for further details), while

     

       82
       +
               <literal>config</literal> contains the full system

     

       83
       +
               configuration. This line can be omitted if there is no reference

     

       84
       +
               to <literal>pkgs</literal> and <literal>config</literal> inside

     

       85
       +
               the module.

     

       86
       +
             </para>

     

       87
       +
           </listitem>

     

       88
       +
           <listitem>

     

       89
       +
             <para>

     

       90
       +
               This <literal>imports</literal> list enumerates the paths to

     

       91
       +
               other NixOS modules that should be included in the evaluation of

     

       92
       +
               the system configuration. A default set of modules is defined in

     

       93
       +
               the file <literal>modules/module-list.nix</literal>. These don't

     

       94
       +
               need to be added in the import list.

     

       95
       +
             </para>

     

       96
       +
           </listitem>

     

       97
       +
           <listitem>

     

       98
       +
             <para>

     

       99
       +
               The attribute <literal>options</literal> is a nested set of

     

       100
       +
               <emphasis>option declarations</emphasis> (described below).

     

       101
       +
             </para>

     

       102
       +
           </listitem>

     

       103
       +
           <listitem>

     

       104
       +
             <para>

     

       105
       +
               The attribute <literal>config</literal> is a nested set of

     

       106
       +
               <emphasis>option definitions</emphasis> (also described below).

     

       107
       +
             </para>

     

       108
       +
           </listitem>

     

       109
       +
         </itemizedlist>

     

       110
       +
         <para>

     

       111
       +
           <link linkend="locate-example">Example: NixOS Module for the

     

       112
       +
           <quote>locate</quote> Service</link> shows a module that handles the

     

       113
       +
           regular update of the <quote>locate</quote> database, an index of

     

       114
       +
           all files in the file system. This module declares two options that

     

       115
       +
           can be defined by other modules (typically the user’s

     

       116
       +
           <literal>configuration.nix</literal>):

     

       117
       +
           <literal>services.locate.enable</literal> (whether the database

     

       118
       +
           should be updated) and <literal>services.locate.interval</literal>

     

       119
       +
           (when the update should be done). It implements its functionality by

     

       120
       +
           defining two options declared by other modules:

     

       121
       +
           <literal>systemd.services</literal> (the set of all systemd

     

       122
       +
           services) and <literal>systemd.timers</literal> (the list of

     

       123
       +
           commands to be executed periodically by <literal>systemd</literal>).

     

       124
       +
         </para>

     

       125
       +
         <anchor xml:id="locate-example" />

     

       126
       +
         <para>

     

       127
       +
           <emphasis role="strong">Example: NixOS Module for the

     

       128
       +
           <quote>locate</quote> Service</emphasis>

     

       129
       +
         </para>

     

       130
       +
         <programlisting language="bash">

     

       131
       +
       { config, lib, pkgs, ... }:

     

       132
       +
       

     

       133
       +
       with lib;

     

       134
       +
       

     

       135
       +
       let

     

       136
       +
         cfg = config.services.locate;

     

       137
       +
       in {

     

       138
       +
         options.services.locate = {

     

       139
       +
           enable = mkOption {

     

       140
       +
             type = types.bool;

     

       141
       +
             default = false;

     

       142
       +
             description = ''

     

       143
       +
               If enabled, NixOS will periodically update the database of

     

       144
       +
               files used by the locate command.

     

       145
       +
             '';

     

       146
       +
           };

     

       147
       +
       

     

       148
       +
           interval = mkOption {

     

       149
       +
             type = types.str;

     

       150
       +
             default = &quot;02:15&quot;;

     

       151
       +
             example = &quot;hourly&quot;;

     

       152
       +
             description = ''

     

       153
       +
               Update the locate database at this interval. Updates by

     

       154
       +
               default at 2:15 AM every day.

     

       155
       +
       

     

       156
       +
               The format is described in

     

       157
       +
               systemd.time(7).

     

       158
       +
             '';

     

       159
       +
           };

     

       160
       +
       

     

       161
       +
           # Other options omitted for documentation

     

       162
       +
         };

     

       163
       +
       

     

       164
       +
         config = {

     

       165
       +
           systemd.services.update-locatedb =

     

       166
       +
             { description = &quot;Update Locate Database&quot;;

     

       167
       +
               path  = [ pkgs.su ];

     

       168
       +
               script =

     

       169
       +
                 ''

     

       170
       +
                   mkdir -m 0755 -p $(dirname ${toString cfg.output})

     

       171
       +
                   exec updatedb \

     

       172
       +
                     --localuser=${cfg.localuser} \

     

       173
       +
                     ${optionalString (!cfg.includeStore) &quot;--prunepaths='/nix/store'&quot;} \

     

       174
       +
                     --output=${toString cfg.output} ${concatStringsSep &quot; &quot; cfg.extraFlags}

     

       175
       +
                 '';

     

       176
       +
             };

     

       177
       +
       

     

       178
       +
           systemd.timers.update-locatedb = mkIf cfg.enable

     

       179
       +
             { description = &quot;Update timer for locate database&quot;;

     

       180
       +
               partOf      = [ &quot;update-locatedb.service&quot; ];

     

       181
       +
               wantedBy    = [ &quot;timers.target&quot; ];

     

       182
       +
               timerConfig.OnCalendar = cfg.interval;

     

       183
       +
             };

     

       184
       +
         };

     

       185
       +
       }

     

       186
       +
       </programlisting>

     

       187
       +
         <xi:include href="option-declarations.section.xml" />

     

       188
       +
         <xi:include href="option-types.section.xml" />

     

       189
       +
         <xi:include href="option-def.section.xml" />

     

       190
       +
         <xi:include href="assertions.section.xml" />

     

       191
       +
         <xi:include href="meta-attributes.section.xml" />

     

       192
       +
         <xi:include href="importing-modules.section.xml" />

     

       193
       +
         <xi:include href="replace-modules.section.xml" />

     

       194
       +
         <xi:include href="freeform-modules.section.xml" />

     

       195
       +
         <xi:include href="settings-options.section.xml" />

     

       196
       +
       </chapter>