Zxdb is a console debugger for native code compiled with DWARF symbols (C, C++ and Rust). The frontend runs on the host computer and connects to the on-device
debug_agent. This document describes how to set up these processes.
debug_agent is run on the target device along with the port number that it should listen to for incoming client connections. Typically this command will be run from a console after ssh-ing in to the system:
run fuchsia-pkg://fuchsia.com/debug_agent#meta/debug_agent.cmx --port=2345
zxdb client program is run on the host computer. It can be connected to the
debug_agent via the interactive
connect debugger command or it can automatically connect based on a command-line flag. Both IPv4 and IPv6 addresses are supported (see device discovery to find the address). The port should match the port number passed to the agent.
zxdb -c "[f370::5051:ff:1e53:589a%qemu]:2345"
Scripts may want to automatically launch the agent and client automatically. The script should wait for the port to be open on the target system before launching the client. Automatic retry is not yet implemented in the client.
To clean up the debug agent gracefully when the client exits, pass the
--quit-agent-on-exit command-line flag to the client.
The debugger expects unstripped ELF files to be available on the local host system. Symbols on the target are not used. The location where the local build stores symbols must be passed to the
Local symbols can be passed on the command line:
The path can be any of:
GNU-style symbol repos are directories of any layout which contain a folder at the root called .build-id. This folder contains the symbolized binaries indexed by the binaries' build IDs. Often these are symlinks pointing to various locations in the folder itself.
Multiple `--symbol-path` parameters may be specified if there are symbols in more than one location. All locations will be searched. Symbol locations can also be edited interactively in the client using the global "symbol-paths" setting (see the interactive "get" and "set" commands).