deal.II GDB documentation
Author: the deal.II authors
Keywords: deal dealii finite elements fem triangulation

# Configuration for debugging deal.II projects via GDB

deal.II comes with a simple set of pretty-printers that provide descriptions to GDB (the GNU debugger) on how to usefully print deal.II objects. For example, without pretty-printing, GDB prints points as

    (gdb) print point
    $1 = {<dealii::Tensor<1, 2, double>> = {static dimension = <optimized out>,
    static rank = <optimized out>, static n_independent_components = <optimized out>, values = {{
    static dimension = <optimized out>, static rank = <optimized out>,
    static n_independent_components = <optimized out>, value = 0}, {
    static dimension = <optimized out>, static rank = <optimized out>,
    static n_independent_components = <optimized out>, value = 0}}}, <No data fields>}

but with pretty-printing enabled GDB prints

    (gdb) print point
    $1 = {0, 0}

which is much easier to read.

## Setting up GDB for just deal.II

If you only plan on using GDB with deal.II then it suffices to rename the provided GDB pretty-printing file and place it in your home directory. This can be done with the following shell commands (where `dealii_source_directory` is the root directory containing all deal.II source files):

    cd dealii_source_directory
    cp contrib/utilities/dotgdbinit.py ~/.gdbinit

## Setting up GDB for deal.II and other sets of printers

Configuring GDB to use multiple sets of pretty-printers (i.e., sets of pretty-printers from deal.II as well as other projects) takes a little more work. The recommended procedure is

1. Decide on a directory where you will place all of your pretty-printing files. A good choice would be creating a new folder `.gdbscripts` in your home directory, and this is the choice assumed for the rest of this demonstration.
2. Move the Python source code parts (so everything after, and not including, the line containing just the word `python` near the beginning up to (and also not including) the line containing just the word `end`) of the file `contrib/utilities/dotgdbinit.py` into the directory from the first step. Rename this file to `deal.py` so that we can import it into the principal GDB configuration file in the next step.
3. Add the following to your `.gdbinit` file, which also resides in your home directory:

       set print pretty 1

       python

       import os
       import sys
       sys.path.append(os.path.expanduser("~/.gdbscripts/"))
       import deal

       end

   The statements between `python` and `end` are executed as python code by GDB. The line

       import deal

   executes the code necessary to enable the deal.II pretty-printers (it loads the file created in the last step).

Use a similar procedure on other pretty-printing files (which should also be located in `.gdbscripts/`) to set up any other pretty-printing code.