18.5 Index Files Speed Up GDB

When GDB finds a symbol file, it scans the symbols in the file in order to construct an internal symbol table. This lets most GDB operations work quickly—at the cost of a delay early on. For large programs, this delay can be quite lengthy, so GDB provides a way to build an index, which speeds up startup.

The index is stored as a section in the symbol file. GDB can write the index to a file, then you can put it into the symbol file using objcopy.

To create an index file, use the save gdb-index command:

save gdb-index directory

Create an index file for each symbol file currently known by GDB. Each file is named after its corresponding symbol file, with ‘.gdb-index’ appended, and is written into the given directory.

Once you have created an index file you can merge it into your symbol file, here named symfile, using objcopy:

$ objcopy --add-section .gdb_index=symfile.gdb-index \
    --set-section-flags .gdb_index=readonly symfile symfile

GDB will normally ignore older versions of .gdb_index sections that have been deprecated. Usually they are deprecated because they are missing a new feature or have performance issues. To tell GDB to use a deprecated index section anyway specify set use-deprecated-index-sections on. The default is off. This can speed up startup, but may result in some functionality being lost. See Index Section Format.

Warning: Setting use-deprecated-index-sections to on must be done before gdb reads the file. The following will not work:

$ gdb -ex "set use-deprecated-index-sections on" <program>

Instead you must do, for example,

$ gdb -iex "set use-deprecated-index-sections on" <program>

There are currently some limitation on indices. They only work when for DWARF debugging information, not stabs. And, they do not currently work for programs using Ada.