lib.debug: debugging functions

lib.debug.traceIf

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

Conditionally trace the supplied message, based on a predicate.

pred

Predicate to check

msg

Message that should be traced

x

Value to return

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

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

lib.debug.traceValFn

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

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

f

Function to apply

x

Value to trace and return

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

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

lib.debug.traceVal

Type: traceVal :: a -> a

Trace the supplied value and return it.

traceVal 42
# trace: 42
=> 42

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

lib.debug.traceSeq

Type: traceSeq :: a -> b -> b

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

x

The value to trace

y

The value to return

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:91 in <nixpkgs>.

lib.debug.traceSeqN

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

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

depth

Function argument

x

Function argument

y

Function argument

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

Located at lib/debug.nix:108 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.

f

Function to apply

v

Value to trace

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

lib.debug.traceValSeq

A combination of traceVal and traceSeq.

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

lib.debug.traceValSeqNFn

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

f

Function to apply

depth

Function argument

v

Value to trace

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

lib.debug.traceValSeqN

A combination of traceVal and traceSeqN.

Located at lib/debug.nix:144 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.

depth

Function argument

name

Function argument

f

Function argument

v

Function argument

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:157 in <nixpkgs>.

lib.debug.runTests

Type:

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

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"];

tests

Tests to run

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:229 in <nixpkgs>.

lib.debug.testAllTrue

Create a test assuming that list elements are true.

expr

Function argument

{ testX = allTrue [ true ]; }

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