Error handling: Difference between revisions

From NixOS Wiki
imported>Pogobanane
Init a page about error handling and debugging
 
imported>Pogobanane
add dedicated debugging section
Line 46: Line 46:


An example for a debugging facility in NixOS is running NixOS tests interactively (see [13]).
An example for a debugging facility in NixOS is running NixOS tests interactively (see [13]).
== Debugging ==
<!-- put debugging into a heading for search engine optimisation -->
As mentioned above, you can use break to debug nix code, breakpointHook to debug nix builds and NixOS facilities to debug NixOS tests.


== See also ==
== See also ==

Revision as of 11:15, 4 May 2023

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.

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

<give examples for both>

Nix

The nix language has some constructs to help with printing messages.

- assert: throw an error [2]

The nix language already comes with some usefult builtin functions [3]:

- throw: throw an error with a message - abort: same as throw, but always stop evaluation - trace: print to stderr - traceVerbose: print, but only when in --trace-verbose mode - break: breakpoint when in --debugger mode - tryEval: catch throws and asserts

Commonly, assert is combined with throw to generate meaningful error messages: assert condition || throw "message"; This pattern is essentially how lib.assertMsg works (see Sec. nixpkgs). [1]

nixpkgs

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

- lib.trivial.* [6]

   - lib.throwIf and throwIfNot
   - lib.warn, warnIf and warnIfNot

- lib.debug.*: tracing functions with some pretty printing [7, 9] - lib.asserts.*: assert functions [8]

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

Nixpkgs also has a debugging facility like nix's break: the breakpointHook (see [12]).

NixOS

The NixOS module system again wraps these library functions and makes them available via module options: [11, 10]

- config.warnings = []; - config.assertions = [];

An example for a debugging facility in NixOS is running NixOS tests interactively (see [13]).

Debugging

As mentioned above, you can use break to debug nix code, breakpointHook to debug nix builds and NixOS facilities to debug NixOS tests.

See also

[1] throw vs assert discussion: https://github.com/NixOS/nixpkgs/issues/154292 [2] https://nixos.org/manual/nix/stable/language/constructs.html?highlight=assert#assertions [3] https://nixos.org/manual/nix/stable/language/builtins.html [4] https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=warnings [5] https://nixos.org/manual/nixpkgs/stable/ [6] https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-trivial [7] https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-debug [8] https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-asserts [9] http://ryantm.github.io/nixpkgs/functions/library/debug/#sec-functions-library-debug [10] https://github.com/NixOS/nixpkgs/blob/nixos-22.11/nixos/doc/manual/development/assertions.section.md [11] https://nixos.org/manual/nixos/stable/index.html#sec-assertions-warnings [12] https://nixos.org/manual/nixpkgs/stable/#breakpointhook [13] https://nixos.org/manual/nixos/stable/index.html#sec-running-nixos-tests-interactively