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

OS X and Linux users: Two or Three Approaches

Running Ardour normally, and then getting information from
a "core" file generated by the operating system, using the debugger

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/ardour<N> --gdb

(replacing <VERSION> and <N> appropriately -
VERSION is the complete version, N is the major version (4
or 5 etc.)

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.