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 <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>
25
26 <para>
27 This is an example of using <literal>warnings</literal>.
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>
45 </section>
46
47 <section xml:id="sec-assertions-assertions">
48 <title>Assertions</title>
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, ... }:
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>
73 </section>
74</section>