From 654bff9a8c0adc3ad869d2ca1f8ab243092a570d Mon Sep 17 00:00:00 2001
From: David Wells
Date: Fri, 11 Sep 2015 14:28:50 -0400
Subject: [PATCH] Added documentation describing our GDB support.
---
README.md | 4 ++
contrib/utilities/dotgdbinit.py | 6 ++-
doc/documentation.html | 1 +
doc/readme.html | 5 +-
doc/users/gdb.html | 96 +++++++++++++++++++++++++++++++++
5 files changed, 110 insertions(+), 2 deletions(-)
create mode 100644 doc/users/gdb.html
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 @@
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.
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
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):
+
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
+
+
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.
+
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.
+
Add the following to your .gdbinit file, which also
+ resides in your home directory:
+
+ 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.
+
+
+