NixOS Manual: document assertions and warnings (#29206)
* NixOS Manual: document assertions and warnings * NixOS manual: re-wrap assertions text
This commit is contained in:
parent
dcdbe960f8
commit
1b1fc65505
|
@ -113,7 +113,8 @@ manual</link> for the rest.</para>
|
||||||
</row>
|
</row>
|
||||||
<row>
|
<row>
|
||||||
<entry><literal>assert 1 + 1 == 2; "yes!"</literal></entry>
|
<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>
|
||||||
<row>
|
<row>
|
||||||
<entry><literal>let x = "foo"; y = "bar"; in x + y</literal></entry>
|
<entry><literal>let x = "foo"; y = "bar"; in x + y</literal></entry>
|
||||||
|
|
80
nixos/doc/manual/development/assertions.xml
Normal file
80
nixos/doc/manual/development/assertions.xml
Normal file
|
@ -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>
|
|
@ -178,6 +178,7 @@ in {
|
||||||
<xi:include href="option-declarations.xml" />
|
<xi:include href="option-declarations.xml" />
|
||||||
<xi:include href="option-types.xml" />
|
<xi:include href="option-types.xml" />
|
||||||
<xi:include href="option-def.xml" />
|
<xi:include href="option-def.xml" />
|
||||||
|
<xi:include href="assertions.xml" />
|
||||||
<xi:include href="meta-attributes.xml" />
|
<xi:include href="meta-attributes.xml" />
|
||||||
<xi:include href="replace-modules.xml" />
|
<xi:include href="replace-modules.xml" />
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue