colin/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

nixos/lib, doc: remove references to mdDoc (#300738)

Browse Source 
* doc: remove references to mdDoc in nixos/doc/manual/development/option-declarations.section.md

* nixos/lib: remove mdDoc in nixos/lib/make-options-doc/default.nix

* nixos/lib: remove mdDoc in nixos/lib/systemd-types.nix

* nixos/lib: remove mdDoc in nixos/lib/systemd-unit-options.nix

* nixos/lib: remove mdDoc in nixos/lib/testing/driver.nix

* nixos/lib: remove mdDoc in nixos/lib/testing/interactive.nix

* nixos/lib: remove mdDoc in nixos/lib/testing/meta.nix

* nixos/lib: remove mdDoc in nixos/lib/testing/name.nix

* nixos/lib: remove mdDoc in nixos/lib/testing/network.nix

* nixos/lib: remove mdDoc in nixos/lib/testing/nodes.nix

* nixos/lib: remove mdDoc in nixos/lib/testing/run.nix

* nixos/lib: remove mdDoc in nixos/lib/testing/testScript.nix
This commit is contained in:
Philip Taron 2024-04-01 16:58:23 -07:00 committed by GitHub
parent abe7e2fa57
commit ebde306504
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
12 changed files with 102 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
nixos/doc/manual/development/option-declarations.section.md
View File

@ -12,7 +12,7 @@ looks like this:
type = type specification; type = type specification;
default = default value; default = default value;
example = example value; example = example value;
description = lib.mdDoc "Description for use in the NixOS manual."; description = "Description for use in the NixOS manual.";
}; };
}; };
} }
@ -58,12 +58,9 @@ The function `mkOption` accepts the following arguments.
`description` `description`
: A textual description of the option, in [Nixpkgs-flavored Markdown]( : A textual description of the option in [Nixpkgs-flavored Markdown](
https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format, that will be https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format that will be
included in the NixOS manual. During the migration process from DocBook included in the NixOS manual.
it is necessary to mark descriptions written in CommonMark with `lib.mdDoc`.
The description may still be written in DocBook (without any marker), but this
is discouraged and will be deprecated in the future.
## Utility functions for common option patterns {#sec-option-declarations-util} ## Utility functions for common option patterns {#sec-option-declarations-util}
@ -81,13 +78,13 @@ For example:
::: {#ex-options-declarations-util-mkEnableOption-magic .example} ::: {#ex-options-declarations-util-mkEnableOption-magic .example}
### `mkEnableOption` usage ### `mkEnableOption` usage
```nix ```nix
lib.mkEnableOption (lib.mdDoc "magic") lib.mkEnableOption "magic"
# is like # is like
lib.mkOption { lib.mkOption {
type = lib.types.bool; type = lib.types.bool;
default = false; default = false;
example = true; example = true;
description = lib.mdDoc "Whether to enable magic."; description = "Whether to enable magic.";
} }
``` ```
::: :::
@ -135,7 +132,7 @@ lib.mkOption {
type = lib.types.package; type = lib.types.package;
default = pkgs.hello; default = pkgs.hello;
defaultText = lib.literalExpression "pkgs.hello"; defaultText = lib.literalExpression "pkgs.hello";
description = lib.mdDoc "The hello package to use."; description = "The hello package to use.";
} }
``` ```
::: :::
@ -153,7 +150,7 @@ lib.mkOption {
default = pkgs.ghc; default = pkgs.ghc;
defaultText = lib.literalExpression "pkgs.ghc"; defaultText = lib.literalExpression "pkgs.ghc";
example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])"; example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
description = lib.mdDoc "The GHC package to use."; description = "The GHC package to use.";
} }
``` ```
::: :::

4
nixos/lib/make-options-doc/default.nix
View File

@ -117,9 +117,7 @@
# deprecated since 23.11. # deprecated since 23.11.
# TODO remove in a while. # TODO remove in a while.
, allowDocBook ? false , allowDocBook ? false
# whether lib.mdDoc is required for descriptions to be read as markdown. # TODO remove in a while (see https://github.com/NixOS/nixpkgs/issues/300735)
# deprecated since 23.11.
# TODO remove in a while.
, markdownByDefault ? true , markdownByDefault ? true
}: }:

9
nixos/lib/systemd-types.nix
View File

@ -31,7 +31,6 @@ let
; ;
inherit (lib) inherit (lib)
mdDoc
mkDefault mkDefault
mkDerivedConfig mkDerivedConfig
mkEnableOption mkEnableOption
@ -81,11 +80,11 @@ rec {
initrdContents = attrsOf (submodule ({ config, options, name, ... }: { initrdContents = attrsOf (submodule ({ config, options, name, ... }: {
options = { options = {
enable = mkEnableOption (mdDoc "copying of this file and symlinking it") // { default = true; }; enable = (mkEnableOption "copying of this file and symlinking it") // { default = true; };
target = mkOption { target = mkOption {
type = path; type = path;
description = mdDoc '' description = ''
Path of the symlink. Path of the symlink.
''; '';
default = name; default = name;
@ -94,12 +93,12 @@ rec {
text = mkOption { text = mkOption {
default = null; default = null;
type = nullOr lines; type = nullOr lines;
description = mdDoc "Text of the file."; description = "Text of the file.";
}; };
source = mkOption { source = mkOption {
type = path; type = path;
description = mdDoc "Path of the source file."; description = "Path of the source file.";
}; };
}; };

109
nixos/lib/systemd-unit-options.nix
View File

@ -17,7 +17,6 @@ let
concatMap concatMap
filterOverrides filterOverrides
isList isList
mdDoc
mergeEqualOption mergeEqualOption
mkIf mkIf
mkMerge mkMerge
@ -55,7 +54,7 @@ in rec {
enable = mkOption { enable = mkOption {
default = true; default = true;
type = types.bool; type = types.bool;
description = mdDoc '' description = ''
If set to false, this unit will be a symlink to If set to false, this unit will be a symlink to
/dev/null. This is primarily useful to prevent specific /dev/null. This is primarily useful to prevent specific
template instances template instances
@ -69,7 +68,7 @@ in rec {
overrideStrategy = mkOption { overrideStrategy = mkOption {
default = "asDropinIfExists"; default = "asDropinIfExists";
type = types.enum [ "asDropinIfExists" "asDropin" ]; type = types.enum [ "asDropinIfExists" "asDropin" ];
description = mdDoc '' description = ''
Defines how unit configuration is provided for systemd: Defines how unit configuration is provided for systemd:
`asDropinIfExists` creates a unit file when no unit file is provided by the package `asDropinIfExists` creates a unit file when no unit file is provided by the package
@ -85,7 +84,7 @@ in rec {
requiredBy = mkOption { requiredBy = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
Units that require (i.e. depend on and need to go down with) this unit. Units that require (i.e. depend on and need to go down with) this unit.
As discussed in the `wantedBy` option description this also creates As discussed in the `wantedBy` option description this also creates
`.requires` symlinks automatically. `.requires` symlinks automatically.
@ -95,7 +94,7 @@ in rec {
upheldBy = mkOption { upheldBy = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
Keep this unit running as long as the listed units are running. This is a continuously Keep this unit running as long as the listed units are running. This is a continuously
enforced version of wantedBy. enforced version of wantedBy.
''; '';
@ -104,7 +103,7 @@ in rec {
wantedBy = mkOption { wantedBy = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
Units that want (i.e. depend on) this unit. The default method for Units that want (i.e. depend on) this unit. The default method for
starting a unit by default at boot time is to set this option to starting a unit by default at boot time is to set this option to
`["multi-user.target"]` for system services. Likewise for user units `["multi-user.target"]` for system services. Likewise for user units
@ -122,7 +121,7 @@ in rec {
aliases = mkOption { aliases = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc "Aliases of that unit."; description = "Aliases of that unit.";
}; };
}; };
@ -132,12 +131,12 @@ in rec {
text = mkOption { text = mkOption {
type = types.nullOr types.str; type = types.nullOr types.str;
default = null; default = null;
description = mdDoc "Text of this systemd unit."; description = "Text of this systemd unit.";
}; };
unit = mkOption { unit = mkOption {
internal = true; internal = true;
description = mdDoc "The generated unit."; description = "The generated unit.";
}; };
}; };
@ -148,19 +147,19 @@ in rec {
description = mkOption { description = mkOption {
default = ""; default = "";
type = types.singleLineStr; type = types.singleLineStr;
description = mdDoc "Description of this unit used in systemd messages and progress indicators."; description = "Description of this unit used in systemd messages and progress indicators.";
}; };
documentation = mkOption { documentation = mkOption {
default = []; default = [];
type = types.listOf types.str; type = types.listOf types.str;
description = mdDoc "A list of URIs referencing documentation for this unit or its configuration."; description = "A list of URIs referencing documentation for this unit or its configuration.";
}; };
requires = mkOption { requires = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
Start the specified units when this unit is started, and stop Start the specified units when this unit is started, and stop
this unit when the specified units are stopped or fail. this unit when the specified units are stopped or fail.
''; '';
@ -169,7 +168,7 @@ in rec {
wants = mkOption { wants = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
Start the specified units when this unit is started. Start the specified units when this unit is started.
''; '';
}; };
@ -177,7 +176,7 @@ in rec {
upholds = mkOption { upholds = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
Keeps the specified running while this unit is running. A continuous version of `wants`. Keeps the specified running while this unit is running. A continuous version of `wants`.
''; '';
}; };
@ -185,7 +184,7 @@ in rec {
after = mkOption { after = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
If the specified units are started at the same time as If the specified units are started at the same time as
this unit, delay this unit until they have started. this unit, delay this unit until they have started.
''; '';
@ -194,7 +193,7 @@ in rec {
before = mkOption { before = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
If the specified units are started at the same time as If the specified units are started at the same time as
this unit, delay them until this unit has started. this unit, delay them until this unit has started.
''; '';
@ -203,7 +202,7 @@ in rec {
bindsTo = mkOption { bindsTo = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
Like ‘requires’, but in addition, if the specified units Like ‘requires’, but in addition, if the specified units
unexpectedly disappear, this unit will be stopped as well. unexpectedly disappear, this unit will be stopped as well.
''; '';
@ -212,7 +211,7 @@ in rec {
partOf = mkOption { partOf = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
If the specified units are stopped or restarted, then this If the specified units are stopped or restarted, then this
unit is stopped or restarted as well. unit is stopped or restarted as well.
''; '';
@ -221,7 +220,7 @@ in rec {
conflicts = mkOption { conflicts = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
If the specified units are started, then this unit is stopped If the specified units are started, then this unit is stopped
and vice versa. and vice versa.
''; '';
@ -230,7 +229,7 @@ in rec {
requisite = mkOption { requisite = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
Similar to requires. However if the units listed are not started, Similar to requires. However if the units listed are not started,
they will not be started and the transaction will fail. they will not be started and the transaction will fail.
''; '';
@ -240,7 +239,7 @@ in rec {
default = {}; default = {};
example = { RequiresMountsFor = "/data"; }; example = { RequiresMountsFor = "/data"; };
type = types.attrsOf unitOption; type = types.attrsOf unitOption;
description = mdDoc '' description = ''
Each attribute in this set specifies an option in the Each attribute in this set specifies an option in the
`[Unit]` section of the unit. See `[Unit]` section of the unit. See
{manpage}`systemd.unit(5)` for details. {manpage}`systemd.unit(5)` for details.
@ -250,7 +249,7 @@ in rec {
onFailure = mkOption { onFailure = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
A list of one or more units that are activated when A list of one or more units that are activated when
this unit enters the "failed" state. this unit enters the "failed" state.
''; '';
@ -259,7 +258,7 @@ in rec {
onSuccess = mkOption { onSuccess = mkOption {
default = []; default = [];
type = types.listOf unitNameType; type = types.listOf unitNameType;
description = mdDoc '' description = ''
A list of one or more units that are activated when A list of one or more units that are activated when
this unit enters the "inactive" state. this unit enters the "inactive" state.
''; '';
@ -267,7 +266,7 @@ in rec {
startLimitBurst = mkOption { startLimitBurst = mkOption {
type = types.int; type = types.int;
description = mdDoc '' description = ''
Configure unit start rate limiting. Units which are started Configure unit start rate limiting. Units which are started
more than startLimitBurst times within an interval time more than startLimitBurst times within an interval time
interval are not permitted to start any more. interval are not permitted to start any more.
@ -276,7 +275,7 @@ in rec {
startLimitIntervalSec = mkOption { startLimitIntervalSec = mkOption {
type = types.int; type = types.int;
description = mdDoc '' description = ''
Configure unit start rate limiting. Units which are started Configure unit start rate limiting. Units which are started
more than startLimitBurst times within an interval time more than startLimitBurst times within an interval time
interval are not permitted to start any more. interval are not permitted to start any more.
@ -295,7 +294,7 @@ in rec {
restartTriggers = mkOption { restartTriggers = mkOption {
default = []; default = [];
type = types.listOf types.unspecified; type = types.listOf types.unspecified;
description = mdDoc '' description = ''
An arbitrary list of items such as derivations. If any item An arbitrary list of items such as derivations. If any item
in the list changes between reconfigurations, the service will in the list changes between reconfigurations, the service will
be restarted. be restarted.
@ -305,7 +304,7 @@ in rec {
reloadTriggers = mkOption { reloadTriggers = mkOption {
default = []; default = [];
type = types.listOf unitOption; type = types.listOf unitOption;
description = mdDoc '' description = ''
An arbitrary list of items such as derivations. If any item An arbitrary list of items such as derivations. If any item
in the list changes between reconfigurations, the service will in the list changes between reconfigurations, the service will
be reloaded. If anything but a reload trigger changes in the be reloaded. If anything but a reload trigger changes in the
@ -323,13 +322,13 @@ in rec {
default = {}; default = {};
type = with types; attrsOf (nullOr (oneOf [ str path package ])); type = with types; attrsOf (nullOr (oneOf [ str path package ]));
example = { PATH = "/foo/bar/bin"; LANG = "nl_NL.UTF-8"; }; example = { PATH = "/foo/bar/bin"; LANG = "nl_NL.UTF-8"; };
description = mdDoc "Environment variables passed to the service's processes."; description = "Environment variables passed to the service's processes.";
}; };
path = mkOption { path = mkOption {
default = []; default = [];
type = with types; listOf (oneOf [ package str ]); type = with types; listOf (oneOf [ package str ]);
description = mdDoc '' description = ''
Packages added to the service's {env}`PATH` Packages added to the service's {env}`PATH`
environment variable. Both the {file}`bin` environment variable. Both the {file}`bin`
and {file}`sbin` subdirectories of each and {file}`sbin` subdirectories of each
@ -343,7 +342,7 @@ in rec {
{ RestartSec = 5; { RestartSec = 5;
}; };
type = types.addCheck (types.attrsOf unitOption) checkService; type = types.addCheck (types.attrsOf unitOption) checkService;
description = mdDoc '' description = ''
Each attribute in this set specifies an option in the Each attribute in this set specifies an option in the
`[Service]` section of the unit. See `[Service]` section of the unit. See
{manpage}`systemd.service(5)` for details. {manpage}`systemd.service(5)` for details.
@ -353,14 +352,14 @@ in rec {
script = mkOption { script = mkOption {
type = types.lines; type = types.lines;
default = ""; default = "";
description = mdDoc "Shell commands executed as the service's main process."; description = "Shell commands executed as the service's main process.";
}; };
scriptArgs = mkOption { scriptArgs = mkOption {
type = types.str; type = types.str;
default = ""; default = "";
example = "%i"; example = "%i";
description = mdDoc '' description = ''
Arguments passed to the main process script. Arguments passed to the main process script.
Can contain specifiers (`%` placeholders expanded by systemd, see {manpage}`systemd.unit(5)`). Can contain specifiers (`%` placeholders expanded by systemd, see {manpage}`systemd.unit(5)`).
''; '';
@ -369,7 +368,7 @@ in rec {
preStart = mkOption { preStart = mkOption {
type = types.lines; type = types.lines;
default = ""; default = "";
description = mdDoc '' description = ''
Shell commands executed before the service's main process Shell commands executed before the service's main process
is started. is started.
''; '';
@ -378,7 +377,7 @@ in rec {
postStart = mkOption { postStart = mkOption {
type = types.lines; type = types.lines;
default = ""; default = "";
description = mdDoc '' description = ''
Shell commands executed after the service's main process Shell commands executed after the service's main process
is started. is started.
''; '';
@ -387,7 +386,7 @@ in rec {
reload = mkOption { reload = mkOption {
type = types.lines; type = types.lines;
default = ""; default = "";
description = mdDoc '' description = ''
Shell commands executed when the service's main process Shell commands executed when the service's main process
is reloaded. is reloaded.
''; '';
@ -396,7 +395,7 @@ in rec {
preStop = mkOption { preStop = mkOption {
type = types.lines; type = types.lines;
default = ""; default = "";
description = mdDoc '' description = ''
Shell commands executed to stop the service. Shell commands executed to stop the service.
''; '';
}; };
@ -404,7 +403,7 @@ in rec {
postStop = mkOption { postStop = mkOption {
type = types.lines; type = types.lines;
default = ""; default = "";
description = mdDoc '' description = ''
Shell commands executed after the service's main process Shell commands executed after the service's main process
has exited. has exited.
''; '';
@ -413,7 +412,7 @@ in rec {
jobScripts = mkOption { jobScripts = mkOption {
type = with types; coercedTo path singleton (listOf path); type = with types; coercedTo path singleton (listOf path);
internal = true; internal = true;
description = mdDoc "A list of all job script derivations of this unit."; description = "A list of all job script derivations of this unit.";
default = []; default = [];
}; };
@ -458,7 +457,7 @@ in rec {
restartIfChanged = mkOption { restartIfChanged = mkOption {
type = types.bool; type = types.bool;
default = true; default = true;
description = mdDoc '' description = ''
Whether the service should be restarted during a NixOS Whether the service should be restarted during a NixOS
configuration switch if its definition has changed. configuration switch if its definition has changed.
''; '';
@ -467,7 +466,7 @@ in rec {
reloadIfChanged = mkOption { reloadIfChanged = mkOption {
type = types.bool; type = types.bool;
default = false; default = false;
description = mdDoc '' description = ''
Whether the service should be reloaded during a NixOS Whether the service should be reloaded during a NixOS
configuration switch if its definition has changed. If configuration switch if its definition has changed. If
enabled, the value of {option}`restartIfChanged` is enabled, the value of {option}`restartIfChanged` is
@ -483,7 +482,7 @@ in rec {
stopIfChanged = mkOption { stopIfChanged = mkOption {
type = types.bool; type = types.bool;
default = true; default = true;
description = mdDoc '' description = ''
If set, a changed unit is restarted by calling If set, a changed unit is restarted by calling
{command}`systemctl stop` in the old configuration, {command}`systemctl stop` in the old configuration,
then {command}`systemctl start` in the new one. then {command}`systemctl start` in the new one.
@ -499,7 +498,7 @@ in rec {
type = with types; either str (listOf str); type = with types; either str (listOf str);
default = []; default = [];
example = "Sun 14:00:00"; example = "Sun 14:00:00";
description = mdDoc '' description = ''
Automatically start this unit at the given date/time, which Automatically start this unit at the given date/time, which
must be in the format described in must be in the format described in
{manpage}`systemd.time(7)`. This is equivalent {manpage}`systemd.time(7)`. This is equivalent
@ -526,7 +525,7 @@ in rec {
default = []; default = [];
type = types.listOf types.str; type = types.listOf types.str;
example = [ "0.0.0.0:993" "/run/my-socket" ]; example = [ "0.0.0.0:993" "/run/my-socket" ];
description = mdDoc '' description = ''
For each item in this list, a `ListenStream` For each item in this list, a `ListenStream`
option in the `[Socket]` section will be created. option in the `[Socket]` section will be created.
''; '';
@ -536,7 +535,7 @@ in rec {
default = []; default = [];
type = types.listOf types.str; type = types.listOf types.str;
example = [ "0.0.0.0:993" "/run/my-socket" ]; example = [ "0.0.0.0:993" "/run/my-socket" ];
description = mdDoc '' description = ''
For each item in this list, a `ListenDatagram` For each item in this list, a `ListenDatagram`
option in the `[Socket]` section will be created. option in the `[Socket]` section will be created.
''; '';
@ -546,7 +545,7 @@ in rec {
default = {}; default = {};
example = { ListenStream = "/run/my-socket"; }; example = { ListenStream = "/run/my-socket"; };
type = types.attrsOf unitOption; type = types.attrsOf unitOption;
description = mdDoc '' description = ''
Each attribute in this set specifies an option in the Each attribute in this set specifies an option in the
`[Socket]` section of the unit. See `[Socket]` section of the unit. See
{manpage}`systemd.socket(5)` for details. {manpage}`systemd.socket(5)` for details.
@ -578,7 +577,7 @@ in rec {
default = {}; default = {};
example = { OnCalendar = "Sun 14:00:00"; Unit = "foo.service"; }; example = { OnCalendar = "Sun 14:00:00"; Unit = "foo.service"; };
type = types.attrsOf unitOption; type = types.attrsOf unitOption;
description = mdDoc '' description = ''
Each attribute in this set specifies an option in the Each attribute in this set specifies an option in the
`[Timer]` section of the unit. See `[Timer]` section of the unit. See
{manpage}`systemd.timer(5)` and {manpage}`systemd.timer(5)` and
@ -611,7 +610,7 @@ in rec {
default = {}; default = {};
example = { PathChanged = "/some/path"; Unit = "changedpath.service"; }; example = { PathChanged = "/some/path"; Unit = "changedpath.service"; };
type = types.attrsOf unitOption; type = types.attrsOf unitOption;
description = mdDoc '' description = ''
Each attribute in this set specifies an option in the Each attribute in this set specifies an option in the
`[Path]` section of the unit. See `[Path]` section of the unit. See
{manpage}`systemd.path(5)` for details. {manpage}`systemd.path(5)` for details.
@ -642,13 +641,13 @@ in rec {
what = mkOption { what = mkOption {
example = "/dev/sda1"; example = "/dev/sda1";
type = types.str; type = types.str;
description = mdDoc "Absolute path of device node, file or other resource. (Mandatory)"; description = "Absolute path of device node, file or other resource. (Mandatory)";
}; };
where = mkOption { where = mkOption {
example = "/mnt"; example = "/mnt";
type = types.str; type = types.str;
description = mdDoc '' description = ''
Absolute path of a directory of the mount point. Absolute path of a directory of the mount point.
Will be created if it doesn't exist. (Mandatory) Will be created if it doesn't exist. (Mandatory)
''; '';
@ -658,21 +657,21 @@ in rec {
default = ""; default = "";
example = "ext4"; example = "ext4";
type = types.str; type = types.str;
description = mdDoc "File system type."; description = "File system type.";
}; };
options = mkOption { options = mkOption {
default = ""; default = "";
example = "noatime"; example = "noatime";
type = types.commas; type = types.commas;
description = mdDoc "Options used to mount the file system."; description = "Options used to mount the file system.";
}; };
mountConfig = mkOption { mountConfig = mkOption {
default = {}; default = {};
example = { DirectoryMode = "0775"; }; example = { DirectoryMode = "0775"; };
type = types.attrsOf unitOption; type = types.attrsOf unitOption;
description = mdDoc '' description = ''
Each attribute in this set specifies an option in the Each attribute in this set specifies an option in the
`[Mount]` section of the unit. See `[Mount]` section of the unit. See
{manpage}`systemd.mount(5)` for details. {manpage}`systemd.mount(5)` for details.
@ -702,7 +701,7 @@ in rec {
where = mkOption { where = mkOption {
example = "/mnt"; example = "/mnt";
type = types.str; type = types.str;
description = mdDoc '' description = ''
Absolute path of a directory of the mount point. Absolute path of a directory of the mount point.
Will be created if it doesn't exist. (Mandatory) Will be created if it doesn't exist. (Mandatory)
''; '';
@ -712,7 +711,7 @@ in rec {
default = {}; default = {};
example = { DirectoryMode = "0775"; }; example = { DirectoryMode = "0775"; };
type = types.attrsOf unitOption; type = types.attrsOf unitOption;
description = mdDoc '' description = ''
Each attribute in this set specifies an option in the Each attribute in this set specifies an option in the
`[Automount]` section of the unit. See `[Automount]` section of the unit. See
{manpage}`systemd.automount(5)` for details. {manpage}`systemd.automount(5)` for details.
@ -743,7 +742,7 @@ in rec {
default = {}; default = {};
example = { MemoryMax = "2G"; }; example = { MemoryMax = "2G"; };
type = types.attrsOf unitOption; type = types.attrsOf unitOption;
description = mdDoc '' description = ''
Each attribute in this set specifies an option in the Each attribute in this set specifies an option in the
`[Slice]` section of the unit. See `[Slice]` section of the unit. See
{manpage}`systemd.slice(5)` for details. {manpage}`systemd.slice(5)` for details.

20
nixos/lib/testing/driver.nix
View File

@ -1,6 +1,6 @@
{ config, lib, hostPkgs, ... }: { config, lib, hostPkgs, ... }:
let let
inherit (lib) mkOption types literalMD mdDoc; inherit (lib) mkOption types literalMD;
# Reifies and correctly wraps the python test driver for # Reifies and correctly wraps the python test driver for
# the respective qemu version and with or without ocr support # the respective qemu version and with or without ocr support
@ -104,13 +104,13 @@ in
options = { options = {
driver = mkOption { driver = mkOption {
description = mdDoc "Package containing a script that runs the test."; description = "Package containing a script that runs the test.";
type = types.package; type = types.package;
defaultText = literalMD "set by the test framework"; defaultText = literalMD "set by the test framework";
}; };
hostPkgs = mkOption { hostPkgs = mkOption {
description = mdDoc "Nixpkgs attrset used outside the nodes."; description = "Nixpkgs attrset used outside the nodes.";
type = types.raw; type = types.raw;
example = lib.literalExpression '' example = lib.literalExpression ''
import nixpkgs { inherit system config overlays; } import nixpkgs { inherit system config overlays; }
@ -118,14 +118,14 @@ in
}; };
qemu.package = mkOption { qemu.package = mkOption {
description = mdDoc "Which qemu package to use for the virtualisation of [{option}`nodes`](#test-opt-nodes)."; description = "Which qemu package to use for the virtualisation of [{option}`nodes`](#test-opt-nodes).";
type = types.package; type = types.package;
default = hostPkgs.qemu_test; default = hostPkgs.qemu_test;
defaultText = "hostPkgs.qemu_test"; defaultText = "hostPkgs.qemu_test";
}; };
globalTimeout = mkOption { globalTimeout = mkOption {
description = mdDoc '' description = ''
A global timeout for the complete test, expressed in seconds. A global timeout for the complete test, expressed in seconds.
Beyond that timeout, every resource will be killed and released and the test will fail. Beyond that timeout, every resource will be killed and released and the test will fail.
@ -137,7 +137,7 @@ in
}; };
enableOCR = mkOption { enableOCR = mkOption {
description = mdDoc '' description = ''
Whether to enable Optical Character Recognition functionality for Whether to enable Optical Character Recognition functionality for
testing graphical programs. See [Machine objects](`ssec-machine-objects`). testing graphical programs. See [Machine objects](`ssec-machine-objects`).
''; '';
@ -146,7 +146,7 @@ in
}; };
extraPythonPackages = mkOption { extraPythonPackages = mkOption {
description = mdDoc '' description = ''
Python packages to add to the test driver. Python packages to add to the test driver.
The argument is a Python package set, similar to `pkgs.pythonPackages`. The argument is a Python package set, similar to `pkgs.pythonPackages`.
@ -159,7 +159,7 @@ in
}; };
extraDriverArgs = mkOption { extraDriverArgs = mkOption {
description = mdDoc '' description = ''
Extra arguments to pass to the test driver. Extra arguments to pass to the test driver.
They become part of [{option}`driver`](#test-opt-driver) via `wrapProgram`. They become part of [{option}`driver`](#test-opt-driver) via `wrapProgram`.
@ -171,7 +171,7 @@ in
skipLint = mkOption { skipLint = mkOption {
type = types.bool; type = types.bool;
default = false; default = false;
description = mdDoc '' description = ''
Do not run the linters. This may speed up your iteration cycle, but it is not something you should commit. Do not run the linters. This may speed up your iteration cycle, but it is not something you should commit.
''; '';
}; };
@ -179,7 +179,7 @@ in
skipTypeCheck = mkOption { skipTypeCheck = mkOption {
type = types.bool; type = types.bool;
default = false; default = false;
description = mdDoc '' description = ''
Disable type checking. This must not be enabled for new NixOS tests. Disable type checking. This must not be enabled for new NixOS tests.
This may speed up your iteration cycle, unless you're working on the [{option}`testScript`](#test-opt-testScript). This may speed up your iteration cycle, unless you're working on the [{option}`testScript`](#test-opt-testScript).

4
nixos/lib/testing/interactive.nix
View File

@ -1,11 +1,11 @@
{ config, lib, moduleType, hostPkgs, ... }: { config, lib, moduleType, hostPkgs, ... }:
let let
inherit (lib) mkOption types mdDoc; inherit (lib) mkOption types;
in in
{ {
options = { options = {
interactive = mkOption { interactive = mkOption {
description = mdDoc '' description = ''
Tests [can be run interactively](#sec-running-nixos-tests-interactively) Tests [can be run interactively](#sec-running-nixos-tests-interactively)
using the program in the test derivation's `.driverInteractive` attribute. using the program in the test derivation's `.driverInteractive` attribute.

10
nixos/lib/testing/meta.nix
View File

@ -1,11 +1,11 @@
{ lib, ... }: { lib, ... }:
let let
inherit (lib) types mkOption mdDoc; inherit (lib) types mkOption;
in in
{ {
options = { options = {
meta = lib.mkOption { meta = lib.mkOption {
description = mdDoc '' description = ''
The [`meta`](https://nixos.org/manual/nixpkgs/stable/#chap-meta) attributes that will be set on the returned derivations. The [`meta`](https://nixos.org/manual/nixpkgs/stable/#chap-meta) attributes that will be set on the returned derivations.
Not all [`meta`](https://nixos.org/manual/nixpkgs/stable/#chap-meta) attributes are supported, but more can be added as desired. Not all [`meta`](https://nixos.org/manual/nixpkgs/stable/#chap-meta) attributes are supported, but more can be added as desired.
@ -16,21 +16,21 @@ in
maintainers = lib.mkOption { maintainers = lib.mkOption {
type = types.listOf types.raw; type = types.listOf types.raw;
default = []; default = [];
description = mdDoc '' description = ''
The [list of maintainers](https://nixos.org/manual/nixpkgs/stable/#var-meta-maintainers) for this test. The [list of maintainers](https://nixos.org/manual/nixpkgs/stable/#var-meta-maintainers) for this test.
''; '';
}; };
timeout = lib.mkOption { timeout = lib.mkOption {
type = types.nullOr types.int; type = types.nullOr types.int;
default = 3600; # 1 hour default = 3600; # 1 hour
description = mdDoc '' description = ''
The [{option}`test`](#test-opt-test)'s [`meta.timeout`](https://nixos.org/manual/nixpkgs/stable/#var-meta-timeout) in seconds. The [{option}`test`](#test-opt-test)'s [`meta.timeout`](https://nixos.org/manual/nixpkgs/stable/#var-meta-timeout) in seconds.
''; '';
}; };
broken = lib.mkOption { broken = lib.mkOption {
type = types.bool; type = types.bool;
default = false; default = false;
description = mdDoc '' description = ''
Sets the [`meta.broken`](https://nixos.org/manual/nixpkgs/stable/#var-meta-broken) attribute on the [{option}`test`](#test-opt-test) derivation. Sets the [`meta.broken`](https://nixos.org/manual/nixpkgs/stable/#var-meta-broken) attribute on the [{option}`test`](#test-opt-test) derivation.
''; '';
}; };

4
nixos/lib/testing/name.nix
View File

@ -1,10 +1,10 @@
{ lib, ... }: { lib, ... }:
let let
inherit (lib) mkOption types mdDoc; inherit (lib) mkOption types;
in in
{ {
options.name = mkOption { options.name = mkOption {
description = mdDoc '' description = ''
The name of the test. The name of the test.
This is used in the derivation names of the [{option}`driver`](#test-opt-driver) and [{option}`test`](#test-opt-test) runner. This is used in the derivation names of the [{option}`driver`](#test-opt-driver) and [{option}`test`](#test-opt-test) runner.

5
nixos/lib/testing/network.nix
View File

@ -5,7 +5,6 @@ let
attrNames concatMap concatMapStrings flip forEach head attrNames concatMap concatMapStrings flip forEach head
listToAttrs mkDefault mkOption nameValuePair optionalString listToAttrs mkDefault mkOption nameValuePair optionalString
range toLower types zipListsWith zipLists range toLower types zipListsWith zipLists
mdDoc
; ;
nodeNumbers = nodeNumbers =
@ -89,7 +88,7 @@ let
default = name; default = name;
# We need to force this in specilisations, otherwise it'd be # We need to force this in specilisations, otherwise it'd be
# readOnly = true; # readOnly = true;
description = mdDoc '' description = ''
The `name` in `nodes.<name>`; stable across `specialisations`. The `name` in `nodes.<name>`; stable across `specialisations`.
''; '';
}; };
@ -98,7 +97,7 @@ let
type = types.int; type = types.int;
readOnly = true; readOnly = true;
default = nodeNumbers.${config.virtualisation.test.nodeName}; default = nodeNumbers.${config.virtualisation.test.nodeName};
description = mdDoc '' description = ''
A unique number assigned for each node in `nodes`. A unique number assigned for each node in `nodes`.
''; '';
}; };

15
nixos/lib/testing/nodes.nix
View File

@ -5,7 +5,6 @@ let
literalExpression literalExpression
literalMD literalMD
mapAttrs mapAttrs
mdDoc
mkDefault mkDefault
mkIf mkIf
mkOption mkForce mkOption mkForce
@ -76,7 +75,7 @@ in
nodes = mkOption { nodes = mkOption {
type = types.lazyAttrsOf config.node.type; type = types.lazyAttrsOf config.node.type;
visible = "shallow"; visible = "shallow";
description = mdDoc '' description = ''
An attribute set of NixOS configuration modules. An attribute set of NixOS configuration modules.
The configurations are augmented by the [`defaults`](#test-opt-defaults) option. The configurations are augmented by the [`defaults`](#test-opt-defaults) option.
@ -88,7 +87,7 @@ in
}; };
defaults = mkOption { defaults = mkOption {
description = mdDoc '' description = ''
NixOS configuration that is applied to all [{option}`nodes`](#test-opt-nodes). NixOS configuration that is applied to all [{option}`nodes`](#test-opt-nodes).
''; '';
type = types.deferredModule; type = types.deferredModule;
@ -96,7 +95,7 @@ in
}; };
extraBaseModules = mkOption { extraBaseModules = mkOption {
description = mdDoc '' description = ''
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). 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).
''; '';
type = types.deferredModule; type = types.deferredModule;
@ -104,7 +103,7 @@ in
}; };
node.pkgs = mkOption { node.pkgs = mkOption {
description = mdDoc '' description = ''
The Nixpkgs to use for the nodes. The Nixpkgs to use for the nodes.
Setting this will make the `nixpkgs.*` options read-only, to avoid mistakenly testing with a Nixpkgs configuration that diverges from regular use. Setting this will make the `nixpkgs.*` options read-only, to avoid mistakenly testing with a Nixpkgs configuration that diverges from regular use.
@ -117,7 +116,7 @@ in
}; };
node.pkgsReadOnly = mkOption { node.pkgsReadOnly = mkOption {
description = mdDoc '' description = ''
Whether to make the `nixpkgs.*` options read-only. This is only relevant when [`node.pkgs`](#test-opt-node.pkgs) is set. Whether to make the `nixpkgs.*` options read-only. This is only relevant when [`node.pkgs`](#test-opt-node.pkgs) is set.
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. 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,7 +129,7 @@ in
node.specialArgs = mkOption { node.specialArgs = mkOption {
type = types.lazyAttrsOf types.raw; type = types.lazyAttrsOf types.raw;
default = { }; default = { };
description = mdDoc '' description = ''
An attribute set of arbitrary values that will be made available as module arguments during the resolution of module `imports`. An attribute set of arbitrary values that will be made available as module arguments during the resolution of module `imports`.
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. 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,7 +138,7 @@ in
nodesCompat = mkOption { nodesCompat = mkOption {
internal = true; internal = true;
description = mdDoc '' description = ''
Basically `_module.args.nodes`, but with backcompat and warnings added. Basically `_module.args.nodes`, but with backcompat and warnings added.
This will go away. This will go away.

8
nixos/lib/testing/run.nix
View File

@ -1,12 +1,12 @@
{ config, hostPkgs, lib, ... }: { config, hostPkgs, lib, ... }:
let let
inherit (lib) types mkOption mdDoc; inherit (lib) types mkOption;
in in
{ {
options = { options = {
passthru = mkOption { passthru = mkOption {
type = types.lazyAttrsOf types.raw; type = types.lazyAttrsOf types.raw;
description = mdDoc '' description = ''
Attributes to add to the returned derivations, Attributes to add to the returned derivations,
which are not necessarily part of the build. which are not necessarily part of the build.
@ -18,7 +18,7 @@ in
rawTestDerivation = mkOption { rawTestDerivation = mkOption {
type = types.package; type = types.package;
description = mdDoc '' description = ''
Unfiltered version of `test`, for troubleshooting the test framework and `testBuildFailure` in the test framework's test suite. Unfiltered version of `test`, for troubleshooting the test framework and `testBuildFailure` in the test framework's test suite.
This is not intended for general use. Use `test` instead. This is not intended for general use. Use `test` instead.
''; '';
@ -28,7 +28,7 @@ in
test = mkOption { test = mkOption {
type = types.package; type = types.package;
# TODO: can the interactive driver be configured to access the network? # TODO: can the interactive driver be configured to access the network?
description = mdDoc '' description = ''
Derivation that runs the test as its "build" process. Derivation that runs the test as its "build" process.
This implies that NixOS tests run isolated from the network, making them This implies that NixOS tests run isolated from the network, making them

6
nixos/lib/testing/testScript.nix
View File

@ -1,13 +1,13 @@
testModuleArgs@{ config, lib, hostPkgs, nodes, moduleType, ... }: testModuleArgs@{ config, lib, hostPkgs, nodes, moduleType, ... }:
let let
inherit (lib) mkOption types mdDoc; inherit (lib) mkOption types;
inherit (types) either str functionTo; inherit (types) either str functionTo;
in in
{ {
options = { options = {
testScript = mkOption { testScript = mkOption {
type = either str (functionTo str); type = either str (functionTo str);
description = mdDoc '' description = ''
A series of python declarations and statements that you write to perform A series of python declarations and statements that you write to perform
the test. the test.
''; '';
@ -25,7 +25,7 @@ in
}; };
withoutTestScriptReferences = mkOption { withoutTestScriptReferences = mkOption {
type = moduleType; type = moduleType;
description = mdDoc '' description = ''
A parallel universe where the testScript is invalid and has no references. A parallel universe where the testScript is invalid and has no references.
''; '';
internal = true; internal = true;