···

       
46
       
 
       
    showFiles

     

       
47
       
 
       
    showOption

     

       
48
       
 
       
    unknownModule

     

       
49
       
-
       
    literalExample

     

       
50
       
 
       
    ;

     

       
51
       
 
       
in

     

       
52
       
 
       


     
···

       
73
       
 
       
                  check ? true

     

       
74
       
 
       
                }:

     

       
75
       
 
       
    let

     

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

     

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

     

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

     

       
79
       
-
       
      # user-defined options

     

       
80
       
 
       
      internalModule = rec {

     

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

     

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

     

       
83
       
 
       


     

       
84
       
 
       
        key = _file;

     

       
85
       
 
       


     

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

     

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

     

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

     

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

     

       
90
       
 
       
        options = {

     

       
91
       
 
       
          _module.args = mkOption {

     

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

     
···

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

     

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

     

       
98
       
 
       
            type = types.lazyAttrsOf types.unspecified;

     

       
99
       
-
       
            internal = prefix != [];

     

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

     

       
101
       
 
       
          };

     

       
102
       
 
       


     
···

       
104
       
 
       
            type = types.bool;

     

       
105
       
 
       
            internal = true;

     

       
106
       
 
       
            default = check;

     

       
107
       
-
       
            description = ''

     

       
108
       
-
       
              Whether to check whether all option definitions have matching

     

       
109
       
-
       
              declarations.

     

       
110
       
-
       


     

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

     

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

     

       
113
       
-
       
            '';

     

       
114
       
 
       
          };

     

       
115
       
 
       


     

       
116
       
 
       
          _module.freeformType = mkOption {

     

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

     

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

     

       
119
       
-
       
            internal = prefix != [];

     

       
120
       
 
       
            default = null;

     

       
121
       
 
       
            description = ''

     

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

     
···

       
129
       
 
       
              turned off.

     

       
130
       
 
       
            '';

     

       
131
       
 
       
          };

     

       
132
       
-
       


     

       
133
       
-
       
          _module.checks = mkOption {

     

       
134
       
-
       
            description = ''

     

       
135
       
-
       
              Evaluation checks to trigger during module evaluation. The

     

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

     

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

     

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

     

       
139
       
-
       
              information.

     

       
140
       
-
       
            '';

     

       
141
       
-
       
            example = literalExample ''

     

       
142
       
-
       
              {

     

       
143
       
-
       
                gpgSshAgent = {

     

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

     

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

     

       
146
       
-
       
                };

     

       
147
       
-
       


     

       
148
       
-
       
                grafanaPassword = {

     

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

     

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

     

       
151
       
-
       
                  type = "warning";

     

       
152
       
-
       
                };

     

       
153
       
-
       
              }

     

       
154
       
-
       
            '';

     

       
155
       
-
       
            default = {};

     

       
156
       
-
       
            internal = prefix != [];

     

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

     

       
158
       
-
       
              options.enable = mkOption {

     

       
159
       
-
       
                description = ''

     

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

     

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

     

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

     

       
163
       
-
       
                '';

     

       
164
       
-
       
                default = true;

     

       
165
       
-
       
                type = types.bool;

     

       
166
       
-
       
              };

     

       
167
       
-
       


     

       
168
       
-
       
              options.check = mkOption {

     

       
169
       
-
       
                description = ''

     

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

     

       
171
       
-
       
                  successful and not trigger a warning or error.

     

       
172
       
-
       
                '';

     

       
173
       
-
       
                readOnly = true;

     

       
174
       
-
       
                type = types.bool;

     

       
175
       
-
       
              };

     

       
176
       
-
       


     

       
177
       
-
       
              options.type = mkOption {

     

       
178
       
-
       
                description = ''

     

       
179
       
-
       
                  The type of the check. The default

     

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

     

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

     

       
182
       
-
       
                  warning.

     

       
183
       
-
       
                '';

     

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

     

       
185
       
-
       
                default = "error";

     

       
186
       
-
       
                example = "warning";

     

       
187
       
-
       
              };

     

       
188
       
-
       


     

       
189
       
-
       
              options.message = mkOption {

     

       
190
       
-
       
                description = ''

     

       
191
       
-
       
                  The message to display if this check triggers.

     

       
192
       
-
       
                  To display option names in the message, add

     

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

     

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

     

       
195
       
-
       
                '';

     

       
196
       
-
       
                type = types.str;

     

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

     

       
198
       
-
       
              };

     

       
199
       
-
       
            });

     

       
200
       
-
       
          };

     

       
201
       
 
       
        };

     

       
202
       
 
       


     

       
203
       
 
       
        config = {

     
···

       
236
       
 
       
          # paths, meaning recursiveUpdate will never override any value

     

       
237
       
 
       
          else recursiveUpdate freeformConfig declaredConfig;

     

       
238
       
 
       


     

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

     

       
240
       
-
       
      triggerChecks = let

     

       
241
       
-
       


     

       
242
       
-
       
        handleCheck = errors: name:

     

       
243
       
-
       
          let

     

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

     

       
245
       
-
       
            show =

     

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

     

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

     

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

     

       
249
       
-
       
          in

     

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

     

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

     

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

     

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

     

       
254
       
-
       


     

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

     

       
256
       
-
       


     

       
257
       
-
       
        errorMessage = ''

     

       
258
       
-
       
          Failed checks:

     

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

     

       
260
       
-
       
        '';

     

       
261
       
-
       


     

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

     

       
263
       
-
       


     

       
264
       
-
       
      in builtins.seq trigger;

     

       
265
       
-
       


     

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

     

       
267
       
-
       


     

       
268
       
 
       
      checkUnmatched =

     

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

     

       
270
       
 
       
          let

     
···

       
284
       
 
       


     

       
285
       
 
       
      result = builtins.seq checkUnmatched {

     

       
286
       
 
       
        inherit options;

     

       
287
       
-
       
        config = finalConfig;

     

       
288
       
 
       
        inherit (config) _module;

     

       
289
       
 
       
      };

     

       
290
       
 
       
    in result;

     
···

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

     

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

     

       
627
       
 
       
        inherit (res) isDefined;

     

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

     

       
629
       
-
       
        __toString = _: showOption loc;

     

       
630
       
 
       
      };

     

       
631
       
 
       


     

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

     
···

       
886
       
 
       
        visible = false;

     

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

     

       
888
       
 
       
      });

     

       
889
       
-
       
      config._module.checks =

     

       
890
       
-
       
        let opt = getAttrFromPath optionName options; in {

     

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

     

       
892
       
 
       
          message = ''

     

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

     

       
894
       
 
       
            ${replacementInstructions}

     

       
895
       
 
       
          '';

     

       
896
       
-
       
        };

     

       
897
       
-
       
      };

     

       
898
       
 
       
    };

     

       
899
       
 
       


     

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

     
···

       
955
       
 
       
      })) from);

     

       
956
       
 
       


     

       
957
       
 
       
      config = {

     

       
958
       
-
       
        _module.checks =

     

       
959
       
-
       
          let warningMessages = map (f:

     

       
960
       
-
       
            let val = getAttrFromPath f config;

     

       
961
       
-
       
                opt = getAttrFromPath f options;

     

       
962
       
-
       
            in {

     

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

     

       
964
       
-
       
                type = "warning";

     

       
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
       
-
       
              };

     

       
967
       
-
       
            }

     

       
968
       
-
       
            ) from;

     

       
969
       
-
       
          in mkMerge warningMessages;

     

       
970
       
 
       
      } // setAttrByPath to (mkMerge

     

       
971
       
 
       
             (optional

     

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

     
···

       
1025
       
 
       
      });

     

       
1026
       
 
       
      config = mkMerge [

     

       
1027
       
 
       
        {

     

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

     

       
1029
       
-
       
            type = "warning";

     

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

     

       
1031
       
-
       
          };

     

       
1032
       
 
       
        }

     

       
1033
       
 
       
        (if withPriority

     

       
1034
       
 
       
          then mkAliasAndWrapDefsWithPriority (setAttrByPath to) fromOpt

     

···

       
46
       
 
       
    showFiles

     

       
47
       
 
       
    showOption

     

       
48
       
 
       
    unknownModule

     

       
0
       
 
       

     

       
49
       
 
       
    ;

     

       
50
       
 
       
in

     

       
51
       
 
       


     
···

       
72
       
 
       
                  check ? true

     

       
73
       
 
       
                }:

     

       
74
       
 
       
    let

     

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

     

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

     

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

     

       
0
       
 
       

     

       
78
       
 
       
      internalModule = rec {

     

       
79
       
+
       
        _file = ./modules.nix;

     

       
0
       
 
       

     

       
80
       
 
       


     

       
81
       
 
       
        key = _file;

     

       
82
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
83
       
 
       
        options = {

     

       
84
       
 
       
          _module.args = mkOption {

     

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

     
···

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

     

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

     

       
91
       
 
       
            type = types.lazyAttrsOf types.unspecified;

     

       
92
       
+
       
            internal = true;

     

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

     

       
94
       
 
       
          };

     

       
95
       
 
       


     
···

       
97
       
 
       
            type = types.bool;

     

       
98
       
 
       
            internal = true;

     

       
99
       
 
       
            default = check;

     

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

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
101
       
 
       
          };

     

       
102
       
 
       


     

       
103
       
 
       
          _module.freeformType = mkOption {

     

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

     

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

     

       
106
       
+
       
            internal = true;

     

       
107
       
 
       
            default = null;

     

       
108
       
 
       
            description = ''

     

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

     
···

       
116
       
 
       
              turned off.

     

       
117
       
 
       
            '';

     

       
118
       
 
       
          };

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
119
       
 
       
        };

     

       
120
       
 
       


     

       
121
       
 
       
        config = {

     
···

       
154
       
 
       
          # paths, meaning recursiveUpdate will never override any value

     

       
155
       
 
       
          else recursiveUpdate freeformConfig declaredConfig;

     

       
156
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
157
       
 
       
      checkUnmatched =

     

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

     

       
159
       
 
       
          let

     
···

       
173
       
 
       


     

       
174
       
 
       
      result = builtins.seq checkUnmatched {

     

       
175
       
 
       
        inherit options;

     

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

     

       
177
       
 
       
        inherit (config) _module;

     

       
178
       
 
       
      };

     

       
179
       
 
       
    in result;

     
···

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

     

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

     

       
516
       
 
       
        inherit (res) isDefined;

     

       
0
       
 
       

     

       
0
       
 
       

     

       
517
       
 
       
      };

     

       
518
       
 
       


     

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

     
···

       
773
       
 
       
        visible = false;

     

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

     

       
775
       
 
       
      });

     

       
776
       
+
       
      config.assertions =

     

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

     

       
778
       
+
       
          assertion = !opt.isDefined;

     

       
779
       
 
       
          message = ''

     

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

     

       
781
       
 
       
            ${replacementInstructions}

     

       
782
       
 
       
          '';

     

       
783
       
+
       
        }];

     

       
0
       
 
       

     

       
784
       
 
       
    };

     

       
785
       
 
       


     

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

     
···

       
841
       
 
       
      })) from);

     

       
842
       
 
       


     

       
843
       
 
       
      config = {

     

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

     

       
845
       
+
       
          let val = getAttrFromPath f config;

     

       
846
       
+
       
              opt = getAttrFromPath f options;

     

       
847
       
+
       
          in

     

       
848
       
+
       
          optionalString

     

       
849
       
+
       
            (val != "_mkMergedOptionModule")

     

       
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
       
+
       
        ) from);

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
852
       
 
       
      } // setAttrByPath to (mkMerge

     

       
853
       
 
       
             (optional

     

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

     
···

       
907
       
 
       
      });

     

       
908
       
 
       
      config = mkMerge [

     

       
909
       
 
       
        {

     

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

     

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

     

       
0
       
 
       

     

       
0
       
 
       

     

       
912
       
 
       
        }

     

       
913
       
 
       
        (if withPriority

     

       
914
       
 
       
          then mkAliasAndWrapDefsWithPriority (setAttrByPath to) fromOpt

     

···

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

     

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

     

       
194
       
 
       
      in

     

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

     

       
196
       
 
       


     

       
197
       
 
       


     

       
198
       
 
       
  /* This function recursively removes all derivation attributes from

     

···

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

     

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

     

       
194
       
 
       
      in

     

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

     

       
196
       
 
       


     

       
197
       
 
       


     

       
198
       
 
       
  /* This function recursively removes all derivation attributes from

     

···

       
655
       
 
       
          modules = [ module ];

     

       
656
       
 
       
        }).options;

     

       
657
       
 
       


     

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

     

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

     

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

     

       
661
       
 
       
  };

     

···

       
655
       
 
       
          modules = [ module ];

     

       
656
       
 
       
        }).options;

     

       
657
       
 
       


     

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

     

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

     

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

     

       
661
       
 
       
  };

     

···

       
27
       
 
       
    fail=$((fail + 1))

     

       
28
       
 
       
}

     

       
29
       
 
       


     

       
30
       
-
       
checkConfigCodeOutErr() {

     

       
31
       
-
       
    local expectedExit=$1

     

       
32
       
-
       
    shift;

     

       
33
       
 
       
    local outputContains=$1

     

       
34
       
 
       
    shift;

     

       
35
       
-
       
    local errorContains=$1

     

       
36
       
-
       
    shift;

     

       
37
       
-
       
    out=$(mktemp)

     

       
38
       
-
       
    err=$(mktemp)

     

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

     

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

     

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

     

       
42
       
-
       
        reportFailure "$@"

     

       
43
       
-
       
        return 1

     

       
44
       
-
       
    fi

     

       
45
       
-
       


     

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

     

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

     

       
48
       
-
       
        reportFailure "$@"

     

       
49
       
-
       
        return 1

     

       
50
       
-
       
    fi

     

       
51
       
-
       


     

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

     

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

     

       
54
       
 
       
        reportFailure "$@"

     

       
55
       
 
       
        return 1

     

       
56
       
 
       
    fi

     

       
57
       
-
       


     

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

     

       
59
       
-
       


     

       
60
       
-
       
    # Clean up temp files

     

       
61
       
-
       
    rm "$out" "$err"

     

       
62
       
-
       
}

     

       
63
       
-
       


     

       
64
       
-
       
checkConfigOutput() {

     

       
65
       
-
       
    local outputContains=$1

     

       
66
       
-
       
    shift;

     

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

     

       
68
       
 
       
}

     

       
69
       
 
       


     

       
70
       
 
       
checkConfigError() {

     

       
71
       
 
       
    local errorContains=$1

     

       
0
       
 
       

     

       
72
       
 
       
    shift;

     

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

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
74
       
 
       
}

     

       
75
       
 
       


     

       
76
       
 
       
# Check boolean option.

     
···

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

     

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

     

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

     

       
277
       
-
       


     

       
278
       
-
       
## Module assertions

     

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

     

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

     

       
281
       
-
       


     

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

     

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

     

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

     

       
285
       
-
       


     

       
286
       
-
       
# Warnings should be displayed on standard error

     

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

     

       
288
       
-
       


     

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

     

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

     

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

     

       
292
       
-
       


     

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

     

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

     

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

     

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

     

       
297
       
-
       


     

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

     

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

     

       
300
       
 
       


     

       
301
       
 
       
cat <<EOF

     

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

     

···

       
27
       
 
       
    fail=$((fail + 1))

     

       
28
       
 
       
}

     

       
29
       
 
       


     

       
30
       
+
       
checkConfigOutput() {

     

       
0
       
 
       

     

       
0
       
 
       

     

       
31
       
 
       
    local outputContains=$1

     

       
32
       
 
       
    shift;

     

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

     

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

     

       
35
       
+
       
        return 0;

     

       
36
       
+
       
    else

     

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

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
38
       
 
       
        reportFailure "$@"

     

       
39
       
 
       
        return 1

     

       
40
       
 
       
    fi

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
41
       
 
       
}

     

       
42
       
 
       


     

       
43
       
 
       
checkConfigError() {

     

       
44
       
 
       
    local errorContains=$1

     

       
45
       
+
       
    local err=""

     

       
46
       
 
       
    shift;

     

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

     

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

     

       
49
       
+
       
        reportFailure "$@"

     

       
50
       
+
       
        return 1

     

       
51
       
+
       
    else

     

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

     

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

     

       
54
       
+
       
            return 0;

     

       
55
       
+
       
        else

     

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

     

       
57
       
+
       
            reportFailure "$@"

     

       
58
       
+
       
            return 1

     

       
59
       
+
       
        fi

     

       
60
       
+
       
    fi

     

       
61
       
 
       
}

     

       
62
       
 
       


     

       
63
       
 
       
# Check boolean option.

     
···

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

     

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

     

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

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
264
       
 
       


     

       
265
       
 
       
cat <<EOF

     

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

     

···

       
1
       
-
       
{

     

       
2
       
-
       


     

       
3
       
-
       
  _module.checks.test = {

     

       
4
       
-
       
    check = true;

     

       
5
       
-
       
    message = "Assertion failed";

     

       
6
       
-
       
  };

     

       
7
       
-
       


     

       
8
       
-
       
}

     

···

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

       
1
       
-
       
{

     

       
2
       
-
       


     

       
3
       
-
       
  _module.checks.test = {

     

       
4
       
-
       
    enable = false;

     

       
5
       
-
       
    check = false;

     

       
6
       
-
       
    message = "Assertion failed";

     

       
7
       
-
       
  };

     

       
8
       
-
       


     

       
9
       
-
       
}

     

···

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

       
1
       
-
       
{

     

       
2
       
-
       


     

       
3
       
-
       
  _module.checks = {

     

       
4
       
-
       
    test1 = {

     

       
5
       
-
       
      check = false;

     

       
6
       
-
       
      message = "Assertion 1 failed";

     

       
7
       
-
       
    };

     

       
8
       
-
       
    test2 = {

     

       
9
       
-
       
      check = false;

     

       
10
       
-
       
      message = "Assertion 2 failed";

     

       
11
       
-
       
    };

     

       
12
       
-
       
    test3 = {

     

       
13
       
-
       
      check = false;

     

       
14
       
-
       
      message = "Warning 3 failed";

     

       
15
       
-
       
      type = "warning";

     

       
16
       
-
       
    };

     

       
17
       
-
       
    test4 = {

     

       
18
       
-
       
      check = false;

     

       
19
       
-
       
      message = "Warning 4 failed";

     

       
20
       
-
       
      type = "warning";

     

       
21
       
-
       
    };

     

       
22
       
-
       
  };

     

       
23
       
-
       
}

     

···

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

       
1
       
-
       
{

     

       
2
       
-
       
  _module.checks.test = {

     

       
3
       
-
       
    check = false;

     

       
4
       
-
       
    message = "Assertion failed";

     

       
5
       
-
       
  };

     

       
6
       
-
       
}

     

···

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

       
1
       
-
       
{ lib, ... }: {

     

       
2
       
-
       


     

       
3
       
-
       
  options.foo = lib.mkOption {

     

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

     

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

     

       
6
       
-
       
      _module.checks.test = {

     

       
7
       
-
       
        check = false;

     

       
8
       
-
       
        message = "Assertion failed";

     

       
9
       
-
       
      };

     

       
10
       
-
       
    }));

     

       
11
       
-
       
  };

     

       
12
       
-
       


     

       
13
       
-
       
}

     

···

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

       
1
       
-
       
{ lib, ... }: {

     

       
2
       
-
       


     

       
3
       
-
       
  options.foo = lib.mkOption {

     

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

     

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

     

       
6
       
-
       
      _module.checks.test = {

     

       
7
       
-
       
        check = false;

     

       
8
       
-
       
        message = "Assertion failed";

     

       
9
       
-
       
      };

     

       
10
       
-
       
    });

     

       
11
       
-
       
  };

     

       
12
       
-
       


     

       
13
       
-
       
}

     

···

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

       
1
       
-
       
{ lib, ... }: {

     

       
2
       
-
       


     

       
3
       
-
       
  options.foo = lib.mkOption {

     

       
4
       
-
       
    default = {};

     

       
5
       
-
       
    type = lib.types.submodule {

     

       
6
       
-
       
      _module.checks.test = {

     

       
7
       
-
       
        check = false;

     

       
8
       
-
       
        message = "Assertion failed";

     

       
9
       
-
       
      };

     

       
10
       
-
       
    };

     

       
11
       
-
       
  };

     

       
12
       
-
       


     

       
13
       
-
       
}

     

···

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

       
1
       
-
       
{

     

       
2
       
-
       


     

       
3
       
-
       
  _module.checks._test = {

     

       
4
       
-
       
    check = false;

     

       
5
       
-
       
    message = "Assertion failed";

     

       
6
       
-
       
  };

     

       
7
       
-
       


     

       
8
       
-
       
}

     

···

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

       
1
       
-
       
{

     

       
2
       
-
       


     

       
3
       
-
       
  _module.checks.test = {

     

       
4
       
-
       
    check = false;

     

       
5
       
-
       
    type = "warning";

     

       
6
       
-
       
    message = "Warning message";

     

       
7
       
-
       
  };

     

       
8
       
-
       


     

       
9
       
-
       
}

     

···

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

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

     

       
4
       
 
       
        version="5.0"

     

       
5
       
 
       
        xml:id="sec-assertions">

     

       
6
       
-
       
 <title>Evaluation Checks</title>

     

       
7
       
 
       


     

       
8
       
 
       
 <para>

     

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

     

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

     

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

     

       
12
       
 
       
 </para>

     

       
13
       
 
       


     

       
14
       
 
       
 <para>

     

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

     

       
16
       
 
       
  <literal>builtins.trace</literal>

     

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

     

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

     

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

     

       
20
       
-
       
  using the NixOS module system.

     

       
21
       
 
       
 </para>

     

       
22
       
 
       


     

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

     

       
24
       
-
       
  <title>Defining Checks</title>

     

       
25
       
-
       


     

       
26
       
-
       
  <para>

     

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

     

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

     

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

     

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

     

       
31
       
-
       
   For the message, you can add

     

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

     

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

     

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

     

       
35
       
-
       
   done.

     

       
36
       
-
       
  </para>

     

       
37
       
-
       


     

       
38
       
-
       
<programlisting>

     

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

     

       
40
       
-
       
  _module.checks.gpgSshAgent = {

     

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

     

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

     

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

     

       
44
       
-
       
  };

     

       
45
       
-
       


     

       
46
       
-
       
  _module.checks.grafanaPassword = {

     

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

     

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

     

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

     

       
50
       
-
       
    # This is a non-fatal warning

     

       
51
       
-
       
    type = "warning";

     

       
52
       
-
       
  };

     

       
53
       
-
       
}

     

       
54
       
-
       
</programlisting>

     

       
55
       
-
       


     

       
56
       
-
       
 </section>

     

       
57
       
-
       


     

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

     

       
59
       
-
       
  <title>Ignoring Checks</title>

     

       
60
       
-
       


     

       
61
       
-
       
  <para>

     

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

     

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

     

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

     

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

     

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

     

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

     

       
68
       
-
       
   follows:

     

       
69
       
-
       
  </para>

     

       
70
       
-
       


     

       
71
       
-
       
<programlisting>

     

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

     

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

     

       
74
       
-
       
error: Failed checks:

     

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

     

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

     

       
77
       
-
       
</programlisting>

     

       
78
       
 
       


     

       
79
       
 
       
  <para>

     

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

     

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

     

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

     

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

     

       
84
       
-
       
   you can adjust them to your liking:

     

       
85
       
 
       
  </para>

     

       
86
       
 
       


     

       
87
       
 
       
<programlisting>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
88
       
 
       
{

     

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

     

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

     

       
91
       
-
       


     

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

     

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

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
94
       
 
       
}

     

       
0
       
 
       

     

       
95
       
 
       
</programlisting>

     

       
96
       
-
       


     

       
97
       
-
       


     

       
98
       
 
       
 </section>

     

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

     

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

     

       
101
       
 
       


     

       
102
       
-
       
  <para>

     

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

     

       
104
       
-
       
  </para>

     

       
105
       
-
       


     

       
106
       
-
       
<programlisting>

     

       
107
       
-
       
{ lib, ... }: {

     

       
108
       
-
       


     

       
109
       
-
       
  options.myServices = lib.mkOption {

     

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

     

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

     

       
112
       
-
       


     

       
113
       
-
       
      config._module.checks.portConflict = {

     

       
114
       
-
       
        check = config.port != 80;

     

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

     

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

     

       
117
       
-
       
        type = "warning";

     

       
118
       
-
       
      };

     

       
119
       
-
       
    }));

     

       
120
       
-
       
  };

     

       
121
       
-
       


     

       
122
       
-
       
}

     

       
123
       
-
       
</programlisting>

     

       
124
       
 
       


     

       
125
       
 
       
  <para>

     

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

     

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

     

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

     

       
129
       
-
       
   correctly shows the context of the option.

     

       
0
       
 
       

     

       
0
       
 
       

     

       
130
       
 
       
  </para>

     

       
131
       
 
       


     

       
132
       
 
       
<programlisting>

     

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

     

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

     

       
135
       
-
       
</programlisting>

     

       
136
       
-
       


     

       
137
       
-
       
  <para>

     

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

     

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

     

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

     

       
141
       
-
       
  </para>

     

       
142
       
-
       


     

       
143
       
-
       
<programlisting>

     

       
144
       
 
       
{

     

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

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
146
       
 
       
}

     

       
0
       
 
       

     

       
147
       
 
       
</programlisting>

     

       
148
       
-
       


     

       
149
       
-
       
<note>

     

       
150
       
-
       
 <para>

     

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

     

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

     

       
153
       
-
       
 </para>

     

       
154
       
-
       
</note>

     

       
155
       
-
       


     

       
156
       
 
       
 </section>

     

       
157
       
 
       
</section>

     

···

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

     

       
4
       
 
       
        version="5.0"

     

       
5
       
 
       
        xml:id="sec-assertions">

     

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

     

       
7
       
 
       


     

       
8
       
 
       
 <para>

     

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

     

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

     

       
11
       
+
       
  and prevents errors after the build.

     

       
12
       
 
       
 </para>

     

       
13
       
 
       


     

       
14
       
 
       
 <para>

     

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

     

       
16
       
 
       
  <literal>builtins.trace</literal>

     

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

     

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

     

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

     

       
20
       
+
       
  NixOS module system.

     

       
21
       
 
       
 </para>

     

       
22
       
 
       


     

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

     

       
24
       
+
       
  <title>Warnings</title>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
25
       
 
       


     

       
26
       
 
       
  <para>

     

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

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
28
       
 
       
  </para>

     

       
29
       
 
       


     

       
30
       
 
       
<programlisting>

     

       
31
       
+
       
<![CDATA[

     

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

     

       
33
       
 
       
{

     

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

     

       
35
       
+
       
    warnings =

     

       
36
       
+
       
      if config.services.foo.bar

     

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

     

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

     

       
39
       
+
       
               '' ]

     

       
40
       
+
       
      else [];

     

       
41
       
+
       
  }

     

       
42
       
 
       
}

     

       
43
       
+
       
]]>

     

       
44
       
 
       
</programlisting>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
45
       
 
       
 </section>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
46
       
 
       


     

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

     

       
48
       
+
       
  <title>Assertions</title>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
49
       
 
       


     

       
50
       
 
       
  <para>

     

       
51
       
+
       
   This example, extracted from the

     

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

     

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

     

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

     

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

     

       
56
       
+
       
   from being built.

     

       
57
       
 
       
  </para>

     

       
58
       
 
       


     

       
59
       
 
       
<programlisting>

     

       
60
       
+
       
<![CDATA[

     

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

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
62
       
 
       
{

     

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

     

       
64
       
+
       
    assertions =

     

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

     

       
66
       
+
       
          message = "rsyslogd conflicts with syslogd";

     

       
67
       
+
       
        }

     

       
68
       
+
       
      ];

     

       
69
       
+
       
  }

     

       
70
       
 
       
}

     

       
71
       
+
       
]]>

     

       
72
       
 
       
</programlisting>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
73
       
 
       
 </section>

     

       
74
       
 
       
</section>

     

···

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

     

       
2
       
 
       


     

       
3
       
 
       
with lib;

     

       
4
       
 
       


     
···

       
30
       
 
       
    };

     

       
31
       
 
       


     

       
32
       
 
       
  };

     

       
33
       
-
       


     

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

     

       
35
       
-
       
    let

     

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

     

       
37
       
-
       
      isWarning = lib.isString value;

     

       
38
       
-
       
      result = {

     

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

     

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

     

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

     

       
42
       
-
       
      };

     

       
43
       
-
       
    in nameValuePair name result

     

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

     

       
45
       
-
       


     

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

     

       
47
       
 
       
}

     

···

       
1
       
+
       
{ lib, ... }:

     

       
2
       
 
       


     

       
3
       
 
       
with lib;

     

       
4
       
 
       


     
···

       
30
       
 
       
    };

     

       
31
       
 
       


     

       
32
       
 
       
  };

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

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

     

       
34
       
 
       
}

     

···

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

     

       
118
       
 
       
  };

     

       
119
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
120
       
 
       
  # Replace runtime dependencies

     

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

     

       
122
       
 
       
      pkgs.replaceDependency { inherit oldDependency newDependency drv; }

     

       
123
       
-
       
    ) baseSystem config.system.replaceRuntimeDependencies;

     

       
124
       
 
       


     

       
125
       
 
       
in

     

       
126
       
 
       


     

···

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

     

       
118
       
 
       
  };

     

       
119
       
 
       


     

       
120
       
+
       
  # Handle assertions and warnings

     

       
121
       
+
       


     

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

     

       
123
       
+
       


     

       
124
       
+
       
  baseSystemAssertWarn = if failedAssertions != []

     

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

     

       
126
       
+
       
    else showWarnings config.warnings baseSystem;

     

       
127
       
+
       


     

       
128
       
 
       
  # Replace runtime dependencies

     

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

     

       
130
       
 
       
      pkgs.replaceDependency { inherit oldDependency newDependency drv; }

     

       
131
       
+
       
    ) baseSystemAssertWarn config.system.replaceRuntimeDependencies;

     

       
132
       
 
       


     

       
133
       
 
       
in

     

       
134