lib/modules: Rename _module.assertions to _module.checks

This commit is contained in:
Silvan Mosberger 2020-11-30 20:04:03 +01:00
parent 3e39d6efdf
commit c9cc8969b4
No known key found for this signature in database
GPG key ID: E8F1E9EAD284E17D
16 changed files with 108 additions and 76 deletions

View file

@ -103,7 +103,13 @@ rec {
type = types.bool;
internal = prefix != [];
default = check;
description = "Whether to check whether all option definitions have matching declarations.";
description = ''
Whether to check whether all option definitions have matching
declarations.
Note that this has nothing to do with the similarly named
<option>_module.checks</option> option
'';
};
_module.freeformType = mkOption {
@ -123,11 +129,11 @@ rec {
'';
};
_module.assertions = mkOption {
_module.checks = mkOption {
description = ''
Assertions and warnings to trigger during module evaluation. The
Evaluation checks to trigger during module evaluation. The
attribute name will be displayed when it is triggered, allowing
users to disable/change these assertions again if necessary. See
users to disable/change these checks if necessary. See
the section on Warnings and Assertions in the manual for more
information.
'';
@ -151,7 +157,7 @@ rec {
# TODO: Rename to assertion? Or allow also setting assertion?
options.enable = mkOption {
description = ''
Whether to enable this assertion.
Whether to enable this check.
<note><para>
This is the inverse of asserting a condition: If a certain
condition should be <literal>true</literal>, then this
@ -164,7 +170,7 @@ rec {
options.type = mkOption {
description = ''
The type of the assertion. The default
The type of the check. The default
<literal>"error"</literal> type will cause evaluation to fail,
while the <literal>"warning"</literal> type will only show a
warning.
@ -176,7 +182,7 @@ rec {
options.message = mkOption {
description = ''
The assertion message to display if this assertion triggers.
The message to display if this check triggers.
To display option names in the message, add
<literal>options</literal> to the module function arguments
and use <literal>''${options.path.to.option}</literal>.
@ -190,24 +196,24 @@ rec {
options.triggerPath = mkOption {
description = ''
The <literal>config</literal> path which when evaluated should
trigger this assertion. By default this is
trigger this check. By default this is
<literal>[]</literal>, meaning evaluating
<literal>config</literal> at all will trigger the assertion.
<literal>config</literal> at all will trigger the check.
On NixOS this default is changed to
<literal>[ "system" "build" "toplevel"</literal> such that
only a system evaluation triggers the assertions.
only a system evaluation triggers the checks.
<warning><para>
Evaluating <literal>config</literal> from within the current
module evaluation doesn't cause a trigger. Only accessing it
from outside will do that. This means it's easy to miss
assertions if this option doesn't have an externally-accessed
failing checks if this option doesn't have an externally-accessed
value.
</para></warning>
'';
# Mark as internal as it's easy to misuse it
internal = true;
type = types.uniq (types.listOf types.str);
# Default to [], causing assertions to be triggered when
# Default to [], causing checks to be triggered when
# anything is evaluated. This is a safe and convenient default.
default = [];
example = [ "system" "build" "vm" ];
@ -253,13 +259,13 @@ rec {
else recursiveUpdate freeformConfig declaredConfig;
/*
Inject a list of assertions into a config value, corresponding to their
Inject a list of checks into a config value, corresponding to their
triggerPath (meaning when that path is accessed from the result of this
function, the assertion triggers).
function, the check triggers).
*/
injectAssertions = assertions: config: let
# Partition into assertions that are triggered on this level and ones that aren't
parted = lib.partition (a: length a.triggerPath == 0) assertions;
injectChecks = checks: config: let
# Partition into checks that are triggered on this level and ones that aren't
parted = lib.partition (a: length a.triggerPath == 0) checks;
# From the ones that are triggered, filter out ones that aren't enabled
# and group into warnings/errors
@ -270,45 +276,45 @@ rec {
errorTrigger = value:
if byType.error or [] == [] then value else
throw ''
Failed assertions:
Failed checks:
${lib.concatMapStringsSep "\n" (a: "- ${a.show}") byType.error}
'';
# Trigger for both warnings and errors
trigger = value: warningTrigger (errorTrigger value);
# From the non-triggered assertions, split off the first element of triggerPath
# to get a mapping from nested attributes to a list of assertions for that attribute
# From the non-triggered checks, split off the first element of triggerPath
# to get a mapping from nested attributes to a list of checks for that attribute
nested = lib.zipAttrs (map (a: {
${head a.triggerPath} = a // {
triggerPath = lib.tail a.triggerPath;
};
}) parted.wrong);
# Recursively inject assertions if config is an attribute set and we
# have assertions under its attributes
# Recursively inject checks if config is an attribute set and we
# have checks under its attributes
result =
if isAttrs config
then
mapAttrs (name: value:
if nested ? ${name}
then injectAssertions nested.${name} value
then injectChecks nested.${name} value
else value
) config
else config;
in trigger result;
# List of assertions for this module evaluation, where each assertion also
# List of checks for this module evaluation, where each check also
# has a `show` attribute for how to show it if triggered
assertions = mapAttrsToList (name: value:
checks = mapAttrsToList (name: value:
let id =
if lib.hasPrefix "_" name then ""
else "[${showOption prefix}${optionalString (prefix != []) "/"}${name}] ";
in value // {
show = "${id}${value.message}";
}
) config._module.assertions;
) config._module.checks;
finalConfig = injectAssertions assertions (removeAttrs config [ "_module" ]);
finalConfig = injectChecks checks (removeAttrs config [ "_module" ]);
checkUnmatched =
if config._module.check && config._module.freeformType == null && merged.unmatchedDefns != [] then
@ -931,7 +937,7 @@ rec {
visible = false;
apply = x: throw "The option `${showOption optionName}' can no longer be used since it's been removed. ${replacementInstructions}";
});
config._module.assertions =
config._module.checks =
let opt = getAttrFromPath optionName options; in {
${showOption optionName} = {
enable = mkDefault opt.isDefined;
@ -1001,7 +1007,7 @@ rec {
})) from);
config = {
_module.assertions =
_module.checks =
let warningMessages = map (f:
let val = getAttrFromPath f config;
opt = getAttrFromPath f options;
@ -1072,7 +1078,7 @@ rec {
});
config = mkMerge [
{
_module.assertions.${showOption from} = {
_module.checks.${showOption from} = {
enable = mkDefault (warn && fromOpt.isDefined);
type = "warning";
message = "The option `${showOption from}' defined in ${showFiles fromOpt.files} has been renamed to `${showOption to}'.";

View file

@ -277,9 +277,9 @@ checkConfigOutput baz config.value.nested.bar.baz ./types-anything/mk-mods.nix
## Module assertions
# Check that assertions are triggered by default for just evaluating config
checkConfigError 'Failed assertions:\n- \[test\] Assertion failed' config ./assertions/simple.nix
checkConfigError 'Failed checks:\n- \[test\] Assertion failed' config ./assertions/simple.nix
# Check that assertions are only triggered if they have a triggerPath that's evaluated
checkConfigError 'Failed assertions:\n- \[test\] Assertion failed' config.foo ./assertions/trigger-lazy.nix
checkConfigError 'Failed checks:\n- \[test\] Assertion failed' config.foo ./assertions/trigger-lazy.nix
checkConfigOutput true config.bar ./assertions/trigger-lazy.nix
# The assertions enable condition should only be evaluated if the trigger is evaluated
@ -294,23 +294,23 @@ checkConfigCodeOutErr 0 '{ }' 'warning: \[test\] Warning message' config ./asser
# A triggerPath can be set to a submodule path
checkConfigOutput '{ baz = <CODE>; }' config.foo.bar ./assertions/trigger-submodule.nix
checkConfigError 'Failed assertions:\n- \[test\] Assertion failed' config.foo.bar.baz ./assertions/trigger-submodule.nix
checkConfigError 'Failed checks:\n- \[test\] Assertion failed' config.foo.bar.baz ./assertions/trigger-submodule.nix
# Check that multiple assertions and warnings can be triggered at once
checkConfigError 'Failed assertions:\n- \[test1\] Assertion 1 failed\n- \[test2\] Assertion 2 failed' config ./assertions/multi.nix
checkConfigError 'Failed checks:\n- \[test1\] Assertion 1 failed\n- \[test2\] Assertion 2 failed' config ./assertions/multi.nix
checkConfigError 'trace: warning: \[test3\] Warning 3 failed\ntrace: warning: \[test4\] Warning 4 failed' config ./assertions/multi.nix
# Submodules should be able to trigger assertions and display the submodule prefix in their error
checkConfigError 'Failed assertions:\n- \[foo/test\] Assertion failed' config.foo ./assertions/submodule.nix
checkConfigError 'Failed assertions:\n- \[foo.bar/test\] Assertion failed' config.foo.bar ./assertions/submodule-attrsOf.nix
checkConfigError 'Failed assertions:\n- \[foo.bar.baz/test\] Assertion failed' config.foo.bar.baz ./assertions/submodule-attrsOf-attrsOf.nix
checkConfigError 'Failed checks:\n- \[foo/test\] Assertion failed' config.foo ./assertions/submodule.nix
checkConfigError 'Failed checks:\n- \[foo.bar/test\] Assertion failed' config.foo.bar ./assertions/submodule-attrsOf.nix
checkConfigError 'Failed checks:\n- \[foo.bar.baz/test\] Assertion failed' config.foo.bar.baz ./assertions/submodule-attrsOf-attrsOf.nix
# Assertions aren't triggered when the trigger path is only evaluated from within the same module evaluation
# This behavior is necessary to allow assertions to depend on config values. This could potentially be changed in the future if all of NixOS' assertions are rewritten to not depend on any config values
checkConfigOutput true config.bar ./assertions/non-cascading.nix
# Assertions with an attribute starting with _ shouldn't have their name displayed
checkConfigError 'Failed assertions:\n- Assertion failed' config ./assertions/underscore-attributes.nix
checkConfigError 'Failed checks:\n- Assertion failed' config ./assertions/underscore-attributes.nix
cat <<EOF
====== module tests ======

View file

@ -1,6 +1,6 @@
{
_module.assertions.test = {
_module.checks.test = {
enable = false;
message = "Assertion failed";
};

View file

@ -8,7 +8,7 @@
default = true;
};
config._module.assertions.test = {
config._module.checks.test = {
enable = throw "enable evaluated";
message = "Assertion failed";
triggerPath = [ "foo" ];

View file

@ -1,6 +1,6 @@
{
_module.assertions = {
_module.checks = {
test1 = {
enable = true;
message = "Assertion 1 failed";

View file

@ -8,7 +8,7 @@
default = config.foo;
};
config._module.assertions.foo = {
config._module.checks.foo = {
enable = true;
message = "Foo assertion";
triggerPath = [ "foo" ];

View file

@ -1,5 +1,5 @@
{
_module.assertions.test = {
_module.checks.test = {
enable = true;
message = "Assertion failed";
};

View file

@ -3,7 +3,7 @@
options.foo = lib.mkOption {
default = { bar.baz = {}; };
type = lib.types.attrsOf (lib.types.attrsOf (lib.types.submodule {
_module.assertions.test = {
_module.checks.test = {
enable = true;
message = "Assertion failed";
};

View file

@ -3,7 +3,7 @@
options.foo = lib.mkOption {
default = { bar = {}; };
type = lib.types.attrsOf (lib.types.submodule {
_module.assertions.test = {
_module.checks.test = {
enable = true;
message = "Assertion failed";
};

View file

@ -3,7 +3,7 @@
options.foo = lib.mkOption {
default = {};
type = lib.types.submodule {
_module.assertions.test = {
_module.checks.test = {
enable = true;
message = "Assertion failed";
};

View file

@ -7,7 +7,7 @@
default = true;
};
config._module.assertions.test = {
config._module.checks.test = {
enable = true;
message = "Assertion failed";
triggerPath = [ "foo" ];

View file

@ -9,7 +9,7 @@
});
};
config._module.assertions.test = {
config._module.checks.test = {
enable = true;
message = "Assertion failed";
triggerPath = [ "foo" "bar" "baz" ];

View file

@ -1,6 +1,6 @@
{
_module.assertions._test = {
_module.checks._test = {
enable = true;
message = "Assertion failed";
};

View file

@ -1,6 +1,6 @@
{
_module.assertions.test = {
_module.checks.test = {
enable = true;
type = "warning";
message = "Warning message";

View file

@ -3,39 +3,49 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-assertions">
<title>Warnings and Assertions</title>
<title>Evaluation Checks</title>
<para>
When configuration problems are detectable in a module, it is a good idea to
write an assertion or warning. Doing so provides clear feedback to the user
and can prevent errors before the build.
write a check for catching it early. Doing so can provide clear feedback to
the user and can prevent errors before the build.
</para>
<para>
Although Nix has the <literal>abort</literal> and
<literal>builtins.trace</literal>
<link xlink:href="https://nixos.org/nix/manual/#ssec-builtins">functions</link>
to perform such tasks, they are not ideally suited for NixOS modules. Instead
of these functions, you can declare your warnings and assertions using the
NixOS module system.
to perform such tasks generally, they are not ideally suited for NixOS
modules. Instead of these functions, you can declare your evaluation checks
using the NixOS module system.
</para>
<section xml:id="sec-assertions-define">
<title>Defining Warnings and Assertions</title>
<title>Defining Checks</title>
<para>
Both warnings and assertions can be defined using the <xref linkend="opt-_module.assertions"/> option. Each assertion needs an attribute name, under which you have to define an enable condition using <xref linkend="opt-_module.assertions._name_.enable"/> and a message using <xref linkend="opt-_module.assertions._name_.message"/>. Note that the enable condition is <emphasis>inverse</emphasis> of what an assertion would be: To assert a value being true, the enable condition should be false in that case, so that it isn't triggered. For the assertion message, you can add <literal>options</literal> to the module arguments and use <literal>${options.path.to.option}</literal> to print a context-aware string representation of the option path. Here is an example showing how this can be done.
Checks can be defined using the <xref linkend="opt-_module.checks"/> option.
Each check needs an attribute name, under which you have to define an enable
condition using <xref linkend="opt-_module.checks._name_.enable"/> and a
message using <xref linkend="opt-_module.checks._name_.message"/>. Note that
the enable condition is <emphasis>inverse</emphasis> of what an assertion
would be: To assert a value being true, the enable condition should be false
in that case, so that it isn't triggered. For the check message, you can add
<literal>options</literal> to the module arguments and use
<literal>${options.path.to.option}</literal> to print a context-aware string
representation of the option path. Here is an example showing how this can be
done.
</para>
<programlisting>
{ config, options, ... }: {
_module.assertions.gpgSshAgent = {
_module.checks.gpgSshAgent = {
enable = config.programs.gnupg.agent.enableSSHSupport &amp;&amp; config.programs.ssh.startAgent;
message = "You can't enable both ${options.programs.ssh.startAgent}"
+ " and ${options.programs.gnupg.agent.enableSSHSupport}!";
};
_module.assertions.grafanaPassword = {
_module.checks.grafanaPassword = {
enable = config.services.grafana.database.password != "";
message = "The grafana password defined with ${options.services.grafana.database.password}"
+ " will be stored as plaintext in the Nix store!";
@ -48,41 +58,51 @@
</section>
<section xml:id="sec-assertions-ignoring">
<title>Ignoring Warnings and Assertions</title>
<title>Ignoring Checks</title>
<para>
Sometimes you can get warnings or assertions that don't apply to your specific case and you wish to ignore them, or at least make assertions non-fatal. You can do so for all assertions defined using <xref linkend="opt-_module.assertions"/> by using the attribute name of the definition, which is conveniently printed using <literal>[...]</literal> when the assertion is triggered. For above example, the evaluation output when the assertions are triggered looks as follows:
Sometimes you can get failing checks that don't apply to your specific case
and you wish to ignore them, or at least make errors non-fatal. You can do so
for all checks defined using <xref linkend="opt-_module.checks"/> by
using the attribute name of the definition, which is conveniently printed
using <literal>[...]</literal> when the check is triggered. For above
example, the evaluation output when the checks are triggered looks as
follows:
</para>
<programlisting>
trace: warning: [grafanaPassword] The grafana password defined with
services.grafana.database.password will be stored as plaintext in the Nix store!
error: Failed assertions:
error: Failed checks:
- [gpgSshAgent] You can't enable both programs.ssh.startAgent and
programs.gnupg.agent.enableSSHSupport!
</programlisting>
<para>
The <literal>[grafanaPassword]</literal> and <literal>[gpgSshAgent]</literal> strings tell you that these were defined under the <literal>grafanaPassword</literal> and <literal>gpgSshAgent</literal> attributes of <xref linkend="opt-_module.assertions"/> respectively. With this knowledge you can adjust them to your liking:
The <literal>[grafanaPassword]</literal> and <literal>[gpgSshAgent]</literal>
strings tell you that these were defined under the <literal>grafanaPassword
</literal> and <literal>gpgSshAgent</literal> attributes of
<xref linkend="opt-_module.checks"/> respectively. With this knowledge
you can adjust them to your liking:
</para>
<programlisting>
{ lib, ... }: {
# Change the assertion into a non-fatal warning
_module.assertions.gpgSshAgent.type = "warning";
# Change the error into a non-fatal warning
_module.checks.gpgSshAgent.type = "warning";
# We don't care about this warning, disable it
_module.assertions.grafanaPassword.enable = lib.mkForce false;
_module.checks.grafanaPassword.enable = lib.mkForce false;
}
</programlisting>
</section>
<section xml:id="sec-assertions-submodules">
<title>Warnings and Assertions in Submodules</title>
<title>Checks in Submodules</title>
<para>
Warnings and assertions can be defined within submodules in the same way. Here is an example:
Evaluation checks can be defined within submodules in the same way. Here is an example:
</para>
<programlisting>
@ -92,7 +112,7 @@ error: Failed assertions:
type = lib.types.attrsOf (lib.types.submodule ({ config, options, ... }: {
options.port = lib.mkOption {};
config._module.assertions.portConflict = {
config._module.checks.portConflict = {
enable = config.port == 80;
message = "Port ${toString config.port} defined using"
+ " ${options.port} is usually used for HTTP";
@ -105,7 +125,10 @@ error: Failed assertions:
</programlisting>
<para>
When this assertion is triggered, it shows both the submodule path along with the assertion attribute within that submodule, joined by a <literal>/</literal>. Note also how <literal>${options.port}</literal> correctly shows the context of the option.
When this check is triggered, it shows both the submodule path along with
the check attribute within that submodule, joined by a
<literal>/</literal>. Note also how <literal>${options.port}</literal>
correctly shows the context of the option.
</para>
<programlisting>
@ -114,18 +137,21 @@ trace: warning: [myServices.foo/portConflict] Port 80 defined using
</programlisting>
<para>
Therefore to disable such an assertion, you can do so by changing the <xref linkend="opt-_module.assertions"/> option within the <literal>myServices.foo</literal> submodule:
Therefore to disable such a check, you can do so by changing the
<xref linkend="opt-_module.checks"/> option within the
<literal>myServices.foo</literal> submodule:
</para>
<programlisting>
{ lib, ... }: {
myServices.foo._module.assertions.portConflict.enable = lib.mkForce false;
myServices.foo._module.checks.portConflict.enable = lib.mkForce false;
}
</programlisting>
<note>
<para>
Assertions defined in submodules under <literal>types.listOf</literal> can't be ignored, since there's no way to change previously defined list items.
Checks defined in submodules under <literal>types.listOf</literal> can't be
ignored, since there's no way to change previously defined list items.
</para>
</note>

View file

@ -29,7 +29,7 @@ with lib;
'';
};
_module.assertions = mkOption {
_module.checks = mkOption {
type = types.attrsOf (types.submodule {
triggerPath = mkDefault [ "system" "build" "toplevel" ];
});
@ -37,7 +37,7 @@ with lib;
};
config._module.assertions = lib.listToAttrs (lib.imap1 (n: value:
config._module.checks = lib.listToAttrs (lib.imap1 (n: value:
let
name = "_${toString n}";
isWarning = lib.isString value;