NixOS Manual: document assertions and warnings (#29206)

* NixOS Manual: document assertions and warnings

* NixOS manual: re-wrap assertions text

3 files changed, 83 insertions, 1 deletions

diff --git a/nixos/doc/manual/configuration/summary.xml b/nixos/doc/manual/configuration/summary.xml
index 6ff0390c0ed3..be1f2263149e 100644
--- a/nixos/doc/manual/configuration/summary.xml
+++ b/nixos/doc/manual/configuration/summary.xml
@@ -113,7 +113,8 @@ manual</link> for the rest.</para>
       </row>
       <row>
         <entry><literal>assert 1 + 1 == 2; "yes!"</literal></entry>
-        <entry>Assertion check (evaluates to <literal>"yes!"</literal>)</entry>
+        <entry>Assertion check (evaluates to <literal>"yes!"</literal>). See <xref
+    linkend="sec-assertions"/> for using assertions in modules</entry>
       </row>
       <row>
         <entry><literal>let x = "foo"; y = "bar"; in x + y</literal></entry>
diff --git a/nixos/doc/manual/development/assertions.xml b/nixos/doc/manual/development/assertions.xml
new file mode 100644
index 000000000000..d3434e1f112e
--- /dev/null
+++ b/nixos/doc/manual/development/assertions.xml
@@ -0,0 +1,80 @@
+<section xmlns="http://docbook.org/ns/docbook"
+        xmlns:xlink="http://www.w3.org/1999/xlink"
+        xmlns:xi="http://www.w3.org/2001/XInclude"
+        version="5.0"
+        xml:id="sec-assertions">
+
+<title>Warnings and Assertions</title>
+
+<para>
+  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.
+</para>
+
+<para>
+  Although Nix has the <literal>abort</literal> and
+  <literal>builtins.trace</literal> <link xlink:href="https://nixos.org/nix/manual/#ssec-builtins">functions</link> 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.
+</para>
+
+<section>
+
+<title>Warnings</title>
+
+<para>
+  This is an example of using <literal>warnings</literal>.
+</para>
+
+<programlisting>
+<![CDATA[
+{ config, lib, ... }:
+{
+  config = lib.mkIf config.services.foo.enable {
+    warnings =
+      if config.services.foo.bar
+      then [ ''You have enabled the bar feature of the foo service.
+               This is known to cause some specific problems in certain situations.
+               '' ]
+      else [];
+  }
+}
+]]>
+</programlisting>
+
+</section>
+
+<section>
+
+<title>Assertions</title>
+
+
+<para>
+  This example, extracted from the
+  <link xlink:href="https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix">
+    <literal>syslogd</literal> module
+  </link> shows how to use <literal>assertions</literal>. 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.
+</para>
+
+<programlisting>
+<![CDATA[
+{ config, lib, ... }:
+{
+  config = lib.mkIf config.services.syslogd.enable {
+    assertions =
+      [ { assertion = !config.services.rsyslogd.enable;
+          message = "rsyslogd conflicts with syslogd";
+        }
+      ];
+  }
+}
+]]>
+</programlisting>
+
+</section>
+
+</section>
diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml
index 5bdcad5ceb57..cb363b45675b 100644
--- a/nixos/doc/manual/development/writing-modules.xml
+++ b/nixos/doc/manual/development/writing-modules.xml
@@ -178,6 +178,7 @@ in {
 <xi:include href="option-declarations.xml" />
 <xi:include href="option-types.xml" />
 <xi:include href="option-def.xml" />
+<xi:include href="assertions.xml" />
 <xi:include href="meta-attributes.xml" />
 <xi:include href="replace-modules.xml" />