Zxdb (zxdb)

zxdb is the host-side frontend of the Fuchsia debugger. It runs on the developer's workstation (Linux or macOS) and talks over debug_ipc (../ipc) to debug_agent (../debug_agent) on the Fuchsia target.

User Documentation

Read the user guide in //docs/development/debugger.

Subdirectories & Layering

Subdirectories follow a strict bottom-up dependency order (common <- symbols <- expr <- {format, client} <- console <- debug_adapter):

• common: Layer 1 (lowest) foundational utilities (Err, ErrOr, AddressRanges, DataExtractor, Curl, CacheDir). Cannot depend on any other zxdb layer.
• symbols: Layer 2 LLVM DWARF/ELF symbol parser, indexer (Index), lazy object model (Symbol, LazySymbol, Type, Function), and BuildIDIndex.
• expr: Layer 3 C++/Rust expression tokenizer, parser, AST (ExprNode), bytecode VM (VmExec), and EvalContext evaluation engine.
• format: Layer 4 styled output buffers (OutputBuffer, AsyncOutputBuffer), FormatNode tree rendering, and identifier/function formatting helpers.
• client: Layer 4 UI-independent debugger session and object model (Session, System, Target, Process, Thread, Stack, Frame, Breakpoint, ThreadController).
• console: Layer 5 CLI frontend, noun/verb parser, ConsoleContext, and CLI verb handlers (console/commands).
• debug_adapter: Layer 6 Debug Adapter Protocol (DAP) server (DebugAdapterServer, DebugAdapterContext) and request handlers (debug_adapter/handlers).

Interface

Top-level host entry points in //src/developer/debug/zxdb include:

• zxdb::ConsoleMain(int argc, const char* argv[]) (main.cc): Host entry point that parses CLI flags, initializes MessageLoopPoll and Session, and runs the console or DAP server.
• zxdb::ForkLocalAgent() and zxdb::LocalAgentResult (local_agent.h, local_agent.cc): Forks a local Linux debug_agent over a debug::BufferedBidiPipe for --local on Linux x64 hosts.
• zxdb::RunLocalAgent(fbl::unique_fd read_pipe, fbl::unique_fd write_pipe) (local_agent.cc): Runs the child debug_agent::DebugAgent backed by debug_agent::LinuxSystemInterface on a debug::MessageLoopPoll.

Invariants

Callers and entry points must preserve these invariants:

• zxdb targets build only on the host toolchain (is_host), and built-in local debug_agent support (SUPPORTS_LOCAL_AGENT) builds only on Linux x64 (is_linux && current_cpu == "x64").
• Subdirectory dependencies flow strictly upward without cycles: common <- symbols <- expr <- {format, client} <- console <- debug_adapter.
• In ConsoleMain, debug::MessageLoopPoll and its deferred Cleanup() must outlive Session, Console, DebugAdapterServer, and BufferedBidiPipe (scoped in an inner block).
• In RunLocalAgent, an inner scope destroys DebugAgent and BufferedBidiPipe before calling message_loop.Cleanup().
• The --core and --connect command-line flags are mutually exclusive.
• When running interactively (without enable_debug_adapter) on a TTY STDIN_FILENO, the process must own the foreground process group (tcgetpgrp(STDIN_FILENO) == getpgrp()) or exit with EXIT_FAILURE.
• When ForkLocalAgent() succeeds, the parent process kills and reaps agent_pid via waitpid() on exit (fit::defer).

Side Effects

Running zxdb produces these process, I/O, and network side effects:

• Ignores SIGPIPE process-wide via signal(SIGPIPE, SIG_IGN).
• Initializes and cleans up global libcurl state (Curl::GlobalInit / Curl::GlobalCleanup) and telemetry (Analytics::Init / Analytics::CleanUp).
• Creates non-blocking OS pipes (pipe2 with O_NONBLOCK) and calls fork() for --local on Linux x64, running and reaping a child DebugAgent.
• Reads command sequences from config_files and script_file, and opens stream_files (O_RDONLY | O_NONBLOCK) to stream output to the console.
• Sends SIGUSR1 via kill(options.signal_when_ready, SIGUSR1) after console initialization and startup commands complete.

Verification

Run these commands to build and test zxdb:

• Build: fx build //src/developer/debug/zxdb
• Test: fx test zxdb_tests