From patchwork Wed Mar 13 23:52:41 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 1911932 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=On78+Gsn; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=gcc.gnu.org (client-ip=8.43.85.97; helo=server2.sourceware.org; envelope-from=gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=patchwork.ozlabs.org) Received: from server2.sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4Tw6mh1TJrz1yWt for ; Thu, 14 Mar 2024 10:54:12 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 2B33A385781D for ; Wed, 13 Mar 2024 23:54:10 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id B0B733857B89 for ; Wed, 13 Mar 2024 23:53:28 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org B0B733857B89 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org B0B733857B89 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1710374010; cv=none; b=oXp/DVLE5oVJEyVGfEWXDQIpveVoRqCXfmS3oS8HctyMP+rLj0r65cIHQk1D92z76UEq1b7YEbPy7EXVGNjvEx+X29xT4bzZFfDjhpRvc/JZwRTDo2GZ0jQFEa32ujjc/pknTBj/BjSPkXEW4ZwNOmSUvnPDYB66COrwEdeO8QI= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1710374010; c=relaxed/simple; bh=BYEmCn7egobbk6BarnQw307XhQ3XdqkQIRRhGNcdbC0=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=T8ZkVB1iMujMc6yp0ahtkQmYeninebL982mAH8cGo41/qM9Tkcoz8PnCOYWKKhM9tY/vm69EiHq0crB3rqkT1Blz3S6AxKbI0qcgdF4CNDlnn+LRQRIged96tedcwF2K8A9rDDQqYCy8zQ2p81vDf6lVs9UnZvc2DvVgwP7Lck8= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1710374008; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=jotbVs14PHD87Lzzmx/tAuDdb2dSVSM08mdJLfEpGRw=; b=On78+GsnNT1a1M7HeHPoAf/cFQSMHPbQFgoKuzEk89AyZUEEVRvQOuyRa1fWloyA/nKqxg kc0ClSOPzFkHYCn+ROGX7EmgjLpjfrEDHc04zE9ovOcCKkd3gH/qpRLu9PMz9BGqhy7ohd pSdjmPz34IxlRJbYCRp08A9Tz6SumZE= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-63-hD_DoQVaM3-NXjgXsWBh5w-1; Wed, 13 Mar 2024 19:53:16 -0400 X-MC-Unique: hD_DoQVaM3-NXjgXsWBh5w-1 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 0745C1C07580; Wed, 13 Mar 2024 23:53:16 +0000 (UTC) Received: from localhost (unknown [10.42.28.8]) by smtp.corp.redhat.com (Postfix) with ESMTP id C8B2A492BD0; Wed, 13 Mar 2024 23:53:15 +0000 (UTC) From: Jonathan Wakely To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed] libstdc++: Improve documentation on debugging with libstdc++ Date: Wed, 13 Mar 2024 23:52:41 +0000 Message-ID: <20240313235315.2594115-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.10 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.6 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org 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 -g -O0 -fno-inline 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, -fno-eliminate-unused-debug-types can be used when additional debug information, such as nested class info, @@ -55,41 +55,30 @@ -
Debug Versions of Library Binary Files - +
Debug Mode - 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 - - - --enable-libstdcxx-debug - -and perhaps - - --enable-libstdcxx-debug-flags='...' - - - Both the normal build and the debug build will persist, without - having to specify CXXFLAGS, and the debug library will - be installed in a separate directory tree, in (prefix)/lib/debug. - For more information, look at the - configuration section. + The Debug Mode + has compile and run-time checks for many containers. - 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 + std::vector. These can be enabled without using + the full Debug Mode, by using + (see ). - - make CXXFLAGS='-g3 -fno-inline -O0' all - + +
+ +
Tracking uncaught exceptions - 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 debug mode. + The verbose + termination handler gives information about uncaught + exceptions which kill the program. +
Memory Leak Hunting @@ -99,6 +88,13 @@ which is enabled by the option. + + The std::vector implementation has additional + instrumentation to work with AddressSanitizer, but this has to be enabled + explicitly by using + (see ). + + 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 @@
-
Tracking uncaught exceptions +
Debug Versions of Library Binary Files - The verbose - termination handler 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. + + + If you would like to debug libstdc++.so 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 + + + --enable-libstdcxx-debug + +and perhaps + + --enable-libstdcxx-debug-flags='...' + + + Both the normal build and the debug build will persist, without + having to specify CXXFLAGS, and the debug library will + be installed in a separate directory tree, in (prefix)/lib/debug. + For more information, look at the + configuration section. + + + + A second approach is to use the configuration flags + + + make CXXFLAGS='-g3 -fno-inline -O0' all + +
-
Debug Mode - - The Debug Mode - has compile and run-time checks for many containers. - -
Compile Time Checking 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 malloc_allocator. 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.