Next: Algorithms, Previous: Summary, Up: Top

## 2 Overall Structure

gdb consists of three major subsystems: user interface, symbol handling (the symbol side), and target system handling (the target side).

The user interface consists of several actual interfaces, plus supporting code.

The symbol side consists of object file readers, debugging info interpreters, symbol table management, source language expression parsing, type and value printing.

The target side consists of execution control, stack frame analysis, and physical target manipulation.

The target side/symbol side division is not formal, and there are a number of exceptions. For instance, core file support involves symbolic elements (the basic core file reader is in BFD) and target elements (it supplies the contents of memory and the values of registers). Instead, this division is useful for understanding how the minor subsystems should fit together.

### 2.1 The Symbol Side

The symbolic side of gdb can be thought of as “everything you can do in gdb without having a live program running”. For instance, you can look at the types of variables, and evaluate many kinds of expressions.

### 2.2 The Target Side

The target side of gdb is the “bits and bytes manipulator”. Although it may make reference to symbolic info here and there, most of the target side will run with only a stripped executable available—or even no executable at all, in remote debugging cases.

Operations such as disassembly, stack frame crawls, and register display, are able to work with no symbolic info at all. In some cases, such as disassembly, gdb will use symbolic info to present addresses relative to symbols rather than as raw numbers, but it will work either way.

### 2.3 Configurations

Host refers to attributes of the system where gdb runs. Target refers to the system where the program being debugged executes. In most cases they are the same machine, in which case a third type of Native attributes come into play.

Defines and include files needed to build on the host are host support. Examples are tty support, system defined types, host byte order, host float format. These are all calculated by `autoconf` when the debugger is built.

Defines and information needed to handle the target format are target dependent. Examples are the stack frame format, instruction set, breakpoint instruction, registers, and how to set up and tear down the stack to call a function.

Information that is only needed when the host and target are the same, is native dependent. One example is Unix child process support; if the host and target are not the same, calling `fork` to start the target process is a bad idea. The various macros needed for finding the registers in the `upage`, running `ptrace`, and such are all in the native-dependent files.

Another example of native-dependent code is support for features that are really part of the target environment, but which require `#include` files that are only available on the host system. Core file handling and `setjmp` handling are two common cases.

When you want to make gdb work as the traditional native debugger on a system, you will need to supply both target and native information.

### 2.4 Source Tree Structure

The gdb source directory has a mostly flat structure—there are only a few subdirectories. A file's name usually gives a hint as to what it does; for example, `stabsread.c` reads stabs, `dwarf2read.c` reads DWARF 2, etc.

Files that are related to some common task have names that share common substrings. For example, `*-thread.c` files deal with debugging threads on various platforms; `*read.c` files deal with reading various kinds of symbol and object files; `inf*.c` files deal with direct control of the inferior program (gdb parlance for the program being debugged).

There are several dozens of files in the `*-tdep.c` family. ‘`tdep`’ stands for target-dependent code—each of these files implements debug support for a specific target architecture (sparc, mips, etc). Usually, only one of these will be used in a specific gdb configuration (sometimes two, closely related).

Similarly, there are many `*-nat.c` files, each one for native debugging on a specific system (e.g., `sparc-linux-nat.c` is for native debugging of Sparc machines running the Linux kernel).

The few subdirectories of the source tree are:

`cli`
  Code that implements CLI, the gdb Command-Line Interpreter. See Command Interpreter.
`gdbserver`
  Code for the gdb remote server.
`gdbtk`
  Code for Insight, the gdb TK-based GUI front-end.
`mi`
  The GDB/MI, the gdb Machine Interface interpreter.
`signals`
  Target signal translation code.
`tui`
  Code for TUI, the gdb Text-mode full-screen User Interface. See TUI.