commit ebde306504e278e4ab153474786091f9ffdfa1e4 · pyrox.dev/nixpkgs

+8 -11

nixos/doc/manual/development/option-declarations.section.md

···

       12
       12
        
             type = type specification;

     

       13
       13
        
             default = default value;

     

       14
       14
        
             example = example value;

     

       15
       15
       -
             description = lib.mdDoc "Description for use in the NixOS manual.";

     

       15
       15
       +
             description = "Description for use in the NixOS manual.";

     

       16
       16
        
           };

     

       17
       17
        
         };

     

       18
       18
        
       }

     
···

       58
       58
        
       

     

       59
       59
        
       `description`

     

       60
       60
        
       

     

       61
       61
       -
       :   A textual description of the option, in [Nixpkgs-flavored Markdown](

     

       62
       62
       -
           https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format, that will be

     

       63
       63
       -
           included in the NixOS manual. During the migration process from DocBook

     

       64
       64
       -
           it is necessary to mark descriptions written in CommonMark with `lib.mdDoc`.

     

       65
       65
       -
           The description may still be written in DocBook (without any marker), but this

     

       66
       66
       -
           is discouraged and will be deprecated in the future.

     

       61
       61
       +
       :   A textual description of the option in [Nixpkgs-flavored Markdown](

     

       62
       62
       +
           https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format that will be

     

       63
       63
       +
           included in the NixOS manual.

     

       67
       64
        
       

     

       68
       65
        
       ## Utility functions for common option patterns {#sec-option-declarations-util}

     

       69
       66
        
       

     
···

       81
       78
        
       ::: {#ex-options-declarations-util-mkEnableOption-magic .example}

     

       82
       79
        
       ### `mkEnableOption` usage

     

       83
       80
        
       ```nix

     

       84
       84
       -
       lib.mkEnableOption (lib.mdDoc "magic")

     

       81
       81
       +
       lib.mkEnableOption "magic"

     

       85
       82
        
       # is like

     

       86
       83
        
       lib.mkOption {

     

       87
       84
        
         type = lib.types.bool;

     

       88
       85
        
         default = false;

     

       89
       86
        
         example = true;

     

       90
       90
       -
         description = lib.mdDoc "Whether to enable magic.";

     

       87
       87
       +
         description = "Whether to enable magic.";

     

       91
       88
        
       }

     

       92
       89
        
       ```

     

       93
       90
        
       :::

     
···

       135
       132
        
         type = lib.types.package;

     

       136
       133
        
         default = pkgs.hello;

     

       137
       134
        
         defaultText = lib.literalExpression "pkgs.hello";

     

       138
       138
       -
         description = lib.mdDoc "The hello package to use.";

     

       135
       135
       +
         description = "The hello package to use.";

     

       139
       136
        
       }

     

       140
       137
        
       ```

     

       141
       138
        
       :::

     
···

       153
       150
        
         default = pkgs.ghc;

     

       154
       151
        
         defaultText = lib.literalExpression "pkgs.ghc";

     

       155
       152
        
         example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";

     

       156
       156
       -
         description = lib.mdDoc "The GHC package to use.";

     

       153
       153
       +
         description = "The GHC package to use.";

     

       157
       154
        
       }

     

       158
       155
        
       ```

     

       159
       156
        
       :::

+1 -3

nixos/lib/make-options-doc/default.nix

···

       117
       117
        
       # deprecated since 23.11.

     

       118
       118
        
       # TODO remove in a while.

     

       119
       119
        
       , allowDocBook ? false

     

       120
       120
       -
       # whether lib.mdDoc is required for descriptions to be read as markdown.

     

       121
       121
       -
       # deprecated since 23.11.

     

       122
       122
       -
       # TODO remove in a while.

     

       120
       120
       +
       # TODO remove in a while (see https://github.com/NixOS/nixpkgs/issues/300735)

     

       123
       121
        
       , markdownByDefault ? true

     

       124
       122
        
       }:

     

       125
       123

+4 -5

nixos/lib/systemd-types.nix

···

       31
       31
        
           ;

     

       32
       32
        
       

     

       33
       33
        
         inherit (lib)

     

       34
       34
       -
           mdDoc

     

       35
       34
        
           mkDefault

     

       36
       35
        
           mkDerivedConfig

     

       37
       36
        
           mkEnableOption

     
···

       81
       80
        
       

     

       82
       81
        
         initrdContents = attrsOf (submodule ({ config, options, name, ... }: {

     

       83
       82
        
           options = {

     

       84
       84
       -
             enable = mkEnableOption (mdDoc "copying of this file and symlinking it") // { default = true; };

     

       83
       83
       +
             enable = (mkEnableOption "copying of this file and symlinking it") // { default = true; };

     

       85
       84
        
       

     

       86
       85
        
             target = mkOption {

     

       87
       86
        
               type = path;

     

       88
       88
       -
               description = mdDoc ''

     

       87
       87
       +
               description = ''

     

       89
       88
        
                 Path of the symlink.

     

       90
       89
        
               '';

     

       91
       90
        
               default = name;

     
···

       94
       93
        
             text = mkOption {

     

       95
       94
        
               default = null;

     

       96
       95
        
               type = nullOr lines;

     

       97
       97
       -
               description = mdDoc "Text of the file.";

     

       96
       96
       +
               description = "Text of the file.";

     

       98
       97
        
             };

     

       99
       98
        
       

     

       100
       99
        
             source = mkOption {

     

       101
       100
        
               type = path;

     

       102
       102
       -
               description = mdDoc "Path of the source file.";

     

       101
       101
       +
               description = "Path of the source file.";

     

       103
       102
        
             };

     

       104
       103
        
           };

     

       105
       104

+54 -55

nixos/lib/systemd-unit-options.nix

···

       17
       17
        
           concatMap

     

       18
       18
        
           filterOverrides

     

       19
       19
        
           isList

     

       20
       20
       -
           mdDoc

     

       21
       20
        
           mergeEqualOption

     

       22
       21
        
           mkIf

     

       23
       22
        
           mkMerge

     
···

       55
       54
        
           enable = mkOption {

     

       56
       55
        
             default = true;

     

       57
       56
        
             type = types.bool;

     

       58
       58
       -
             description = mdDoc ''

     

       57
       57
       +
             description = ''

     

       59
       58
        
               If set to false, this unit will be a symlink to

     

       60
       59
        
               /dev/null. This is primarily useful to prevent specific

     

       61
       60
        
               template instances

     
···

       69
       68
        
           overrideStrategy = mkOption {

     

       70
       69
        
             default = "asDropinIfExists";

     

       71
       70
        
             type = types.enum [ "asDropinIfExists" "asDropin" ];

     

       72
       72
       -
             description = mdDoc ''

     

       71
       71
       +
             description = ''

     

       73
       72
        
               Defines how unit configuration is provided for systemd:

     

       74
       73
        
       

     

       75
       74
        
               `asDropinIfExists` creates a unit file when no unit file is provided by the package

     
···

       85
       84
        
           requiredBy = mkOption {

     

       86
       85
        
             default = [];

     

       87
       86
        
             type = types.listOf unitNameType;

     

       88
       88
       -
             description = mdDoc ''

     

       87
       87
       +
             description = ''

     

       89
       88
        
               Units that require (i.e. depend on and need to go down with) this unit.

     

       90
       89
        
               As discussed in the `wantedBy` option description this also creates

     

       91
       90
        
               `.requires` symlinks automatically.

     
···

       95
       94
        
           upheldBy = mkOption {

     

       96
       95
        
             default = [];

     

       97
       96
        
             type = types.listOf unitNameType;

     

       98
       98
       -
             description = mdDoc ''

     

       97
       97
       +
             description = ''

     

       99
       98
        
               Keep this unit running as long as the listed units are running. This is a continuously

     

       100
       99
        
               enforced version of wantedBy.

     

       101
       100
        
             '';

     
···

       104
       103
        
           wantedBy = mkOption {

     

       105
       104
        
             default = [];

     

       106
       105
        
             type = types.listOf unitNameType;

     

       107
       107
       -
             description = mdDoc ''

     

       106
       106
       +
             description = ''

     

       108
       107
        
               Units that want (i.e. depend on) this unit. The default method for

     

       109
       108
        
               starting a unit by default at boot time is to set this option to

     

       110
       109
        
               `["multi-user.target"]` for system services. Likewise for user units

     
···

       122
       121
        
           aliases = mkOption {

     

       123
       122
        
             default = [];

     

       124
       123
        
             type = types.listOf unitNameType;

     

       125
       125
       -
             description = mdDoc "Aliases of that unit.";

     

       124
       124
       +
             description = "Aliases of that unit.";

     

       126
       125
        
           };

     

       127
       126
        
       

     

       128
       127
        
         };

     
···

       132
       131
        
           text = mkOption {

     

       133
       132
        
             type = types.nullOr types.str;

     

       134
       133
        
             default = null;

     

       135
       135
       -
             description = mdDoc "Text of this systemd unit.";

     

       134
       134
       +
             description = "Text of this systemd unit.";

     

       136
       135
        
           };

     

       137
       136
        
       

     

       138
       137
        
           unit = mkOption {

     

       139
       138
        
             internal = true;

     

       140
       140
       -
             description = mdDoc "The generated unit.";

     

       139
       139
       +
             description = "The generated unit.";

     

       141
       140
        
           };

     

       142
       141
        
       

     

       143
       142
        
         };

     
···

       148
       147
        
             description = mkOption {

     

       149
       148
        
               default = "";

     

       150
       149
        
               type = types.singleLineStr;

     

       151
       151
       -
               description = mdDoc "Description of this unit used in systemd messages and progress indicators.";

     

       150
       150
       +
               description = "Description of this unit used in systemd messages and progress indicators.";

     

       152
       151
        
             };

     

       153
       152
        
       

     

       154
       153
        
             documentation = mkOption {

     

       155
       154
        
               default = [];

     

       156
       155
        
               type = types.listOf types.str;

     

       157
       157
       -
               description = mdDoc "A list of URIs referencing documentation for this unit or its configuration.";

     

       156
       156
       +
               description = "A list of URIs referencing documentation for this unit or its configuration.";

     

       158
       157
        
             };

     

       159
       158
        
       

     

       160
       159
        
             requires = mkOption {

     

       161
       160
        
               default = [];

     

       162
       161
        
               type = types.listOf unitNameType;

     

       163
       163
       -
               description = mdDoc ''

     

       162
       162
       +
               description = ''

     

       164
       163
        
                 Start the specified units when this unit is started, and stop

     

       165
       164
        
                 this unit when the specified units are stopped or fail.

     

       166
       165
        
               '';

     
···

       169
       168
        
             wants = mkOption {

     

       170
       169
        
               default = [];

     

       171
       170
        
               type = types.listOf unitNameType;

     

       172
       172
       -
               description = mdDoc ''

     

       171
       171
       +
               description = ''

     

       173
       172
        
                 Start the specified units when this unit is started.

     

       174
       173
        
               '';

     

       175
       174
        
             };

     
···

       177
       176
        
             upholds = mkOption {

     

       178
       177
        
               default = [];

     

       179
       178
        
               type = types.listOf unitNameType;

     

       180
       180
       -
               description = mdDoc ''

     

       179
       179
       +
               description = ''

     

       181
       180
        
                 Keeps the specified running while this unit is running. A continuous version of `wants`.

     

       182
       181
        
               '';

     

       183
       182
        
             };

     
···

       185
       184
        
             after = mkOption {

     

       186
       185
        
               default = [];

     

       187
       186
        
               type = types.listOf unitNameType;

     

       188
       188
       -
               description = mdDoc ''

     

       187
       187
       +
               description = ''

     

       189
       188
        
                 If the specified units are started at the same time as

     

       190
       189
        
                 this unit, delay this unit until they have started.

     

       191
       190
        
               '';

     
···

       194
       193
        
             before = mkOption {

     

       195
       194
        
               default = [];

     

       196
       195
        
               type = types.listOf unitNameType;

     

       197
       197
       -
               description = mdDoc ''

     

       196
       196
       +
               description = ''

     

       198
       197
        
                 If the specified units are started at the same time as

     

       199
       198
        
                 this unit, delay them until this unit has started.

     

       200
       199
        
               '';

     
···

       203
       202
        
             bindsTo = mkOption {

     

       204
       203
        
               default = [];

     

       205
       204
        
               type = types.listOf unitNameType;

     

       206
       206
       -
               description = mdDoc ''

     

       205
       205
       +
               description = ''

     

       207
       206
        
                 Like ‘requires’, but in addition, if the specified units

     

       208
       207
        
                 unexpectedly disappear, this unit will be stopped as well.

     

       209
       208
        
               '';

     
···

       212
       211
        
             partOf = mkOption {

     

       213
       212
        
               default = [];

     

       214
       213
        
               type = types.listOf unitNameType;

     

       215
       215
       -
               description = mdDoc ''

     

       214
       214
       +
               description = ''

     

       216
       215
        
                 If the specified units are stopped or restarted, then this

     

       217
       216
        
                 unit is stopped or restarted as well.

     

       218
       217
        
               '';

     
···

       221
       220
        
             conflicts = mkOption {

     

       222
       221
        
               default = [];

     

       223
       222
        
               type = types.listOf unitNameType;

     

       224
       224
       -
               description = mdDoc ''

     

       223
       223
       +
               description = ''

     

       225
       224
        
                 If the specified units are started, then this unit is stopped

     

       226
       225
        
                 and vice versa.

     

       227
       226
        
               '';

     
···

       230
       229
        
             requisite = mkOption {

     

       231
       230
        
               default = [];

     

       232
       231
        
               type = types.listOf unitNameType;

     

       233
       233
       -
               description = mdDoc ''

     

       232
       232
       +
               description = ''

     

       234
       233
        
                 Similar to requires. However if the units listed are not started,

     

       235
       234
        
                 they will not be started and the transaction will fail.

     

       236
       235
        
               '';

     
···

       240
       239
        
               default = {};

     

       241
       240
        
               example = { RequiresMountsFor = "/data"; };

     

       242
       241
        
               type = types.attrsOf unitOption;

     

       243
       243
       -
               description = mdDoc ''

     

       242
       242
       +
               description = ''

     

       244
       243
        
                 Each attribute in this set specifies an option in the

     

       245
       244
        
                 `[Unit]` section of the unit.  See

     

       246
       245
        
                 {manpage}`systemd.unit(5)` for details.

     
···

       250
       249
        
             onFailure = mkOption {

     

       251
       250
        
               default = [];

     

       252
       251
        
               type = types.listOf unitNameType;

     

       253
       253
       -
               description = mdDoc ''

     

       252
       252
       +
               description = ''

     

       254
       253
        
                 A list of one or more units that are activated when

     

       255
       254
        
                 this unit enters the "failed" state.

     

       256
       255
        
               '';

     
···

       259
       258
        
             onSuccess = mkOption {

     

       260
       259
        
               default = [];

     

       261
       260
        
               type = types.listOf unitNameType;

     

       262
       262
       -
               description = mdDoc ''

     

       261
       261
       +
               description = ''

     

       263
       262
        
                 A list of one or more units that are activated when

     

       264
       263
        
                 this unit enters the "inactive" state.

     

       265
       264
        
               '';

     
···

       267
       266
        
       

     

       268
       267
        
             startLimitBurst = mkOption {

     

       269
       268
        
                type = types.int;

     

       270
       270
       -
                description = mdDoc ''

     

       269
       269
       +
                description = ''

     

       271
       270
        
                  Configure unit start rate limiting. Units which are started

     

       272
       271
        
                  more than startLimitBurst times within an interval time

     

       273
       272
        
                  interval are not permitted to start any more.

     
···

       276
       275
        
       

     

       277
       276
        
             startLimitIntervalSec = mkOption {

     

       278
       277
        
                type = types.int;

     

       279
       279
       -
                description = mdDoc ''

     

       278
       278
       +
                description = ''

     

       280
       279
        
                  Configure unit start rate limiting. Units which are started

     

       281
       280
        
                  more than startLimitBurst times within an interval time

     

       282
       281
        
                  interval are not permitted to start any more.

     
···

       295
       294
        
             restartTriggers = mkOption {

     

       296
       295
        
               default = [];

     

       297
       296
        
               type = types.listOf types.unspecified;

     

       298
       298
       -
               description = mdDoc ''

     

       297
       297
       +
               description = ''

     

       299
       298
        
                 An arbitrary list of items such as derivations.  If any item

     

       300
       299
        
                 in the list changes between reconfigurations, the service will

     

       301
       300
        
                 be restarted.

     
···

       305
       304
        
             reloadTriggers = mkOption {

     

       306
       305
        
               default = [];

     

       307
       306
        
               type = types.listOf unitOption;

     

       308
       308
       -
               description = mdDoc ''

     

       307
       307
       +
               description = ''

     

       309
       308
        
                 An arbitrary list of items such as derivations.  If any item

     

       310
       309
        
                 in the list changes between reconfigurations, the service will

     

       311
       310
        
                 be reloaded.  If anything but a reload trigger changes in the

     
···

       323
       322
        
               default = {};

     

       324
       323
        
               type = with types; attrsOf (nullOr (oneOf [ str path package ]));

     

       325
       324
        
               example = { PATH = "/foo/bar/bin"; LANG = "nl_NL.UTF-8"; };

     

       326
       326
       -
               description = mdDoc "Environment variables passed to the service's processes.";

     

       325
       325
       +
               description = "Environment variables passed to the service's processes.";

     

       327
       326
        
             };

     

       328
       327
        
       

     

       329
       328
        
             path = mkOption {

     

       330
       329
        
               default = [];

     

       331
       330
        
               type = with types; listOf (oneOf [ package str ]);

     

       332
       332
       -
               description = mdDoc ''

     

       331
       331
       +
               description = ''

     

       333
       332
        
                 Packages added to the service's {env}`PATH`

     

       334
       333
        
                 environment variable.  Both the {file}`bin`

     

       335
       334
        
                 and {file}`sbin` subdirectories of each

     
···

       343
       342
        
                 { RestartSec = 5;

     

       344
       343
        
                 };

     

       345
       344
        
               type = types.addCheck (types.attrsOf unitOption) checkService;

     

       346
       346
       -
               description = mdDoc ''

     

       345
       345
       +
               description = ''

     

       347
       346
        
                 Each attribute in this set specifies an option in the

     

       348
       347
        
                 `[Service]` section of the unit.  See

     

       349
       348
        
                 {manpage}`systemd.service(5)` for details.

     
···

       353
       352
        
             script = mkOption {

     

       354
       353
        
               type = types.lines;

     

       355
       354
        
               default = "";

     

       356
       356
       -
               description = mdDoc "Shell commands executed as the service's main process.";

     

       355
       355
       +
               description = "Shell commands executed as the service's main process.";

     

       357
       356
        
             };

     

       358
       357
        
       

     

       359
       358
        
             scriptArgs = mkOption {

     

       360
       359
        
               type = types.str;

     

       361
       360
        
               default = "";

     

       362
       361
        
               example = "%i";

     

       363
       363
       -
               description = mdDoc ''

     

       362
       362
       +
               description = ''

     

       364
       363
        
                 Arguments passed to the main process script.

     

       365
       364
        
                 Can contain specifiers (`%` placeholders expanded by systemd, see {manpage}`systemd.unit(5)`).

     

       366
       365
        
               '';

     
···

       369
       368
        
             preStart = mkOption {

     

       370
       369
        
               type = types.lines;

     

       371
       370
        
               default = "";

     

       372
       372
       -
               description = mdDoc ''

     

       371
       371
       +
               description = ''

     

       373
       372
        
                 Shell commands executed before the service's main process

     

       374
       373
        
                 is started.

     

       375
       374
        
               '';

     
···

       378
       377
        
             postStart = mkOption {

     

       379
       378
        
               type = types.lines;

     

       380
       379
        
               default = "";

     

       381
       381
       -
               description = mdDoc ''

     

       380
       380
       +
               description = ''

     

       382
       381
        
                 Shell commands executed after the service's main process

     

       383
       382
        
                 is started.

     

       384
       383
        
               '';

     
···

       387
       386
        
             reload = mkOption {

     

       388
       387
        
               type = types.lines;

     

       389
       388
        
               default = "";

     

       390
       390
       -
               description = mdDoc ''

     

       389
       389
       +
               description = ''

     

       391
       390
        
                 Shell commands executed when the service's main process

     

       392
       391
        
                 is reloaded.

     

       393
       392
        
               '';

     
···

       396
       395
        
             preStop = mkOption {

     

       397
       396
        
               type = types.lines;

     

       398
       397
        
               default = "";

     

       399
       399
       -
               description = mdDoc ''

     

       398
       398
       +
               description = ''

     

       400
       399
        
                 Shell commands executed to stop the service.

     

       401
       400
        
               '';

     

       402
       401
        
             };

     
···

       404
       403
        
             postStop = mkOption {

     

       405
       404
        
               type = types.lines;

     

       406
       405
        
               default = "";

     

       407
       407
       -
               description = mdDoc ''

     

       406
       406
       +
               description = ''

     

       408
       407
        
                 Shell commands executed after the service's main process

     

       409
       408
        
                 has exited.

     

       410
       409
        
               '';

     
···

       413
       412
        
             jobScripts = mkOption {

     

       414
       413
        
               type = with types; coercedTo path singleton (listOf path);

     

       415
       414
        
               internal = true;

     

       416
       416
       -
               description = mdDoc "A list of all job script derivations of this unit.";

     

       415
       415
       +
               description = "A list of all job script derivations of this unit.";

     

       417
       416
        
               default = [];

     

       418
       417
        
             };

     

       419
       418
        
       

     
···

       458
       457
        
             restartIfChanged = mkOption {

     

       459
       458
        
               type = types.bool;

     

       460
       459
        
               default = true;

     

       461
       461
       -
               description = mdDoc ''

     

       460
       460
       +
               description = ''

     

       462
       461
        
                 Whether the service should be restarted during a NixOS

     

       463
       462
        
                 configuration switch if its definition has changed.

     

       464
       463
        
               '';

     
···

       467
       466
        
             reloadIfChanged = mkOption {

     

       468
       467
        
               type = types.bool;

     

       469
       468
        
               default = false;

     

       470
       470
       -
               description = mdDoc ''

     

       469
       469
       +
               description = ''

     

       471
       470
        
                 Whether the service should be reloaded during a NixOS

     

       472
       471
        
                 configuration switch if its definition has changed.  If

     

       473
       472
        
                 enabled, the value of {option}`restartIfChanged` is

     
···

       483
       482
        
             stopIfChanged = mkOption {

     

       484
       483
        
               type = types.bool;

     

       485
       484
        
               default = true;

     

       486
       486
       -
               description = mdDoc ''

     

       485
       485
       +
               description = ''

     

       487
       486
        
                 If set, a changed unit is restarted by calling

     

       488
       487
        
                 {command}`systemctl stop` in the old configuration,

     

       489
       488
        
                 then {command}`systemctl start` in the new one.

     
···

       499
       498
        
               type = with types; either str (listOf str);

     

       500
       499
        
               default = [];

     

       501
       500
        
               example = "Sun 14:00:00";

     

       502
       502
       -
               description = mdDoc ''

     

       501
       501
       +
               description = ''

     

       503
       502
        
                 Automatically start this unit at the given date/time, which

     

       504
       503
        
                 must be in the format described in

     

       505
       504
        
                 {manpage}`systemd.time(7)`.  This is equivalent

     
···

       526
       525
        
               default = [];

     

       527
       526
        
               type = types.listOf types.str;

     

       528
       527
        
               example = [ "0.0.0.0:993" "/run/my-socket" ];

     

       529
       529
       -
               description = mdDoc ''

     

       528
       528
       +
               description = ''

     

       530
       529
        
                 For each item in this list, a `ListenStream`

     

       531
       530
        
                 option in the `[Socket]` section will be created.

     

       532
       531
        
               '';

     
···

       536
       535
        
               default = [];

     

       537
       536
        
               type = types.listOf types.str;

     

       538
       537
        
               example = [ "0.0.0.0:993" "/run/my-socket" ];

     

       539
       539
       -
               description = mdDoc ''

     

       538
       538
       +
               description = ''

     

       540
       539
        
                 For each item in this list, a `ListenDatagram`

     

       541
       540
        
                 option in the `[Socket]` section will be created.

     

       542
       541
        
               '';

     
···

       546
       545
        
               default = {};

     

       547
       546
        
               example = { ListenStream = "/run/my-socket"; };

     

       548
       547
        
               type = types.attrsOf unitOption;

     

       549
       549
       -
               description = mdDoc ''

     

       548
       548
       +
               description = ''

     

       550
       549
        
                 Each attribute in this set specifies an option in the

     

       551
       550
        
                 `[Socket]` section of the unit.  See

     

       552
       551
        
                 {manpage}`systemd.socket(5)` for details.

     
···

       578
       577
        
               default = {};

     

       579
       578
        
               example = { OnCalendar = "Sun 14:00:00"; Unit = "foo.service"; };

     

       580
       579
        
               type = types.attrsOf unitOption;

     

       581
       581
       -
               description = mdDoc ''

     

       580
       580
       +
               description = ''

     

       582
       581
        
                 Each attribute in this set specifies an option in the

     

       583
       582
        
                 `[Timer]` section of the unit.  See

     

       584
       583
        
                 {manpage}`systemd.timer(5)` and

     
···

       611
       610
        
               default = {};

     

       612
       611
        
               example = { PathChanged = "/some/path"; Unit = "changedpath.service"; };

     

       613
       612
        
               type = types.attrsOf unitOption;

     

       614
       614
       -
               description = mdDoc ''

     

       613
       613
       +
               description = ''

     

       615
       614
        
                 Each attribute in this set specifies an option in the

     

       616
       615
        
                 `[Path]` section of the unit.  See

     

       617
       616
        
                 {manpage}`systemd.path(5)` for details.

     
···

       642
       641
        
             what = mkOption {

     

       643
       642
        
               example = "/dev/sda1";

     

       644
       643
        
               type = types.str;

     

       645
       645
       -
               description = mdDoc "Absolute path of device node, file or other resource. (Mandatory)";

     

       644
       644
       +
               description = "Absolute path of device node, file or other resource. (Mandatory)";

     

       646
       645
        
             };

     

       647
       646
        
       

     

       648
       647
        
             where = mkOption {

     

       649
       648
        
               example = "/mnt";

     

       650
       649
        
               type = types.str;

     

       651
       651
       -
               description = mdDoc ''

     

       650
       650
       +
               description = ''

     

       652
       651
        
                 Absolute path of a directory of the mount point.

     

       653
       652
        
                 Will be created if it doesn't exist. (Mandatory)

     

       654
       653
        
               '';

     
···

       658
       657
        
               default = "";

     

       659
       658
        
               example = "ext4";

     

       660
       659
        
               type = types.str;

     

       661
       661
       -
               description = mdDoc "File system type.";

     

       660
       660
       +
               description = "File system type.";

     

       662
       661
        
             };

     

       663
       662
        
       

     

       664
       663
        
             options = mkOption {

     

       665
       664
        
               default = "";

     

       666
       665
        
               example = "noatime";

     

       667
       666
        
               type = types.commas;

     

       668
       668
       -
               description = mdDoc "Options used to mount the file system.";

     

       667
       667
       +
               description = "Options used to mount the file system.";

     

       669
       668
        
             };

     

       670
       669
        
       

     

       671
       670
        
             mountConfig = mkOption {

     

       672
       671
        
               default = {};

     

       673
       672
        
               example = { DirectoryMode = "0775"; };

     

       674
       673
        
               type = types.attrsOf unitOption;

     

       675
       675
       -
               description = mdDoc ''

     

       674
       674
       +
               description = ''

     

       676
       675
        
                 Each attribute in this set specifies an option in the

     

       677
       676
        
                 `[Mount]` section of the unit.  See

     

       678
       677
        
                 {manpage}`systemd.mount(5)` for details.

     
···

       702
       701
        
             where = mkOption {

     

       703
       702
        
               example = "/mnt";

     

       704
       703
        
               type = types.str;

     

       705
       705
       -
               description = mdDoc ''

     

       704
       704
       +
               description = ''

     

       706
       705
        
                 Absolute path of a directory of the mount point.

     

       707
       706
        
                 Will be created if it doesn't exist. (Mandatory)

     

       708
       707
        
               '';

     
···

       712
       711
        
               default = {};

     

       713
       712
        
               example = { DirectoryMode = "0775"; };

     

       714
       713
        
               type = types.attrsOf unitOption;

     

       715
       715
       -
               description = mdDoc ''

     

       714
       714
       +
               description = ''

     

       716
       715
        
                 Each attribute in this set specifies an option in the

     

       717
       716
        
                 `[Automount]` section of the unit.  See

     

       718
       717
        
                 {manpage}`systemd.automount(5)` for details.

     
···

       743
       742
        
               default = {};

     

       744
       743
        
               example = { MemoryMax = "2G"; };

     

       745
       744
        
               type = types.attrsOf unitOption;

     

       746
       746
       -
               description = mdDoc ''

     

       745
       745
       +
               description = ''

     

       747
       746
        
                 Each attribute in this set specifies an option in the

     

       748
       747
        
                 `[Slice]` section of the unit.  See

     

       749
       748
        
                 {manpage}`systemd.slice(5)` for details.

+10 -10

nixos/lib/testing/driver.nix

···

       1
       1
        
       { config, lib, hostPkgs, ... }:

     

       2
       2
        
       let

     

       3
       3
       -
         inherit (lib) mkOption types literalMD mdDoc;

     

       3
       3
       +
         inherit (lib) mkOption types literalMD;

     

       4
       4
        
       

     

       5
       5
        
         # Reifies and correctly wraps the python test driver for

     

       6
       6
        
         # the respective qemu version and with or without ocr support

     
···

       104
       104
        
         options = {

     

       105
       105
        
       

     

       106
       106
        
           driver = mkOption {

     

       107
       107
       -
             description = mdDoc "Package containing a script that runs the test.";

     

       107
       107
       +
             description = "Package containing a script that runs the test.";

     

       108
       108
        
             type = types.package;

     

       109
       109
        
             defaultText = literalMD "set by the test framework";

     

       110
       110
        
           };

     

       111
       111
        
       

     

       112
       112
        
           hostPkgs = mkOption {

     

       113
       113
       -
             description = mdDoc "Nixpkgs attrset used outside the nodes.";

     

       113
       113
       +
             description = "Nixpkgs attrset used outside the nodes.";

     

       114
       114
        
             type = types.raw;

     

       115
       115
        
             example = lib.literalExpression ''

     

       116
       116
        
               import nixpkgs { inherit system config overlays; }

     
···

       118
       118
        
           };

     

       119
       119
        
       

     

       120
       120
        
           qemu.package = mkOption {

     

       121
       121
       -
             description = mdDoc "Which qemu package to use for the virtualisation of [{option}`nodes`](#test-opt-nodes).";

     

       121
       121
       +
             description = "Which qemu package to use for the virtualisation of [{option}`nodes`](#test-opt-nodes).";

     

       122
       122
        
             type = types.package;

     

       123
       123
        
             default = hostPkgs.qemu_test;

     

       124
       124
        
             defaultText = "hostPkgs.qemu_test";

     

       125
       125
        
           };

     

       126
       126
        
       

     

       127
       127
        
           globalTimeout = mkOption {

     

       128
       128
       -
             description = mdDoc ''

     

       128
       128
       +
             description = ''

     

       129
       129
        
               A global timeout for the complete test, expressed in seconds.

     

       130
       130
        
               Beyond that timeout, every resource will be killed and released and the test will fail.

     

       131
       131
        
       

     
···

       137
       137
        
           };

     

       138
       138
        
       

     

       139
       139
        
           enableOCR = mkOption {

     

       140
       140
       -
             description = mdDoc ''

     

       140
       140
       +
             description = ''

     

       141
       141
        
               Whether to enable Optical Character Recognition functionality for

     

       142
       142
        
               testing graphical programs. See [Machine objects](`ssec-machine-objects`).

     

       143
       143
        
             '';

     
···

       146
       146
        
           };

     

       147
       147
        
       

     

       148
       148
        
           extraPythonPackages = mkOption {

     

       149
       149
       -
             description = mdDoc ''

     

       149
       149
       +
             description = ''

     

       150
       150
        
               Python packages to add to the test driver.

     

       151
       151
        
       

     

       152
       152
        
               The argument is a Python package set, similar to `pkgs.pythonPackages`.

     
···

       159
       159
        
           };

     

       160
       160
        
       

     

       161
       161
        
           extraDriverArgs = mkOption {

     

       162
       162
       -
             description = mdDoc ''

     

       162
       162
       +
             description = ''

     

       163
       163
        
               Extra arguments to pass to the test driver.

     

       164
       164
        
       

     

       165
       165
        
               They become part of [{option}`driver`](#test-opt-driver) via `wrapProgram`.

     
···

       171
       171
        
           skipLint = mkOption {

     

       172
       172
        
             type = types.bool;

     

       173
       173
        
             default = false;

     

       174
       174
       -
             description = mdDoc ''

     

       174
       174
       +
             description = ''

     

       175
       175
        
               Do not run the linters. This may speed up your iteration cycle, but it is not something you should commit.

     

       176
       176
        
             '';

     

       177
       177
        
           };

     
···

       179
       179
        
           skipTypeCheck = mkOption {

     

       180
       180
        
             type = types.bool;

     

       181
       181
        
             default = false;

     

       182
       182
       -
             description = mdDoc ''

     

       182
       182
       +
             description = ''

     

       183
       183
        
               Disable type checking. This must not be enabled for new NixOS tests.

     

       184
       184
        
       

     

       185
       185
        
               This may speed up your iteration cycle, unless you're working on the [{option}`testScript`](#test-opt-testScript).

+2 -2

nixos/lib/testing/interactive.nix

···

       1
       1
        
       { config, lib, moduleType, hostPkgs, ... }:

     

       2
       2
        
       let

     

       3
       3
       -
         inherit (lib) mkOption types mdDoc;

     

       3
       3
       +
         inherit (lib) mkOption types;

     

       4
       4
        
       in

     

       5
       5
        
       {

     

       6
       6
        
         options = {

     

       7
       7
        
           interactive = mkOption {

     

       8
       8
       -
             description = mdDoc ''

     

       8
       8
       +
             description = ''

     

       9
       9
        
               Tests [can be run interactively](#sec-running-nixos-tests-interactively)

     

       10
       10
        
               using the program in the test derivation's `.driverInteractive` attribute.

     

       11
       11

+5 -5

nixos/lib/testing/meta.nix

···

       1
       1
        
       { lib, ... }:

     

       2
       2
        
       let

     

       3
       3
       -
         inherit (lib) types mkOption mdDoc;

     

       3
       3
       +
         inherit (lib) types mkOption;

     

       4
       4
        
       in

     

       5
       5
        
       {

     

       6
       6
        
         options = {

     

       7
       7
        
           meta = lib.mkOption {

     

       8
       8
       -
             description = mdDoc ''

     

       8
       8
       +
             description = ''

     

       9
       9
        
               The [`meta`](https://nixos.org/manual/nixpkgs/stable/#chap-meta) attributes that will be set on the returned derivations.

     

       10
       10
        
       

     

       11
       11
        
               Not all [`meta`](https://nixos.org/manual/nixpkgs/stable/#chap-meta) attributes are supported, but more can be added as desired.

     
···

       16
       16
        
                 maintainers = lib.mkOption {

     

       17
       17
        
                   type = types.listOf types.raw;

     

       18
       18
        
                   default = [];

     

       19
       19
       -
                   description = mdDoc ''

     

       19
       19
       +
                   description = ''

     

       20
       20
        
                     The [list of maintainers](https://nixos.org/manual/nixpkgs/stable/#var-meta-maintainers) for this test.

     

       21
       21
        
                   '';

     

       22
       22
        
                 };

     

       23
       23
        
                 timeout = lib.mkOption {

     

       24
       24
        
                   type = types.nullOr types.int;

     

       25
       25
        
                   default = 3600;  # 1 hour

     

       26
       26
       -
                   description = mdDoc ''

     

       26
       26
       +
                   description = ''

     

       27
       27
        
                     The [{option}`test`](#test-opt-test)'s [`meta.timeout`](https://nixos.org/manual/nixpkgs/stable/#var-meta-timeout) in seconds.

     

       28
       28
        
                   '';

     

       29
       29
        
                 };

     

       30
       30
        
                 broken = lib.mkOption {

     

       31
       31
        
                   type = types.bool;

     

       32
       32
        
                   default = false;

     

       33
       33
       -
                   description = mdDoc ''

     

       33
       33
       +
                   description = ''

     

       34
       34
        
                     Sets the [`meta.broken`](https://nixos.org/manual/nixpkgs/stable/#var-meta-broken) attribute on the [{option}`test`](#test-opt-test) derivation.

     

       35
       35
        
                   '';

     

       36
       36
        
                 };

+2 -2

nixos/lib/testing/name.nix

···

       1
       1
        
       { lib, ... }:

     

       2
       2
        
       let

     

       3
       3
       -
         inherit (lib) mkOption types mdDoc;

     

       3
       3
       +
         inherit (lib) mkOption types;

     

       4
       4
        
       in

     

       5
       5
        
       {

     

       6
       6
        
         options.name = mkOption {

     

       7
       7
       -
           description = mdDoc ''

     

       7
       7
       +
           description = ''

     

       8
       8
        
             The name of the test.

     

       9
       9
        
       

     

       10
       10
        
             This is used in the derivation names of the [{option}`driver`](#test-opt-driver) and [{option}`test`](#test-opt-test) runner.

+2 -3

nixos/lib/testing/network.nix

···

       5
       5
        
           attrNames concatMap concatMapStrings flip forEach head

     

       6
       6
        
           listToAttrs mkDefault mkOption nameValuePair optionalString

     

       7
       7
        
           range toLower types zipListsWith zipLists

     

       8
       8
       -
           mdDoc

     

       9
       8
        
           ;

     

       10
       9
        
       

     

       11
       10
        
         nodeNumbers =

     
···

       89
       88
        
               default = name;

     

       90
       89
        
               # We need to force this in specilisations, otherwise it'd be

     

       91
       90
        
               # readOnly = true;

     

       92
       92
       -
               description = mdDoc ''

     

       91
       91
       +
               description = ''

     

       93
       92
        
                 The `name` in `nodes.<name>`; stable across `specialisations`.

     

       94
       93
        
               '';

     

       95
       94
        
             };

     
···

       98
       97
        
               type = types.int;

     

       99
       98
        
               readOnly = true;

     

       100
       99
        
               default = nodeNumbers.${config.virtualisation.test.nodeName};

     

       101
       101
       -
               description = mdDoc ''

     

       100
       100
       +
               description = ''

     

       102
       101
        
                 A unique number assigned for each node in `nodes`.

     

       103
       102
        
               '';

     

       104
       103
        
             };

+7 -8

nixos/lib/testing/nodes.nix

···

       5
       5
        
           literalExpression

     

       6
       6
        
           literalMD

     

       7
       7
        
           mapAttrs

     

       8
       8
       -
           mdDoc

     

       9
       8
        
           mkDefault

     

       10
       9
        
           mkIf

     

       11
       10
        
           mkOption mkForce

     
···

       76
       75
        
           nodes = mkOption {

     

       77
       76
        
             type = types.lazyAttrsOf config.node.type;

     

       78
       77
        
             visible = "shallow";

     

       79
       79
       -
             description = mdDoc ''

     

       78
       78
       +
             description = ''

     

       80
       79
        
               An attribute set of NixOS configuration modules.

     

       81
       80
        
       

     

       82
       81
        
               The configurations are augmented by the [`defaults`](#test-opt-defaults) option.

     
···

       88
       87
        
           };

     

       89
       88
        
       

     

       90
       89
        
           defaults = mkOption {

     

       91
       91
       -
             description = mdDoc ''

     

       90
       90
       +
             description = ''

     

       92
       91
        
               NixOS configuration that is applied to all [{option}`nodes`](#test-opt-nodes).

     

       93
       92
        
             '';

     

       94
       93
        
             type = types.deferredModule;

     
···

       96
       95
        
           };

     

       97
       96
        
       

     

       98
       97
        
           extraBaseModules = mkOption {

     

       99
       99
       -
             description = mdDoc ''

     

       98
       98
       +
             description = ''

     

       100
       99
        
               NixOS configuration that, like [{option}`defaults`](#test-opt-defaults), is applied to all [{option}`nodes`](#test-opt-nodes) and can not be undone with [`specialisation.<name>.inheritParentConfig`](https://search.nixos.org/options?show=specialisation.%3Cname%3E.inheritParentConfig&from=0&size=50&sort=relevance&type=packages&query=specialisation).

     

       101
       100
        
             '';

     

       102
       101
        
             type = types.deferredModule;

     
···

       104
       103
        
           };

     

       105
       104
        
       

     

       106
       105
        
           node.pkgs = mkOption {

     

       107
       107
       -
             description = mdDoc ''

     

       106
       106
       +
             description = ''

     

       108
       107
        
               The Nixpkgs to use for the nodes.

     

       109
       108
        
       

     

       110
       109
        
               Setting this will make the `nixpkgs.*` options read-only, to avoid mistakenly testing with a Nixpkgs configuration that diverges from regular use.

     
···

       117
       116
        
           };

     

       118
       117
        
       

     

       119
       118
        
           node.pkgsReadOnly = mkOption {

     

       120
       120
       -
             description = mdDoc ''

     

       119
       119
       +
             description = ''

     

       121
       120
        
               Whether to make the `nixpkgs.*` options read-only. This is only relevant when [`node.pkgs`](#test-opt-node.pkgs) is set.

     

       122
       121
        
       

     

       123
       122
        
               Set this to `false` when any of the [`nodes`](#test-opt-nodes) needs to configure any of the `nixpkgs.*` options. This will slow down evaluation of your test a bit.

     
···

       130
       129
        
           node.specialArgs = mkOption {

     

       131
       130
        
             type = types.lazyAttrsOf types.raw;

     

       132
       131
        
             default = { };

     

       133
       133
       -
             description = mdDoc ''

     

       132
       132
       +
             description = ''

     

       134
       133
        
               An attribute set of arbitrary values that will be made available as module arguments during the resolution of module `imports`.

     

       135
       134
        
       

     

       136
       135
        
               Note that it is not possible to override these from within the NixOS configurations. If you argument is not relevant to `imports`, consider setting {option}`defaults._module.args.<name>` instead.

     
···

       139
       138
        
       

     

       140
       139
        
           nodesCompat = mkOption {

     

       141
       140
        
             internal = true;

     

       142
       142
       -
             description = mdDoc ''

     

       141
       141
       +
             description = ''

     

       143
       142
        
               Basically `_module.args.nodes`, but with backcompat and warnings added.

     

       144
       143
        
       

     

       145
       144
        
               This will go away.

+4 -4

nixos/lib/testing/run.nix

···

       1
       1
        
       { config, hostPkgs, lib, ... }:

     

       2
       2
        
       let

     

       3
       3
       -
         inherit (lib) types mkOption mdDoc;

     

       3
       3
       +
         inherit (lib) types mkOption;

     

       4
       4
        
       in

     

       5
       5
        
       {

     

       6
       6
        
         options = {

     

       7
       7
        
           passthru = mkOption {

     

       8
       8
        
             type = types.lazyAttrsOf types.raw;

     

       9
       9
       -
             description = mdDoc ''

     

       9
       9
       +
             description = ''

     

       10
       10
        
               Attributes to add to the returned derivations,

     

       11
       11
        
               which are not necessarily part of the build.

     

       12
       12
        
       

     
···

       18
       18
        
       

     

       19
       19
        
           rawTestDerivation = mkOption {

     

       20
       20
        
             type = types.package;

     

       21
       21
       -
             description = mdDoc ''

     

       21
       21
       +
             description = ''

     

       22
       22
        
               Unfiltered version of `test`, for troubleshooting the test framework and `testBuildFailure` in the test framework's test suite.

     

       23
       23
        
               This is not intended for general use. Use `test` instead.

     

       24
       24
        
             '';

     
···

       28
       28
        
           test = mkOption {

     

       29
       29
        
             type = types.package;

     

       30
       30
        
             # TODO: can the interactive driver be configured to access the network?

     

       31
       31
       -
             description = mdDoc ''

     

       31
       31
       +
             description = ''

     

       32
       32
        
               Derivation that runs the test as its "build" process.

     

       33
       33
        
       

     

       34
       34
        
               This implies that NixOS tests run isolated from the network, making them

+3 -3

nixos/lib/testing/testScript.nix

···

       1
       1
        
       testModuleArgs@{ config, lib, hostPkgs, nodes, moduleType, ... }:

     

       2
       2
        
       let

     

       3
       3
       -
         inherit (lib) mkOption types mdDoc;

     

       3
       3
       +
         inherit (lib) mkOption types;

     

       4
       4
        
         inherit (types) either str functionTo;

     

       5
       5
        
       in

     

       6
       6
        
       {

     

       7
       7
        
         options = {

     

       8
       8
        
           testScript = mkOption {

     

       9
       9
        
             type = either str (functionTo str);

     

       10
       10
       -
             description = mdDoc ''

     

       10
       10
       +
             description = ''

     

       11
       11
        
               A series of python declarations and statements that you write to perform

     

       12
       12
        
               the test.

     

       13
       13
        
             '';

     
···

       25
       25
        
           };

     

       26
       26
        
           withoutTestScriptReferences = mkOption {

     

       27
       27
        
             type = moduleType;

     

       28
       28
       -
             description = mdDoc ''

     

       28
       28
       +
             description = ''

     

       29
       29
        
               A parallel universe where the testScript is invalid and has no references.

     

       30
       30
        
             '';

     

       31
       31
        
             internal = true;