Boot the target system with networking support:
fx emu -Nfx qemu -N(If using x64 with an emulator on a Linux host, we also recommend the “-k” flag, which will make it run faster).
To manually validate network connectivity run fx shell or fx get-device-addr.
The binary is tools/zxdb in the Fuchsia SDK. SDK users will have to do an extra step to set up your symbols. See “Running out-of-tree” below for more.
A Fuchsia “core” build includes (as of this writing) the necessary targets for the debugger. So this build configuration is sufficient:
fx --dir=out/x64 set core.x64
If you‘re compiling with another product, you may not get it by default. If you don’t have the debugger in your build, add //bundles:tools to your “universe”, either with:
fx <normal_stuff_you_use> --with //bundles:tools
Or you can edit your GN args directly by editing <build_dir>/args.gn and adding to the bottom:
universe_package_labels += [ "//bundles:tools" ]
You can use the fx utility to start the debug agent and connect automatically.
For most build configurations, the debug agent will be in the “universe” (i.e. “available to use”) but not in the base build so won't be on the system before boot. You will need to run:
fx serve
to make the debug agent's package available for serving to the system. Otherwise you will get the message “Timed out trying to find the Debug Agent”.
Once the server is running, launch the debugger in another terminal window:
fx debug
To manually validate packages can be loaded, run ls from within the Fuchsia shell (for most setups this requires fx serve to be successfully serving packages).
In some cases you may want to run the debug agent and connect manually. To do so, follow these steps:
On the target system pick a port and run the debug agent:
run fuchsia-pkg://fuchsia.com/debug_agent#meta/debug_agent.cmx --port=2345
If you get an error “Cannot create child process: ... failed to resolve ...” it means the debug agent can't be loaded. You may need to run fx serve or its equivalent in your environment to make it available.
You will want to note the target's IP address. Run ifconfig on the target to see this, or run fx get-device-addr on the host.
On the host system (where you do the build), run the client. Use the IP address of the target and the port you picked above in the connect command. If running in-tree, fx get-device-addr will tell you this address.
For QEMU, we recommend using IPv6 and link local addresses. These addresses have to be annotated with the interface they apply to, so make sure the address you use includes the appropriate interface (should be the name of the bridge device).
The address should look like fe80::5054:ff:fe63:5e7a%br0
$ fx zxdb or out/<out_dir>/host_x64/zxdb [zxdb] connect [fe80::5054:ff:fe63:5e7a%br0]:2345
(Substitute your build directory as-needed).
If you're connecting or running many times, there are command-line switches:
zxdb -c [fe80::5054:ff:fe63:5e7a%br0]:2345
The status command will give you a summary of the current state of the debugger.
See help connect for more examples, including IPv6 syntax.
You can run with kernels or user programs compiled elsewhere with some extra steps. We hope this will become easier over time.
Be aware that we aren't yet treating the protocol as frozen. Ideally the debugger will be from the same build as the operating system itself (more precisely, it needs to match the debug_agent). But the protocol does not change very often so there is some flexibility.
When you run out-of-tree, you will need to tell zxdb where your symbols and source code are on the local development box (Linux or Mac). Zxdb can not use symbols in the binary that you pushed to the Fuchsia target device.
See Diagnosing symbol problems.
There are three command-line flags to control the symbol lookup locations for zxdb: --build-id-dir, --ids-txt, and a general --symbol-path. They all have the corresponding settings that can be manipulated using set or get.
For example, to add a “.build-id” directory, either use --build-id-dir flag:
zxdb --build-id-dir some/other_location/.build-id
Or add it to the build-id-dirs list option in the interactive UI:
[zxdb] set build-id-dirs += some/other_location/.build-id
For in-tree development, fx debug automatically sets up all necessary flags.
build-id-dirSome builds produce a .build-id directory. Symbol files in it are already indexed according to their build IDs. For example, the Fuchsia build itself makes a .build-id directory inside the build directory, e.g., out/x64/.build-id. They can be added to zxdb by --build-id-dir command-line flag or build-id-dirs setting. This is the best option.
ids-txtInstead of a .build-id directory, some builds produce a file called ids.txt that lists build IDs and local paths to the corresponding binaries. They can be added to zxdb by --ids-txt command-line flag or ids-txts setting. This is the second-best option.
symbol-pathIn addition, --symbol-path flag can be used to add arbitrary files or directories to symbol index. If the path is pointing to a file, it will be treated as an ELF file and added to the symbol index. If it's a directory, all binaries under the given path are indexed.
The Fuchsia build generates symbols relative to the build directory so relative paths look like ../../src/my_component/file.cc).
If your files are not being found with the default build directories, you will need to provide a build directory to locate the files. This build directory does not need have been used to build, it just needs to produce correct absolute paths when concatenated with the relative paths from the symbol file.
You can add additional build directories on the command line:
zxdb -b /home/me/fuchsia/out/x64
Or interactively from within the debugger:
[zxdb] set build-dirs += /home/me/fuchsia/out/x64
If debugger is finding the wrong file, you can replace the entire build directory list by omitting the +=:
[zxdb] set build-dirs /home/me/fuchsia/out/x64
If your build produces DWARF symbols with absolute file paths the files must be in that location on the local system. Absolute file paths in the symbols are not affected by the build search path. Clang users should use the -fdebug-prefix-map, which will also help with build hermeticity.