How to help us debug Ardour

Telling Ardour developers “Ardour crashes” isn’t enough information to fix the issue. Ardour has a very large and complex codebase. Pinpointing the actual problem is often a large part of the fixing process, and to do that it is normally helpful to know how to duplicate the crash. If the crash isn’t duplicatable, the developer needs something called a backtrace. This document describes how to do provide duplication instructions, and how to generate backtraces.

Duplication report

Simply put, the the developer needs the steps to take which make Ardour crash or exhibit unwanted behaviour. In some cases the steps are easy to produce, but sometimes there are a lot of variables to get right to produce the issue.

A good starting point for a crash duplication report is with creating a new session. This eliminates a lot of variables from the equation and makes it easy for the developer to analyze the situation.

You should take care to mention every step along the way how miniscule it might seem. For example the connection options you select for the new session, the order you execute the steps in and especially any options you notice having an effect on the crash.

For example:

  1. Create a new session which uses a master bus and connects inputs automatically to physical ports.
  2. Create two mono tracks.
  3. Rename “Audio 1” to “[ThisNameContainsIllegalCharacters]”.
  4. Arm both tracks.
  5. Record enable session and press play.
  6. Wait for diskspace to run out.
  7. Ardour segfaults.

You don’t need to write a novel containing all your configuration variables, but if nothing else helps, posting the configuration information from your ardour.rc from ~/.ardour/ (or ~/.ardour2/ for 2.0) might be a good idea.

Some basic rules when writing a duplication guide:

  • Mention the port configuration (mono, stereo, etc) of tracks or buses to create.
  • If the process involves restarting Ardour with the session, mention how you load the session - via command line, recent menu or the open session dialog.
  • If regions are manipulated, mention your selected layering and crossfade models

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, a short explanation on what caused the crash the backtrace describes is appreciated. There are two ways to generate a backtrace, described below.

Pre-requisites for generating good backtraces

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”. To do this, simply give scons the argument DEBUG=1 when compiling ardour. If you have already compiled ardour without this, just do it again with DEBUG=1, no other steps are required. More information on building ardour is available.

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

The gtk_ardour (or gtk2_ardour) directory inside the Ardour source directory contains a script called “ardbg” which makes starting GDB with Ardour a lot easier. To start the debugger go into that directory and execute the script via ./ardbg . You can also give parameters to the script which will be passed to GDB.

Running GDB looks like this:

sh# cd /where/the/ardour/source/code/is/gtk2_ardour
sh# ./ardbg
GNU gdb 6.4-debian
Copyright 2005 Free Software Foundation, Inc.
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)

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:


sh# 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 with the “ardbg” script and pass the name of the core file as a parameter:


sh# ./ardbg core.82929

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

Once you get the (gdb) prompt, 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.

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.

Running JACK in realtime mode makes it very hard to get a good backtrace, so be sure to start JACK without the –realtime / -R switch. Also the client timeout variable should be set to 5000 or 10000 (–timeout / -t).

To start Ardour within GDB you should use the “ardbg” script inside Ardours’ source path as described earlier. Inside GDB you can start Ardour via the command “run”. If you want to give parameters to Ardour you can give those parameters to the “run” command. This will start the application and Ardour will work as normally.

Once Ardour crashes the GUI will not disappear, but it will freeze and stop redrawing itself. Once this happens, the terminal you started GDB from should show you the GDB prompt. At that prompt, give the command “thread apply all bt” and send the developers all of the output (there will normally be a lot of it).