Debug (`//src/developer/debug`)

This directory contains the host and target components of the Fuchsia debugger.

User Documentation

Read the user guide in //docs/development/debugger. For AI agent rules and subsystem conventions, read AGENTS.md.

This directory partitions the debugger into these subsystems:

debug_agent: Target-side debugger stub for Fuchsia and experimental Linux. Manages job/process/thread attachment, breakpoints, watchpoints, filters, ProcessLimbo, stack unwinding, and debug_ipc/FIDL servers. Low-level POSIX/Linux helpers live in debug_agent/posix.
ffx_zxdb: Host Rust crate that integrates zxdb with ffx debug. Provides command builders, process management, and UNIX domain socket to FDomain FIDL socket forwarding (ffx_zxdb/src).
ipc: Binary wire protocol (debug_ipc) shared between zxdb and debug_agent. Defines request/reply and notification records, versioned serialization (MessageReader, MessageWriter), filter matching, and exception decoding.
shared: Cross-platform abstractions shared by zxdb and debug_agent. Provides MessageLoop, StreamBuffer, buffered I/O streams, CPU register metadata, AddressRange, Status/Result, and hierarchical logging (shared/logging).
zxdb: Host debugger frontend layered upward across zxdb/common, zxdb/symbols, zxdb/expr, zxdb/format, zxdb/client, zxdb/console (commands), and zxdb/debug_adapter (handlers).
e2e_tests: Host-driven .script end-to-end tests (zxdb_e2e_tests) and Debug Adapter Protocol (DAP) integration suites (dap_integration_tests).
skills/fuchsia-debugger: Agent skill instructions for debugging Fuchsia test failures with fx debug cli.
.agents/skills/editing_zxdb: Agent skill workflows for building and testing zxdb and debug_agent.

All components under //src/developer/debug enforce these invariants:

Host/Target Split & Wire Compatibility: zxdb builds only on the host toolchain (is_host). It talks to debug_agent over the debug_ipc binary protocol within the [kMinimumProtocolVersion, kCurrentProtocolVersion] ABI window from the Hello handshake.
Upward Subsystem Layering: Dependencies flow strictly upward without cycles: shared <- ipc <- {debug_agent, zxdb/common <- zxdb/symbols <- zxdb/expr <- {zxdb/format, zxdb/client} <- zxdb/console <- zxdb/debug_adapter}.
Single-Threaded Event Loop & Weak Lifetimes: Both zxdb and debug_agent dispatch IPC, socket I/O, and asynchronous callbacks on a thread-bound debug::MessageLoop. Never hold raw pointers to transient session objects (Target, Process, Thread, Frame, Breakpoint, DebuggedProcess, DebuggedThread, FormatNode) across asynchronous callbacks. Use fxl::WeakPtr for transient objects and fxl::RefPtr for reference-counted symbol or expression nodes.
Dual Bazel/GN Build Definitions: Do not manually edit BUILD.gn files below # BAZEL2GN SENTINEL markers. Edit the matching BUILD.bazel file and run fx bazel2gn.

Running the debugger produces these target and host side effects:

Target OS & Process Mutation: Attaches to Zircon exception channels, suspends and resumes target threads, and patches trap instructions into process memory. Also writes CPU general and debug registers, starts components and tests via fuchsia.debugger and fuchsia.component, and claims or releases crashed processes in ProcessLimbo.
Host I/O, Networking, & Subprocesses: Opens local UNIX domain and TCP sockets for debug_ipc and DAP connections, and spawns zxdb and optional local debug_agent processes. Also memory-maps local ELF/DWARF binaries, downloads debug symbols over HTTP/HTTPS via libcurl into local LRU caches, and reads or writes terminal streams and ~/.zxdb_history.

Run these commands to build and test all debugger components:

Build: fx build //src/developer/debug //src/developer/debug/zxdb
Test: fx test zxdb_tests debug_agent_unit_tests debug_agent_launcher_unit_tests debug_agent_integration_tests