27.6.5.1 GDB User Interface Layout

If the variable gdb-many-windows is nil (the default), M-x gdb normally displays only the GUD interaction buffer. However, if the variable gdb-show-main is also non- nil, it starts with two windows: one displaying the GUD interaction buffer, and the other showing the source for the main function of the program you are debugging.

If gdb-many-windows is non- nil, then M-x gdb displays the following frame layout:

+--------------------------------+--------------------------------+
|   GUD interaction buffer       |   Locals/Registers buffer      |
|--------------------------------+--------------------------------+
|   Primary Source buffer        |   I/O buffer for debugged pgm  |
|--------------------------------+--------------------------------+
|   Stack buffer                 |   Breakpoints/Threads buffer   |
+--------------------------------+--------------------------------+

You can customize the window layout based on the one above and save that layout to a file using gdb-save-window-configuration. Then you can later load this layout back using gdb-load-window-configuration. (Internally, Emacs uses the term window configuration instead of window layout.) You can set your custom layout as the default one used by gdb-many-windows by customizing gdb-default-window-configuration-file. If it is not an absolute file name, GDB looks under gdb-window-configuration-directory for the file. gdb-window-configuration-directory defaults to user-emacs-directory (see How Emacs Finds Your Init File).

If you ever change the window layout, you can restore the default layout by typing M-x gdb-restore-windows. To toggle between the many windows layout and a simple layout with just the GUD interaction buffer and a source file, type M-x gdb-many-windows.

If you have an elaborate window setup, and don’t want gdb-many-windows to disrupt that, it is better to invoke M-x gdb in a separate frame to begin with, then the arrangement of windows on your original frame will not be affected. A separate frame for GDB sessions can come in especially handy if you work on a text-mode terminal, where the screen estate for windows could be at a premium. If you choose to start GDB in the same frame, consider setting gdb-restore-window-configuration-after-quit to a non- nil value. Your original layout will then be restored after GDB quits. Use t to always restore; use if-gdb-many-windows to restore only when gdb-many-windows is non- nil; use if-gdb-show-main to restore only when gdb-show-main is non- nil.

You may also specify additional GDB-related buffers to display, either in the same frame or a different one. Select the buffers you want by typing M-x gdb-display-buffertype-buffer or M-x gdb-frame-buffertype-buffer, where buffertype is the relevant buffer type, such as ‘ breakpoints’. You can do the same with the menu bar, with the ‘ GDB-Windows’ and ‘ GDB-Frames’ sub-menus of the ‘ GUD’ menu.

By default, GDB uses at most one window to display the source file. You can make it use more windows by customizing gdb-max-source-window-count. You can also customize gdb-display-source-buffer-action to control how GDB displays source files.

When you finish debugging, kill the GUD interaction buffer with C-x k, which will also kill all the buffers associated with the session. However you need not do this if, after editing and re-compiling your source code within Emacs, you wish to continue debugging. When you restart execution, GDB automatically finds the new executable. Keeping the GUD interaction buffer has the advantage of keeping the shell history as well as GDB’s breakpoints. You do need to check that the breakpoints in recently edited source files are still in the right places.