| # Debugger (zxdb) |
| |
| 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. |
| |
| ## Running the agent |
| |
| The `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](ssh.md) in to the system: |
| |
| ``` |
| run fuchsia-pkg://fuchsia.com/debug_agent#meta/debug_agent.cmx --port=2345 |
| ``` |
| |
| ## Connecting the client |
| |
| The `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](device_discovery.md) to find |
| the address). The port should match the port number passed to the agent. |
| |
| ``` |
| zxdb -c "[f370::5051:ff:1e53:589a%qemu]:2345" |
| ``` |
| |
| ### Connecting via a script |
| |
| 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. |
| |
| ## Specifying symbol paths |
| |
| 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 `zxdb` client. |
| |
| For more information on how to specify symbol paths, see [set the symbol |
| location](/docs/development/debugger/README.md#set-symbol-location) |
