This page describes source breakpoints and variables in an image launched by
okrun --debugger with openkal-ld 0.5.0 or later. Remote board debug servers
and external debug-sidecar loading are separate interfaces.
Compile the image with DWARF debug information (-g) and retain its debug
relocations at link time (--emit-relocs). Retain the .rela.debug_* sections
when further processing the linked ELF. The normal requirements-note, placement
and format checks still apply.
For GDB:
gdb --args okrun --debugger app.oke
(gdb) set breakpoint pending on
(gdb) break ok_main
(gdb) run
For LLDB:
lldb -- okrun --debugger app.oke
(lldb) settings set plugin.jit-loader.gdb.enable on
(lldb) breakpoint set --name ok_main
(lldb) run
The debugger resolves the pending breakpoint when the image is registered. Source-line breakpoints, local variables, stepping and normal exit are verified on Linux x86-64 with the GDB and LLDB bundled in CLion 2026.1.5.2. The runtime matrix for Windows, macOS and Linux AArch64 does not establish native source-debugger compatibility on those systems.
The debugger-object builder accepts little-endian ELF64 metadata for x86-64
and AArch64. Embedded debug sections may use ELF zlib compression
(SHF_COMPRESSED); the loader expands them in the debugger object. The
executable image and its persistent compressed bytes remain unchanged.
An image containing .debug_info or .debug_line needs retained debug
relocations. Debugger mode refuses an image that lacks them. Ordinary runs
remain available. An image without source debug information can still expose
its retained defined symbols.
GNU legacy .zdebug_* sections, zstd-compressed debug sections and native
TLS symbols are unsupported in this debugger view. A stripped image's
external debug sidecar is not automatically loaded by the JIT path.
okld debug-split and the scripts in tools/scripts retain their separate
build-id-based interface for symbols outside the image.