debug

A software debugger toolkit for Jda programs. Provides breakpoints that pause execution, variable inspection with formatted output, runtime assertions that abort on failure, watchpoints that detect value changes, and hit counters.

Usage

import debug

fn main() {
    dbg_init()
    dbg_enable()

    let x = 42
    dbg_inspect_int("x", x)
    // Output: [DBG] x = 42

    dbg_assert_eq(x, 42, "x should be 42")

    // Watchpoints
    dbg_watch(0, "x", &x)
    x = 99
    let changed = dbg_check()
    // changed == 1

    // Hit counter
    dbg_counter_reset()
    dbg_counter_inc()
    dbg_counter_inc()
    dbg_counter_print("iterations")
    // Output: [DBG] iterations: 2

    ret 0
}

Function Reference

Function	Signature	Description
`dbg_init`	`()`	Initialise debugger state
`dbg_enable`	`()`	Enable debug output
`dbg_disable`	`()`	Disable debug output
`dbg_is_enabled`	`() -> i64`	Check if debugging is enabled
`dbg_print`	`(msg: &i8)`	Print debug message (no newline)
`dbg_println`	`(msg: &i8)`	Print debug message with newline
`dbg_break`	`(label: &i8)`	Breakpoint — pauses execution via stdin read
`dbg_inspect_int`	`(name: &i8, val: i64)`	Print `[DBG] name = <decimal>`
`dbg_inspect_hex`	`(name: &i8, val: i64)`	Print `[DBG] name = 0x<hex>`
`dbg_inspect_ptr`	`(name: &i8, ptr: i64)`	Print `[DBG] name = 0x<hex>` (pointer)
`dbg_inspect_bool`	`(name: &i8, val: i64)`	Print `[DBG] name = true/false`
`dbg_assert`	`(cond: i64, msg: &i8)`	Assert condition is truthy, abort if false
`dbg_assert_eq`	`(a: i64, b: i64, msg: &i8)`	Assert a == b
`dbg_assert_ne`	`(a: i64, b: i64, msg: &i8)`	Assert a != b
`dbg_assert_gt`	`(a: i64, b: i64, msg: &i8)`	Assert a > b
`dbg_assert_lt`	`(a: i64, b: i64, msg: &i8)`	Assert a < b
`dbg_watch`	`(slot: i64, name: &i8, ptr: &i64)`	Watch a memory address for changes (max 16 slots)
`dbg_unwatch`	`(slot: i64)`	Stop watching a slot
`dbg_watch_count`	`() -> i64`	Return number of active watchpoints
`dbg_check`	`() -> i64`	Check all watchpoints, return count of changed values
`dbg_counter_reset`	`()`	Reset the hit counter to zero
`dbg_counter_inc`	`()`	Increment the hit counter
`dbg_counter_get`	`() -> i64`	Return current counter value
`dbg_counter_print`	`(label: &i8)`	Print `[DBG] label: <count>`

Detailed API

dbg_init

fn dbg_init()

Initialise the debugger. Resets all watchpoints, counters, and enables output. Call once at the start of your program.

dbg_enable

fn dbg_enable()

Enable debug output. When disabled, inspect/print/break/counter_print calls are silently skipped. Assertions still fire regardless of enable state.

dbg_disable

fn dbg_disable()

Disable debug output. Useful for suppressing noise in production builds while keeping assertions active.

dbg_break

fn dbg_break(label: &i8)

Insert a breakpoint. Prints [BREAK] <label> — press Enter to continue and blocks on stdin. Skipped when debugging is disabled.

dbg_break("before sort")
sort_vec(v)
dbg_break("after sort")

dbg_inspect_int

fn dbg_inspect_int(name: &i8, val: i64)

Print a variable’s name and decimal value to stdout.

let count = 42
dbg_inspect_int("count", count)
// Output: [DBG] count = 42

dbg_inspect_hex

fn dbg_inspect_hex(name: &i8, val: i64)

Print a variable’s name and hexadecimal value.

dbg_inspect_hex("flags", 255)
// Output: [DBG] flags = 0x00000000000000FF

dbg_inspect_bool

fn dbg_inspect_bool(name: &i8, val: i64)

Print a variable as true (non-zero) or false (zero).

dbg_inspect_bool("found", 1)
// Output: [DBG] found = true

dbg_assert

fn dbg_assert(cond: i64, msg: &i8)

Assert that cond is truthy. If false, prints [ASSERT FAIL] <msg> to stderr and aborts with exit code 1.

dbg_assert(len > 0, "length must be positive")

dbg_assert_eq

fn dbg_assert_eq(a: i64, b: i64, msg: &i8)

Assert a == b. On failure, prints both values and the message.

dbg_watch

fn dbg_watch(slot: i64, name: &i8, ptr: &i64)

Register a watchpoint. Monitors the memory at ptr for value changes. Up to 16 slots (0-15). The initial value is recorded when dbg_watch is called.

let x = 10
dbg_watch(0, "x", &x)
x = 20
let changed = dbg_check()
// changed == 1, prints: [WATCH] x changed: 10 -> 20

dbg_check

fn dbg_check() -> i64

Check all active watchpoints. For each slot where the current value differs from the previously recorded value, prints a change notification and updates the stored value. Returns the number of changed watchpoints.

dbg_counter_reset

fn dbg_counter_reset()

Reset the hit counter to zero. Useful for counting loop iterations, function calls, or events.

dbg_counter_print

fn dbg_counter_print(label: &i8)

Print the current counter value with a label.

dbg_counter_reset()
for i in range(100) {
    dbg_counter_inc()
}
dbg_counter_print("loop iterations")
// Output: [DBG] loop iterations: 100