commit 9e6737710c4fb2613850e699178b23d54f1a3261 · pyrox.dev/nixpkgs

+22 -142

lib/modules.nix

···

       46
       46
        
           showFiles

     

       47
       47
        
           showOption

     

       48
       48
        
           unknownModule

     

       49
       49
       -
           literalExample

     

       50
       49
        
           ;

     

       51
       50
        
       in

     

       52
       51
        
       

     
···

       73
       72
        
                         check ? true

     

       74
       73
        
                       }:

     

       75
       74
        
           let

     

       76
       76
       -
             # An internal module that's always added, defining special options which

     

       77
       77
       -
             # change the behavior of the module evaluation itself. This is under a

     

       78
       78
       -
             # `_`-prefixed namespace in order to prevent name clashes with

     

       79
       79
       -
             # user-defined options

     

       75
       75
       +
             # This internal module declare internal options under the `_module'

     

       76
       76
       +
             # attribute.  These options are fragile, as they are used by the

     

       77
       77
       +
             # module system to change the interpretation of modules.

     

       80
       78
        
             internalModule = rec {

     

       81
       81
       -
               # FIXME: Using ./modules.nix directly breaks the doc for some reason

     

       82
       82
       -
               _file = "lib/modules.nix";

     

       79
       79
       +
               _file = ./modules.nix;

     

       83
       80
        
       

     

       84
       81
        
               key = _file;

     

       85
       82
        
       

     

       86
       86
       -
               # Most of these options are set to be internal only for prefix != [],

     

       87
       87
       -
               # aka it's a submodule evaluation. This way their docs are displayed

     

       88
       88
       -
               # only once as a top-level NixOS option, but will be hidden for all

     

       89
       89
       -
               # submodules, even though they are available there too

     

       90
       83
        
               options = {

     

       91
       84
        
                 _module.args = mkOption {

     

       92
       85
        
                   # Because things like `mkIf` are entirely useless for

     
···

       96
       89
        
                   # a `_module.args.pkgs = import (fetchTarball { ... }) {}` won't

     

       97
       90
        
                   # start a download when `pkgs` wasn't evaluated.

     

       98
       91
        
                   type = types.lazyAttrsOf types.unspecified;

     

       99
       99
       -
                   internal = prefix != [];

     

       92
       92
       +
                   internal = true;

     

       100
       93
        
                   description = "Arguments passed to each module.";

     

       101
       94
        
                 };

     

       102
       95
        
       

     
···

       104
       97
        
                   type = types.bool;

     

       105
       98
        
                   internal = true;

     

       106
       99
        
                   default = check;

     

       107
       107
       -
                   description = ''

     

       108
       108
       -
                     Whether to check whether all option definitions have matching

     

       109
       109
       -
                     declarations.

     

       110
       110
       -
       

     

       111
       111
       -
                     Note that this has nothing to do with the similarly named

     

       112
       112
       -
                     <option>_module.checks</option> option

     

       113
       113
       -
                   '';

     

       100
       100
       +
                   description = "Whether to check whether all option definitions have matching declarations.";

     

       114
       101
        
                 };

     

       115
       102
        
       

     

       116
       103
        
                 _module.freeformType = mkOption {

     

       117
       104
        
                   # Disallow merging for now, but could be implemented nicely with a `types.optionType`

     

       118
       105
        
                   type = types.nullOr (types.uniq types.attrs);

     

       119
       119
       -
                   internal = prefix != [];

     

       106
       106
       +
                   internal = true;

     

       120
       107
        
                   default = null;

     

       121
       108
        
                   description = ''

     

       122
       109
        
                     If set, merge all definitions that don't have an associated option

     
···

       129
       116
        
                     turned off.

     

       130
       117
        
                   '';

     

       131
       118
        
                 };

     

       132
       132
       -
       

     

       133
       133
       -
                 _module.checks = mkOption {

     

       134
       134
       -
                   description = ''

     

       135
       135
       -
                     Evaluation checks to trigger during module evaluation. The

     

       136
       136
       -
                     attribute name will be displayed when it is triggered, allowing

     

       137
       137
       -
                     users to disable/change these checks if necessary. See

     

       138
       138
       -
                     the section on Warnings and Assertions in the manual for more

     

       139
       139
       -
                     information.

     

       140
       140
       -
                   '';

     

       141
       141
       -
                   example = literalExample ''

     

       142
       142
       -
                     {

     

       143
       143
       -
                       gpgSshAgent = {

     

       144
       144
       -
                         enable = config.programs.gnupg.agent.enableSSHSupport && config.programs.ssh.startAgent;

     

       145
       145
       -
                         message = "You can't use ssh-agent and GnuPG agent with SSH support enabled at the same time!";

     

       146
       146
       -
                       };

     

       147
       147
       -
       

     

       148
       148
       -
                       grafanaPassword = {

     

       149
       149
       -
                         enable = config.services.grafana.database.password != "";

     

       150
       150
       -
                         message = "Grafana passwords will be stored as plaintext in the Nix store!";

     

       151
       151
       -
                         type = "warning";

     

       152
       152
       -
                       };

     

       153
       153
       -
                     }

     

       154
       154
       -
                   '';

     

       155
       155
       -
                   default = {};

     

       156
       156
       -
                   internal = prefix != [];

     

       157
       157
       -
                   type = types.attrsOf (types.submodule {

     

       158
       158
       -
                     options.enable = mkOption {

     

       159
       159
       -
                       description = ''

     

       160
       160
       -
                         Whether to enable this check. Set this to false to not trigger

     

       161
       161
       -
                         any errors or warning messages. This is useful for ignoring a

     

       162
       162
       -
                         check in case it doesn't make sense in certain scenarios.

     

       163
       163
       -
                       '';

     

       164
       164
       -
                       default = true;

     

       165
       165
       -
                       type = types.bool;

     

       166
       166
       -
                     };

     

       167
       167
       -
       

     

       168
       168
       -
                     options.check = mkOption {

     

       169
       169
       -
                       description = ''

     

       170
       170
       -
                         The condition that must succeed in order for this check to be

     

       171
       171
       -
                         successful and not trigger a warning or error.

     

       172
       172
       -
                       '';

     

       173
       173
       -
                       readOnly = true;

     

       174
       174
       -
                       type = types.bool;

     

       175
       175
       -
                     };

     

       176
       176
       -
       

     

       177
       177
       -
                     options.type = mkOption {

     

       178
       178
       -
                       description = ''

     

       179
       179
       -
                         The type of the check. The default

     

       180
       180
       -
                         <literal>"error"</literal> type will cause evaluation to fail,

     

       181
       181
       -
                         while the <literal>"warning"</literal> type will only show a

     

       182
       182
       -
                         warning.

     

       183
       183
       -
                       '';

     

       184
       184
       -
                       type = types.enum [ "error" "warning" ];

     

       185
       185
       -
                       default = "error";

     

       186
       186
       -
                       example = "warning";

     

       187
       187
       -
                     };

     

       188
       188
       -
       

     

       189
       189
       -
                     options.message = mkOption {

     

       190
       190
       -
                       description = ''

     

       191
       191
       -
                         The message to display if this check triggers.

     

       192
       192
       -
                         To display option names in the message, add

     

       193
       193
       -
                         <literal>options</literal> to the module function arguments

     

       194
       194
       -
                         and use <literal>''${options.path.to.option}</literal>.

     

       195
       195
       -
                       '';

     

       196
       196
       -
                       type = types.str;

     

       197
       197
       -
                       example = "Enabling both \${options.services.foo.enable} and \${options.services.bar.enable} is not possible.";

     

       198
       198
       -
                     };

     

       199
       199
       -
                   });

     

       200
       200
       -
                 };

     

       201
       119
        
               };

     

       202
       120
        
       

     

       203
       121
        
               config = {

     
···

       236
       154
        
                 # paths, meaning recursiveUpdate will never override any value

     

       237
       155
        
                 else recursiveUpdate freeformConfig declaredConfig;

     

       238
       156
        
       

     

       239
       239
       -
             # Triggers all checks defined by _module.checks before returning its argument

     

       240
       240
       -
             triggerChecks = let

     

       241
       241
       -
       

     

       242
       242
       -
               handleCheck = errors: name:

     

       243
       243
       -
                 let

     

       244
       244
       -
                   value = config._module.checks.${name};

     

       245
       245
       -
                   show =

     

       246
       246
       -
                     # Assertions with a _ prefix aren't meant to be configurable

     

       247
       247
       -
                     if lib.hasPrefix "_" name then value.message

     

       248
       248
       -
                     else "[${showOption prefix}${optionalString (prefix != []) "/"}${name}] ${value.message}";

     

       249
       249
       -
                 in

     

       250
       250
       -
                   if value.enable -> value.check then errors

     

       251
       251
       -
                   else if value.type == "warning" then lib.warn show errors

     

       252
       252
       -
                   else if value.type == "error" then errors ++ [ show ]

     

       253
       253
       -
                   else abort "Unknown check type ${value.type}";

     

       254
       254
       -
       

     

       255
       255
       -
               errors = lib.foldl' handleCheck [] (lib.attrNames config._module.checks);

     

       256
       256
       -
       

     

       257
       257
       -
               errorMessage = ''

     

       258
       258
       -
                 Failed checks:

     

       259
       259
       -
                 ${lib.concatMapStringsSep "\n" (a: "- ${a}") errors}

     

       260
       260
       -
               '';

     

       261
       261
       -
       

     

       262
       262
       -
               trigger = if errors == [] then null else throw errorMessage;

     

       263
       263
       -
       

     

       264
       264
       -
             in builtins.seq trigger;

     

       265
       265
       -
       

     

       266
       266
       -
             finalConfig = triggerChecks (removeAttrs config [ "_module" ]);

     

       267
       267
       -
       

     

       268
       157
        
             checkUnmatched =

     

       269
       158
        
               if config._module.check && config._module.freeformType == null && merged.unmatchedDefns != [] then

     

       270
       159
        
                 let

     
···

       284
       173
        
       

     

       285
       174
        
             result = builtins.seq checkUnmatched {

     

       286
       175
        
               inherit options;

     

       287
       287
       -
               config = finalConfig;

     

       176
       176
       +
               config = removeAttrs config [ "_module" ];

     

       288
       177
        
               inherit (config) _module;

     

       289
       178
        
             };

     

       290
       179
        
           in result;

     
···

       625
       514
        
               definitions = map (def: def.value) res.defsFinal;

     

       626
       515
        
               files = map (def: def.file) res.defsFinal;

     

       627
       516
        
               inherit (res) isDefined;

     

       628
       628
       -
               # This allows options to be correctly displayed using `${options.path.to.it}`

     

       629
       629
       -
               __toString = _: showOption loc;

     

       630
       517
        
             };

     

       631
       518
        
       

     

       632
       519
        
         # Merge definitions of a value of a given type.

     
···

       886
       773
        
               visible = false;

     

       887
       774
        
               apply = x: throw "The option `${showOption optionName}' can no longer be used since it's been removed. ${replacementInstructions}";

     

       888
       775
        
             });

     

       889
       889
       -
             config._module.checks =

     

       890
       890
       -
               let opt = getAttrFromPath optionName options; in {

     

       891
       891
       -
               ${"removed-" + showOption optionName} = lib.mkIf opt.isDefined {

     

       776
       776
       +
             config.assertions =

     

       777
       777
       +
               let opt = getAttrFromPath optionName options; in [{

     

       778
       778
       +
                 assertion = !opt.isDefined;

     

       892
       779
        
                 message = ''

     

       893
       780
        
                   The option definition `${showOption optionName}' in ${showFiles opt.files} no longer has any effect; please remove it.

     

       894
       781
        
                   ${replacementInstructions}

     

       895
       782
        
                 '';

     

       896
       896
       -
               };

     

       897
       897
       -
             };

     

       783
       783
       +
               }];

     

       898
       784
        
           };

     

       899
       785
        
       

     

       900
       786
        
         /* Return a module that causes a warning to be shown if the

     
···

       955
       841
        
             })) from);

     

       956
       842
        
       

     

       957
       843
        
             config = {

     

       958
       958
       -
               _module.checks =

     

       959
       959
       -
                 let warningMessages = map (f:

     

       960
       960
       -
                   let val = getAttrFromPath f config;

     

       961
       961
       -
                       opt = getAttrFromPath f options;

     

       962
       962
       -
                   in {

     

       963
       963
       -
                     ${"merged" + showOption f} = lib.mkIf (val != "_mkMergedOptionModule") {

     

       964
       964
       -
                       type = "warning";

     

       965
       965
       -
                       message = "The option `${showOption f}' defined in ${showFiles opt.files} has been changed to `${showOption to}' that has a different type. Please read `${showOption to}' documentation and update your configuration accordingly.";

     

       966
       966
       -
                     };

     

       967
       967
       -
                   }

     

       968
       968
       -
                   ) from;

     

       969
       969
       -
                 in mkMerge warningMessages;

     

       844
       844
       +
               warnings = filter (x: x != "") (map (f:

     

       845
       845
       +
                 let val = getAttrFromPath f config;

     

       846
       846
       +
                     opt = getAttrFromPath f options;

     

       847
       847
       +
                 in

     

       848
       848
       +
                 optionalString

     

       849
       849
       +
                   (val != "_mkMergedOptionModule")

     

       850
       850
       +
                   "The option `${showOption f}' defined in ${showFiles opt.files} has been changed to `${showOption to}' that has a different type. Please read `${showOption to}' documentation and update your configuration accordingly."

     

       851
       851
       +
               ) from);

     

       970
       852
        
             } // setAttrByPath to (mkMerge

     

       971
       853
        
                    (optional

     

       972
       854
        
                      (any (f: (getAttrFromPath f config) != "_mkMergedOptionModule") from)

     
···

       1025
       907
        
             });

     

       1026
       908
        
             config = mkMerge [

     

       1027
       909
        
               {

     

       1028
       1028
       -
                 _module.checks.${"renamed-" + showOption from} = mkIf (warn && fromOpt.isDefined) {

     

       1029
       1029
       -
                   type = "warning";

     

       1030
       1030
       -
                   message = "The option `${showOption from}' defined in ${showFiles fromOpt.files} has been renamed to `${showOption to}'.";

     

       1031
       1031
       -
                 };

     

       910
       910
       +
                 warnings = optional (warn && fromOpt.isDefined)

     

       911
       911
       +
                   "The option `${showOption from}' defined in ${showFiles fromOpt.files} has been renamed to `${showOption to}'.";

     

       1032
       912
        
               }

     

       1033
       913
        
               (if withPriority

     

       1034
       914
        
                 then mkAliasAndWrapDefsWithPriority (setAttrByPath to) fromOpt

+1 -1

lib/options.nix

···

       192
       192
        
                 let ss = opt.type.getSubOptions opt.loc;

     

       193
       193
        
                 in if ss != {} then optionAttrSetToDocList' opt.loc ss else [];

     

       194
       194
        
             in

     

       195
       195
       -
               [ docOption ] ++ optionals (docOption.visible && ! docOption.internal) subOptions) (collect isOption options);

     

       195
       195
       +
               [ docOption ] ++ optionals docOption.visible subOptions) (collect isOption options);

     

       196
       196
        
       

     

       197
       197
        
       

     

       198
       198
        
         /* This function recursively removes all derivation attributes from

+1 -1

lib/tests/misc.nix

···

       655
       655
        
                 modules = [ module ];

     

       656
       656
        
               }).options;

     

       657
       657
        
       

     

       658
       658
       -
               locs = filter (o: ! o.internal) (optionAttrSetToDocList (removeAttrs options [ "_module" ]));

     

       658
       658
       +
               locs = filter (o: ! o.internal) (optionAttrSetToDocList options);

     

       659
       659
        
             in map (o: o.loc) locs;

     

       660
       660
        
           expected = [ [ "foo" ] [ "foo" "<name>" "bar" ] [ "foo" "bar" ] ];

     

       661
       661
        
         };

+21 -57

lib/tests/modules.sh

···

       27
       27
        
           fail=$((fail + 1))

     

       28
       28
        
       }

     

       29
       29
        
       

     

       30
       30
       -
       checkConfigCodeOutErr() {

     

       31
       31
       -
           local expectedExit=$1

     

       32
       32
       -
           shift;

     

       30
       30
       +
       checkConfigOutput() {

     

       33
       31
        
           local outputContains=$1

     

       34
       32
        
           shift;

     

       35
       35
       -
           local errorContains=$1

     

       36
       36
       -
           shift;

     

       37
       37
       -
           out=$(mktemp)

     

       38
       38
       -
           err=$(mktemp)

     

       39
       39
       -
           evalConfig "$@" 1>"$out" 2>"$err"

     

       40
       40
       -
           if [[ "$?" -ne "$expectedExit" ]]; then

     

       41
       41
       -
               echo 2>&1 "error: Expected exit code $expectedExit while evaluating"

     

       42
       42
       -
               reportFailure "$@"

     

       43
       43
       -
               return 1

     

       44
       44
       -
           fi

     

       45
       45
       -
       

     

       46
       46
       -
           if [[ -n "$outputContains" ]] && ! grep -zP --silent "$outputContains" "$out"; then

     

       47
       47
       -
               echo 2>&1 "error: Expected output matching '$outputContains', while evaluating"

     

       48
       48
       -
               reportFailure "$@"

     

       49
       49
       -
               return 1

     

       50
       50
       -
           fi

     

       51
       51
       -
       

     

       52
       52
       -
           if [[ -n "$errorContains" ]] && ! grep -zP --silent "$errorContains" "$err"; then

     

       53
       53
       -
               echo 2>&1 "error: Expected error matching '$errorContains', while evaluating"

     

       33
       33
       +
           if evalConfig "$@" 2>/dev/null | grep --silent "$outputContains" ; then

     

       34
       34
       +
               pass=$((pass + 1))

     

       35
       35
       +
               return 0;

     

       36
       36
       +
           else

     

       37
       37
       +
               echo 2>&1 "error: Expected result matching '$outputContains', while evaluating"

     

       54
       38
        
               reportFailure "$@"

     

       55
       39
        
               return 1

     

       56
       40
        
           fi

     

       57
       57
       -
       

     

       58
       58
       -
           pass=$((pass + 1))

     

       59
       59
       -
       

     

       60
       60
       -
           # Clean up temp files

     

       61
       61
       -
           rm "$out" "$err"

     

       62
       62
       -
       }

     

       63
       63
       -
       

     

       64
       64
       -
       checkConfigOutput() {

     

       65
       65
       -
           local outputContains=$1

     

       66
       66
       -
           shift;

     

       67
       67
       -
           checkConfigCodeOutErr 0 "$outputContains" "" "$@"

     

       68
       41
        
       }

     

       69
       42
        
       

     

       70
       43
        
       checkConfigError() {

     

       71
       44
        
           local errorContains=$1

     

       45
       45
       +
           local err=""

     

       72
       46
        
           shift;

     

       73
       73
       -
           checkConfigCodeOutErr 1 "" "$errorContains" "$@"

     

       47
       47
       +
           if err==$(evalConfig "$@" 2>&1 >/dev/null); then

     

       48
       48
       +
               echo 2>&1 "error: Expected error code, got exit code 0, while evaluating"

     

       49
       49
       +
               reportFailure "$@"

     

       50
       50
       +
               return 1

     

       51
       51
       +
           else

     

       52
       52
       +
               if echo "$err" | grep -zP --silent "$errorContains" ; then

     

       53
       53
       +
                   pass=$((pass + 1))

     

       54
       54
       +
                   return 0;

     

       55
       55
       +
               else

     

       56
       56
       +
                   echo 2>&1 "error: Expected error matching '$errorContains', while evaluating"

     

       57
       57
       +
                   reportFailure "$@"

     

       58
       58
       +
                   return 1

     

       59
       59
       +
               fi

     

       60
       60
       +
           fi

     

       74
       61
        
       }

     

       75
       62
        
       

     

       76
       63
        
       # Check boolean option.

     
···

       274
       261
        
       checkConfigOutput true config.value.mkbefore ./types-anything/mk-mods.nix

     

       275
       262
        
       checkConfigOutput 1 config.value.nested.foo ./types-anything/mk-mods.nix

     

       276
       263
        
       checkConfigOutput baz config.value.nested.bar.baz ./types-anything/mk-mods.nix

     

       277
       277
       -
       

     

       278
       278
       -
       ## Module assertions

     

       279
       279
       -
       # Check that assertions are triggered by default for just evaluating config

     

       280
       280
       -
       checkConfigError 'Failed checks:\n- \[test\] Assertion failed' config ./assertions/simple.nix

     

       281
       281
       -
       

     

       282
       282
       -
       # Assertion is not triggered when enable is false or condition is true

     

       283
       283
       -
       checkConfigOutput '{ }' config ./assertions/condition-true.nix

     

       284
       284
       -
       checkConfigOutput '{ }' config ./assertions/enable-false.nix

     

       285
       285
       -
       

     

       286
       286
       -
       # Warnings should be displayed on standard error

     

       287
       287
       -
       checkConfigCodeOutErr 0 '{ }' 'warning: \[test\] Warning message' config ./assertions/warning.nix

     

       288
       288
       -
       

     

       289
       289
       -
       # Check that multiple assertions and warnings can be triggered at once

     

       290
       290
       -
       checkConfigError 'Failed checks:\n- \[test1\] Assertion 1 failed\n- \[test2\] Assertion 2 failed' config ./assertions/multi.nix

     

       291
       291
       -
       checkConfigError 'trace: warning: \[test3\] Warning 3 failed\ntrace: warning: \[test4\] Warning 4 failed' config ./assertions/multi.nix

     

       292
       292
       -
       

     

       293
       293
       -
       # Submodules should be able to trigger assertions and display the submodule prefix in their error

     

       294
       294
       -
       checkConfigError 'Failed checks:\n- \[foo/test\] Assertion failed' config.foo ./assertions/submodule.nix

     

       295
       295
       -
       checkConfigError 'Failed checks:\n- \[foo.bar/test\] Assertion failed' config.foo.bar ./assertions/submodule-attrsOf.nix

     

       296
       296
       -
       checkConfigError 'Failed checks:\n- \[foo.bar.baz/test\] Assertion failed' config.foo.bar.baz ./assertions/submodule-attrsOf-attrsOf.nix

     

       297
       297
       -
       

     

       298
       298
       -
       # Assertions with an attribute starting with _ shouldn't have their name displayed

     

       299
       299
       -
       checkConfigError 'Failed checks:\n- Assertion failed' config ./assertions/underscore-attributes.nix

     

       300
       264
        
       

     

       301
       265
        
       cat <<EOF

     

       302
       266
        
       ====== module tests ======

-8

lib/tests/modules/assertions/condition-true.nix

···

       1
       1
       -
       {

     

       2
       2
       -
       

     

       3
       3
       -
         _module.checks.test = {

     

       4
       4
       -
           check = true;

     

       5
       5
       -
           message = "Assertion failed";

     

       6
       6
       -
         };

     

       7
       7
       -
       

     

       8
       8
       -
       }

-9

lib/tests/modules/assertions/enable-false.nix

···

       1
       1
       -
       {

     

       2
       2
       -
       

     

       3
       3
       -
         _module.checks.test = {

     

       4
       4
       -
           enable = false;

     

       5
       5
       -
           check = false;

     

       6
       6
       -
           message = "Assertion failed";

     

       7
       7
       -
         };

     

       8
       8
       -
       

     

       9
       9
       -
       }

-23

lib/tests/modules/assertions/multi.nix

···

       1
       1
       -
       {

     

       2
       2
       -
       

     

       3
       3
       -
         _module.checks = {

     

       4
       4
       -
           test1 = {

     

       5
       5
       -
             check = false;

     

       6
       6
       -
             message = "Assertion 1 failed";

     

       7
       7
       -
           };

     

       8
       8
       -
           test2 = {

     

       9
       9
       -
             check = false;

     

       10
       10
       -
             message = "Assertion 2 failed";

     

       11
       11
       -
           };

     

       12
       12
       -
           test3 = {

     

       13
       13
       -
             check = false;

     

       14
       14
       -
             message = "Warning 3 failed";

     

       15
       15
       -
             type = "warning";

     

       16
       16
       -
           };

     

       17
       17
       -
           test4 = {

     

       18
       18
       -
             check = false;

     

       19
       19
       -
             message = "Warning 4 failed";

     

       20
       20
       -
             type = "warning";

     

       21
       21
       -
           };

     

       22
       22
       -
         };

     

       23
       23
       -
       }

-6

lib/tests/modules/assertions/simple.nix

···

       1
       1
       -
       {

     

       2
       2
       -
         _module.checks.test = {

     

       3
       3
       -
           check = false;

     

       4
       4
       -
           message = "Assertion failed";

     

       5
       5
       -
         };

     

       6
       6
       -
       }

-13

lib/tests/modules/assertions/submodule-attrsOf-attrsOf.nix

···

       1
       1
       -
       { lib, ... }: {

     

       2
       2
       -
       

     

       3
       3
       -
         options.foo = lib.mkOption {

     

       4
       4
       -
           default = { bar.baz = {}; };

     

       5
       5
       -
           type = lib.types.attrsOf (lib.types.attrsOf (lib.types.submodule {

     

       6
       6
       -
             _module.checks.test = {

     

       7
       7
       -
               check = false;

     

       8
       8
       -
               message = "Assertion failed";

     

       9
       9
       -
             };

     

       10
       10
       -
           }));

     

       11
       11
       -
         };

     

       12
       12
       -
       

     

       13
       13
       -
       }

-13

lib/tests/modules/assertions/submodule-attrsOf.nix

···

       1
       1
       -
       { lib, ... }: {

     

       2
       2
       -
       

     

       3
       3
       -
         options.foo = lib.mkOption {

     

       4
       4
       -
           default = { bar = {}; };

     

       5
       5
       -
           type = lib.types.attrsOf (lib.types.submodule {

     

       6
       6
       -
             _module.checks.test = {

     

       7
       7
       -
               check = false;

     

       8
       8
       -
               message = "Assertion failed";

     

       9
       9
       -
             };

     

       10
       10
       -
           });

     

       11
       11
       -
         };

     

       12
       12
       -
       

     

       13
       13
       -
       }

-13

lib/tests/modules/assertions/submodule.nix

···

       1
       1
       -
       { lib, ... }: {

     

       2
       2
       -
       

     

       3
       3
       -
         options.foo = lib.mkOption {

     

       4
       4
       -
           default = {};

     

       5
       5
       -
           type = lib.types.submodule {

     

       6
       6
       -
             _module.checks.test = {

     

       7
       7
       -
               check = false;

     

       8
       8
       -
               message = "Assertion failed";

     

       9
       9
       -
             };

     

       10
       10
       -
           };

     

       11
       11
       -
         };

     

       12
       12
       -
       

     

       13
       13
       -
       }

-8

lib/tests/modules/assertions/underscore-attributes.nix

···

       1
       1
       -
       {

     

       2
       2
       -
       

     

       3
       3
       -
         _module.checks._test = {

     

       4
       4
       -
           check = false;

     

       5
       5
       -
           message = "Assertion failed";

     

       6
       6
       -
         };

     

       7
       7
       -
       

     

       8
       8
       -
       }

-9

lib/tests/modules/assertions/warning.nix

···

       1
       1
       -
       {

     

       2
       2
       -
       

     

       3
       3
       -
         _module.checks.test = {

     

       4
       4
       -
           check = false;

     

       5
       5
       -
           type = "warning";

     

       6
       6
       -
           message = "Warning message";

     

       7
       7
       -
         };

     

       8
       8
       -
       

     

       9
       9
       -
       }

+38 -121

nixos/doc/manual/development/assertions.xml

···

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

     

       4
       4
        
               version="5.0"

     

       5
       5
        
               xml:id="sec-assertions">

     

       6
       6
       -
        <title>Evaluation Checks</title>

     

       6
       6
       +
        <title>Warnings and Assertions</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
        
         When configuration problems are detectable in a module, it is a good idea to

     

       10
       10
       -
         write a check for catching it early. Doing so can provide clear feedback to

     

       11
       11
       -
         the user and can prevent errors before the build.

     

       10
       10
       +
         write an assertion or warning. Doing so provides clear feedback to the user

     

       11
       11
       +
         and prevents errors after the build.

     

       12
       12
        
        </para>

     

       13
       13
        
       

     

       14
       14
        
        <para>

     

       15
       15
        
         Although Nix has the <literal>abort</literal> and

     

       16
       16
        
         <literal>builtins.trace</literal>

     

       17
       17
        
         <link xlink:href="https://nixos.org/nix/manual/#ssec-builtins">functions</link>

     

       18
       18
       -
         to perform such tasks generally, they are not ideally suited for NixOS

     

       19
       19
       -
         modules. Instead of these functions, you can declare your evaluation checks

     

       20
       20
       -
         using the NixOS module system.

     

       18
       18
       +
         to perform such tasks, they are not ideally suited for NixOS modules. Instead

     

       19
       19
       +
         of these functions, you can declare your warnings and assertions using the

     

       20
       20
       +
         NixOS module system.

     

       21
       21
        
        </para>

     

       22
       22
        
       

     

       23
       23
       -
        <section xml:id="sec-assertions-define">

     

       24
       24
       -
         <title>Defining Checks</title>

     

       25
       25
       -
       

     

       26
       26
       -
         <para>

     

       27
       27
       -
          Checks can be defined using the <xref linkend="opt-_module.checks"/> option.

     

       28
       28
       -
          Each check needs an attribute name, under which you can define a trigger

     

       29
       29
       -
          assertion using <xref linkend="opt-_module.checks._name_.check"/> and a

     

       30
       30
       -
          message using <xref linkend="opt-_module.checks._name_.message"/>.

     

       31
       31
       -
          For the message, you can add

     

       32
       32
       -
          <literal>options</literal> to the module arguments and use

     

       33
       33
       -
          <literal>${options.path.to.option}</literal> to print a context-aware string

     

       34
       34
       -
          representation of an option path. Here is an example showing how this can be

     

       35
       35
       -
          done.

     

       36
       36
       -
         </para>

     

       37
       37
       -
       

     

       38
       38
       -
       <programlisting>

     

       39
       39
       -
       { config, options, ... }: {

     

       40
       40
       -
         _module.checks.gpgSshAgent = {

     

       41
       41
       -
           check = config.programs.gnupg.agent.enableSSHSupport -> !config.programs.ssh.startAgent;

     

       42
       42
       -
           message = "If you have ${options.programs.gnupg.agent.enableSSHSupport} enabled,"

     

       43
       43
       -
             + " you can't enable ${options.programs.ssh.startAgent} as well!";

     

       44
       44
       -
         };

     

       45
       45
       -
       

     

       46
       46
       -
         _module.checks.grafanaPassword = {

     

       47
       47
       -
           check = config.services.grafana.database.password == "";

     

       48
       48
       -
           message = "The grafana password defined with ${options.services.grafana.database.password}"

     

       49
       49
       -
             + " will be stored as plaintext in the Nix store!";

     

       50
       50
       -
           # This is a non-fatal warning

     

       51
       51
       -
           type = "warning";

     

       52
       52
       -
         };

     

       53
       53
       -
       }

     

       54
       54
       -
       </programlisting>

     

       55
       55
       -
       

     

       56
       56
       -
        </section>

     

       57
       57
       -
       

     

       58
       58
       -
        <section xml:id="sec-assertions-ignoring">

     

       59
       59
       -
         <title>Ignoring Checks</title>

     

       60
       60
       -
       

     

       61
       61
       -
         <para>

     

       62
       62
       -
          Sometimes you can get failing checks that don't apply to your specific case

     

       63
       63
       -
          and you wish to ignore them, or at least make errors non-fatal. You can do so

     

       64
       64
       -
          for all checks defined using <xref linkend="opt-_module.checks"/> by

     

       65
       65
       -
          using the attribute name of the definition, which is conveniently printed

     

       66
       66
       -
          using <literal>[...]</literal> when the check is triggered. For above

     

       67
       67
       -
          example, the evaluation output when the checks are triggered looks as

     

       68
       68
       -
          follows:

     

       69
       69
       -
         </para>

     

       70
       70
       -
       

     

       71
       71
       -
       <programlisting>

     

       72
       72
       -
       trace: warning: [grafanaPassword] The grafana password defined with

     

       73
       73
       -
         services.grafana.database.password will be stored as plaintext in the Nix store!

     

       74
       74
       -
       error: Failed checks:

     

       75
       75
       -
       - [gpgSshAgent] If you have programs.gnupg.agent.enableSSHSupport

     

       76
       76
       -
         enabled, you can't enable programs.ssh.startAgent as well!

     

       77
       77
       -
       </programlisting>

     

       23
       23
       +
        <section xml:id="sec-assertions-warnings">

     

       24
       24
       +
         <title>Warnings</title>

     

       78
       25
        
       

     

       79
       26
        
         <para>

     

       80
       80
       -
          The <literal>[grafanaPassword]</literal> and <literal>[gpgSshAgent]</literal>

     

       81
       81
       -
          strings tell you that these were defined under the <literal>grafanaPassword

     

       82
       82
       -
          </literal> and <literal>gpgSshAgent</literal> attributes of

     

       83
       83
       -
          <xref linkend="opt-_module.checks"/> respectively. With this knowledge

     

       84
       84
       -
          you can adjust them to your liking:

     

       27
       27
       +
          This is an example of using <literal>warnings</literal>.

     

       85
       28
        
         </para>

     

       86
       29
        
       

     

       87
       30
        
       <programlisting>

     

       31
       31
       +
       <![CDATA[

     

       32
       32
       +
       { config, lib, ... }:

     

       88
       33
        
       {

     

       89
       89
       -
         # Change the error into a non-fatal warning

     

       90
       90
       -
         _module.checks.gpgSshAgent.type = "warning";

     

       91
       91
       -
       

     

       92
       92
       -
         # We don't care about this warning, disable it

     

       93
       93
       -
         _module.checks.grafanaPassword.enable = false;

     

       34
       34
       +
         config = lib.mkIf config.services.foo.enable {

     

       35
       35
       +
           warnings =

     

       36
       36
       +
             if config.services.foo.bar

     

       37
       37
       +
             then [ ''You have enabled the bar feature of the foo service.

     

       38
       38
       +
                      This is known to cause some specific problems in certain situations.

     

       39
       39
       +
                      '' ]

     

       40
       40
       +
             else [];

     

       41
       41
       +
         }

     

       94
       42
        
       }

     

       43
       43
       +
       ]]>

     

       95
       44
        
       </programlisting>

     

       96
       96
       -
       

     

       97
       97
       -
       

     

       98
       45
        
        </section>

     

       99
       99
       -
        <section xml:id="sec-assertions-submodules">

     

       100
       100
       -
         <title>Checks in Submodules</title>

     

       101
       46
        
       

     

       102
       102
       -
         <para>

     

       103
       103
       -
          Evaluation checks can be defined within submodules in the same way. Here is an example:

     

       104
       104
       -
         </para>

     

       105
       105
       -
       

     

       106
       106
       -
       <programlisting>

     

       107
       107
       -
       { lib, ... }: {

     

       108
       108
       -
       

     

       109
       109
       -
         options.myServices = lib.mkOption {

     

       110
       110
       -
           type = lib.types.attrsOf (lib.types.submodule ({ config, options, ... }: {

     

       111
       111
       -
             options.port = lib.mkOption {};

     

       112
       112
       -
       

     

       113
       113
       -
             config._module.checks.portConflict = {

     

       114
       114
       -
               check = config.port != 80;

     

       115
       115
       -
               message = "Port ${toString config.port} defined using"

     

       116
       116
       -
                 + " ${options.port} is usually used for HTTP";

     

       117
       117
       -
               type = "warning";

     

       118
       118
       -
             };

     

       119
       119
       -
           }));

     

       120
       120
       -
         };

     

       121
       121
       -
       

     

       122
       122
       -
       }

     

       123
       123
       -
       </programlisting>

     

       47
       47
       +
        <section xml:id="sec-assertions-assertions">

     

       48
       48
       +
         <title>Assertions</title>

     

       124
       49
        
       

     

       125
       50
        
         <para>

     

       126
       126
       -
          When this check is triggered, it shows both the submodule path along with

     

       127
       127
       -
          the check attribute within that submodule, joined by a

     

       128
       128
       -
          <literal>/</literal>. Note also how <literal>${options.port}</literal>

     

       129
       129
       -
          correctly shows the context of the option.

     

       51
       51
       +
          This example, extracted from the

     

       52
       52
       +
          <link xlink:href="https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix">

     

       53
       53
       +
          <literal>syslogd</literal> module </link> shows how to use

     

       54
       54
       +
          <literal>assertions</literal>. Since there can only be one active syslog

     

       55
       55
       +
          daemon at a time, an assertion is useful to prevent such a broken system

     

       56
       56
       +
          from being built.

     

       130
       57
        
         </para>

     

       131
       58
        
       

     

       132
       59
        
       <programlisting>

     

       133
       133
       -
       trace: warning: [myServices.foo/portConflict] Port 80 defined using

     

       134
       134
       -
         myServices.foo.port is usually used for HTTP

     

       135
       135
       -
       </programlisting>

     

       136
       136
       -
       

     

       137
       137
       -
         <para>

     

       138
       138
       -
          Therefore to disable such a check, you can do so by changing the

     

       139
       139
       -
          <xref linkend="opt-_module.checks"/> option within the

     

       140
       140
       -
          <literal>myServices.foo</literal> submodule:

     

       141
       141
       -
         </para>

     

       142
       142
       -
       

     

       143
       143
       -
       <programlisting>

     

       60
       60
       +
       <![CDATA[

     

       61
       61
       +
       { config, lib, ... }:

     

       144
       62
        
       {

     

       145
       145
       -
         myServices.foo._module.checks.portConflict.enable = false;

     

       63
       63
       +
         config = lib.mkIf config.services.syslogd.enable {

     

       64
       64
       +
           assertions =

     

       65
       65
       +
             [ { assertion = !config.services.rsyslogd.enable;

     

       66
       66
       +
                 message = "rsyslogd conflicts with syslogd";

     

       67
       67
       +
               }

     

       68
       68
       +
             ];

     

       69
       69
       +
         }

     

       146
       70
        
       }

     

       71
       71
       +
       ]]>

     

       147
       72
        
       </programlisting>

     

       148
       148
       -
       

     

       149
       149
       -
       <note>

     

       150
       150
       -
        <para>

     

       151
       151
       -
         Checks defined in submodules under <literal>types.listOf</literal> can't be

     

       152
       152
       -
         ignored, since there's no way to change previously defined list items.

     

       153
       153
       -
        </para>

     

       154
       154
       -
       </note>

     

       155
       155
       -
       

     

       156
       73
        
        </section>

     

       157
       74
        
       </section>

+1 -14

nixos/modules/misc/assertions.nix

···

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

     

       1
       1
       +
       { lib, ... }:

     

       2
       2
        
       

     

       3
       3
        
       with lib;

     

       4
       4
        
       

     
···

       30
       30
        
           };

     

       31
       31
        
       

     

       32
       32
        
         };

     

       33
       33
       -
       

     

       34
       34
       -
         config._module.checks = lib.listToAttrs (lib.imap1 (n: value:

     

       35
       35
       -
           let

     

       36
       36
       -
             name = "_${toString n}";

     

       37
       37
       -
             isWarning = lib.isString value;

     

       38
       38
       -
             result = {

     

       39
       39
       -
               check = if isWarning then false else value.assertion;

     

       40
       40
       -
               type = if isWarning then "warning" else "error";

     

       41
       41
       -
               message = if isWarning then value else value.message;

     

       42
       42
       -
             };

     

       43
       43
       -
           in nameValuePair name result

     

       44
       44
       -
         ) (config.assertions ++ config.warnings));

     

       45
       45
       -
       

     

       46
       33
        
         # impl of assertions is in <nixpkgs/nixos/modules/system/activation/top-level.nix>

     

       47
       34
        
       }

+9 -1

nixos/modules/system/activation/top-level.nix

···

       117
       117
        
           perl = "${pkgs.perl}/bin/perl " + (concatMapStringsSep " " (lib: "-I${lib}/${pkgs.perl.libPrefix}") (with pkgs.perlPackages; [ FileSlurp NetDBus XMLParser XMLTwig ]));

     

       118
       118
        
         };

     

       119
       119
        
       

     

       120
       120
       +
         # Handle assertions and warnings

     

       121
       121
       +
       

     

       122
       122
       +
         failedAssertions = map (x: x.message) (filter (x: !x.assertion) config.assertions);

     

       123
       123
       +
       

     

       124
       124
       +
         baseSystemAssertWarn = if failedAssertions != []

     

       125
       125
       +
           then throw "\nFailed assertions:\n${concatStringsSep "\n" (map (x: "- ${x}") failedAssertions)}"

     

       126
       126
       +
           else showWarnings config.warnings baseSystem;

     

       127
       127
       +
       

     

       120
       128
        
         # Replace runtime dependencies

     

       121
       129
        
         system = fold ({ oldDependency, newDependency }: drv:

     

       122
       130
        
             pkgs.replaceDependency { inherit oldDependency newDependency drv; }

     

       123
       123
       -
           ) baseSystem config.system.replaceRuntimeDependencies;

     

       131
       131
       +
           ) baseSystemAssertWarn config.system.replaceRuntimeDependencies;

     

       124
       132
        
       

     

       125
       133
        
       in

     

       126
       134