pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="sec-assertions">
6
7<title>Warnings and Assertions</title>
8
9<para>
10 When configuration problems are detectable in a module, it is a good
11 idea to write an assertion or warning. Doing so provides clear
12 feedback to the user and prevents errors after the build.
13</para>
14
15<para>
16 Although Nix has the <literal>abort</literal> and
17 <literal>builtins.trace</literal> <link xlink:href="https://nixos.org/nix/manual/#ssec-builtins">functions</link> to perform such tasks,
18 they are not ideally suited for NixOS modules. Instead of these
19 functions, you can declare your warnings and assertions using the
20 NixOS module system.
21</para>
22
23<section>
24
25<title>Warnings</title>
26
27<para>
28 This is an example of using <literal>warnings</literal>.
29</para>
30
31<programlisting>
32<![CDATA[
33{ config, lib, ... }:
34{
35 config = lib.mkIf config.services.foo.enable {
36 warnings =
37 if config.services.foo.bar
38 then [ ''You have enabled the bar feature of the foo service.
39 This is known to cause some specific problems in certain situations.
40 '' ]
41 else [];
42 }
43}
44]]>
45</programlisting>
46
47</section>
48
49<section>
50
51<title>Assertions</title>
52
53
54<para>
55 This example, extracted from the
56 <link xlink:href="https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix">
57 <literal>syslogd</literal> module
58 </link> shows how to use <literal>assertions</literal>. Since there
59 can only be one active syslog daemon at a time, an assertion is useful to
60 prevent such a broken system from being built.
61</para>
62
63<programlisting>
64<![CDATA[
65{ config, lib, ... }:
66{
67 config = lib.mkIf config.services.syslogd.enable {
68 assertions =
69 [ { assertion = !config.services.rsyslogd.enable;
70 message = "rsyslogd conflicts with syslogd";
71 }
72 ];
73 }
74}
75]]>
76</programlisting>
77
78</section>
79
80</section>