Zxdb should automatically set symbol settings by your environment. This section explains how zxdb loads symbols. If you are looking for ways to troubleshoot common issues with zxdb's symbolizer, see [Diagnose problems with symbols](https://fuchsia.dev/docs/development/debugger/troubleshooting#diagnose-problems-symbols). ## build IDs Zxdb locates the symbols for a binary on a target device by using the binary's **build ID**. For example, to see the build ID for a binary on Linux, dump the `notes` for the ELF binary: $ readelf -n my_binary ... (some other notes omitted) ... Displaying notes found in: .note.gnu.build-id Owner Data size Description GNU 0x00000014 NT_GNU_BUILD_ID (unique build ID bitstring) Build ID: 18cec080fc47cdc07ec554f946f2e73d38541869 The `sym-stat` zxdb command shows the build IDs for each binary and the library that is currently loaded in the attached process. It also displays the corresponding symbol file if found. ## Symbol servers Zxdb can load symbols for prebuilt libraries from Google servers or upstream `debuginfod` servers. This is the mechanism how symbols are delivered for SDK users for anything that isn't built locally. For more information, see [Downloading symbols](https://fuchsia.dev/docs/development/debugger/advanced#download-symbols). When working with large binaries, symbols can be several gigabytes so the download process may take some time (usually in the range of several minutes). The `sym-stat` command displays `Downloading...` while downloading symbols. When zxdb downloads symbols, it stores them in the symbol cache. The `symbol-cache` setting contains the name of this directory. For example: get symbol-cache symbol-cache = /home/me/.fuchsia/debug/symbol-cache When zxdb downloads symbols from prebuilt binaries fetched from upstream packages, the debuginfo may not have a corresponding ELF binary (depending on the server and the package). When this happens, zxdb may display errors that look like: ... binary for build_id 26820458adaf5d95718fb502d170fe374ae3ee70 not found on 5 servers binary for build_id 53eaa845e9ca621f159b0622daae7387cdea1e97 not found on 5 servers binary for build_id f3fd699712aae08bbaae3191eedba514c766f9d2 not found on 5 servers binary for build_id 4286bd11475e673b194ee969f5f9e9759695e644 not found on 5 servers binary for build_id 2d28b51427b49abcd41dcf611f8f3aa6a2811734 not found on 5 servers binary for build_id 0401bd8da6edab3e45399d62571357ab12545133 not found on 5 servers ... This indicates that the ELF binary file was not found on the debuginfod servers. When this happens, the ELF symbols are not available for this particular binary, which is typically fine for most debugging scenarios. The most commonly used ELF specific symbols that may be unavailable are PLT symbols. You can use the `sym-stat` command to verify that DWARF information has been loaded: > [!NOTE] > **Note:** DWARF information is downloaded separately from the ELF symbols. libc.so.6 Base: 0x1c85fdc2000 Build ID: 0401bd8da6edab3e45399d62571357ab12545133 Symbols loaded: Yes Symbol file: /home/alice/.fuchsia/debug/symbol-cache/04/01bd8da6edab3e45399d62571357ab12545133.debug Source files indexed: 1745 Symbols indexed: 10130 ### .build-id directory symbol databases > [!CAUTION] > **Caution:** If you are working from a Fuchsia checkout or with a Fuchsia SDK, you don't need to consider the information from this section. Many build environments, including the main `fuchsia.git` repository, add symbolized binaries in a standard directory structure called `.build-id`. This directory contains subdirectories that are named according to the first two characters of the binary's build ID. These subdirectories contain the symbol files named according to the remaining characters of the build ID. You can set one or more build ID directories on the command line or interactively by using the `build-id-dirs` setting which is a list of directory paths. For example, to add `/home/alice/project/out/x64/.build-id` as a `build-id-dirs`: > [!NOTE] > **Note:** These directories do not need to be named `.build-id` ### zxdb instance > [!NOTE] > **Note:** These `build-id-dirs` are only added for the duration of the zxdb instance. set build-id-dirs += /home/alice/project/out/x64/.build-id ### ffx > [!NOTE] > **Note:** These paths are added to the configuration of zxdb and persist through zxdb instances. Make sure to use a path that is relative to your Fuchsia checkout ```bash ffx debug symbol-index add out/default/.build-id ``` These directories are then annotated with `(folder)` in the output of the `sym-stat` instead of the number of binaries that are contained in the directory. These binaries are not displayed in the `sym-stat --dump-index` output because zxdb searches these directories on demand when searching for symbols rather than enumerating them in advance. ### Individual files and directories > [!CAUTION] > **Caution:** If you are working from a Fuchsia checkout or with a Fuchsia SDK, you don't need to consider the information from this section. If you have a single binary file without one of the other symbol database formats, you can configure zxdb for that specific file. You can use configure the `symbol-paths` for a particular file by adding it to the list of paths. For example, to add `/home/alice/project/a.out` to the `symbol-paths` setting: > [!NOTE] > **Note:** This setting also accepts directory names. In the case of directories case, zxdb non-recursively enumerates all files in that directory and attempts to find binaries with build IDs. ### File set symbol-paths += /home/alice/project/a.out ### Directory set symbol-paths += /home/me/project/build/ You can see the status of the locations you configured with the `sym-stat` command. For example: > [!NOTE] > **Note:** You can also see the build IDs and file names of the binaries added with the `sym-stat --dump-index` command. sym-stat Symbol index status This command just refreshed the index. Use "sym-stat --dump-index" to see the individual mappings. Indexed Source path 1 /home/alice/a.out 2 /home/alice/project/build/ ### ids.txt symbol index Some older internal Google projects generate a file called `ids.txt`. This file provides a mapping from a binary's build ID to the symbol path on the local system. If your build produces such a file and it is not automatically loaded, you can specify it for Zxdb with the `ids-txts` setting (a list of file names): > [!NOTE] > **Note:** `ids-txts` is a list of file names. For example, to add `/home/alice/project/build/ids.txt` to the `ids-txts` setting: set ids-txts += /home/alice/project/build/ids.txt The symbol files from `ids.txt` files is also displayed when you run the `sym-stat` or the `sym-stat --dump-index` commands. ## Symbol settings The settings described in [Understand how Zxdb loads symbols](https://fuchsia.dev/fuchsia-src/development/debugger/symbols.md.txt#understand-load-symbols) section get automatically applied by your environment. This section describes how these settings are set. The `symbol-index-files` setting contains one or more JSON-format files that are set by the development environment: get symbol-index-files symbol-index-files = • /home/alice/.fuchsia/debug/symbol-index.json This file can contain some global settings and reference other `symbol-index` files. Typically each build environment that you are actively using has a similar file that is referenced from this global file. If you are switching between build environments and notice that symbols aren't loading, make sure that your environment is registered with the `ffx debug symbol-index list` command. [](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/debugger/symbols.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/debugger/symbols.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/debugger/symbols.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/debugger/symbols.md "Edit the source code of this page")