From 5058f9a5dfc5aece634d6f2a23df86b944603aa9 Mon Sep 17 00:00:00 2001 From: Ryan Mulligan Date: Thu, 3 Jun 2021 20:12:16 -0700 Subject: [PATCH] nixos/doc: convert assertions and warnings section to CommonMark --- .../manual/development/assertions.section.md | 40 ++++++++++ nixos/doc/manual/development/assertions.xml | 74 ------------------- .../manual/development/writing-modules.xml | 2 +- .../development/assertions.section.xml | 58 +++++++++++++++ 4 files changed, 99 insertions(+), 75 deletions(-) create mode 100644 nixos/doc/manual/development/assertions.section.md delete mode 100644 nixos/doc/manual/development/assertions.xml create mode 100644 nixos/doc/manual/from_md/development/assertions.section.xml 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 @@ -
- Warnings and 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 - 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 - - - This is an example of using warnings. - - - - - -
- -
- Assertions - - - This example, extracted from the - - syslogd module 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. - - - - - -
-
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 { - + 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 @@ +
+ Warnings and 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 + 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 + + This is an example of using warnings. + + +{ 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 + + This example, extracted from the + syslogd + module 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. + + +{ config, lib, ... }: +{ + config = lib.mkIf config.services.syslogd.enable { + assertions = + [ { assertion = !config.services.rsyslogd.enable; + message = "rsyslogd conflicts with syslogd"; + } + ]; + } +} + +
+