Debugging from the editor
oxl dap is a thin proxy over lldb-dap: messages pass unchanged except for the launch of the program and a few OxL requests
(debugger guide). lldb-18 is needed; lldb-dap is found through --lldb-dap <path>, OXL_LLDB_DAP or
/usr/lib/llvm-18/bin/lldb-dap.
launch parameters#
| Field | Value |
|---|---|
program | an .oxl file, a package directory (built with oxl build --debug-info full) or a ready executable |
args, env, cwd | as in any DAP configuration (cwd defaults to the package directory) |
oxlProfile | dev (default), test, prod |
oxlFormatters | false: do not load the pretty-printers for str, List, Map, T? |
stopOnEntry | stop at the start |
Configurations#
VS Code (.vscode/launch.json; the type oxl comes from the extension):
{
"version": "0.2.0",
"configurations": [
{ "type": "oxl", "request": "launch", "name": "Debug OxL package", "program": "${workspaceFolder}" },
{ "type": "oxl", "request": "launch", "name": "Debug current file", "program": "${file}", "oxlProfile": "dev" }
]
}Other clients run the command oxl dap and send the same launch: nvim-dap in Neovim, Helix in Helix,
Emacs in Emacs, JetBrains in LSP4IJ.
The debugger supports line, conditional and function breakpoints and logpoints; stacks, variables and watches with OxL values;
special breakpoints rpc Users.get, msg Cart.add, step placeOrder#2, error PayError, panic (as function breakpoints);
the console commands oxl tasks / oxl waits list tasks and the "who waits for whom" graph; parked tasks appear as threads.
Debugging one test#
oxl test --exact "checkout empty cart" --debug
oxl test --exact "checkout empty cart" --debug=dap
oxl test --exact "checkout empty cart" --debug=lldbExactly one test must be selected; it is built with -O0 and full debug information.
A remote node#
A running node can be debugged over the network, directly or through the cluster (mTLS, role debug, audited):
./shop --debug-listen 0.0.0.0:2345 --role api
oxl debug attach 10.0.3.7:2345 --cert me.crt --key me.key --ca me.ca.crt
oxl keys issue --role debug --name alice
oxl debug enable --node api-2 --for 30m --cluster shop.internal:7000 --cert … --key … --ca …
oxl debug --node api-2 --cluster shop.internal:7000 --cert … [--all-stop|--non-stop] [--binary ./shop]oxl debug … is the same kind of DAP adapter, so it plugs into clients that can start an adapter command (nvim-dap, Helix, dape,
LSP4IJ): command = "oxl", args = ["debug", "attach", "host:port", …]. The mode --non-stop stops only the task with a
breakpoint while the others keep running; the distributed stop shows the stacks of the calling nodes of the chain. The VS Code
extension of this release supports only launch of a local program; debug a remote node from VS Code through a terminal or a
client that can start the adapter by command. The profiler of a node is oxl prof cpu|heap|tasks.