Difference between revisions of "Stack Trace"

Latest revision as of 16:59, 3 October 2024

Languages	עִברִית

What is a Stack Trace?

A stack trace lists the chain of function calls leading to a point in a program's execution. Here's an example from Mac OS X; other operating systems will display the information a bit differently:

Exception Type:        EXC_CRASH (SIGABRT)
Exception Codes:       0x0000000000000000, 0x0000000000000000
 
Application Specific Information:
abort() called

Thread 0 Crashed:: Dispatch queue: com.apple.main-thread
0   libsystem_kernel.dylib        	0x9769169a __pthread_kill + 10
1   libsystem_pthread.dylib       	0x9836bf19 pthread_kill + 101
2   libsystem_c.dylib             	0x9bde5eee abort + 156
3   libglib-2.0.0.dylib           	0x02b5dd8a g_assertion_message + 346
4   libglib-2.0.0.dylib           	0x02b5e470 g_assertion_message_expr + 96
5   libgncmod-gnome-utils.dylib   	0x0029ec4a gnc_main_window_init + 2650
6   libgobject-2.0.0.dylib        	0x02ae7496 g_type_create_instance + 470
7   libgobject-2.0.0.dylib        	0x02ad51a2 g_object_new_internal + 562
8   libgobject-2.0.0.dylib        	0x02ad5a90 g_object_newv + 480
9   libgobject-2.0.0.dylib        	0x02ad5b7d g_object_new + 61
10  libgncmod-gnome-utils.dylib   	0x002a03d7 gnc_main_window_new + 39
11  libgncmod-gnome-utils.dylib   	0x0029a6f5 gnc_gui_init + 581
12  Gnucash-bin                   	0x00011387 main + 1143
13  Gnucash-bin                   	0x00010ed6 start + 54

This shows why GnuCash crashed (an assertion failed in the main window init function); without a stack trace crashes can be very difficult to diagnose. Developers will usually also ask for the Tracefile, which will often provide additional useful information. In the case above we'd find the actual assertion message that would explain the abort.

Better with Debugging Symbols

A stack trace can be obtained in several different levels of verbosity. By default, most distributions will enable only a very coarse stack trace where not much information is shown about each function. The stack trace gets much more useful if debugging symbols are available. Please try to enable them, if possible. Recent (as in the last 5 years) versions of most Linux distros provide a package called debuginfo; many install it by default. With it installed gdb will fetch the debug symbols for all of the libraries participating in the stack. If you're using an older distro and can't or don't want to upgrade, please find the debug package at least for GnuCash:

search with your package manager for the corresponding -dbg or -debug package and install it.
- If other packages like AqBanking are used, try to find and install their corresponding -dbg packages, too. If your problem is solved, you can uninstall them again.
When built locally from the sources, add -DCMAKE_BUILD_TYPE=Debug to your cmake options and redo the make process.

Optional Preparation of Scheme Code

ToDo: perhaps somewhere else is a better place for this sction.

If reports are affected, see The Guile Reference Manual: Programmatic Error Handling

How to obtain a Stack Trace

macOS

Every time an application crashes in macOS, the system writes a crash report with a stack trace to

$HOME/Library/Logs/DiagnosticReports or

$HOME/Library/Logs/CrashReporter, or

both, depending on what version of macOS you're running.

The crash reports are easily viewed with Applications:Utilities:Console, and if you're reporting a crash in Bugzilla or to the user's list you should attach one to your report.

About Debuggers

In order to get a stack trace on Linux or Windows one must have either the GNU Debugger gdb or the LLVM Debugger lldb installed.

Linux users should use their package manager to install one or the other if necessary.
Window users can download them at
- gdb: see #Windows;
- lldb: https://releases.llvm.org/download.html.

Gdb is a bit simpler to use, so the instructions below are for gdb.

Linux

Additionally, if you're using packages supplied through a linux distribution (you did not compile GnuCash yourself) you probably also need to install a debug symbol package (see below).

Many distros have adopted systemd-coredump, a feature that captures coredumps whenever there's a system crash. If it's enabled on your system (it is by default on Fedora 28 and later) you can run gdb on it and get a stack trace with

coredumpctl gdb
bt full

Otherwise, read on: Once you have installed a debugger (and symbols as needed), there are two ways to put GnuCash under the debugger's control. Starting GnuCash under the debugger is a bit more straightforward, but the debugger slows down the program quite a bit. So it might work better for you to start GnuCash as usual, get to the point where some action provokes the crash, then attach the debugger to the running GnuCash.

Starting GnuCash under gdb

run gdb gnucash

at the gdb prompt, type: "run". If you need to pass command line arguments, add them here, e.g. "run --nofile"

Example

$ gdb gnucash
GNU gdb (GDB; openSUSE Tumbleweed) 8.3.1
Copyright (C) 2019 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "x86_64-suse-linux".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://bugs.opensuse.org/>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from gnucash...
(gdb) run --nofile

Attach gdb to running process

Start gnucash normally.
In a terminal window run ps afx (some people prefer ps aux) to find out the process number (PID) of the running gnucash process; it might be called "gnucash" or "gnucash-bin". Say the PID is 12345.
Run gdb gnucash
Attach to the running process by typing attach 12345; gdb will temporarily stop the program
Continue program execution by typing c at the "(gdb)" prompt

Obtain the stack trace

Provoke the crash. When GnuCash crashes gdb will print the reason for the crash and present the "(gdb)" prompt again.
Type bt (bt full might provide additional info about local variables).
Gdb will print the backtrace.

Exit Gdb

ctrl-d or quit will end the gdb session.

Please copy and paste the error and stack trace from the terminal into a bug report; see Bugzilla for details about creating a new one if you haven't already.

You can read more about getting stack traces in Linux from Gnome Project Handbook: Stack Traces.

Windows

On Windows gdb has to be installed before you can generate a stack trace. While we provide some details below on how to do all of that we recognize this may be too challenging for the average user. If you have been asked to provide a stack trace, but you are using GnuCash on Windows only and find these instructions too daunting, please respond along the lines of

"I'm sorry, but I encountered this problem only on Windows and I am not familiar enough with gdb on Windows to obtain stack traces there"

That's a fair answer even though in many cases your bugreport can only be worked on if you or someone else can actually produce such a stack trace.

Download the MSYS2 build of gdb
Extract the archive to your user directory.
Open a Powershell window and type:
```
win32-gdb\gdb.exe "C:\Program Files\gnucash\bin\gnucash.exe"
```
Be careful to use the actual paths in which you have installed gdb and gnucash respectively.
#Obtain the stack trace with the instructions above.

You can provide even better stack traces if you tell gdb where in memory dynamically loaded modules got mapped to, because otherwise function calls into those are only written as '??'. See here and here for a way to do this.

To enter [ and ], use set editing off.

Linux debug symbol information

Gnucash needs to be compiled in a way that has the debug symbols still included in the resulting binary libraries.

Self Compiling

This is achieved using the CMake option -DCMAKE_BUILD_TYPE="Debug". See CMake and Gnucash Build Options.

Distributions

Binary Distributions

Recent ones offer Debuginfod that enables gdb to download all of the symbols it needs automatically. See your distro's documentation for how to make sure that it's installed. Otherwise they usually offer debug symbols in a separate package appending -dbg or -debug. See e.g. https://wiki.ubuntu.com/DebuggingProgramCrash and https://wiki.ubuntu.com/Backtrace.

Gentoo

When emerging gnucash on gentoo, you need to make sure that

the "debug" USE flag is enabled
and "FEATURES=nostrip" is set to disable symbol stripping.

Flatpak: It offers the symbols in a separate .Debug package via flatpak install org.gnucash.GnuCash.Debug. See Flatpak.

Tracefile

Logging

Bugzilla#Using Bugzilla

FAQ#Q: How do I run GnuCash under gdb and get a stack trace?

Difference between revisions of "Stack Trace"

Latest revision as of 16:59, 3 October 2024

Contents

What is a Stack Trace?

Better with Debugging Symbols

Optional Preparation of Scheme Code

How to obtain a Stack Trace

macOS

About Debuggers

Linux

Starting GnuCash under gdb

Attach gdb to running process

Obtain the stack trace

Exit Gdb

Windows

See also

Linux debug symbol information

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Related Sites

Contributing

Tools

@@ Line 1: / Line 1: @@
-__NOTOC__
+{| class="wikitable" style="margin: auto;"
+! scope="row"|Languages
+| [[He/{{PAGENAME:Stack_Trace}}|עִברִית]]
+|}
 == What is a Stack Trace? ==
-If GnuCash terminates abnormally (i. e. it crashes), then a ''stack trace'' is a very helpful information for the developers to figure out the program error that caused this crash.
+A stack trace lists the chain of function calls leading to a point in a program's execution. Here's an example from Mac OS X; other operating systems will display the information a bit differently: <syntaxhighlight lang="console">
+Exception Type:        EXC_CRASH (SIGABRT)
+Exception Codes:       0x0000000000000000, 0x0000000000000000
+Application Specific Information:
+abort() called
-Additionally, some interesting logging messages are written into the [[Tracefile]] at each run of GnuCash.
+Thread 0 Crashed:: Dispatch queue: com.apple.main-thread
+   libsystem_kernel.dylib        	0x9769169a __pthread_kill + 10
-=== MacOSX is Easiest ===
+   libsystem_pthread.dylib       	0x9836bf19 pthread_kill + 101
-Every time an application crashes in MacOSX, the system writes a crash report with a stack trace to <tt>$HOME/Library/Logs/DiagnosticReports</tt> or <tt>$HOME/Library/Logs/CrashReporter</tt>, or both, depending on what version of OSX you're running. The crash reports are easily viewed with <tt>Applications:Utilities:Console</tt>, and if you're reporting a crash in Bugzilla or to the user's list you should attach one to your report.
+   libsystem_c.dylib             	0x9bde5eee abort + 156
+   libglib-2.0.0.dylib           	0x02b5dd8a g_assertion_message + 346
+   libglib-2.0.0.dylib           	0x02b5e470 g_assertion_message_expr + 96
+   libgncmod-gnome-utils.dylib   	0x0029ec4a gnc_main_window_init + 2650
+   libgobject-2.0.0.dylib        	0x02ae7496 g_type_create_instance + 470
+   libgobject-2.0.0.dylib        	0x02ad51a2 g_object_new_internal + 562
+   libgobject-2.0.0.dylib        	0x02ad5a90 g_object_newv + 480
+   libgobject-2.0.0.dylib        	0x02ad5b7d g_object_new + 61
+  libgncmod-gnome-utils.dylib   	0x002a03d7 gnc_main_window_new + 39
+  libgncmod-gnome-utils.dylib   	0x0029a6f5 gnc_gui_init + 581
+  Gnucash-bin                   	0x00011387 main + 1143
+  Gnucash-bin                   	0x00010ed6 start + 54
+</syntaxhighlight>
+This shows why GnuCash crashed (an assertion failed in the main window init function); without a stack trace crashes can be very difficult to diagnose. Developers will usually also ask for the [[Tracefile]], which will often provide additional useful information. In the case above we'd find the actual assertion message that would explain the abort.
 === Better with Debugging Symbols ===
-A stack trace can be obtained in several different levels of verbosity. By default, most distributions will enable only a very coarse stack trace where not much information is shown about each of the stack levels. The stack trace gets much more useful if '''debugging symbols''' are available.  Please try to enable them, if possible. If you are running GnuCash
+A stack trace can be obtained in several different levels of verbosity. By default, most distributions will enable only a very coarse stack trace where not much information is shown about each function. The stack trace gets much more useful if '''debugging symbols''' are available.  Please try to enable them, if possible.
-* from a ''ready made package'', search with your package manager for the corresponding '''-dbg''' or -debug package and install it.
+Recent (as in the last 5 years) versions of most Linux distros provide a package called debuginfo; many install it by default. With it installed gdb will fetch the debug symbols for all of the libraries participating in the stack. If you're using an older distro and can't or don't want to upgrade, please find the debug package at least for GnuCash:
+* search with your package manager for the corresponding '''-dbg''' or '''-debug''' package and install it.
 ** If other packages like AqBanking are used, try to find and install their corresponding -dbg packages, too. If your problem is solved, you can uninstall them again.
-* ''self made'' from the sources, add '''--debug''' to your ''configure'' options and redo the make process.
+* When built locally from the sources, add '''-DCMAKE_BUILD_TYPE=Debug''' to your ''cmake'' options and redo the make process.
-=== Also on Windows? ===
+== Optional Preparation of Scheme Code ==
-However, on [[Windows]] it is currently not so easy to obtain such a stack trace. Some explanation on how to do this for experts is on [[Windows#Debugging_with_gdb]], but we are aware of the fact that this is rather difficult for the average user. If you have been asked to provide a stack trace, but you are using GnuCash on Windows only and feel too unfamiliar with gdb debugging, please respond along the lines of "I'm sorry, but I encountered this problem only on Windows and I am not familiar enough with gdb on Windows to obtain stack traces there". Thanks a lot. Nevertheless, in many cases your bugreport can only be worked on if you or someone else can actually produce such a stack trace.
+;ToDo: perhaps somewhere else is a better place for this sction.
+If reports are affected, see [{{URL:guile-manual}}Programmatic-Error-Handling.html The Guile Reference Manual: Programmatic Error Handling]
 == How to obtain a Stack Trace ==
-There are two possibilities to obtain a stack trace. You can choose either one, whichever seems easier or works better for you.
-=== Attach gdb to running process ===
+=== {{Mac}} ===
-The program "gnucash" itself is not an executable but a script. Therefore it cannot be called directly by the ''gdb'' debugger. We propose to "attach" the gdb to the running gnucash process instead.
+Every time an application crashes in {{Mac}}, the system writes a crash report with a stack trace to
+:<tt>$HOME/Library/Logs/DiagnosticReports</tt> or
+:<tt>$HOME/Library/Logs/CrashReporter</tt>, or
+:both, depending on what version of {{Mac}} you're running.
+The crash reports are easily viewed with <tt>Applications:Utilities:Console</tt>, and if you're reporting a crash in Bugzilla or to the user's list you should attach one to your report.
+=== About Debuggers ===
+In order to get a stack trace on Linux or Windows one must have either the [{{URL:Gnu}}software/gdb/ '''GNU Debugger''' gdb] or the [{{URL:llvm}} '''LLVM Debugger''' lldb] installed.
+*Linux users should use their package manager to install one or the other if necessary.
+*Window users can download them at
+** gdb: see [[#Windows]];
+** lldb: {{URL:llvm|releases.}}download.html.
+Gdb is a bit simpler to use, so the instructions below are for gdb.
+=== Linux ===
+Additionally, if you're using packages supplied through a linux distribution (you did not compile GnuCash yourself) you probably also need to install a [[#Debug_symbol_information |debug symbol package (see below)]].
+Many distros have adopted <code>systemd-coredump</code>, a feature that captures coredumps whenever there's a system crash. If it's enabled on your system (it is by default on Fedora 28 and later) you can run gdb on it and get a stack trace with <syntaxhighlight lang="sh">
+coredumpctl gdb
+bt full
+</syntaxhighlight>
+Otherwise, read on:
+Once you have installed a debugger (and symbols as needed), there are two ways to put GnuCash under the debugger's control. Starting GnuCash under the debugger is a bit more straightforward, but the debugger slows down the program quite a bit. So it might work better for you to start GnuCash as usual, get to the point where some action provokes the crash, then attach the debugger to the running GnuCash.
+==== Starting GnuCash under gdb ====
+# run <tt>gdb gnucash</tt>
+# at the ''gdb'' prompt, type: "run". If you need to pass '''command line arguments''', add them here, e.g. "run --nofile"
+#;Example:<syntaxhighlight lang="console">
+$ gdb gnucash
+GNU gdb (GDB; openSUSE Tumbleweed) 8.3.1
+Copyright (C) 2019 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+Type "show copying" and "show warranty" for details.
+This GDB was configured as "x86_64-suse-linux".
+Type "show configuration" for configuration details.
+For bug reporting instructions, please see:
+<http://bugs.opensuse.org/>.
+Find the GDB manual and other documentation resources online at:
+    <http://www.gnu.org/software/gdb/documentation/>.
-To attach to the running gnucash process:
+For help, type "help".
+Type "apropos word" to search for commands related to "word"...
+Reading symbols from gnucash...
+(gdb) run --nofile
+</syntaxhighlight>
-# Start gnucash normally
+==== Attach gdb to running process ====
-# Use "ps afx" (some people prefere "ps aux") to find out the process number (PID) of the running gnucash process; it might be called "gnucash" or "gnucash-bin". Say the PID is 12345.
+# Start gnucash normally.
-# Start gdb by typing "gdb"
+# In a terminal window run <tt>ps afx</tt> (some people prefer <tt>ps aux</tt>) to find out the process number (PID) of the running gnucash process; it might be called "gnucash" or "gnucash-bin". Say the PID is 12345.
-# Attach to the running process by typing "attach 12345"; gdb will temporarily stop the program
+# Run <tt>gdb gnucash</tt>
-# Continue program execution by typing "continue" at the "(gdb)" prompt
+# Attach to the running process by typing <tt>attach 12345</tt>; gdb will temporarily stop the program
-# Provoke the crash; type "backtrace" or shorthand "bt" at the gdb prompt to obtain the backtrace ("bt full" might provide additional info about local variables).
+# Continue program execution by typing <tt>c</tt> at the "(gdb)" prompt
-Please submit the backtrace together with the instructions on how to reproduce this crash as a new bug report into [[Bugzilla]]. Thank you for your contribution.
+==== Obtain the stack trace ====
+# Provoke the crash. When GnuCash crashes gdb will print the reason for the crash and present the "(gdb)" prompt again.
+# Type <tt>bt</tt> (<tt>bt full</tt> might provide additional info about local variables).
+# Gdb will print the backtrace.
-=== Starting GnuCash under gdb ===
+==== Exit Gdb ====
+<tt>ctrl-d</tt> or <tt>quit</tt> will end the gdb session.
-Sometimes GnuCash might crash too early in the startup sequence such that you cannot attach gdb to the running process.  In that case you can run gnucash under gdb.  This is much easier as of GnuCash 2.0.  To run GnuCash under gdb from the beginning:
+Please copy and paste the error and stack trace from the terminal into a bug report; see [[Bugzilla]] for details about creating a new one if you haven't already.
-# run "gnucash-env gdb gnucash"
+You can read more about getting stack traces in Linux from [{{URL:Gnome|handbook}}issues/stack-traces.html Gnome Project Handbook: Stack Traces].
-# at the ''gdb'' prompt, type: "run". Also add your parameters here, like "run --nofile"
-# Provoke the crash; type "backtrace" or shorthand "bt" at the gdb prompt to obtain the backtrace ("bt full" might provide additional info about local variables).
-=== See also ===
+=== Windows ===
-Other explanations on how to obtain stack traces:
+On [[Windows]] gdb has to be installed before you can generate a stack trace. While we provide some details below on how to do all of that we recognize this may be too challenging for the average user. If you have been asked to provide a stack trace, but you are using GnuCash on Windows only and find these instructions too daunting, please respond along the lines of
-* [[Windows#gdb]] for Windows-specific comments
+:"I'm sorry, but I encountered this problem only on Windows and I am not familiar enough with gdb on Windows to obtain stack traces there"
-* http://live.gnome.org/GettingTraces
+That's a fair answer even though in many cases your bugreport can only be worked on if you or someone else can actually produce such a stack trace.
-* http://www.dirac.org/linux/gdb/06-Debugging_A_Running_Process.php
-* (in German) http://www.linuxwiki.de/gdb
+# Download the [{{URL:SF|downloads.}}project/gnucash/gdb-windows/win32-gdb.zip MSYS2 build of gdb]
+# Extract the archive to your user directory.
+# Open a Powershell window and type: <syntaxhighlight lang="posh">
+win32-gdb\gdb.exe "C:\Program Files\gnucash\bin\gnucash.exe"
+</syntaxhighlight>
+#:Be careful to use the actual paths in which you have installed gdb and gnucash respectively.
+# [[#Obtain the stack trace]] with the instructions above.
+You can provide even better stack traces if you tell gdb where in memory dynamically loaded modules got mapped to, because otherwise function calls into those are only written as '??'. See [{{URL:mail_archive|devel}}2006-November/019042.html here] and [{{URL:mail_archive|devel}}2006-November/019048.html here] for a way to do this.
-== Debug symbol information ==
+To enter <code>[</code> and <code>]</code>, use <tt>set editing off</tt>.
-Gnucash needs to be compiled in a way that has the debug symbols still included in the resulting binary libraries. When compiling gnucash from the tarball yourself, this is achieved by using the configure option <tt>./configure --enable-debug</tt>.
-=== Gentoo ===
+See also [[Windows Debugging]].
-When emerging gnucash on gentoo, you need to make sure that
-# the "debug" USE flag is enabled
-# ''and'' "<tt>FEATURES=nostrip</tt>" is set to disable symbol stripping.
-=== Ubuntu / Debian===
+=== See also ===
-On Ubuntu, the debug symbols are available in a separate package called <tt>gnucash-dbg</tt>. See https://wiki.ubuntu.com/DebuggingProgramCrash
+Other explanations on how to obtain stack traces:
+* [{{URL:Gnome|handbook}}issues/stack-traces.html Gnome Project Handbook: Stack Traces]
+* [http://www.dirac.org/linux/gdb/06-Debugging_A_Running_Process.php Peter's gdb Tutorial: Debugging A Running Process ]
+* (in German) https://www.linuxwiki.de/gdb
-This issue is also explained here https://wiki.ubuntu.com/Backtrace.
+== Linux debug symbol information ==
+Gnucash needs to be compiled in a way that has the debug symbols still included in the resulting binary libraries.
+;Self Compiling: This is achieved using the CMake option <tt>-DCMAKE_BUILD_TYPE="Debug"</tt>. See [[CMake]] and [[Gnucash Build Options]].
+;Distributions:
+:;Binary Distributions: Recent ones offer [https://sourceware.org/elfutils/Debuginfod.html Debuginfod] that enables gdb to download all of the symbols it needs automatically. See your distro's documentation for how to make sure that it's installed. Otherwise they usually offer debug symbols in a separate package appending <tt>-dbg</tt> or <tt>-debug</tt>. See e.g. https://wiki.ubuntu.com/DebuggingProgramCrash and https://wiki.ubuntu.com/Backtrace.
+:;Gentoo: When emerging gnucash on gentoo, you need to make sure that
+::# the "debug" USE flag is enabled
+::# ''and'' "<tt>FEATURES=nostrip</tt>" is set to disable symbol stripping.
+;Flatpak: It offers the symbols in a separate .Debug package via <tt>flatpak install org.gnucash.GnuCash.Debug</tt>. See [[Flatpak]].
+----
+{|cellpadding="10"
+| [[Tracefile]]
+| [[Logging]]
+| [[Bugzilla#Using Bugzilla]]
+| [[FAQ#Q: How do I run GnuCash under gdb and get a stack trace?]]
+|}