Error handling: Difference between revisions

(7 intermediate revisions by 2 users not shown)

Line 1:

This page is a collection of facilities and tools from nix, nixpkgs and NixOS for error handling and debugging. You can use them to convey configuration errors to users or to debug nix expressions trough interactive or print debugging.

~~{{Expansion|This page is currently being worked on (04~~.05.~~2023)~~ and ~~desperately needs usage examples~~.}}

In most cases you will want to stick to the highest level abstraction: <code>config.warnings</code> or <code>lib.warn</code> and its relatives.

~~In most cases you will want to stick to the highest level abstraction~~: config.warnings or lib.~~assertMsg~~

{ config, lib, ... }:

<~~give examples for both~~>

# in any nix code:

lib.warn "This is a sample warning message."

{

config.warnings = (

# Some NixOS module: throw error, if services.foo.bar == true

lib.optionals config.services.foo.bar "This is also a sample warning message, but invoked differently."

);

}

</syntaxHighlight>

== Nix ==

Line 11:

Line 19:

The nix language has a construct to help with printing messages.

* '''assert''': throw an error (see [https://nixos.org/manual/nix/stable/language/~~constructs~~.html?highlight=assert#assertions; Nix manual: Assertions])

* '''assert''': throw an error (see [https://nixos.org/manual/nix/stable/language/syntax.html?highlight=assert#assertions Nix manual: Assertions])

The nix language also comes with some related [https://nixos.org/manual/nix/stable/language/builtins.html; builtin functions]:

The nix language also comes with some related [https://nixos.org/manual/nix/stable/language/builtins.html builtin functions]:

* '''throw''': throw an error with a message

Line 22:

Line 30:

* '''tryEval''': catch throws and asserts

Commonly, assert is combined with throw to generate meaningful error messages: <code>assert condition || throw "message";</code>. This pattern is essentially how <code>lib.assertMsg</code> works (see Sec. nixpkgs). <ref>[https://github.com/NixOS/nixpkgs/issues/154292; throw vs assert discussion]</ref>

Most of those functions (nix builtins as well as nixpkgs lib functions) take an expression <code>e</code> as their last argument which they return unmodified. Thus they are chained in front of some expression:

a = builtins.trace "trace message" {

# what should be assigned to a

};

</syntaxHighlight>

Commonly, assert is combined with throw to generate meaningful error messages: <code>assert condition || throw "message";</code>. This pattern is essentially how <code>lib.assertMsg</code> works (see Sec. nixpkgs). <ref>[https://github.com/NixOS/nixpkgs/issues/154292 throw vs assert discussion]</ref>

== nixpkgs ==

Line 28:

Line 44:

There are three main facilities for printing errors and do print debugging in nixpkgs:

* lib.trivial.* (see [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-trivial; nixpkgs manual: lib.trivial])

* lib.trivial.* (see [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-trivial nixpkgs manual: lib.trivial])

** lib.'''throwIf''' and throwIfNot

** lib.'''warn''', '''warnIf''' and warnIfNot

* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-debug; lib.'''debug'''.*]: tracing functions with some pretty printing <ref>[http://ryantm.github.io/nixpkgs/functions/library/debug/#sec-functions-library-debug; Nixpkgs/docs: lib.debug]</ref>

* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-debug lib.'''debug'''.*]: tracing functions with some pretty printing (e.g. <code>lib.debug.traceIf</code>) <ref>[http://ryantm.github.io/nixpkgs/functions/library/debug/#sec-functions-library-debug Nixpkgs/docs: lib.debug]</ref>

* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-asserts; lib.'''asserts'''.*]: assert functions

* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-asserts lib.'''asserts'''.*]: assert functions (e.g. <code>lib.asserts.assertMsg</code>)

These facilities also expose their attributes directly via <code>lib.*</code> (e.g. <code>lib.throwIf</code>).

Nixpkgs also has a debugging facility like nix's <code>break</code>: the [https://nixos.org/manual/nixpkgs/stable/#breakpointhook; breakpointHook].

Nixpkgs also has a debugging facility like nix's <code>break</code>: the [https://nixos.org/manual/nixpkgs/stable/#breakpointhook breakpointHook].

== NixOS ==

The NixOS module system again wraps these library functions and makes them available via module options (see [https://nixos.org/manual/nixos/stable/index.html#sec-assertions-warnings; NixOS manual: Assertions/Warnings]): <ref>[https://github.com/NixOS/nixpkgs/blob/nixos-22.11/nixos/doc/manual/development/assertions.section.md; Nixpkgs/docs: Assertions]</ref>

The NixOS module system again wraps these library functions and makes them available via module options (see [https://nixos.org/manual/nixos/stable/index.html#sec-assertions-warnings NixOS manual: Assertions/Warnings]): <ref>[https://github.com/NixOS/nixpkgs/blob/nixos-22.11/nixos/doc/manual/development/assertions.section.md Nixpkgs/docs: Assertions]</ref>

* <code>config.warnings = [];</code>

* <code>config.assertions = [];</code>

An example for a debugging facility in NixOS is running [https://nixos.org/manual/nixos/stable/index.html#sec-running-nixos-tests-interactively; NixOS tests interactively].

An example for a debugging facility in NixOS is running [https://nixos.org/manual/nixos/stable/index.html#sec-running-nixos-tests-interactively NixOS tests interactively].

== Debugging ==

Line 51:

Line 67:

~~As mentioned above~~, you can use <code>break</code> to debug nix code, <code>breakpointHook</code> to debug nix builds and interactive tools to debug NixOS tests.

To summarise debugging approaches discussed in this article, you can use <code>break</code> to debug nix code, <code>breakpointHook</code> to debug nix builds and interactive tools to debug NixOS tests.

To find the location where variables get defined, you can use the following tools:

For bare nix code, use <code>builtins.unsafeGetAttrPos

</code> ([https://github.com/NixOS/nix/blob/b17c4290cf61d8a0386817b87231762c175097c5/tests/lang/eval-okay-getattrpos.nix example]) which returns the line and column of where an attribute is defined. It is undocumented and considered bad practice.

(soon to come [https://github.com/NixOS/nixpkgs/pull/249243 github PR]): For NixOS options unsafeGetAttrPos doesn't work, but the module system itself records that information: to find the location of <code>config.networking.hostName</code>, use <code>:p options.networking.hostName.declarationPositions</code>.

== References ==

@@ Line 1: / Line 1: @@
 This page is a collection of facilities and tools from nix, nixpkgs and NixOS for error handling and debugging. You can use them to convey configuration errors to users or to debug nix expressions trough interactive or print debugging.
-{{Expansion|This page is currently being worked on (04.05.2023) and desperately needs usage examples.}}
+In most cases you will want to stick to the highest level abstraction: <code>config.warnings</code> or <code>lib.warn</code> and its relatives.
-In most cases you will want to stick to the highest level abstraction: config.warnings or lib.assertMsg
+<syntaxHighlight lang=nix>
+{ config, lib, ... }:
-<give examples for both>
+# in any nix code:
+lib.warn "This is a sample warning message."
+{
+    config.warnings = (
+      # Some NixOS module: throw error, if services.foo.bar == true
+      lib.optionals config.services.foo.bar "This is also a sample warning message, but invoked differently."
+    );
+}
+</syntaxHighlight>
 == Nix ==
@@ Line 11: / Line 19: @@
 The nix language has a construct to help with printing messages.
-* '''assert''': throw an error (see [https://nixos.org/manual/nix/stable/language/constructs.html?highlight=assert#assertions; Nix manual: Assertions])
+* '''assert''': throw an error (see [https://nixos.org/manual/nix/stable/language/syntax.html?highlight=assert#assertions Nix manual: Assertions])
-The nix language also comes with some related [https://nixos.org/manual/nix/stable/language/builtins.html; builtin functions]:
+The nix language also comes with some related [https://nixos.org/manual/nix/stable/language/builtins.html builtin functions]:
 * '''throw''': throw an error with a message
@@ Line 22: / Line 30: @@
 * '''tryEval''': catch throws and asserts
-Commonly, assert is combined with throw to generate meaningful error messages: <code>assert condition || throw "message";</code>. This pattern is essentially how <code>lib.assertMsg</code> works (see Sec. nixpkgs). <ref>[https://github.com/NixOS/nixpkgs/issues/154292; throw vs assert discussion]</ref>
+Most of those functions (nix builtins as well as nixpkgs lib functions) take an expression <code>e</code> as their last argument which they return unmodified. Thus they are chained in front of some expression:
+<syntaxHighlight lang=nix>
+a = builtins.trace "trace message" {
+   # what should be assigned to a
+};
+</syntaxHighlight>
+Commonly, assert is combined with throw to generate meaningful error messages: <code>assert condition || throw "message";</code>. This pattern is essentially how <code>lib.assertMsg</code> works (see Sec. nixpkgs). <ref>[https://github.com/NixOS/nixpkgs/issues/154292 throw vs assert discussion]</ref>
 == nixpkgs ==
@@ Line 28: / Line 44: @@
 There are three main facilities for printing errors and do print debugging in nixpkgs:
-* lib.trivial.* (see [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-trivial; nixpkgs manual: lib.trivial])
+* lib.trivial.* (see [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-trivial nixpkgs manual: lib.trivial])
 ** lib.'''throwIf''' and throwIfNot
 ** lib.'''warn''', '''warnIf''' and warnIfNot
-* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-debug; lib.'''debug'''.*]: tracing functions with some pretty printing <ref>[http://ryantm.github.io/nixpkgs/functions/library/debug/#sec-functions-library-debug; Nixpkgs/docs: lib.debug]</ref>
+* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-debug lib.'''debug'''.*]: tracing functions with some pretty printing (e.g. <code>lib.debug.traceIf</code>) <ref>[http://ryantm.github.io/nixpkgs/functions/library/debug/#sec-functions-library-debug Nixpkgs/docs: lib.debug]</ref>
-* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-asserts; lib.'''asserts'''.*]: assert functions
+* [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-asserts lib.'''asserts'''.*]: assert functions (e.g. <code>lib.asserts.assertMsg</code>)
 These facilities also expose their attributes directly via <code>lib.*</code> (e.g. <code>lib.throwIf</code>).
-Nixpkgs also has a debugging facility like nix's <code>break</code>: the [https://nixos.org/manual/nixpkgs/stable/#breakpointhook; breakpointHook].
+Nixpkgs also has a debugging facility like nix's <code>break</code>: the [https://nixos.org/manual/nixpkgs/stable/#breakpointhook breakpointHook].
 == NixOS ==
-The NixOS module system again wraps these library functions and makes them available via module options (see [https://nixos.org/manual/nixos/stable/index.html#sec-assertions-warnings; NixOS manual: Assertions/Warnings]): <ref>[https://github.com/NixOS/nixpkgs/blob/nixos-22.11/nixos/doc/manual/development/assertions.section.md; Nixpkgs/docs: Assertions]</ref>
+The NixOS module system again wraps these library functions and makes them available via module options (see [https://nixos.org/manual/nixos/stable/index.html#sec-assertions-warnings NixOS manual: Assertions/Warnings]): <ref>[https://github.com/NixOS/nixpkgs/blob/nixos-22.11/nixos/doc/manual/development/assertions.section.md Nixpkgs/docs: Assertions]</ref>
 * <code>config.warnings = [];</code>
 * <code>config.assertions = [];</code>
-An example for a debugging facility in NixOS is running [https://nixos.org/manual/nixos/stable/index.html#sec-running-nixos-tests-interactively; NixOS tests interactively].
+An example for a debugging facility in NixOS is running [https://nixos.org/manual/nixos/stable/index.html#sec-running-nixos-tests-interactively NixOS tests interactively].
 == Debugging ==
@@ Line 51: / Line 67: @@
 <!-- put debugging into a heading for search engine optimisation -->
-As mentioned above, you can use <code>break</code> to debug nix code, <code>breakpointHook</code> to debug nix builds and interactive tools to debug NixOS tests.
+To summarise debugging approaches discussed in this article, you can use <code>break</code> to debug nix code, <code>breakpointHook</code> to debug nix builds and interactive tools to debug NixOS tests.
+To find the location where variables get defined, you can use the following tools:
+For bare nix code, use <code>builtins.unsafeGetAttrPos
+</code> ([https://github.com/NixOS/nix/blob/b17c4290cf61d8a0386817b87231762c175097c5/tests/lang/eval-okay-getattrpos.nix example]) which returns the line and column of where an attribute is defined. It is undocumented and considered bad practice.
+(soon to come [https://github.com/NixOS/nixpkgs/pull/249243 github PR]): For NixOS options unsafeGetAttrPos doesn't work, but the module system itself records that information: to find the location of <code>config.networking.hostName</code>, use <code>:p options.networking.hostName.declarationPositions</code>.
 == References ==