1 files changed, 74 insertions, 0 deletions
diff --git a/nixpkgs/nixos/doc/manual/development/assertions.xml b/nixpkgs/nixos/doc/manual/development/assertions.xml
new file mode 100644
index 000000000000..32f90cf2e7c4
--- /dev/null
+++ b/nixpkgs/nixos/doc/manual/development/assertions.xml
@@ -0,0 +1,74 @@
+<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 xml:id="sec-assertions-warnings">
+  <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 xml:id="sec-assertions-assertions">
+  <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>