Documentation
Playground GitHub

whitehall logs and trace

logcat that names your .wh files, and the rewrite behind it.

You are not meant to read the generated Kotlin, but a crash names FeedScreen.kt:212 and a kotlinc error names it with a column. Every build writes a .whmap source map next to each generated .kt, and these two verbs use it to put the reference back where you wrote it.

logs

whitehall logs [image | package] [options] [-- logcat args…]
whitehall logs showcase            # that app only, with .wh file references
whitehall logs                     # the whole phone, still rewritten
whitehall logs showcase --raw      # the phone's own references
whitehall logs showcase --dump     # what is in the buffer, then exit
whitehall logs -c showcase         # empty the buffer first

With an image, logs shows only that program's lines, filtered by pid (logcat --pid=), not by a grep on the tag. A stack trace's continuation lines carry no tag, so a grep loses them, and they are the lines you wanted. Every line goes through trace:

at com.x.feed.FeedScreenKt.FeedScreen(FeedScreen.kt:41)
  ↓
at com.x.feed.FeedScreenKt.FeedScreen(src/routes/feed/+screen.wh:12)
FlagWhat it does
-d, --device <id>Which phone. Auto-selects when only one is connected
--project <dir>The project holding the source maps. Default .
--dumpDump the buffer and exit, instead of following
--rawKeep the phone's own file references; do not rewrite to .wh
-c, --clearEmpty the log buffer before reading

Arguments after -- go to logcat itself. logcat is an alias for logs.

trace

whitehall trace [file] [--project <dir>] [-v]

Reads a stack trace, a build log or logcat — from a file, or from stdin — and replaces every Foo.kt:123 with the .wh line that produced it. Anything that is not a file reference passes through untouched, so it is safe to leave in a pipe permanently.

whitehall trace crash.txt
some-tool 2>&1 | whitehall trace
whitehall trace crash.txt --verbose     # keep the generated reference beside the source one
e: file:///…/FeedScreen.kt:41:9: error: unresolved reference: shwos
  ↓
e: src/routes/feed/+screen.wh:12: error: unresolved reference: shwos

The column is dropped on purpose: it describes the generated file's geometry and means nothing in the source.

FlagWhat it does
--project <dir>The project directory holding the build output with the source maps. Default .
-v, --verboseKeep the generated reference alongside the source one
A failed build, run or install already does this to its own Gradle output: a kotlinc error is printed against src/routes/+screen.wh:10, not a path inside .whitehall/android. trace is for everything else.

An unmapped line is a shrug, not a lie

A line with no anchor of its own belongs to the nearest anchor above it, and a line above every anchor is reported as generated scaffolding rather than attributed to line 1. The map leaves a line unmapped before it maps it wrongly.

See Also