diff options
-rw-r--r-- | nixos/doc/manual/configuration/summary.xml | 3 | ||||
-rw-r--r-- | nixos/doc/manual/development/assertions.xml | 80 | ||||
-rw-r--r-- | nixos/doc/manual/development/writing-modules.xml | 1 |
3 files changed, 83 insertions, 1 deletions
diff --git a/nixos/doc/manual/configuration/summary.xml b/nixos/doc/manual/configuration/summary.xml index 6ff0390c0ed34..be1f2263149e4 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 0000000000000..d3434e1f112ee --- /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 5bdcad5ceb574..cb363b45675bf 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" /> |