Merge commit '7e567a3d092b7de69cdf5deaeb8d9526de230916'

# Conflicts:
#	nixpkgs/pkgs/top-level/all-packages.nix

1 files changed, 58 insertions, 0 deletions

diff --git a/nixpkgs/nixos/doc/manual/from_md/development/assertions.section.xml b/nixpkgs/nixos/doc/manual/from_md/development/assertions.section.xml
new file mode 100644
index 000000000000..0844d484d60f
--- /dev/null
+++ b/nixpkgs/nixos/doc/manual/from_md/development/assertions.section.xml
@@ -0,0 +1,58 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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 language="bash">
+{ 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-assetions">
+    <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 language="bash">
+{ config, lib, ... }:
+{
+  config = lib.mkIf config.services.syslogd.enable {
+    assertions =
+      [ { assertion = !config.services.rsyslogd.enable;
+          message = &quot;rsyslogd conflicts with syslogd&quot;;
+        }
+      ];
+  }
+}
+</programlisting>
+  </section>
+</section>