diff options
author | Ryan Mulligan <ryan@ryantm.com> | 2021-06-03 20:12:16 -0700 |
---|---|---|
committer | Ryan Mulligan <ryan@ryantm.com> | 2021-06-03 20:12:16 -0700 |
commit | 5058f9a5dfc5aece634d6f2a23df86b944603aa9 (patch) | |
tree | f63f17f7301d7134d39c36d331344b4bc4e0e37c /nixos | |
parent | 1eaaeaaabe0f5fb65019bf0c87cd4905a94d0234 (diff) | |
download | nixlib-5058f9a5dfc5aece634d6f2a23df86b944603aa9.tar nixlib-5058f9a5dfc5aece634d6f2a23df86b944603aa9.tar.gz nixlib-5058f9a5dfc5aece634d6f2a23df86b944603aa9.tar.bz2 nixlib-5058f9a5dfc5aece634d6f2a23df86b944603aa9.tar.lz nixlib-5058f9a5dfc5aece634d6f2a23df86b944603aa9.tar.xz nixlib-5058f9a5dfc5aece634d6f2a23df86b944603aa9.tar.zst nixlib-5058f9a5dfc5aece634d6f2a23df86b944603aa9.zip |
nixos/doc: convert assertions and warnings section to CommonMark
Diffstat (limited to 'nixos')
-rw-r--r-- | nixos/doc/manual/development/assertions.section.md | 40 | ||||
-rw-r--r-- | nixos/doc/manual/development/assertions.xml | 74 | ||||
-rw-r--r-- | nixos/doc/manual/development/writing-modules.xml | 2 | ||||
-rw-r--r-- | nixos/doc/manual/from_md/development/assertions.section.xml | 58 |
4 files changed, 99 insertions, 75 deletions
diff --git a/nixos/doc/manual/development/assertions.section.md b/nixos/doc/manual/development/assertions.section.md new file mode 100644 index 000000000000..cc6d81e56990 --- /dev/null +++ b/nixos/doc/manual/development/assertions.section.md @@ -0,0 +1,40 @@ +# Warnings and Assertions {#sec-assertions} + +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. + +Although Nix has the `abort` and `builtins.trace` [functions](https://nixos.org/nix/manual/#ssec-builtins) 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. + +## Warnings {#sec-assertions-warnings} + +This is an example of using `warnings`. + +```nix +{ 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 []; + } +} +``` + +## Assertions {#sec-assertions-assetions} + +This example, extracted from the [`syslogd` module](https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix) shows how to use `assertions`. 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. + +```nix +{ config, lib, ... }: +{ + config = lib.mkIf config.services.syslogd.enable { + assertions = + [ { assertion = !config.services.rsyslogd.enable; + message = "rsyslogd conflicts with syslogd"; + } + ]; + } +} +``` diff --git a/nixos/doc/manual/development/assertions.xml b/nixos/doc/manual/development/assertions.xml deleted file mode 100644 index 32f90cf2e7c4..000000000000 --- a/nixos/doc/manual/development/assertions.xml +++ /dev/null @@ -1,74 +0,0 @@ -<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> diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml index fad4637f51f0..04497db77b89 100644 --- a/nixos/doc/manual/development/writing-modules.xml +++ b/nixos/doc/manual/development/writing-modules.xml @@ -182,7 +182,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="../from_md/development/assertions.section.xml" /> <xi:include href="meta-attributes.xml" /> <xi:include href="importing-modules.xml" /> <xi:include href="replace-modules.xml" /> diff --git a/nixos/doc/manual/from_md/development/assertions.section.xml b/nixos/doc/manual/from_md/development/assertions.section.xml new file mode 100644 index 000000000000..0844d484d60f --- /dev/null +++ b/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 = "rsyslogd conflicts with syslogd"; + } + ]; + } +} +</programlisting> + </section> +</section> |