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
