Stack Trace

From GnuCash
Revision as of 19:32, 25 April 2015 by Jralls (talk | contribs) (General clarification and better ordering of sections. Removed obsolete instructions.)
Jump to: navigation, search

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. If you are running GnuCash

  • from a ready made package on Linux, 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 --enable-debug to your configure options and redo the make process.

How to obtain a Stack Trace

MacOSX

Every time an application crashes in Mac OS X, 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 OS X 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.

Linux

In order to get a stack trace on Linux one must have either the GNU Debugger, gdb, or the LLVM Debugger, lldb, installed. Use your package manager to install one or the other if necessary. Gdb is a bit simpler to use, so the instructions below are for gdb.

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

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

Attach gdb to running process

  1. Start gnucash normally.
  2. 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.
  3. Run gdb gnucash
  4. Attach to the running process by typing attach 12345; gdb will temporarily stop the program
  5. Continue program execution by typing c at the "(gdb)" prompt

Obtain the stack trace

  1. Provoke the crash. When GnuCash crashes gdb will print the reason for the crash and present the "(gdb)" prompt again.
  2. Type bt (bt full might provide additional info about local variables).
  3. 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.

Windows

On Windows it is currently not so easy to obtain such a stack trace. Some explanation on how to do this for experts is below, but we recognize 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 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". 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.

  • Install "gdb" from mingw.org [1]
  • Open a Windows command prompt and type:
   set PATH=C:\Program Files\gdb\bin;%PATH%
   gdb "C:\Program Files\gnucash\bin\gnucash"
Be careful to use the actual paths in which you have installed gdb and gnucash respectively.

If you build gnucash with the help of install.sh, make sure you export DISABLE_OPTIMIZATIONS=yes in packaging/win32/custom.sh to include debugging symbols and avoid optimizations that complicate debugging.

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.


See also

Other explanations on how to obtain stack traces:

Debug symbol information

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 ./configure --enable-debug.

Gentoo

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

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

Ubuntu / Debian

On Ubuntu, the debug symbols are available in a separate package called gnucash-dbg. See https://wiki.ubuntu.com/DebuggingProgramCrash

This issue is also explained here https://wiki.ubuntu.com/Backtrace.


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