Debug an app

Start a debug session

datumhue debug opens its window and waits for your editor to connect:

$ datumhue debug
$ datumhue debug --dir photos:pictures
$ datumhue debug --dap-listen 127.0.0.1:0

1. Start datumhue debug. It listens on 127.0.0.1:4711, the port most editors dial; --dap-listen 127.0.0.1:0 takes a free port instead and prints it.
2. Point your editor's debugger at that address, as a debug adapter reached over TCP.
3. Start a session that sends a launch request whose program is a .lua file, a package folder or a .dhpkg archive. The window stays empty until it arrives.

Grants go on datumhue debug itself, such as --dir and --file, since the editor's request carries only the program (datumhue debug).

What you can do

• Breakpoints on a line, with a condition, a hit count or a log message, and on a function by its name. A breakpoint matches a file by its full path, and takes effect only on a line that runs: one on a comment or a blank line never stops.
• Step in, over and out, and pause a running app.
• Read and change variables in any frame of the stack while paused.
• Evaluate Lua in the paused frame, from the debug console or by hovering: locals are in scope, and require works.
• Coroutines each show as a thread of their own.

A breakpoint you set before the session starts shows as unverified, since its file has not loaded yet. It still stops once the file runs.

Your program's registry dependencies come with it when the session starts it, as they do for datumhue run. Stepping into one shows its code: it has no file on your disk, so your editor shows the copy the debugger sends.

Debug a test suite

datumhue pkg test with --dap waits for your editor in the same way, and runs the package's tests instead of the app, with breakpoints in your test files as well (Test a package).

$ datumhue pkg test calc --dap

See also

• Set up your editor
• Test a package
• Find what's slow