| # Understand how symbols are loaded {:#understand-load-symbols} | |
| 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][troubleshoot-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: | |
| ```none {:.devsite-disable-click-to-copy} | |
| $ 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 {#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][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: | |
| ```none {: .devsite-terminal data-terminal-prefix="[zxdb]" } | |
| 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: | |
| ```none {:.devsite-disable-click-to-copy} | |
| ... | |
| 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: DWARF information is downloaded separately from the ELF symbols. | |
| ```none {:.devsite-disable-click-to-copy} | |
| 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: 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: These directories do not need to be named `.build-id` | |
| * {zxdb instance} | |
| Note: These `build-id-dirs` are only added for the duration of the zxdb | |
| instance. | |
| ```none {: .devsite-terminal data-terminal-prefix="[zxdb]" } | |
| set build-id-dirs += /home/alice/project/out/x64/.build-id | |
| ``` | |
| * {ffx} | |
| 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 | |
| ```posix-terminal | |
| 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: 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: 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} | |
| ```none {: .devsite-terminal data-terminal-prefix="[zxdb]" } | |
| set symbol-paths += /home/alice/project/a.out | |
| ``` | |
| * {Directory} | |
| ```none {: .devsite-terminal data-terminal-prefix="[zxdb]" } | |
| 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: You can also see the build IDs and file names of the binaries added with | |
| the `sym-stat --dump-index` command. | |
| ```none {: .devsite-terminal data-terminal-prefix="[zxdb]" } | |
| 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: `ids-txts` is a list of file names. | |
| For example, to add `/home/alice/project/build/ids.txt` to the `ids-txts` setting: | |
| ```none {: .devsite-terminal data-terminal-prefix="[zxdb]" } | |
| 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 {#symbol-settings} | |
| The settings described in | |
| [Understand how Zxdb loads symbols](#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: | |
| ```none {: .devsite-terminal data-terminal-prefix="[zxdb]" } | |
| 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. | |
| [advanced-download-symbols]: /docs/development/debugger/advanced.md#download-symbols | |
| [troubleshoot-symbols]: /docs/development/debugger/troubleshooting.md#diagnose-problems-symbols | |
| [ffx-symbol-index]: /reference/tools/sdk/ffx.md#symbol-index |