Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
NixOS Manual: document assertions and warnings (#29206)
* NixOS Manual: document assertions and warnings * NixOS manual: re-wrap assertions text
- Loading branch information
Showing
3 changed files
with
83 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters