]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Added documentation describing our GDB support. 1582/head
authorDavid Wells <wellsd2@rpi.edu>
Fri, 11 Sep 2015 18:28:50 +0000 (14:28 -0400)
committerDavid Wells <wellsd2@rpi.edu>
Mon, 14 Sep 2015 00:25:20 +0000 (20:25 -0400)
README.md
contrib/utilities/dotgdbinit.py
doc/documentation.html
doc/readme.html
doc/users/gdb.html [new file with mode: 0644]

index 20ad47423a2d12db7cc6dd76b9044a0e2bfbd817..bd1dc1d9ec63a71f3e8aacbe12cfaef82797f8ca 100644 (file)
--- 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:
 --------
 
index 56786a78aa6cb96e5d9a4a4a832e68348e832043..ff0a04966381cd6fc8fe34ef82a3b3292bbc2e80 100644 (file)
 
 #
 # 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,
index b61fb7f41acdb2eac725c0f72dd3f614a305b2ca..e70238aaf05f4199fe4ec81f37f2b4aada237988 100644 (file)
@@ -31,6 +31,7 @@
           <li><a href="users/cmake.html" target="body">CMake documentation</a></li>
           <li><a href="users/cmakelists.html" target="body">CMake in user projects</a></li>
           <li><a href="users/testsuite.html" target="body">Setting up testsuite in user projects</a></li>
+          <li><a href="users/gdb.html" target="body">Configuration for debugging via GDB</a></li>
           <li><a href="doxygen/deal.II/Tutorial.html" target="_top">Tutorial</a></li>
           <li><a href="doxygen/deal.II/index.html" target="_top">Manual</a></li>
           <li><a href="http://www.math.tamu.edu/~bangerth/videos.html" target="_top">Wolfgang's lectures</a></li>
index fdd4d5f14bec28c19e0c5cb1a1be8b4dea6df278..393ce342fac05ec1f86081dc605efdeb735330bc 100644 (file)
            for it. Most integrated development environments
            like <a href="http://www.kdevelop.org/" target="_top">kdevelop</a>
            or <a href="http://eclipse.org/" target="_top">Eclipse</a> have built
-           in debuggers as well.
+           in debuggers as well. <acronym>deal.II</acronym> has some support for
+           pretty printing its own classes through GDB;
+           see <a href="users/gdb.html">the GDB configuration guide</a> for
+           setup information.
        </li>
 
       <li> <p>
diff --git a/doc/users/gdb.html b/doc/users/gdb.html
new file mode 100644 (file)
index 0000000..2ab1f4a
--- /dev/null
@@ -0,0 +1,96 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+          "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+  <head>
+    <meta http-equiv="Content-type" content="text/html;charset=UTF-8">
+    <title>deal.II GDB documentation</title>
+    <link href="../screen.css" rel="StyleSheet">
+    <meta name="author" content="the deal.II authors">
+    <meta name="copyright" content="Copyright (C) 2012 - 2015 by the deal.II authors">
+    <meta name="keywords" content="deal dealii finite elements fem triangulation">
+    <meta http-equiv="content-language" content="en">
+  </head>
+  <body>
+
+    <h1>Configuration for debugging deal.II projects via GDB</h1>
+
+    <p><acronym>deal.II</acronym> comes with a simple set of pretty-printers
+      that provide descriptions to GDB (the GNU debugger) on how to usefully
+      print <acronym>deal.II</acronym> objects. For example, without
+      pretty-printing, GDB prints points as</p>
+    <pre class="sample">
+(gdb) print point
+$1 = {&lt;dealii::Tensor&lt;1, 2, double&gt;&gt; = {static dimension = &lt;optimized out&gt;,
+static rank = &lt;optimized out&gt;, static n_independent_components = &lt;optimized out&gt;, values = {{
+static dimension = &lt;optimized out&gt;, static rank = &lt;optimized out&gt;,
+static n_independent_components = &lt;optimized out&gt;, value = 0}, {
+static dimension = &lt;optimized out&gt;, static rank = &lt;optimized out&gt;,
+static n_independent_components = &lt;optimized out&gt;, value = 0}}}, &lt;No data fields&gt;}</pre>
+    but with pretty-printing enabled GDB prints
+    <pre class="sample">
+(gdb) print point
+$1 = {0, 0}</pre>
+    which is much easier to read.</p>
+
+<h2>Setting up GDB for just deal.II</h2>
+<p>If you only plan on using GDB with <acronym>deal.II</acronym> 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 <code>dealii_source_directory</code> is the root directory containing
+  all <acronym>deal.II</acronym> source files):
+  <pre class="sample">
+cd dealii_source_directory
+cp contrib/utilities/dotgdbinit.py ~/.gdbinit</pre>
+</p>
+
+<h2>Setting up GDB for deal.II and other sets of printers</h2>
+<p>
+  Configuring GDB to use multiple sets of pretty printers (i.e., sets of pretty
+  printers from <acronym>deal.II</acronym> as well as other projects) takes a
+  little more work. The recommended procedure is
+  <ol>
+    <li> Decide on a directory where you will place all of your pretty printing
+      files. A good choice would be creating a new
+      folder <code>.gdbscripts</code> in your home directory, and this is the
+      choice assumed for the rest of this demonstration.
+    <li> Move the Python source code parts (so everything after, and not
+      including, the line containing just the word <code>python</code> near the
+      beginning up to (and also not including) the line containing just the
+      word <code>end</code>) of the
+      file <code>contrib/utilities/dotgdbinit.py</code> into the directory from
+      the first step. Rename this file to <code>deal.py</code> so that we can
+      import it into the master GDB file in the next step.
+    <li> Add the following to your <code>.gdbinit</code> file, which also
+      resides in your home directory:
+      <pre class="sample">
+set print pretty 1
+
+python
+
+import os
+import sys
+sys.path.append(os.path.expanduser("~/.gdbscripts/"))
+import deal
+
+end</pre>
+      The statements between <code>python</code> and <code>end</code> are
+      executed as python code by GDB. The line
+      <pre class="sample">
+import deal</pre>
+      executes the code necessary to enable the <acronym>deal.II</acronym>
+      pretty printers (it loads the file created in the last step).
+  </ol>
+  Use a similar procedure on other pretty printing files (which should
+  also be located in <code>.gdbfiles/</code>) to set up any other pretty
+  printing code.
+</p>
+<hr />
+<div class="right">
+  <a href="http://validator.w3.org/check?uri=referer" target="_top">
+    <img style="border:0" src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+  <a href="http://jigsaw.w3.org/css-validator/check/referer" target="_top">
+    <img style="border:0;width:88px;height:31px" src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+</div>
+
+</body>
+</html>

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.