Difference between revisions of "Stack Trace"

Revision as of 17:48, 15 April 2015

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.

Additionally, some interesting logging messages are written into the Tracefile at each run of GnuCash.

MacOSX is Easiest

Every time an application crashes in MacOSX, 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 OSX 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.

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

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

Also on Windows?

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 below, 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.

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

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.

To attach to the running gnucash process:

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

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.

Starting GnuCash under gdb

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:

1. run "gnucash-env gdb gnucash"
2. at the gdb prompt, type: "run". Also add your parameters here, like "run --nofile"
3. 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).

Windows

Here are a few instructions on how to run gnucash under gdb on Windows:

• Install "gdb" from mingw.org [1]
• GnuCash 2.2.9 and older

• Modify the installed "bin\gnucash.cmd" script by inserting one and changing one line. It should end like

   set PATH=C:\Program Files\gdb\bin;%PATH%
   start gdb --args gnucash-bin %*

Be careful to use the actual paths in which you have installed gdb.exe

• Then start gnucash as usual

• GnuCash 2.4.0 and more recent

• 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.

• For all versions: this will open a gdb prompt
• Type run at the gdb prompt.
• Then provoke the crash and type backtrace or shorthand bt at the gdb prompt to obtain the backtrace, as explained on Stack Trace as well.

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:

• Windows#gdb for Windows-specific comments
• http://live.gnome.org/GettingTraces
• http://www.dirac.org/linux/gdb/06-Debugging_A_Running_Process.php
• (in German) http://www.linuxwiki.de/gdb

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.