Debugging Vidalia

1. Debug Logs
2. Getting a Stack Trace

Vidalia is still under development and, unfortunately, still has some bugs. Ideally, when you report a bug your ticket includes enough information for Vidalia's developers to reproduce the bug themselves. Some bugs are tricky, though, and only exist on certain platforms or under certain conditions that the developers are unable to recreate on their own. In these cases, we really need your help to get accurate information about the source of the bug, which helps us fix the bug faster.

The information on this page is intended to help you gather more information for a bug report, in case the Vidalia developers are unable to reproduce your bug.

Debug Logs

Vidalia can optionally display information about what it's doing while running. To start Vidalia with debug logging enabled, run the following command from a terminal or command prompt:

vidalia --loglevel debug

Vidalia has several other log levels, if the debug level is too "noisy." The available log levels in increasing order of message severity are debug, info, notice, warn, and error.

If you are on Windows, or if you would also like Vidalia to write its output to a file, then you should also specify a file to which Vidalia will write its logging messages:

vidalia --loglevel debug --logfile debug.log

You can replace debug and debug.log with whatever log level and filename you like. When you report a crash or freeze bug, you should attach your log file to your new ticket. If the log output is only a few lines, you can simply copy-paste the output into your ticket instead of attaching a text file.

Getting a Stack Trace

The instructions below are intended to help you get a stack trace when your Vidalia process crashes or freezes. The stack trace will (hopefully) tell us exactly where in Vidalia's code it crashed or froze.

Unix-ish Platforms

On Unix-like platforms, such as Linux, OS X, FreeBSD, etc., you will need to first build Vidalia from source. You should make sure you have the debug versions of Qt 4 installed. On Debian, for example, these libraries are called libqt4-debug-dev or similar. Also make sure that you have gdb installed.

You can then run your Vidalia binary under gdb by running gdb vidalia and then typing "run" at the (gdb) prompt. When Vidalia crashes, you can then run "thread apply all bt" at the (gdb) prompt. If Vidalia froze, you may need to press CTRL+C to get back to the (gdb) prompt.

Windows

Getting a stack trace on Windows requires installing a couple extra software packages and downloading a special, much larger Vidalia executable that includes extra debugging information.

1. Download and install MinGW.
2. Download and install the GNU Source-level Debugger, also called "gdb".
   1. Make sure gdb is included in your PATH. You can either edit your PATH environment variable, or type "set PATH=%PATH%;C:\MinGW\bin" after you open a command prompt in step 4. Change 'C:\MinGW\bin' to the folder where you installed gdb, if necessary.
3. Download and install the debug version of Vidalia's Windows installer.
4. Open a command prompt by clicking on Start -> Run, then entering 'cmd' and pressing Enter.
5. cd to the directory to which you installed Vidalia in Step 3. For example, 'cd "C:\Program Files\Vidalia"'
6. Open vidalia.exe under gdb by typing 'gdb vidalia.exe' and pressing Enter.
7. Start Vidalia by typing 'run' at the (gdb) prompt and pressing Enter.
8. Now repeat whatever action makes Vidalia crash or freeze. If Vidalia crashes, type 'thread apply all bt' and press Enter. If Vidalia freezes, click on the gdb window and press CTRL+C to return you to the (gdb) prompt. Then, type 'thread apply all bt' and press Enter.

Example Stack Trace

The following is an example stack trace on Windows obtained after Vidalia crashed.

C:\vidalia\trunk\debug>gdb vidalia
GNU gdb 6.3
Copyright 2004 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "i686-pc-mingw32"...
(gdb) run
Starting program: C:\vidalia\trunk\debug/vidalia.exe

Program received signal SIGSEGV, Segmentation fault.
0x00405884 in MainWindow::start (this=0x22fc10) at src/gui/mainwindow.cpp:502
502       int bar = *foo;
Current language:  auto; currently c++
(gdb) thread apply all bt

Thread 1 (thread 3692.0x790):
#0  0x00405884 in MainWindow::start (this=0x22fc10)
    at src/gui/mainwindow.cpp:502
#1  0x00402044 in MainWindow::MainWindow (this=0x22fc10)
    at src/gui/mainwindow.cpp:156
#2  0x00453f9c in qMain ()
    at ../../Qt/4.3.1/include/QtCore/../../src/corelib/thread/qatomic.h:176
#3  0x004bfa65 in WinMain (instance=0x400000, prevInstance=0x0, cmdShow=10)
    at qtmain_win.cpp:120
#4  0x004bf5fa in main ()
    at ../../Qt/4.3.1/include/QtCore/../../src/corelib/thread/qatomic.h:176
(gdb)

You should include the above information in your bug report. If the stack trace is only a few lines, it's OK to include it inline in your ticket. Otherwise, please attach a text file containing your stack trace to your ticket.