Debugging Ardour

Telling Ardour developers "Ardour crashes when I ..." generally isn't enough information to fix the issue. Ardour has a very large and complex codebase. If the crash isn't easily duplicatable (and many of them are not), then we need something called a backtrace.

Creating a Backtrace

A backtrace lets Ardour's developers see precisely what the program was doing when it crashed. This can be very helpful in fixing bugs - sometimes it is all the information that we need, sometimes its a n excellent starting point. A backtrace is sometimes a bit difficult to understand by itself, so a short explanation on what caused the crash the backtrace is generally useful.

For the backtrace to be helpful for the developers the version of Ardour from which the backtrace is generated needs to be compiled with "debug symbols". If you built Ardour yourself and did not explicitly turn debugging off, then your version will have debug symbols available. If you got Ardour from ardour.org, then (... mumble ...)

Two or Three Approaches

Generating a backtrace can be done in one of two ways:

  1. Running Ardour "live" inside the debugger (called "gdb") and getting information directly from gdb when Ardour crashes.
  2. Running Ardour normally, and then getting information from a "core" file generated by the operating system, using the debugger
  3. On OS X (on most systems, at least), the operating system will generate a backtrace automatically for you. It probably will not show it to you though, so you will have to find it.

We describe each of these approaches below.

Option 1: Running Ardour inside GDB

While getting a core dump needs some preparation, it might be handy for bugs which occur rarely and only during normal operation. Running Ardour inside GDB can be a bit more confusing for a beginner but it offers more possibilities if the bug you are dealing with requires deeper analyis.

Be sure to start JACK without the --realtime / -R switch. Also the client timeout variable should be set to a large value such as 5000 (--timeout / -t).

GDB (the GNU debugger)

To generate backtrace, you need the GNU debugger (GDB) for both. See your distro repository and or documentation for pre-built binaries for your system. On OS X, you will need XCode and the XCode Command Line Tools installed.

How to run gdb

Self-built version of Ardour

cd /where/the/ardour/source/code/is/gtk2_ardour
./ardbg
        

Ardour from ardour.org

Start it from the command line in a Terminal window using the following command:

Linux
/opt/Ardour_<VERSION>/bin/ardour3 --debug
(replacing <VERSION> appropriately)
OS X
to be determined

As gdb starts, you will see this sort of output, ending with the (gdb) which indicates that gdb is ready and waiting for a command.

GNU gdb ..... < version info > ....
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 "i486-linux-gnu"...Using host libthread_db library "/lib/tls/i686/cmov/libthread_db.so.1".

(gdb)
	  

Type run at the prompt to start Ardour.

Once Ardour crashes the GUI will not disappear, but it will freeze and stop redrawing itself. Once this happens, the Terminal window in which you started GDB from should show you the GDB prompt again. At the (gdb) prompt, type the command thread apply all bt, press the Enter key. It will normally produce multiple pages of data, be sure you get all of it so you can attach it your bug report.

Option 2: Generating Backtraces from Core Dumps

When a program crashes, it can write a "core dump" to disk which can be used by gdb to generate a backtrace. However, by default most Linux systems have this behaviour turned off. So your first task is to turn it back on. In a Terminal window, type:

ulimit -c unlimited 

After that just start Ardour using the shell or terminal you ran that command from. Once you crash Ardour, a file called "core", "core.[pid]" or something equivalent will appear.

Now start GDB as described above. At the (gdb) prompt, tell the debugger name of the core file you want it to use:

(gdb) core-file core.82929

(the .82929 would be different for your particular corefile).

Now you can give GDB the command "thread apply all bt". That command will normally produce the backtrace. It will normally produce multiple pages of data, be sure you get all of it so you can attach it your bug report.

Option 3: Using the OS X Crash Log

If Ardour crashes and produces a crash report, then you should attach the contents of the crash log to your bug report as an attachment (or paste it directly into the "More Information" field).

But I don't have a crash report!

Most OS X systems are configured with the system crash reporter enabled. However, most modern OS X systems do not tend to show the crash log by default. If Ardour crashes on your system and you not get a report about it, open the Console (Applications > Utilities > Console) and look near the end of its contents. You will almost certainly see a line or two that mention the crash and the location of the crash log file.