[committed] libstdc++: Improve documentation on debugging with libstdc++

[committed] libstdc++: Improve documentation on debugging with libstdc++

[Jonathan Wakely]

Pushed to trunk.

-- >8 --

libstdc++-v3/ChangeLog:

	* doc/xml/manual/debug.xml: Improve docs on debug builds and
	using ASan. Mention _GLIBCXX_ASSERTIONS. Reorder sections to put
	the most relevant ones first.
	* doc/xml/manual/using.xml: Add comma.
	* doc/html/*: Regenerate.
---
 libstdc++-v3/doc/html/index.html              |  2 +-
 libstdc++-v3/doc/html/manual/debug.html       | 75 +++++++++------
 .../doc/html/manual/ext_compile_checks.html   | 18 ++--
 libstdc++-v3/doc/html/manual/index.html       |  2 +-
 libstdc++-v3/doc/html/manual/intro.html       |  2 +-
 libstdc++-v3/doc/html/manual/using.html       |  2 +-
 .../doc/html/manual/using_macros.html         |  2 +-
 libstdc++-v3/doc/xml/manual/debug.xml         | 95 +++++++++++--------
 libstdc++-v3/doc/xml/manual/using.xml         |  2 +-
 9 files changed, 120 insertions(+), 80 deletions(-)

diff --git a/libstdc++-v3/doc/xml/manual/debug.xml b/libstdc++-v3/doc/xml/manual/debug.xml
index 7f6d0876fc6..23dbae5e521 100644
--- a/libstdc++-v3/doc/xml/manual/debug.xml
+++ b/libstdc++-v3/doc/xml/manual/debug.xml
@@ -30,7 +30,7 @@
     flags can be varied to change debugging characteristics. For
     instance, turning off all optimization via the <code>-g -O0
     -fno-inline</code> flags will disable inlining and optimizations,
-    and add debugging information, so that stepping through all functions,
+    and include debugging information, so that stepping through all functions,
     (including inlined constructors and destructors) is possible. In
     addition, <code>-fno-eliminate-unused-debug-types</code> can be
     used when additional debug information, such as nested class info,
@@ -55,41 +55,30 @@
 </para>
 </section>
 
-<section xml:id="debug.req"><info><title>Debug Versions of Library Binary Files</title></info>
-
+<section xml:id="debug.debug_mode"><info><title>Debug Mode</title></info>
 
 <para>
-  If you would like debug symbols in libstdc++, there are two ways to
-  build libstdc++ with debug flags. The first is to create a separate
-  debug build by running make from the top-level of a tree
-  freshly-configured with
-</para>
-<programlisting>
-     --enable-libstdcxx-debug
-</programlisting>
-<para>and perhaps</para>
-<programlisting>
-     --enable-libstdcxx-debug-flags='...'
-</programlisting>
-<para>
-  Both the normal build and the debug build will persist, without
-  having to specify <code>CXXFLAGS</code>, and the debug library will
-  be installed in a separate directory tree, in <code>(prefix)/lib/debug</code>.
-  For more information, look at the
-  <link linkend="manual.intro.setup.configure">configuration</link> section.
+  The <link linkend="manual.ext.debug_mode">Debug Mode</link>
+  has compile and run-time checks for many containers.
 </para>
 
 <para>
-  A second approach is to use the configuration flags
+  There are also lightweight assertions for checking function preconditions,
+  such as checking for out-of-bounds indices when accessing a
+  <classname>std::vector</classname>. These can be enabled without using
+  the full Debug Mode, by using <option>-D_GLIBCXX_ASSERTIONS</option>
+  (see <xref linkend="manual.intro.using.macros"/>).
 </para>
-<programlisting>
-     make CXXFLAGS='-g3 -fno-inline -O0' all
-</programlisting>
+
+</section>
+
+<section xml:id="debug.exceptions"><info><title>Tracking uncaught exceptions</title></info>
 
 <para>
-  This quick and dirty approach is often sufficient for quick
-  debugging tasks, when you cannot or don't want to recompile your
-  application to use the <link linkend="manual.ext.debug_mode">debug mode</link>.</para>
+  The <link linkend="support.termination.verbose">verbose
+  termination handler</link> gives information about uncaught
+  exceptions which kill the program.
+</para>
 </section>
 
 <section xml:id="debug.memory"><info><title>Memory Leak Hunting</title></info>
@@ -99,6 +88,13 @@
   which is enabled by the <option>-fsanitize=address</option> option.
 </para>
 
+<para>
+  The <classname>std::vector</classname> implementation has additional
+  instrumentation to work with AddressSanitizer, but this has to be enabled
+  explicitly by using <option>-D_GLIBCXX_SANITIZE_VECTOR</option>
+  (see <xref linkend="manual.intro.using.macros"/>).
+</para>
+
 <para>
   There are also various third party memory tracing and debug utilities
   that can be used to provide detailed memory allocation information
@@ -331,21 +327,44 @@
 
 </section>
 
-<section xml:id="debug.exceptions"><info><title>Tracking uncaught exceptions</title></info>
+<section xml:id="debug.req"><info><title>Debug Versions of Library Binary Files</title></info>
 
 <para>
-  The <link linkend="support.termination.verbose">verbose
-  termination handler</link> gives information about uncaught
-  exceptions which kill the program.
+  As described above, libstdc++ is built with debug symbols enabled by default,
+  but because it's also built with optimizations the code can be hard to
+  follow when stepping into the library in a debugger.
 </para>
+
+<para>
+  If you would like to debug <filename>libstdc++.so</filename> itself,
+  there are two ways to build an unoptimized libstdc++ with debug flags.
+  The first is to create a separate debug build by running make from the
+  top-level of a tree freshly-configured with
+</para>
+<programlisting>
+     --enable-libstdcxx-debug
+</programlisting>
+<para>and perhaps</para>
+<programlisting>
+     --enable-libstdcxx-debug-flags='...'
+</programlisting>
+<para>
+  Both the normal build and the debug build will persist, without
+  having to specify <code>CXXFLAGS</code>, and the debug library will
+  be installed in a separate directory tree, in <code>(prefix)/lib/debug</code>.
+  For more information, look at the
+  <link linkend="manual.intro.setup.configure">configuration</link> section.
+</para>
+
+<para>
+  A second approach is to use the configuration flags
+</para>
+<programlisting>
+     make CXXFLAGS='-g3 -fno-inline -O0' all
+</programlisting>
+
 </section>
 
-<section xml:id="debug.debug_mode"><info><title>Debug Mode</title></info>
-
-  <para> The <link linkend="manual.ext.debug_mode">Debug Mode</link>
-  has compile and run-time checks for many containers.
-  </para>
-</section>
 
 <section xml:id="debug.compile_time_checks"><info><title>Compile Time Checking</title></info>
 
diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml
index b3b0c368e44..8ac7e74034c 100644
--- a/libstdc++-v3/doc/xml/manual/using.xml
+++ b/libstdc++-v3/doc/xml/manual/using.xml
@@ -1341,7 +1341,7 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
         or <classname>malloc_allocator</classname></link>. The annotations
         must be present on all vector operations or none, so this macro must
         be defined to the same value for all translation units that create,
-        destroy or modify vectors.
+        destroy, or modify vectors.
       </para>
     </listitem></varlistentry>
     </variablelist>
-- 
2.44.0