From: David Wells Date: Fri, 11 Sep 2015 18:28:50 +0000 (-0400) Subject: Added documentation describing our GDB support. X-Git-Tag: v8.4.0-rc2~430^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=654bff9a8c0adc3ad869d2ca1f8ab243092a570d;p=dealii.git Added documentation describing our GDB support. --- diff --git a/README.md b/README.md index 20ad47423a..bd1dc1d9ec 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,10 @@ The tutorial steps are located under examples/ of the installation. Information about the tutorial steps can be found at doc/doxygen/tutorial/index.html or at http://www.dealii.org/. +deal.II includes support for pretty-printing deal.II objects inside GDB. See +`contrib/utilities/dotgdbinit.py` or the new documentation page (under +'information for users') for instructions on how to set this up. + License: -------- diff --git a/contrib/utilities/dotgdbinit.py b/contrib/utilities/dotgdbinit.py index 56786a78aa..ff0a049663 100644 --- a/contrib/utilities/dotgdbinit.py +++ b/contrib/utilities/dotgdbinit.py @@ -15,7 +15,11 @@ # # Instructions: Place a copy of this file, renamed as ".gdbinit", in your home -# directory to enable pretty-printing of various deal.II objects. +# directory to enable pretty-printing of various deal.II objects. If you already +# have a ".gdbinit" file or would like to manage multiple sets of pretty +# printers, then see the directions included in the Documentation, in the +# "Configuration for debugging via GDB" section in the "Information for users" +# category. # # This has only been tested with GDB 7.7.1 and newer, but it should work with # slightly older versions of GDB (the Python interface was added in 7.0, diff --git a/doc/documentation.html b/doc/documentation.html index b61fb7f41a..e70238aaf0 100644 --- a/doc/documentation.html +++ b/doc/documentation.html @@ -31,6 +31,7 @@
  • CMake documentation
  • CMake in user projects
  • Setting up testsuite in user projects
  • +
  • Configuration for debugging via GDB
  • Tutorial
  • Manual
  • Wolfgang's lectures
  • diff --git a/doc/readme.html b/doc/readme.html index fdd4d5f14b..393ce342fa 100644 --- a/doc/readme.html +++ b/doc/readme.html @@ -119,7 +119,10 @@ for it. Most integrated development environments like kdevelop or Eclipse have built - in debuggers as well. + in debuggers as well. deal.II has some support for + pretty printing its own classes through GDB; + see the GDB configuration guide for + setup information.
  • diff --git a/doc/users/gdb.html b/doc/users/gdb.html new file mode 100644 index 0000000000..2ab1f4ae15 --- /dev/null +++ b/doc/users/gdb.html @@ -0,0 +1,96 @@ + + + + + deal.II GDB documentation + + + + + + + + +

    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 master GDB 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 .gdbfiles/) to set up any other pretty + printing code. +

    +
    +
    + + Valid HTML 4.01! + + Valid CSS! +
    + + +