Developing On Linux

Overview
Compiling Audacity, or any GNU/Linux program for that matter, is basically a six stage process.
 * 1) Install build tools: the programs needed to create other programs.
 * 2) Install dependencies: other software used by the program you are trying to compile
 * 3) Download the source code into a local directory.
 * 4) Configure the compile with options, if any.
 * 5) Compile
 * 6) Install

The first and second stages are crucial: lack of build tools and required dependencies are the cause of 99% of failed compiles. This page should help with that.

The standard commands to compile a piece of software for stages 4, 5 and 6 are as follows, issued from within the local directory containing the source code.
 * 1) CONFIGURE: $ ./configure --[options-list]
 * 2) COMPILE: $ make
 * 3) INSTALL: $ sudo make install

Build Tools
Most Linux distributions come with the core set of development tools already installed, but if not you will need to install the following packages, probably from your distribution's package manager:
 * Shell. The configure script for Audacity is generated for a bourne-compatible shell. It is very unlikely that your system does not have one of these, but if in doubt, install the Bash shell.
 * GNU Make Other Makes may work, but may well not. Make on any Linux system will be GNU make.
 *  CMake is required to build libsoxr which is the Audacity default resampling library.
 * GCC (at least the C and C++ compilers) from GNU Compiler Collection. The only other compiler actively maintained by the Audacity development team is Microsoft's Visual C++, although we welcome patches to make Audacity compile with other compilers, for example the OpenSolaris compiler.
 * pkg-config
 * Autoconf Program which writes configure scripts. Needed to modify the build system
 * Automake Program which writes Makefiles. Needed to modify the build system
 * SVN Source code version control program
 * Patch Program for applying patches to files
 * GDB The GNU Debugger (for debugging crashes; see note below)
 * gettext. In order to build the translations for Audacity the tools are required. These are normally installed in order to be able to build wxWidgets (see below).

Dependencies
Audacity requires relatively few libraries and tools to build a minimum working program. There are then a larger number of optional libraries that extend Audacity to enable more features and facilities. It's therefore up to you whether you install these or not. If you don't install them, then decide later you need the extra features, you will need to rebuild Audacity after installing the extra libraries.

Note that some Linux distributions make a practice of splitting each library they package into two parts, those required for running programs using the library, and all the other files only needed when compiling applications using the library. The latter are often found in a package with a -dev suffix to the name. For the purposes of these instructions, whenever a library is listed as being needed, it means that both parts are needed in order to compile Audacity.

Prerequisites
These libraries are required to build Audacity.

wxWidgets
The main requirement to build Audacity is wxWidgets. WX 2.8 is required, preferably 2.8.12. wxGTK 2.8.10 has a known CPU hogging issue so is not recommended for Audacity. WX 2.9 makes too many API changes for us, and isn't yet supported by Audacity. The default Unicode build of WX is required as ANSI builds of Audacity are no longer supported.

Audacity supports for Linux (and other Unices) requires the wxGTK implementation of wxWidgets. There is no support for wxMotif, wxX11 or other wx variants, as they are incomplete in key areas. The GTK+ headers are also required as Audacity includes extensions to wxGTK which need the underlying toolkit headers to compile.

Whilst building Audacity with a standard distribution-supplied wxGTK 2.8.11 or 2.8.12 package will work fine, it will be difficult to debug some features as wxWidgets will have been built in Release mode (even if the debugging symbols package has been installed). For Audacity development you will want to compile wxGTK from source in debug mode, thus obtaining both a full set of debug symbols and additional checking in the wxWidgets code. This copy of wxWidgets does not have to be installed as the system copy, provided that the WX_CONFIG environment variable is used to tell the configure script to use the debug build. For example if your debug build of wxWidgets is in /home/user/dev/wxbuild/ then run ./configure WX_CONFIG=/home/user/dev/wxbuild/wx-config

(by putting the environment variable after the configure script invocation, the setting will be cached by the configure script and you don't need to re-specify it when re-configuring Audacity as you would if it was placed before the invocation).

We also have some notes on the libraries already supplied with different Linux Distributions. For example, Ubuntu tend to update to newer libraries sooner than Debian do.

libsndfile
libsndfile is required to build Audacity. It is almost certainly already installed on your system, although you may have to install the development package (see above). It is rarely necessary to compile libsndfile from source, although a copy is also included in Audacity SVN.

Optional Packages and Features
The configure script of Audacity gives the option to link in or not to link in a number of optional packages or features. In a few cases there is a choice of two packages but one or the other must be used (not neither and not both).

Obtaining Audacity
For development you will always want to obtain the SVN HEAD version of Audacity so you can stay abreast of the latest changes. For more information, see our development code download.

A typical command to check out the current development version of Audacity from SVN would be

svn checkout http://audacity.googlecode.com/svn/audacity-src/trunk/ audacity-read-only

Configure possibilities for libraries range from whether to include them or not, and whether to use local or system versions. In almost all cases these are standard libraries, and only provided in SVN for convenience, so if you have up-to-date versions installed as shared libraries you should select the external copies. The exceptions are Nyquist (which we have modified to integrate it with Audacity), and PortAudio (which has had to be patched to make it work).

Examples:

To enable support for ogg files: system]

To use an external sndfile library (which you have previously built and installed):

To disable Nyquist: --without-nyquist

Compiling on Unix
To compile Audacity on Linux (or for that matter, Mac OS X and most other Unix systems), use the standard "configure; make" sequence: ./configure make

However, you may want to start by running ./configure --help first to see the options, and possibly add special options.

If you are compiling from a SVN checkout, then you can re-generate the configure script by running ./autogen.sh

in the top level directory first.

In order to use ALSA devices with PortAudio v19 (the default for Audacity 1.3 and later) it is necessary to have the ALSA development library installed before compiling Audacity. In Debian-based Linux including Ubuntu and Ubuntu Studio, for example, this can be installed by running: sudo apt-get install libasound2-dev

On other distributions for example RHEL/CentOS, the required package is called "alsa-lib-devel".

Applying and revering patches
To apply a patch use the following syntax ( see help with patch syntax and the p or strip option ) : patch -p0 < name of patch file being applied

To revert a patch: patch -p0 -R < name of patch file being reverted

Useful rules when modifying the source
If you modify a file:


 * make

If you modify #includes in files:


 * make dep; make

If you modify configure.ac, Makefile.am, or any files in m4/ :


 *  autoreconf; ./configure; make dep; make

If you add or remove files:


 * ./configure; make dep; make

A good rule when applying a patch is to make dep before and after applying the patch in any case.

Old example dependencies: Audacity 1.3.4/Ubuntu 7.10
Dependencies: gettext libasound2-dev libflac-dev libflac++-dev libgtk2.0-dev libgtk-dev libid3tag0-dev libjack0.100.0-dev libmad0-dev libogg-dev libtwolame0 libtwolame-dev libvorbis-dev libwxbase2.6-dev libwxgtk-dev libwxgtk2.6-dev twolame portaudio19-dev wx2.6-headers zlib1g-dev

A suggested apt-get command to install the above dependencies:

$ sudo apt-get install gettext libasound2-dev libflac-dev libflac++-dev libgtk2.0-dev libgtk-dev libid3tag0-dev libjack0.100.0-dev libmad0-dev libogg-dev libtwolame0 libtwolame-dev libvorbis-dev libwxbase2.6-dev libwxgtk-dev libwxgtk2.6-dev twolame portaudio19-dev wx2.6-headers zlib1g-dev

A suggested ./configure command for full functionality:

$ ./configure --with-libvorbis --with-libflac --with-libid3tag --with-soundtouch

A more up-to-date set of steps on Ubuntu to obtain wxWidgets then use "sudo apt-get build-dep audacity" to build the Audacity dependencies is available in Compiling Audacity for Beginners.

KDevelop
KDevelop is a free, open source and cross-platform Integrated Development Environment (IDE) produced by KDE. Although not officially supported by Audacity, KDevelop can in principle be used for building or developing Audacity on Linux using any desktop environment. There is some information on building Audacity on KDevelop here - note the link thereon to www.crotchett.com for a tutorial on Audacity and KDevelop is no longer retrievable.

Problems with GDB and keyboard/mouse grabs
Running GUI programs in GDB is tricky, because GDB doesn't understand keyboard/mouse grabbing. In most X11 programs when you're in a menu, dragging a slider, or similar, the program grabs control of the keyboard or mouse to prevent other programs from getting their events until the drag/menu action is over. If you hit a breakpoint with the keyboard or mouse grabbed you're really stuck. For this reason, people often debug in a nested X server like Xephyr (similar to the older Xnest). Here's how you do that:


 * Install the Xephyr package. On Ubuntu it's called xserver-xephyr... probably similar in other distros
 * Install a simple window manager to run in the nested X server... I usually use wm2, because it doesn't require any configuration.
 * Run Xephyr. To get a 1024x768 window with address :5 (usually your main X server is at :0, and sometimes if you have two monitors the second is at :1) run $ Xephyr :5 -screen 1024x768
 * Start up wm2 (or whatever you like for a simple window manager) in the Xephyr window: $ DISPLAY=:5 wm2
 * Pop open a new terminal for GDB. Set the shell variable DISPLAY to ":5" so that all X11 programs started from that shell will use the new server at :5: $ DISPLAY=:5
 * cd to the source tree and run gdb as usual. The Audacity window should come up inside the xephyr window.

If your keyboard map is messed up in the Audacity window you can run the following command, which copies the keyboard map from your main display to the new one $ xkbcomp :0 :5

Alternately there's a way to force-ungrab the KB/mouse, but it requires some X configuration (I like Xephyr, but you might prefer this). AWD: The force-ungrab stuff has apparently been removed from recent versions of X.org. So you shouldn't rely on it unless you're specifically using an old version that still has this feature.