axon-debug

axon-debug

Debugging tools for the Axon programming language — GDB and LLDB pretty printers, crash symbolicators, and profiling helpers.

Features

• GDB Pretty Printers — Human-readable display of Axon types (Option, Result, String, Vec, Map) in GDB
• LLDB Type Formatters — Equivalent type summary/synthetic providers for LLDB
• Crash Symbolicator (axon-sym) — Parse crash traces and resolve addresses to source file:line; supports free-form traces, explicit addresses, and structured JSON crash reports
• C Bindings Generator (axon-bindgen) — Generate Axon .axs extern declarations from C header files
• Performance Benchmarks (tools/bench.py) — Micro-benchmarks for addr2line and bindgen with CI thresholds
• Memory Profiler (tools/memprof.py) — Heap allocation tracker + leak detector (issue #34)
• CPU Profiler (tools/cpu.py) — Sampling CPU profiler with hot-spot aggregation (issue #122)
• Panic Handler (tools/panic_hook.py) — Structured panic reporter with category classification (issue #120)
• DAP Server (tools/dap.py) — Minimal Debug Adapter Protocol server for editors like VS Code and Cursor (issue #123)
• MCP Server (tools/mcp.py) — Model Context Protocol server (stdio / JSON-RPC 2.0) exposing 7 debug tools — addr2line, crash decode, memprof + CPU summaries, ownership, replay inspect, launch plan — to AI agents like Claude Code and Cursor (issue #127)

Supported Types

Axon Type	GDB Display	LLDB Display
Option	Some(42) / None	Some(42) / None
Result	Ok(val) / Err(e)	Ok(val) / Err(e)
String	"hello world"	"hello world"
Vec	Vec(len=3, cap=8) [0]=1 [1]=2 [2]=3	Vec(len=3, cap=8)
Map	Map(string, len=2, cap=4)	Map(string, len=2, cap=4)
Sum / Enum	Tag::Variant(data)	Tag::Variant(data)
Tuple	(1, "hello", 3.14)	(1, "hello", 3.14)

Installation

For full per-platform install instructions (Homebrew, apt, winget, manual, dev), see docs/INSTALL.md.

Quick Start

# macOS / Linux (one-time, auto-detects GDB and/or LLDB):
git clone https://git.catalystgroup.tech/labs/axon/axon-debug.git
cd axon-debug
./install.sh

# Verify:
./install.sh --check      # show status
./install.sh --verify     # actually load printers in debugger

Other install paths

Platform	Command
macOS	brew install axon-debug (after tap; see packaging/homebrew/)
Ubuntu/Debian	sudo dpkg -i axon-debug_*_all.deb (build with packaging/debian/build-deb.sh)
Windows	winget install catalystgroup.axon-debug (manifest in packaging/winget/)
Any (release)	Download tarball from Releases + run ./install.sh

Usage

GDB

$ gdb ./my_axon_program
(gdb) break main
(gdb) run
(gdb) print my_option
$1 = Some(42)
(gdb) print my_result
$2 = Ok("success")
(gdb) print my_string
$3 = "hello world"

LLDB

$ lldb ./my_axon_program
(lldb) breakpoint set --name main
(lldb) run
(lldb) frame variable my_option
(axon::Option) my_option = Some(42)
(lldb) frame variable my_result
(axon::Result) my_result = Ok("success")

Crash Symbolication (axon-sym / tools/addr2line.py)

axon-sym resolves hex addresses in crash traces to source file:line pairs. It works in three modes:

Mode 1 — Free-form text / piped trace:

my_program 2>&1 | python3 tools/addr2line.py ./my_program
python3 tools/addr2line.py ./my_program crash.log
python3 tools/addr2line.py ./my_program 0x1234 0x5678

Mode 2 — JSON crash report (--crash-file):

When an Axon program crashes, axon_panic_handler() in libaxon_rt.a writes a structured crash.json to ~/.axon/crashes/. The --crash-file mode symbolicates the full stack:

# Use binary_path embedded in the crash report (most common):
python3 tools/addr2line.py --crash-file ~/.axon/crashes/2026-06-20T03-26-21Z.json

# Override binary path if missing from report:
python3 tools/addr2line.py --crash-file crash.json --binary ./my_program

# Machine-readable JSON output (for Sentry pipelines):
python3 tools/addr2line.py --crash-file crash.json --output json > symbolized.json

# Text output with per-frame detail:
python3 tools/addr2line.py --crash-file crash.json --output text

See docs/CRASH_REPORTS.md for the full crash.json schema and storage location documentation.

Project Structure

axon-debug/
├── gdb/
│   ├── __init__.py            # GDB auto-load package init
│   └── axon_printers.py       # GDB pretty printers (Option, Result, String, Vec, Map)
├── lldb/
│   └── axon_formatters.py     # LLDB type formatters + synthetic children providers
├── tools/
│   ├── addr2line.py           # Crash trace symbolicator (free-form + JSON crash reports)
│   ├── bindgen.py             # C header → Axon .axs extern generator
│   ├── aggregate_metrics.py   # JUnit + coverage.json → public/metrics.json
│   ├── run_tests.sh           # Canonical test runner (JUnit + coverage)
│   ├── bench.py               # Performance micro-benchmarks (addr2line + bindgen)
│   ├── dap.py                 # Debug Adapter Protocol server (stdio/TCP)
│   ├── mcp.py                 # Model Context Protocol server (stdio/JSON-RPC, 7 debug tools)
│   └── remove_blocks.py       # Strip axon-debug version blocks from init files
├── tests/
│   ├── fixtures/
│   │   ├── basic_types.axs    # Test fixture (i32, i64, bool)
│   │   └── crash_test.c        # C test binary for addr2line end-to-end tests
│   ├── conftest.py            # Shared pytest fixtures
│   ├── test_printers.py       # Printer unit tests (no debugger needed)
│   ├── test_lldb_formatters.py # LLDB provider interface + parity tests
│   ├── test_basic_types.py    # GDB integration tests
│   ├── test_bindgen.py        # bindgen CLI tests
│   ├── test_addr2line.py      # addr2line unit + end-to-end tests
│   ├── test_mcp.py            # MCP server tests (handshake, schema, 7 tools)
│   └── test_bench.py          # bench.py smoke tests
├── docs/
│   ├── INSTALL.md              # Full per-platform install guide
│   ├── CRASH_REPORTS.md        # crash.json schema and storage
│   ├── tools.md                # tools/ directory reference
│   ├── dap.md                  # Debug Adapter Protocol server guide
│   ├── mcp.md                  # Model Context Protocol server guide
│   ├── FORMATTERS.md            # GDB/LLDB formatter architecture
│   └── CI.md                   # CI pipeline and metrics infrastructure
├── public/
│   └── metrics.json            # GitLab Pages metrics (deployed by CI)
├── requirements.txt            # Python dependencies
├── .gitlab-ci.yml              # CI pipeline
├── install.sh                  # GDB/LLDB installer with idempotency + versioning
├── CONTRIBUTING.md             # Contributor guide (start here!)
└── README.md

Running Tests

Using the canonical runner (recommended)

tools/run_tests.sh              # full suite with JUnit + coverage
tools/run_tests.sh --no-cov     # skip coverage (faster)
tools/run_tests.sh --keep-results  # keep results.xml / coverage files
tools/run_tests.sh tests/test_printers.py  # single file
tools/run_tests.sh --help       # show all flags

Using pytest directly

pytest tests/ -v                # all tests
pytest tests/test_printers.py -v # unit tests only (no GDB/LLDB required)
pytest tests/test_basic_types.py -v  # GDB integration tests

GDB tests auto-skip on macOS (outdated GDB). LLDB tests require an LLVM-based lldb (default on macOS).

Running benchmarks

python3 tools/bench.py  # writes benchmarks.json

Benchmarks measure addr2line (10/100/1000 frames) and bindgen (10/50/100 declarations) wall-clock time.

Development

Prerequisites

• Python 3.8+
• GDB 10+ (with Python support) and/or LLDB 12+
• Axon compiler (for building test fixtures)
• For addr2line end-to-end tests: binutils (addr2line) and a C compiler (cc)

Setup

pip install -r requirements.txt

Linting

ruff check gdb/ tools/ tests/ lldb/

Recent Changes

MR	Summary
#127	tools/mcp.py — Model Context Protocol server exposing 7 debug tools over stdio (see docs/mcp.md, CHANGELOG.md)
#123	tools/dap.py — minimal Debug Adapter Protocol server (see docs/dap.md)
!12	tests/test_bench.py — coverage fix for benchmark tests
!11	tools/bench.py — performance micro-benchmarks for addr2line + bindgen, CI threshold
!10	Coverage threshold gate (23%) added to CI
!9	Metrics pipeline: run_tests.sh, aggregate_metrics.py, GitLab Pages deployment
!8	addr2line.py --crash-file JSON mode, docs/CRASH_REPORTS.md
!7	install.sh rewrite: idempotency, versioning, --verify flag

Related

• axon-lang — The Axon compiler
• axon-std — Axon standard library
• axon-db — Database driver library

License

See LICENSE for details.