pyrox.dev
Merge pull request #125604 from ryantm/md-assertions
nixos/doc: convert assertions and warnings section to CommonMark
authored by Ryan Mulligan and committed by GitHub 5707a8ef d37b25ca
+40
nixos/doc/manual/development/assertions.section.md
+40
nixos/doc/manual/development/assertions.section.md
···
1
+
# Warnings and Assertions {#sec-assertions}
2
+
3
+
When configuration problems are detectable in a module, it is a good idea to write an assertion or warning. Doing so provides clear feedback to the user and prevents errors after the build.
4
+
5
+
Although Nix has the `abort` and `builtins.trace` [functions](https://nixos.org/nix/manual/#ssec-builtins) to perform such tasks, they are not ideally suited for NixOS modules. Instead of these functions, you can declare your warnings and assertions using the NixOS module system.
6
+
7
+
## Warnings {#sec-assertions-warnings}
8
+
9
+
This is an example of using `warnings`.
10
+
11
+
```nix
12
+
{ config, lib, ... }:
13
+
{
14
+
config = lib.mkIf config.services.foo.enable {
15
+
warnings =
16
+
if config.services.foo.bar
17
+
then [ ''You have enabled the bar feature of the foo service.
18
+
This is known to cause some specific problems in certain situations.
19
+
'' ]
20
+
else [];
21
+
}
22
+
}
23
+
```
24
+
25
+
## Assertions {#sec-assertions-assetions}
26
+
27
+
This example, extracted from the [`syslogd` module](https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix) shows how to use `assertions`. Since there can only be one active syslog daemon at a time, an assertion is useful to prevent such a broken system from being built.
28
+
29
+
```nix
30
+
{ config, lib, ... }:
31
+
{
32
+
config = lib.mkIf config.services.syslogd.enable {
33
+
assertions =
34
+
[ { assertion = !config.services.rsyslogd.enable;
35
+
message = "rsyslogd conflicts with syslogd";
36
+
}
37
+
];
38
+
}
39
+
}
40
+
```
-74
nixos/doc/manual/development/assertions.xml
-74
nixos/doc/manual/development/assertions.xml
···
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>
+1
-1
nixos/doc/manual/development/writing-modules.xml
+1
-1
nixos/doc/manual/development/writing-modules.xml
···
182
182
<xi:include href="option-declarations.xml" />
183
183
<xi:include href="option-types.xml" />
184
184
<xi:include href="option-def.xml" />
185
-
<xi:include href="assertions.xml" />
185
+
<xi:include href="../from_md/development/assertions.section.xml" />
186
186
<xi:include href="meta-attributes.xml" />
187
187
<xi:include href="importing-modules.xml" />
188
188
<xi:include href="replace-modules.xml" />
+58
nixos/doc/manual/from_md/development/assertions.section.xml
+58
nixos/doc/manual/from_md/development/assertions.section.xml
···
1
+
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-assertions">
2
+
<title>Warnings and Assertions</title>
3
+
<para>
4
+
When configuration problems are detectable in a module, it is a good
5
+
idea to write an assertion or warning. Doing so provides clear
6
+
feedback to the user and prevents errors after the build.
7
+
</para>
8
+
<para>
9
+
Although Nix has the <literal>abort</literal> and
10
+
<literal>builtins.trace</literal>
11
+
<link xlink:href="https://nixos.org/nix/manual/#ssec-builtins">functions</link>
12
+
to perform such tasks, they are not ideally suited for NixOS
13
+
modules. Instead of these functions, you can declare your warnings
14
+
and assertions using the NixOS module system.
15
+
</para>
16
+
<section xml:id="sec-assertions-warnings">
17
+
<title>Warnings</title>
18
+
<para>
19
+
This is an example of using <literal>warnings</literal>.
20
+
</para>
21
+
<programlisting language="bash">
22
+
{ config, lib, ... }:
23
+
{
24
+
config = lib.mkIf config.services.foo.enable {
25
+
warnings =
26
+
if config.services.foo.bar
27
+
then [ ''You have enabled the bar feature of the foo service.
28
+
This is known to cause some specific problems in certain situations.
29
+
'' ]
30
+
else [];
31
+
}
32
+
}
33
+
</programlisting>
34
+
</section>
35
+
<section xml:id="sec-assertions-assetions">
36
+
<title>Assertions</title>
37
+
<para>
38
+
This example, extracted from the
39
+
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix"><literal>syslogd</literal>
40
+
module</link> shows how to use <literal>assertions</literal>.
41
+
Since there can only be one active syslog daemon at a time, an
42
+
assertion is useful to prevent such a broken system from being
43
+
built.
44
+
</para>
45
+
<programlisting language="bash">
46
+
{ config, lib, ... }:
47
+
{
48
+
config = lib.mkIf config.services.syslogd.enable {
49
+
assertions =
50
+
[ { assertion = !config.services.rsyslogd.enable;
51
+
message = "rsyslogd conflicts with syslogd";
52
+
}
53
+
];
54
+
}
55
+
}
56
+
</programlisting>
57
+
</section>
58
+
</section>