Difference between revisions of "Developing On Linux"

From Audacity Wiki
Jump to: navigation, search
m
(long-standing typo in ednote)
 
(87 intermediate revisions by 13 users not shown)
Line 1: Line 1:
Note: if you use Linux and need to compile Audacity from source (say, if you use Linux but we don't have a binary package like an RPM available for your distribution) but you don't know how, see [[CompilingAudacityForBeginners]]
+
{{ednote|'''Peter 15Jan17:''' [[ToDo-1]] This page really should be updated and maintained to deal with building the latest Audacity, otherwise it is of limited value.  }}
 +
{{alert|1=These instructions are for Audacity 2.1.1 or earlier. Audacity 2.1.2 requires wxWidgets 3.x (at time of writing, preferably 3.0.2). This page will be updated in due course.}}
  
For building with Windows, see [install-directory]\win\compile.txt
+
{{Introrel|1=Users on Linux and Unix systems often compile Audacity from source code to experiment with the latest version, or even the latest code in [https://github.com/audacity/audacity GitHub]. This page describes the requirements for the latter case, i.e. compiling and making changes to development code that has not been released. |2=If you need to compile Audacity because there is no suitable Audacity package for your distribution, please see [[CompilingAudacityForBeginners|Compiling Audacity Step by Step Guide]].|3=[[Developing On Windows]]
 +
 +
* [[Building On Mac]]}}
  
= Getting Audacity =
+
==Overview==
  
* Stable tarball: The easiest way to get Audacity is to download a release from the [http://audacity.sourceforge.net Audacity website].  All past releases of Audacity are archived on our [http://sourceforge.net/project/showfiles.php?group_id=6235 Sourceforge file release page].
+
Compiling Audacity, or any GNU/Linux application for that matter, is basically a six stage process.
 +
#Install build tools: the applications needed to create other applications.
 +
#Install dependencies: other software used by the application you are trying to compile
 +
#Download the source code into a local directory.
 +
#Configure the compile with options, if any.
 +
#Compile
 +
#Install
  
* CVS: The other main way to get Audacity is to use CVS - this is the best way if you want to actively develop Audacity, or keep up with the latest and greatest features.  For more information, see our [http://audacity.sourceforge.net/community/developers#cvs CVS page].
+
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.
  
= Prerequisites =
+
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.
 +
#CONFIGURE:  $ ./configure --[options-list]
 +
#COMPILE:  $ make
 +
#INSTALL:  $ sudo make install
  
== Audacity 1.2.x (stable) ==
+
== 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.
 +
* '''{{external|[http://www.cmake.org/ CMake]}}''' CMake is required to build libsoxr which is the Audacity default resampling library.
 +
* '''GCC''' (at least the C and C++ compilers) from [http://gcc.gnu.org/ 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''' Application which writes configure scripts. Needed to modify [[Audacity Configure Script|the build system]]
 +
* '''Automake''' Application which writes Makefiles. Needed to modify [[Audacity Configure Script|the build system]]
 +
* '''Git''' Source code version control application
 +
* '''Patch''' Application 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 {{external|[http://www.gnu.org/software/gettext/ GNU gettext]}} tools are required. These are normally installed in order to be able to build wxWidgets (see below).
  
At a minimum, Audacity 1.2.x requires [http://wxwidgets.org/ wxWidgets].  Currently we recommend using version 2.4.0.  You're welcome to use any 2.4.x release, but there were some new bugs in 2.4.1 that cause problems, so the Audacity developers are mostly sticking with 2.4.0. Audacity will not work with wxX11 (as it's incomplete, and things like dialogues are missing that we need), or with unicode builds of wxWidgets (so configure with --disable-unicode)
+
== Dependencies ==
 +
Audacity requires relatively few libraries and tools to build a minimum working application. 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.
  
Older versions are completely unsupported.  It may be possible to compile Audacity 1.2.x with wxWindows 2.5.x, but please don't expect it to compile out-of-the-box. Unfortunately this hasn't stopped some distros trying, and so annoying a lot of users. WXWidgets 2.4.0 is no longer linked from the wxWidgets home page, but the U.K. mirror is [ftp://biolpc22.york.ac.uk/pub/2.4.0/ Here]. Note that wxWidgets 2.4.2 for Mac OSX does not compile correctly; getting it from CVS resolves the issue. WXWidgets 2.4.2 should work equally well on Linux.
+
Note that some Linux distributions make a practice of splitting each library they package into two parts, those required for running applications 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.
  
Audacity supports wxGTK for Linux (and other Unix), wxMac for Mac OS X, and wxMSW for Windows using either MSVC++ or Cygwin. There is no support for wxMotif, wxX11, or other wx variants yet.
+
=== Prerequisites ===
 +
These libraries are required to build Audacity.
 +
==== wxWidgets ====
 +
The main requirement to build Audacity is [http://wxwidgets.org/ wxWidgets]. WX 3.0 is required, preferably 3.0.2. Older wxGTK 3.0.x versions may have bugs or missing features which stop Audacity working.  
  
Audacity does not currently support the Unicode or GTK2 builds of wxWidgets. When configuring wxWidgets on Unix, make sure you don't enable these features. To be safe:
+
Audacity supports for Linux (and other Unices) requires the wxGTK implementation of wxWidgets. There is no support for wxQt, 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.
  
  ./configure --disable-gtk2 --disable-unicode
+
Whilst building Audacity with a standard distribution-supplied wxGTK 3.0.2 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
 +
{{code|1=./configure WX_CONFIG=/home/user/dev/wxbuild/wx-config}}
  
Having GTK2 enabled does not usually cause any problems, however, providing the build and runtime versions match exactly (not always the case with binary distributions).
+
(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).
  
If you have Mac OS X, you may want to patch wxMac before building it - see below.
+
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.
  
== Audacity 1.3 (unstable) ==
+
==== libsndfile ====
The development branch of audacity (version 1.3, currently only in CVS) requires wxWidgets 2.6.1 or higher. Unicode and GTK2 builds are supported by default. Older development versions (2.5.x) may not work, so get the current wxWidgets 2.6.x release.
+
[http://www.mega-nerd.com/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 on GitHub.
  
= Optional Packages =
+
<div id="optional"></div>
 +
=== Packages and features options ===
 +
{{ednote|'''Peter 14Feb19:''' [[ToDo-1]] QucickTime has been deprecated by Apple}}
 +
The configure script of Audacity gives the option to link in or not to link in a number of optional packages or features, and to link to a local or system version of the required libsndfile library.
  
The configure script of Audacity gives the option to link in or not to link in a number of 'optional' packages. 'Optional' as some are more optional than others.
+
In the case of resampling libraries there is a choice of three packages but only one or none must be used.
  
There are possibilities surrounding the following packages:
+
{| style="background:#F9F9F9; border:1px solid #CCCCCC" cellpadding="5 px"
  libmad[http://www.mars.org/home/rob/proj/mpeg/]          use libmad for mp3 decoding support
+
|-
  vorbis[http://www.xiph.org/ogg/vorbis/]           enable ogg vorbis support
+
|width="20%" valign="top"|[[Audio Units|audiounits]]
  id3tag              use libid3tag for mp3 id3 tag support
+
|enable Audio Units plug-in support (Mac only) [default=auto]
  libsndfile[http://www.zip.com.au/~erikd/libsndfile/]       which libsndfile to use: [local], [system]
+
|-
  libresample        use libresample: [yes], [no]
+
|valign="top"|[[expat]]
  libsamplerate[http://www.mega-nerd.com/SRC/]   use libsamplerate (instead of libresample): [local], [system], [none]
+
|which expat to use for XML file support: [local], [system]
  libflac[http://flac.sourceforge.net/]         local system none - enable FLAC support [default=none]
+
|-
   ladspa[http://www.ladspa.org/]           compile with ladspa plug-in support [default=yes]
+
|valign="top"|[http://www.ffmpeg.org/ FFmpeg]
  nyquist[http://www-2.cs.cmu.edu/~music/music.software.html]         compile with Nyquist support [default=yes]
+
|use [[FFmpeg integration|FFmpeg]] for import and export support
  portmixer           compile with [[PortMixer]]  [default=yes]
+
|-
  portaudio[http://www.portaudio.com/]       which version of [[PortAudio]]  to use (=[v18,v19])[default=v18]
+
|valign="top"|[http://gstreamer.freedesktop.org/ GStreamer]         
   soundtouch         compile with [[SoundTouch]]  [default=yes]
+
|include GStreamer import/export support
  help                Make the help file "audacity-1.2-help.htb"[default=yes]
+
|-
 +
|valign="top"|[http://www.ladspa.org/ ladspa]         
 +
|enable LADSPA plug-in support [default=yes]
 +
|-
 +
|valign="top"|[http://flac.sourceforge.net/ libflac]  
 +
|use libFLAC for FLAC support: [local], [system], [none]
 +
|-
 +
|valign="top"|[http://sourceforge.net/project/showfiles.php?group_id=12349&package_id=87002 libid3tag]
 +
|use libid3tag for MP3 ID3 tag support  
 +
|-
 +
|valign="top"|[http://www.mars.org/home/rob/proj/mpeg/ libmad]
 +
|use libmad for mp3 decoding support
 +
|-
 +
|valign="top"|[[libresample]]
 +
|Alternative sample rate conversion algorithm instead of the default, recommended libsoxr: [local], [system], [none]
 +
|-
 +
|valign="top"|[http://www.mega-nerd.com/SRC/ libsamplerate]  
 +
|Alternative sample rate conversion algorithm instead of the default, recommended libsoxr: [local], [system], [none]. Should not be used if VST plug-in support is enabled, due to licensing reasons.
 +
|-
 +
|valign="top"|[http://www.mega-nerd.com/libsndfile/ libsndfile]  
 +
|choose which libsndfile to use: [local], [system]
 +
|-
 +
|valign="top"|[[Libsoxr|libsoxr]]
 +
|Audacity's default sample rate conversion algorithm offering both high quality and high speed: [local], [system], [none]
 +
|-
 +
|valign="top"|[http://www.twolame.org/ libtwolame]    
 +
|use libtwolame for MP2 export support
 +
|-
 +
|valign="top"|[http://www.vamp-plugins.org/ libvamp]      
 +
|use libvamp for Vamp plug-in support [default=yes]  
 +
|-
 +
|valign="top"|[http://www.xiph.org/ogg/vorbis/ libvorbis]     
 +
|use libvorbis for Ogg Vorbis support
 +
|-
 +
|valign="top"|[http://lv2plug.in/ LV2]     
 +
|use lv2 for LV2 plug-in support
 +
|-
 +
|valign="top"|[[Midi|midi]]
 +
|use [http://sourceforge.net/apps/trac/portmedia/wiki/portsmf portSMF] for Midi support
 +
|-
 +
|valign="top"|[http://www-2.cs.cmu.edu/~music/music.software.html nyquist]
 +
|enable [[Nyquist Audio Programming|Nyquist]] plug-in support [default=yes]
 +
|-
 +
|valign="top"|[http://www.portaudio.com/ portaudio] 
 +
|use portaudio v19
 +
|-
 +
|valign="top"|portmixer
 +
|compile with PortMixer [default=yes]
 +
|-
 +
|valign="top"|[http://en.wikipedia.org/wiki/QuickTime quicktime]
 +
|enable QuickTime import support (Mac only) [default=auto]  
 +
|-
 +
|valign="top"|[http://sourceforge.net/projects/sbsms/files/ sbsms]    
 +
|use libsbsms for slower, more accurate pitch and tempo changing
 +
|-
 +
|valign="top"|[http://www.surina.net/soundtouch/ soundtouch] 
 +
|use [[SoundTouch]] for pitch and tempo changing [default=yes]  
 +
|}
  
The following syntax is used as a parameter to the configure script to enable or disable a package or to pass further information about the package.
+
== Obtaining Audacity ==
 +
For development you will always want to obtain the GitHub HEAD version of Audacity so you can stay abreast of the latest changes.  For more information, see our [https://web.audacityteam.org/community/developers development code download] page and [[GitHub]].  
  
  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
+
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 GitHub 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).
  --without-PACKAGE      do not use PACKAGE (same as --with-PACKAGE=no)
 
  
The possibilities range from whether to include them or not to whether to use local or system versions.
+
'''Examples:'''
Unless there is reason not to, it is generally best to use the local packages which come bundled with Audacity. The reason being that the Audacity guru's have blown lightly on these in order to optimise them for Audacity. That said, in many cases, the standard libraries will also work well.
 
  
Examples:
+
To enable support for ogg files:
 +
{{code|<nowiki>--with-vorbis=[local|system]</nowiki>}}
  
To enable support for ogg files:
 
--with-vorbis
 
  
 
To use an external sndfile library (which you have previously built and installed):
 
To use an external sndfile library (which you have previously built and installed):
--with-libsndfile=system
+
{{code|<nowiki>--with-libsndfile=system</nowiki>}}
  
To disable nyquist:
 
--without-nyquist
 
  
= Compiling on Unix =
+
To disable Nyquist:
 +
{{code|<nowiki>--without-nyquist</nowiki>}}
  
To compile Audacity on Linux, Mac OS X, and most other Unix systems, use the standard "configure; make" sequence:
+
== Compiling on Unix ==
  
  ./configure
+
To compile Audacity on Linux (or for that matter, Mac and most other Unix systems), use a modified "configure; make" sequence:
  make
+
{{code|1=./configure CXXFLAGS="-std=gnu++11"<br>make}}
  
 
However, you may want to start by running ./configure --help first to see the options, and possibly add special options.
 
However, you may want to start by running ./configure --help first to see the options, and possibly add special options.
  
If you are compliling from a CVS checkout, then you can re-generate the configure script by running
+
If you are re-compiling from Git HEAD you can re-generate the configure script by running
<code>
+
{{code|autoreconf --no-recursive -i}}
$ autoreconf
 
</code>
 
 
in the top level directory first.
 
in the top level directory first.
  
Note: see the page [[CompilingAudacityForBeginners]] if you are confused by anything above.  We walk you through the process step-by-step.
+
In order to use ALSA devices with PortAudio v19 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:
 +
{{code|sudo apt-get install libasound2-dev}}
 +
 
 +
On other distributions for example RHEL/CentOS, the required package is called "alsa-lib-devel".
  
If this causes trouble, with errors like
+
== Modifying the source ==
  
$ configure: warning: CC=gcc: invalid host type
+
=== Applying and reverting patches ===
$ configure: warning: CXX=g++: invalid host type
 
$ configure: error: can only configure for one host and one target at a time
 
$ configure: error: /bin/sh './configure' failed for lib-src/portaudio-v19
 
  
Then try prefixing the configure command with "env -i"
+
To apply a [[SubmittingPatches|patch]] use the following syntax ( see [http://linux.die.net/man/1/patch help with patch syntax and the <i>p</i> or <i>strip</i> option] ) :
 +
{{code|patch -p0 < <i>name of patch file being applied</i>}}
  
$ env -i ./configure --without-portmixer --with-portaudio=v19
+
To revert a patch:
 +
{{code|patch -p0 -R < <i>name of patch file being reverted</i>}}
  
This appears to be fixed for audacity 1.2.4 (CVS).
+
=== Useful rules when modifying the source ===
 +
{{note|Whenever modifying the source, delete "audacity" in the root of the build tree and delete "audacity" in src/ before following the below.}}
 +
If you modify a file or an #include in a file:
  
Only in Audacity 1.2.0 pre-2:
+
:'''make'''
NOTE: If you want vorbis or other things, but you dont have it, you'll have to get those sources and put
 
them in the lib-src/ directory.
 
  
= Compiling on Windows =
+
If you modify configure.ac, Makefile.am, or any files in m4/ :
  
See the file win/compile.txt in the Audacity source code.  Feel free to add any tips or tricks here.
+
:''' autoreconf --no-recursive -i; ./configure; make'''
  
As of December 2004, now in CVS are *.vcproj files which will build in the newer versions of MS VC++ (.NET).
+
If you add or remove files:
  
===  Chacko 2004.05.28 Compile with MS VC++ under Win2K ===
+
:'''./configure; make'''
  
I tried version 1.2.1 (unmodified) from audacity-src-1.2.1.tar.bz2, with wxWindows-2.4.2 (unmodified) from wxMSW-2.4.2.zip, using the instructions in the above win/compile.txt file.  The only minor change needed was for compiling the wxWidgets; I had to open the src/wxWindows.dsw, (instead of the wxWidgets.dsw specified in the above instructions).  It worked without any major errors -- there were many warnings.  This resulted in a working Audacity (under win2000), of course without any of the options since I did not add any before the build.
+
== Old example dependencies: Audacity 1.3.4/Ubuntu 7.10 ==
 
   
 
   
For uncompressing the .bz2 on W2K, I used 7-zip 3.13 (freeware) downloaded as 7z313.exe
+
Dependencies:
 +
<pre>
 +
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
 +
</pre>
 +
 
 +
 
 +
A suggested apt-get command to install the above dependencies:
 +
 
 +
{{code|$ 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}}
 +
 
 +
{{ednote|'''Gale 26Jun15:''' [[ToDo-2]] The "suggested ./configure command for full functionality" 
 +
seems to be redundant as the default ./configure would now do that. Maybe better to show a non-default configure command that e.g. used system LV2 and local PortAudio.}} 
 +
A suggested ./configure command for full functionality:
  
If anybody has detailed instructions on building in all the options, to bring to the form of the current release, please add the details here.
+
{{code|$  ./configure --with-libvorbis --with-libflac --with-libid3tag --with-soundtouch}}
==== End Chacko 2004.05.08 ====
 
  
  
================ start Yonatan 2 Dec 2003 =================
+
{{ednote|'''Steve 01Jul15:''' Recent versions of Ubuntu, Mint, Debian and their derivatives will pull in WxGTK3.x if "sudo apt-get build-dep audacity" is used, so commenting out the next paragraph.
I tried to compile version 1.2.0.pre3 'out of the box' on windows without any the extra options - just wxWidgets
 
and the default stuff that comes with audacity - it doesn't quite work - here is a summary.
 
  
1) There seems to be a bug in the project definition, the path for 'libresample.dsp' was wrong
 
( as seen in the 'File View of the left pane in VCC++) it is in win and not in win\libresample.
 
2) The missing links in the readme file are
 
  a) need to edit  win\configwin.h and do #udef (NOT #define ...0) to the libraries that are unneeded
 
  b) remove the appropriate libraries from Project Setting Link tab, project Options.
 
  
summary
+
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 [[CompilingAudacityForBeginners#simple|Compiling Audacity for Beginners]].}}
In order to compile the minimal audacity (no options) I had to
 
1) double click on the libresample on the left (File view) pane - it then found the correct dsw file
 
2) edit win\configwin.h as follows:-
 
#undef USE_LIBMAD
 
#undef USE_LIBVORBIS
 
3) remove the following libraries from the settings
 
libsamplerated.lib
 
madd.lib
 
ogg_static_d.lib
 
vorbis_static_d.lib
 
vorbisfile_static_d.lib
 
libFLAC++d.lib
 
libFLACd.lib
 
  
================ end Yonatan 2 Dec 2003 =================
+
See also [[CompilingAudacityForBeginners#simple|Compiling Audacity for Beginners]].
  
= Compiling on Mac OS X =
+
== KDevelop ==  
  
Currently only command-line building is supported; there is no up-to-date Project Builder or Xcode project file. Compile just as you would a Unix program (see above). After building "audacity", an additional step is performed, that creates "Audacity.app". Make sure that you run "Audacity.app" and not "audacity", otherwise it won't work. Note that in the "mac" directory there is a patch file for wxMac-2.4.0 - it's recommended that you apply this patch first. This enables support for custom cursors, allows disabling anti-aliased text (for speed), and fixes a couple of bugs.
+
[http://www.kdevelop.org/ KDevelop] is a free, open source and cross-platform [http://en.wikipedia.org/wiki/Integrated_development_environment Integrated Development Environment] (IDE) produced by [http://www.kde.org/ 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 [http://www.kdevelop.org/phorum5/read.php?2,31411 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 applications in GDB is tricky, because GDB doesn't understand keyboard/mouse grabbing.  In most X11 applications when you're in a menu, dragging a slider, or similar, the application grabs control of the keyboard or mouse to prevent other applications 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 {{code|$ Xephyr :5 -screen 1024x768}}
 +
* Start up wm2 (or whatever you like for a simple window manager) in the Xephyr window: {{code|<nowiki>$ DISPLAY=:5 wm2</nowiki>}}
 +
* Pop open a new terminal for GDB.  Set the shell variable DISPLAY to ":5" so that all X11 applications started from that shell will use the new server at :5: {{code|<nowiki>$ DISPLAY=:5</nowiki>}}
 +
* cd to the source tree and run gdb as usual.  The Audacity window should come up inside the xephyr window.
  
= Mini FAQ about issues on this page =
+
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
 +
{{code|$ xkbcomp :0 :5}}
  
Q: Will wxWidgets-2.5.3 (wxWidgetsALL) work?
+
Alternately [http://www.ogre3d.org/forums/viewtopic.php?t=20690 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.
  
A: No. For unstable Audacity 1.3 from CVS, you need wxWidgets 2.6. For Audacity 1.2.x you need wxwidgets 2.4.x
+
[[Category:Linux and Unix Platform]] [[Category:For Developers]]

Latest revision as of 09:55, 20 July 2019

Peter 15Jan17: ToDo-1 This page really should be updated and maintained to deal with building the latest Audacity, otherwise it is of limited value.
Warning icon These instructions are for Audacity 2.1.1 or earlier. Audacity 2.1.2 requires wxWidgets 3.x (at time of writing, preferably 3.0.2). This page will be updated in due course.


Users on Linux and Unix systems often compile Audacity from source code to experiment with the latest version, or even the latest code in GitHub. This page describes the requirements for the latter case, i.e. compiling and making changes to development code that has not been released.
If you need to compile Audacity because there is no suitable Audacity package for your distribution, please see Compiling Audacity Step by Step Guide.
 
Related article(s):

Overview

Compiling Audacity, or any GNU/Linux application for that matter, is basically a six stage process.

  1. Install build tools: the applications needed to create other applications.
  2. Install dependencies: other software used by the application 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  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 Application which writes configure scripts. Needed to modify the build system
  • Automake Application which writes Makefiles. Needed to modify the build system
  • Git Source code version control application
  • Patch Application 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 GNU gettext  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 application. 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 applications 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 3.0 is required, preferably 3.0.2. Older wxGTK 3.0.x versions may have bugs or missing features which stop Audacity working.

Audacity supports for Linux (and other Unices) requires the wxGTK implementation of wxWidgets. There is no support for wxQt, 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 3.0.2 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 on GitHub.

Packages and features options

Peter 14Feb19: ToDo-1 QucickTime has been deprecated by Apple

The configure script of Audacity gives the option to link in or not to link in a number of optional packages or features, and to link to a local or system version of the required libsndfile library.

In the case of resampling libraries there is a choice of three packages but only one or none must be used.

audiounits enable Audio Units plug-in support (Mac only) [default=auto]
expat which expat to use for XML file support: [local], [system]
FFmpeg use FFmpeg for import and export support
GStreamer include GStreamer import/export support
ladspa enable LADSPA plug-in support [default=yes]
libflac use libFLAC for FLAC support: [local], [system], [none]
libid3tag use libid3tag for MP3 ID3 tag support
libmad use libmad for mp3 decoding support
libresample Alternative sample rate conversion algorithm instead of the default, recommended libsoxr: [local], [system], [none]
libsamplerate Alternative sample rate conversion algorithm instead of the default, recommended libsoxr: [local], [system], [none]. Should not be used if VST plug-in support is enabled, due to licensing reasons.
libsndfile choose which libsndfile to use: [local], [system]
libsoxr Audacity's default sample rate conversion algorithm offering both high quality and high speed: [local], [system], [none]
libtwolame use libtwolame for MP2 export support
libvamp use libvamp for Vamp plug-in support [default=yes]
libvorbis use libvorbis for Ogg Vorbis support
LV2 use lv2 for LV2 plug-in support
midi use portSMF for Midi support
nyquist enable Nyquist plug-in support [default=yes]
portaudio use portaudio v19
portmixer compile with PortMixer [default=yes]
quicktime enable QuickTime import support (Mac only) [default=auto]
sbsms use libsbsms for slower, more accurate pitch and tempo changing
soundtouch use SoundTouch for pitch and tempo changing [default=yes]

Obtaining Audacity

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

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 GitHub 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:

--with-vorbis=[local|system]


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

--with-libsndfile=system


To disable Nyquist:

--without-nyquist

Compiling on Unix

To compile Audacity on Linux (or for that matter, Mac and most other Unix systems), use a modified "configure; make" sequence:

./configure CXXFLAGS="-std=gnu++11"
make

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

If you are re-compiling from Git HEAD you can re-generate the configure script by running

autoreconf --no-recursive -i

in the top level directory first.

In order to use ALSA devices with PortAudio v19 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".

Modifying the source

Applying and reverting 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

Whenever modifying the source, delete "audacity" in the root of the build tree and delete "audacity" in src/ before following the below.

If you modify a file or an #include in a file:

make

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

autoreconf --no-recursive -i; ./configure; make

If you add or remove files:

./configure; make

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
Gale 26Jun15: ToDo-2 The "suggested ./configure command for full functionality" seems to be redundant as the default ./configure would now do that. Maybe better to show a non-default configure command that e.g. used system LV2 and local PortAudio.

A suggested ./configure command for full functionality:

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


Steve 01Jul15: Recent versions of Ubuntu, Mint, Debian and their derivatives will pull in WxGTK3.x if "sudo apt-get build-dep audacity" is used, so commenting out the next paragraph.


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.

See also 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 applications in GDB is tricky, because GDB doesn't understand keyboard/mouse grabbing. In most X11 applications when you're in a menu, dragging a slider, or similar, the application grabs control of the keyboard or mouse to prevent other applications 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 applications 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.