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, please ensure you are running a DEBUG nightly build which can be downloaded from the nightly builds on the site.

Windows users

This is how to get backtraces on Windows:

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

In your user's home folder (Start → User's Documents or simply use the Explorer 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.

Linux Users

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

Running Ardour "live" inside the debugger (called "gdb") and getting information directly from gdb when Ardour crashes.
Running Ardour normally, and then getting information from a "core" file generated by the operating system, using the debugger

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

If you use JACK, 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). Debug builds of Ardour come with a "Dummy" backend which is usually a better option.

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.

How to run gdb

Self-built version of Ardour

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

Ardour from ardour.org

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

Ardour<N> --gdb

(replacing <N> with the major version (7 or 8 etc.)

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 "x86_64-linux-gnu".
...

(gdb)

Type run (followed by the ⏎ 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 ⏎ 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 behavior 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 core file).

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.

Mac OS

On MacOS (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.

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 Mac OS 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.