docs/development/debugger/symbols.md - fuchsia - Git at Google

 # 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**.

 Note: If you are using macOS, you have to install `readelf`.

 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
	# 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.

	Note: If you are using macOS, you have to install `readelf`.

	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