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

Windows users

This is how to get backtraces on Windows:

1. Download and install a debug build from nightly.ardour.org
2. Start → Ardour → Ardour (GDB)
3. A command-terminal comes up -- don't panic :) Ardour starts normally
4. When ardour crashes (or hangs,..): Do not press the "Close application, ..report to Microsoft" button.
5. Go to the command window. press Ctrl and C to get a command prompt (this is only needed if ardour hangs, but also safe otherwise).
6. Type thread apply all bt and press the Enter key
7. Type quit and press enter

In your user's home folder (start-menu → User's Documents or simply use the Expolorer to go to My Documents) there is now a file ardour-debug.log.

Attach this to a bug-report on http://tracker.ardour.org/ along with a brief description how you produced that crash. Thanks in advance.

OS X and Linux users: 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.

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)
	  

On many Linux systems you will need to type this before anything else: handle SIG32 noprint nostop (followed by the return key). This is not always needed, but it does no harm to use it anyway.

Type run (followed by the return key) 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.