]> Savannah Git Hosting - gnulib.git/commitdiff
doc: Document the stack-trace and abort-debug modules.
authorBruno Haible <bruno@clisp.org>
Thu, 18 Jul 2024 12:23:23 +0000 (14:23 +0200)
committerBruno Haible <bruno@clisp.org>
Thu, 18 Jul 2024 12:23:23 +0000 (14:23 +0200)
* doc/stack-trace.texi: New file.
* doc/gnulib.texi (Particular Modules): Include it.

ChangeLog
doc/gnulib.texi
doc/stack-trace.texi [new file with mode: 0644]

index dbdc2e0740b11bd39437d2ec9463e6051d20a111..69a4afdb5f442fa684f676d0c875e83dedc22c9f 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2024-07-18  Bruno Haible  <bruno@clisp.org>
+
+       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  <bruno@clisp.org>
 
        stdlib: Don't define print_stack_trace unconditionally.
index b6ce2c653d7be1d12875d0615e60860d8b718422..d67caa666084f1bc3e4ecd2676202bbe7f42ac17 100644 (file)
@@ -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 (file)
index 0000000..e7fc453
--- /dev/null
@@ -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 <https://www.gnu.org/licenses/fdl-1.3.en.html>.
+
+@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.