Error handling: Difference between revisions
imported>Pogobanane No edit summary |
imported>Pogobanane m fix layouting |
||
| Line 9: | Line 9: | ||
== Nix == | == Nix == | ||
The nix language has | The nix language has a construct to help with printing messages. | ||
* '''assert''': throw an error [ | * '''assert''': throw an error (see [https://nixos.org/manual/nix/stable/language/constructs.html?highlight=assert#assertions; Nix manual: Assertions]) | ||
The nix language | 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 | * '''throw''': throw an error with a message | ||
* '''abort''': same as throw, but always stop evaluation | * '''abort''': same as throw, but always stop evaluation | ||
* '''trace''': print to stderr | * '''trace''': print to stderr | ||
* '''traceVerbose''': print, but only when in --trace-verbose mode | * '''traceVerbose''': print, but only when in <code>--trace-verbose</code> mode | ||
* '''break''': breakpoint when in --debugger mode | * '''break''': breakpoint when in <code>--debugger</code> mode | ||
* '''tryEval''': catch throws and asserts | * '''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). [ | 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 == | == nixpkgs == | ||
| Line 28: | Line 28: | ||
There are three main facilities for printing errors and do print debugging in nixpkgs: | There are three main facilities for printing errors and do print debugging in nixpkgs: | ||
* 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 | |||
* lib.debug.*: tracing functions with some pretty printing [ | * [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> | ||
* lib.asserts.*: assert functions | * [https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-asserts; lib.'''asserts'''.*]: assert functions | ||
These facilities also expose their attributes directly via lib.* (e.g. lib.throwIf). | 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 break: the breakpointHook | Nixpkgs also has a debugging facility like nix's <code>break</code>: the [https://nixos.org/manual/nixpkgs/stable/#breakpointhook; breakpointHook]. | ||
== NixOS == | == NixOS == | ||
The NixOS module system again wraps these library functions and makes them available via module options: [11 | 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> | ||
* config.warnings = []; | * <code>config.warnings = [];</code> | ||
* config.assertions = []; | * <code>config.assertions = [];</code> | ||
An example for a debugging facility in NixOS is running 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 == | == Debugging == | ||
| Line 51: | Line 51: | ||
<!-- put debugging into a heading for search engine optimisation --> | <!-- 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 | 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. | ||
== | == References == | ||
Revision as of 13:37, 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.
 |
This article or section needs expansion.
Reason: This page is currently being worked on (04.05.2023) and desperately needs usage examples. (Discuss in Talk:Error handling#)
Please consult the pedia article metapage for guidelines on contributing. |
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 a construct to help with printing messages.
- assert: throw an error (see Nix manual: Assertions)
The nix language also comes with some related builtin functions:
- 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-verbosemode - break: breakpoint when in
--debuggermode - 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.* (see nixpkgs manual: lib.trivial)
- lib.throwIf and throwIfNot
- lib.warn, warnIf and warnIfNot
- lib.debug.*: tracing functions with some pretty printing [2]
- lib.asserts.*: assert functions
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.
NixOS
The NixOS module system again wraps these library functions and makes them available via module options (see NixOS manual: Assertions/Warnings): [3]
config.warnings = [];config.assertions = [];
An example for a debugging facility in NixOS is running NixOS tests interactively.
Debugging
As mentioned above, you can use break to debug nix code, breakpointHook to debug nix builds and interactive tools to debug NixOS tests.