lib.debug: debugging functions

Collection of functions useful for debugging broken nix expressions.

trace-like functions take two values, print the first to stderr and return the second.
traceVal-like functions take one argument which both printed and returned.
traceSeq-like functions fully evaluate their traced value before printing (not just to “weak head normal form” like trace does by default).
Functions that end in -Fn take an additional function as their first argument, which is applied to the traced value before it is printed.

`lib.debug.traceIf`

Conditionally trace the supplied message, based on a predicate.

Inputs

pred

: Predicate to check

msg

: Message that should be traced

x

: Value to return

Type

traceIf :: bool -> string -> a -> a

Examples

lib.debug.traceIf usage example

traceIf true "hello" 3
trace: hello
=> 3

Located at lib/debug.nix:72 in <nixpkgs>.

`lib.debug.traceValFn`

Trace the supplied value after applying a function to it, and return the original value.

Inputs

f

: Function to apply

x

: Value to trace and return

Type

traceValFn :: (a -> b) -> a -> a

Examples

lib.debug.traceValFn usage example

traceValFn (v: "mystring ${v}") "foo"
trace: mystring foo
=> "foo"

Located at lib/debug.nix:110 in <nixpkgs>.

`lib.debug.traceVal`

Trace the supplied value and return it.

Inputs

x

: Value to trace and return

Type

traceVal :: a -> a

Examples

lib.debug.traceVal usage example

traceVal 42
# trace: 42
=> 42

Located at lib/debug.nix:141 in <nixpkgs>.

`lib.debug.traceSeq`

builtins.trace, but the value is builtins.deepSeqed first.

Inputs

x

: The value to trace

y

: The value to return

Type

traceSeq :: a -> b -> b

Examples

lib.debug.traceSeq usage example

trace { a.b.c = 3; } null
trace: { a = <CODE>; }
=> null
traceSeq { a.b.c = 3; } null
trace: { a = { b = { c = 3; }; }; }
=> null

Located at lib/debug.nix:178 in <nixpkgs>.

`lib.debug.traceSeqN`

Like traceSeq, but only evaluate down to depth n. This is very useful because lots of traceSeq usages lead to an infinite recursion.

Inputs

depth

: 1. Function argument

x

: 2. Function argument

y

: 3. Function argument

Type

traceSeqN :: Int -> a -> b -> b

Examples

lib.debug.traceSeqN usage example

traceSeqN 2 { a.b.c = 3; } null
trace: { a = { b = {…}; }; }
=> null

Located at lib/debug.nix:220 in <nixpkgs>.

`lib.debug.traceValSeqFn`

A combination of traceVal and traceSeq that applies a provided function to the value to be traced after deepSeqing it.

Inputs

f

: Function to apply

v

: Value to trace

Located at lib/debug.nix:249 in <nixpkgs>.

`lib.debug.traceValSeq`

A combination of traceVal and traceSeq.

Inputs

v

: Value to trace

Located at lib/debug.nix:263 in <nixpkgs>.

`lib.debug.traceValSeqNFn`

A combination of traceVal and traceSeqN that applies a provided function to the value to be traced.

Inputs

f

: Function to apply

depth

: 2. Function argument

v

: Value to trace

Located at lib/debug.nix:284 in <nixpkgs>.

`lib.debug.traceValSeqN`

A combination of traceVal and traceSeqN.

Inputs

depth

: 1. Function argument

v

: Value to trace

Located at lib/debug.nix:302 in <nixpkgs>.

`lib.debug.traceFnSeqN`

Trace the input and output of a function f named name, both down to depth.

This is useful for adding around a function call, to see the before/after of values as they are transformed.

Inputs

depth

: 1. Function argument

name

: 2. Function argument

f

: 3. Function argument

v

: 4. Function argument

Examples

lib.debug.traceFnSeqN usage example

traceFnSeqN 2 "id" (x: x) { a.b.c = 3; }
trace: { fn = "id"; from = { a.b = {…}; }; to = { a.b = {…}; }; }
=> { a.b.c = 3; }

Located at lib/debug.nix:343 in <nixpkgs>.

`lib.debug.runTests`

Evaluates a set of tests.

A test is an attribute set {expr, expected}, denoting an expression and its expected result.

The result is a list of failed tests, each represented as {name, expected, result},

expected
What was passed as expected
result
The actual result of the test

Used for regression testing of the functions in lib; see tests.nix for more examples.

Important: Only attributes that start with test are executed.

If you want to run only a subset of the tests add the attribute tests = ["testName"];

Inputs

tests

: Tests to run

Type

runTests :: {
  tests = [ String ];
  ${testName} :: {
    expr :: a;
    expected :: a;
  };
}
->
[
  {
    name :: String;
    expected :: a;
    result :: a;
  }
]

Examples

lib.debug.runTests usage example

runTests {
  testAndOk = {
    expr = lib.and true false;
    expected = false;
  };
  testAndFail = {
    expr = lib.and true false;
    expected = true;
  };
}
->
[
  {
    name = "testAndFail";
    expected = true;
    result = false;
  }
]

Located at lib/debug.nix:432 in <nixpkgs>.

`lib.debug.testAllTrue`

Create a test assuming that list elements are true.

Inputs

expr

: 1. Function argument

Examples

lib.debug.testAllTrue usage example

{ testX = allTrue [ true ]; }

Located at lib/debug.nix:463 in <nixpkgs>.