From fe50479c32909987fa75e50ceb7446160aceae79 Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Thu, 18 Jul 2024 14:23:23 +0200 Subject: [PATCH] doc: Document the stack-trace and abort-debug modules. * doc/stack-trace.texi: New file. * doc/gnulib.texi (Particular Modules): Include it. --- ChangeLog | 6 ++++ doc/gnulib.texi | 3 ++ doc/stack-trace.texi | 67 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 76 insertions(+) create mode 100644 doc/stack-trace.texi diff --git a/ChangeLog b/ChangeLog index dbdc2e0740..69a4afdb5f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2024-07-18 Bruno Haible + + doc: Document the stack-trace and abort-debug modules. + * doc/stack-trace.texi: New file. + * doc/gnulib.texi (Particular Modules): Include it. + 2024-07-18 Bruno Haible stdlib: Don't define print_stack_trace unconditionally. diff --git a/doc/gnulib.texi b/doc/gnulib.texi index b6ce2c653d..d67caa6660 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -7156,6 +7156,7 @@ to POSIX that it can be treated like any other Unix-like platform. * Closed standard fds:: * Handling strings with NUL characters:: * Container data types:: +* Stack traces:: * Recognizing Option Arguments:: * Quoting:: * progname and getprogname:: @@ -7197,6 +7198,8 @@ to POSIX that it can be treated like any other Unix-like platform. @include containers.texi +@include stack-trace.texi + @include argmatch.texi @include quote.texi diff --git a/doc/stack-trace.texi b/doc/stack-trace.texi new file mode 100644 index 0000000000..e7fc453d88 --- /dev/null +++ b/doc/stack-trace.texi @@ -0,0 +1,67 @@ +@node Stack traces +@section Stack traces + +@c Copyright (C) 2024 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.3 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +@c copy of the license is at . + +@c Written by Bruno Haible. + +Printing a stack trace +was traditionally seen as a feature of the debugging environment +and thus only implemented in the debuggers (@command{gdb} etc.). +However, they are also useful in production code, +for use in two circumstances: +@itemize +@item +When a problem occurs on a user's machine, +when the user is merely a user, not a programmer. +@item +In unit tests that run in continuous-integration environments. +In such environments, the virtual machine is discarded +immediately after the tests have run. +It is not possible to run a debugger in such environments. +@end itemize +@noindent +And in fact, printing a stack trace is part of the basic runtime system +in programming languages such as +Java (@url{https://docs.oracle.com/javase/8/docs/api/java/lang/Throwable.html#printStackTrace--, printStackTrace method}), +Python (@url{https://docs.python.org/3/library/traceback.html, print_exception method}), +Go (@url{https://pkg.go.dev/runtime/debug#PrintStack, PrintStack function}), +and +ISO C++ 23 (@url{https://en.cppreference.com/w/cpp/utility/basic_stacktrace, std::stacktrace class}). + +Gnulib provides a module @samp{stack-trace} with this feature: +@code{print_stack_trace ()} +prints a stack trace of the current thread to standard error. + +For it to work best, three requirements need to be met: +@itemize +@item +The @url{https://github.com/ianlancetaylor/libbacktrace, libbacktrace library} +or GCC's sanitizer library @code{libasan} needs to be installed. +@item +The program needs to be compiled with debugging information (option @code{-g}). +@item +On macOS, where debugging information +is stored in a separate directory rather than in the compiled binary +(see @url{https://stackoverflow.com/questions/10044697/#12827463}), +the @code{dsymutil} program needs to be used when linking, +and the debugging information needs to be copied when the program is installed. +Cf. @url{https://github.com/ianlancetaylor/libbacktrace/issues/122#issuecomment-2122589147}. +@end itemize + +When these requirements are not met, the function @code{print_stack_trace ()} +either prints a stack trace without source file names and line numbers, +or prints nothing at all. + +Gnulib also provides a module @samp{abort-debug}, +that overrides the @code{abort} function so that +it prints the stack trace of the current thread, before actually aborting. +Thus, @code{abort ()} remains the idiom of choice +for signaling a fatal situation that requires developer attention: +it is useful both in debugging environments and production code. -- 2.39.5