Debugging with GDB: Index Files

Next: Symbol Errors, Previous: MiniDebugInfo, Up: GDB Files [Contents][Index]

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

For convenience, GDB comes with a program, `gdb-add-index`, which can be used to add the index to a symbol file. It takes the symbol file as its only argument:

    $ gdb-add-index symfile

See gdb-add-index.

It is also possible to do the work manually. Here is what `gdb-add-index` does behind the curtains.

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 [-dwarf-5] directory`

  Create index files for all symbol files currently known by GDB. For each known symbol-file, this command by default creates it produces a single file `symbol-file.gdb-index`. If you invoke this command with the `-dwarf-5` option, it produces 2 files: `symbol-file.debug_names` and `symbol-file.debug_str`. The files are created in 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

Or for `-dwarf-5`:

    $ objcopy --dump-section .debug_str=symfile.debug_str.new symfile
    $ cat symfile.debug_str >>symfile.debug_str.new
    $ objcopy --add-section .debug_names=symfile.gdb-index \
        --set-section-flags .debug_names=readonly \
        --update-section .debug_str=symfile.debug_str.new 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.

Next: Symbol Errors, Previous: MiniDebugInfo, Up: GDB Files [Contents][Index]