Missing Debug Info In Python (Debugging with GDB)

#### 23.3.2.41 Missing Debug Info In Python ¶

When GDB encounters a new objfile (see Objfiles In Python), e.g. the primary executable, or any shared libraries used by the inferior, GDB will attempt to load the corresponding debug information for that objfile. The debug information might be found within the objfile itself, or within a separate objfile which GDB will automatically locate and load.

Sometimes though, GDB might not find any debug information for an objfile, in this case the debugging experience will be restricted.

If GDB fails to locate any debug information for a particular objfile, there is an opportunity for a Python extension to step in. A Python extension can potentially locate the missing debug information using some platform- or project-specific steps, and inform GDB of its location. Or a Python extension might provide some platform- or project-specific advice to the user about how to obtain the missing debug information.

A missing debug information Python extension consists of a handler object which has the `name` and `enabled` attributes, and implements the `__call__` method. When GDB encounters an objfile for which it is unable to find any debug information, it invokes the `__call__` method. Full details of how handlers are written can be found below.

#### The `gdb.missing_debug` Module ¶

GDB comes with a `gdb.missing_debug` module which contains the following class and global function:

class: gdb.missing_debug.MissingDebugHandler ¶

  `MissingDebugHandler` is a base class from which user-created handlers can derive, though it is not required that handlers derive from this class, so long as any user created handler has the `name` and `enabled` attributes, and implements the `__call__` method.

  Function: MissingDebugHandler.__init__ (name) ¶

    The name is a string used to reference this missing debug handler within some GDB commands. Valid names consist of the characters `[-_a-zA-Z0-9]`, creating a handler with an invalid name raises a `ValueError` exception.

  Function: MissingDebugHandler.__call__ (objfile) ¶

    Sub-classes must override the `__call__` method. The objfile argument will be a `gdb.Objfile`, this is the objfile for which GDB was unable to find any debug information.

    The return value from the `__call__` method indicates what GDB should do next. The possible return values are:

    - `None`

      This indicates that this handler could not help with objfile, GDB should call any other registered handlers.

    - `True`

      This indicates that this handler has installed the debug information into a location where GDB would normally expect to find it when looking for separate debug information files (see Debugging Information in Separate Files). GDB will repeat the normal lookup process, which should now find the separate debug file.

      If GDB still doesn’t find the separate debug information file after this second attempt, then the Python missing debug information handlers are not invoked a second time, this prevents a badly behaved handler causing GDB to get stuck in a loop. GDB will continue without any debug information for objfile.

    - `False`

      This indicates that this handler has done everything that it intends to do with objfile, but no separate debug information can be found. GDB will not call any other registered handlers for objfile. GDB will continue without debugging information for objfile.

    - A string

      The returned string should contain a filename. GDB will not call any further registered handlers, and will instead load the debug information from the file identified by the returned filename.

    Invoking the `__call__` method from this base class will raise a `NotImplementedError` exception.

  Variable: MissingDebugHandler.name ¶

    A read-only attribute which is a string, the name of this handler passed to the `__init__` method.

  Variable: MissingDebugHandler.enabled ¶

    A modifiable attribute containing a boolean; when `True`, the handler is enabled, and will be used by GDB. When `False`, the handler has been disabled, and will not be used.

Function: gdb.missing_debug.register_handler (locus, handler, replace=`False`) ¶

  Register a new missing debug handler with GDB.

  handler is an instance of a sub-class of `MissingDebugHandler`, or at least an instance of an object that has the same attributes and methods as `MissingDebugHandler`.

  locus specifies to which handler list to prepend handler. It can be either a `gdb.Progspace` (see Program Spaces In Python) or `None`, in which case the handler is registered globally. The newly registered handler will be called before any other handler from the same locus. Two handlers in the same locus cannot have the same name, an attempt to add a handler with an already existing name raises an exception unless replace is `True`, in which case the old handler is deleted and the new handler is prepended to the selected handler list.

  GDB first calls the handlers for the current program space, and then the globally registered handlers. As soon as a handler returns a value other than `None`, no further handlers are called for this objfile.