Debugging BibleTime
This is an introduction to debugging BibleTime problems.
Contents |
Building BibleTime for debugging
This section discusses how to manually compile BibleTime with debug symbols. To use operating system provided debug files see the See also section.
| TODO |
Running BibleTime in debug mode
To run BibleTime in debugging mode, pass --debug as an command-line argument to the bibletime binary. This causes BibleTime to output error messages to the console. Under Microsoft windows, a log file is generated instead.
Debugging with GDB
Especially when BibleTime crashes, it is useful to run it in a debugger such as GDB, the GNU Project Debugger. For details on using GDB, please read the GDB User Manual. The rest of this section is a short introduction to debugging BibleTime to provide a detailed backtrace. To help us fix crashes in BibleTime, these backtraces are usually extremely important for us. Therefore, this short walk-through also serves as a guide to people who report BibleTime crashes, which the BibleTime team is unable to reproduce themselves.
| COMMAND LINE: Loading BibleTime into GDB |
|
gdb /path/to/bibletime
|
Typing the above command into a terminal loads BibleTime into the GDB debugger, but does not yet start BibleTime. Instead you should get a (gdb) prompt. Let's first make sure that GDB passes the --debug command line argument to BibleTime. To do this, type the following into the GDB console:
| (gdb): Making GDB pass --debug to the binary being debugged |
|
set args --debug
|
Next, we'll try to reproduce the BibleTime crash. To do so, we must start BibleTime from the debugger:
| (gdb): Starting a program in GDB |
|
run
|
Directly after the crash or hang, switch back to the GDB console. In case there is no active (gdb) prompt, try pressing CTRL+C to interrupt BibleTime. Once you get to the (gdb) prompt, type
| (gdb): Printing a full backtrace from all threads |
|
thread apply all bt full
|
to get a full backtrace for all running BibleTime threads. The output produced by this command is usually of paramount importance for our developers to start fixing the bug.
When we have finished debugging, shut down the debugger:
| (gdb): Exiting GDB |
|
quit
|
In case the program being debugged has not fully terminated when you try to exit GDB, the debugger might also ask you whether it should terminate the program before exiting.
