Browse Source

Update the build documentation

Dmitry Vedenko 1 year ago
committed by Dmitry Vedenko
  1. 249
  2. 5
  3. 92
  4. 144
  5. 136


@ -0,0 +1,249 @@
# Building Audacity
## Prerequisites
* **python3** >= 3.9.1
* **conan** >= 1.32.0
* **cmake** >= 1.36
* A working C++ 14 compiler
### Conan
[The best way to install Conan is `pip`.](
To install Conan on Windows:
$ pip install conan
To install Conan on macOS and Linux:
$ sudo pip3 install conan
Alternatively, on macOS, Conan is available from `brew`.
### CMake
On Windows, please use the [prebuilt binaries](
On macOS, the easiest way to install CMake is `brew install cmake`.
On Linux, `cmake` is usually available from the system package manager. The latest CMake version is available from Snap: `sudo snap instal cmake --classic`.
### Windows
We build Audacity using [Microsoft Visual Studio 2019]( In order to build Audacity **Desktop development with C++** workload is required.
As we require only C++14 - MSVC 2017 should work just well too.
### MacOS
We build Audacity using XCode 12. However, it is likely possible to build it with XCode 7.
### Linux
We use GCC 9, but any C++14 compliant compiler should work.
On Debian or Ubuntu, you can install everything required using the following commands:
$ sudo apt-get update
$ sudo apt-get install -y build-essential cmake git python3-pip
$ sudo pip3 install conan
$ sudo apt-get install libgtk2.0-dev libasound2-dev libavformat-dev libjack-jackd2-dev
## Building on Windows
1. Clone Audacity from the Audacity GitHub project.
For example, in the **git-bash** run:
$ git clone
2. Open CMake GUI.
Set the **Where is the source code** to the location Audicity was cloned.
Set **Where to build the binaries** to the location you want to place your build in. It is preffered, that this location is not within the directory with the source code.
3. Press **Configure**. You can choose which version of Visual Studio to use and the platform to build for in the popup. We support **x64** and **Win32** platforms. The **x64** platform is a default option. Press **Finish** to start the configuration process.
4. After the successful configuration, you will see `Configuring done` in the last line of the log. Press **Generate** to generate the Visual Studio project.
5. After you see "Generating done", press **Open Project** to open the project in Visual Studio.
6. Select "Build -> Build Solution".
7. You can now run and debug Audacity!
Generally, steps 1-5 are only needed for the first-time configuration. Then, after you've generated the solution - you can open it in Visual Studio next time. In case when the project configuration has changed - the IDE will invoke CMake internally.
> Conan Center provides prebuilt binaries only for **x64**. Configuring the project for Win32 will take much longer, as all the 3d party libraries will be built during the configuration.
## macOS
1. Clone Audacity from the Audacity GitHub project.
$ git clone
2. Configure Audacity using CMake:
$ mkdir build && cd build
$ cmake -GXCode -T buildsystem=1 ../audacity
3. Open Audacity XCode project:
$ open Audacity.xcodeproj
and build Audacity using the IDE.
Steps 1 and 2 are only required for the first-time builds.
Alternatively, you can use **CLion**. If you chose so, open the directory where you have cloned Audacity using CLion and you are good to go.
At the moment, we only support **x86_64** builds. It is possible to build using AppleSilicon harware, but **mad** and **id3tag** should be disabled:
cmake -GXCode -T buildsystem=1 -Daudacity_use_mad="off" -Daudacity_use_id3tag=off ../audacity
## Linux & Other OS
1. Clone Audacity from the Audacity GitHub project.
$ git clone
2. Configure Audacity using CMake:
$ mkdir build && cd build
$ cmake -G "Unix Makefiles" -Daudacity_use_ffmpeg=loaded ../audacity
3. Build Audacity:
$ make -j'nproc`
4. Testing the build:
Adding a "Portable Settings" folder allows Audacity to ignore the settings of any existing Audacity installation.
$ cd bin/Release
$ mkdir "Portable Settings"
$ ./audacity
5. Installing Audacity
$ cd <build directory>
$ sudo make install
## Advanced
### CMake options
You can use `cmake -LH` to get a list of the options available (or use CMake GUI or `ccmake`).
The most notable options are:
| Name | Type | Default | Description |
| :-------------------------------- | :----- | :--------- | :-------------------------------------------------------------- |
| CMAKE_BUILD_TYPE | STRING | Debug | Type of the build: Debug, Release, RelWithDebInfo, MinSizeRel |
| CMAKE_INSTALL_PREFIX | PATH | /usr/local | Install path prefix, prepended onto install directories. |
| audacity_lib_preference | STRING | local | Library preference [system (if available), local] |
| audacity_obey_system_dependencies | BOOL | Off | Use only system packages to satisfy dependencies |
| audacity_use_expat | STRING | system | Use expat library [system (if available), local, off] |
| audacity_use_ffmpeg | STRING | loaded | Use ffmpeg library [loaded, linked, off] |
| audacity_use_flac | STRING | local | Use flac library [system (if available), local, off] |
| audacity_use_id3tag | STRING | local | Use id3tag library [system (if available), local, off] |
| audacity_use_ladspa | BOOL | ON | Use LADSPA plug-in support [on, off] |
| audacity_use_libmad | STRING | local | Use libmad library [system (if available), local, off] |
| audacity_use_libmp3lame | STRING | local | Use libmp3lame library [system (if available), local, off] |
| audacity_use_lv2 | STRING | local | Use lv2 library [system (if available), local, off] |
| audacity_use_mad | STRING | local | Use mad library [system (if available), local, off] |
| audacity_use_midi | STRING | local | Use midi library [system (if available), local, off] |
| audacity_use_nyquist | STRING | local | Use nyquist library [local, off] |
| audacity_use_ogg | STRING | local | Use ogg library [system (if available), local, off] |
| audacity_use_pa_alsa | BOOL | YES | Use the portaudio ALSA interface if available |
| audacity_use_pa_jack | STRING | linked | Use the JACK audio interface if available [loaded, linked, off] |
| audacity_use_pa_oss | BOOL | YES | Use the OSS audio interface if available |
| audacity_use_pch | BOOL | YES | Use precompiled headers [yes, no] |
| audacity_use_portaudio | STRING | local | Use portaudio library [local] |
| audacity_use_portmixer | STRING | local | Use portmixer library [local, off] |
| audacity_use_portsmf | STRING | local | Use portsmf library [system (if available), local, off] |
| audacity_use_sbsms | STRING | local | Use sbsms library [system (if available), local, off] |
| audacity_use_sndfile | STRING | local | Use sndfile library [system (if available), local] |
| audacity_use_soundtouch | STRING | local | Use soundtouch library [system (if available), local, off] |
| audacity_use_soxr | STRING | local | Use soxr library [system (if available), local] |
| audacity_use_sqlite | STRING | local | Use sqlite library [system (if available), local] |
| audacity_use_twolame | STRING | local | Use twolame library [system (if available), local, off] |
| audacity_use_vamp | STRING | local | Use vamp library [system (if available), local, off] |
| audacity_use_vorbis | STRING | local | Use vorbis library [system (if available), local, off] |
| audacity_use_vst | BOOL | ON | Use VST2 plug-in support [on, off] |
| audacity_use_wxwidgets | STRING | local | Use wxwidgets library [system (if available), local, off] |
| audacity_use_zlib | STRING | system | Use zlib library [system (if available), local, off] |
### Building using system libraries
On Linux, it is possible to build Audacity using (almost) only the libraries provided by the package manager. We require the following version of the packages to be installed:
| Name | Version | Ubuntu 20.04 package |
| :---------------- | :------------ | :------------------------------------------- |
| wxWidgets | >= 3.1.3 | **N/A** |
| expat | >= 2.2.9 | libexpat1-dev |
| libmp3lame | >= 3.100 | libmp3lame-dev |
| libsndfile | >= 1.0.28 | libsndfile-dev |
| libsoxr | >= 0.1.3 | libsoxr-dev |
| ~~portaudio-v19~~ | ~~>= 19.6.0~~ | ~~portaudio19-dev~~ |
| sqlite3 | >= 3.31.1 | libsqlite3-dev |
| libcurl | >= 7.68.0 | libcurl-dev |
| ffmpeg | >= 4.2.4 | libavcodec-dev libavformat-dev libavutil-dev |
| libid3tag | >= 0.15.1b | libid3tag0-dev |
| libmad | >= 0.15.1b | libmad0-dev |
| vamp-host-sdk | >= 2.9.0 | N/A |
| libogg | >= 1.3.4 | libogg-dev |
| libvorbis | >= 1.3.6 | libvorbis-dev |
| libflac | >= 1.3.3 | libflac-dev libflac++-dev |
| lilv | >= 0.24.6 | liblilv-dev |
| lv2 | >= 1.16.0 | lv2-dev |
| serd | >= 0.30.2 | libserd-dev |
| sord | >= 0.16.4 | libsord-dev |
| sratom | >= 0.6.4 | libsratom-dev |
| suil | >= 0.10.6 | libsuil-dev |
| portmidi | >= 217 | libportmidi-dev |
| portsmf | >= 0.1 | libportsmf-dev |
| libsbsms | >= 2.0.2 | libsbsms-dev |
| soundtouch | >= 2.1.2 | libsoundtouch-dev |
| twolame | >= 0.4.0 | libtwolame-dev |
| zlib | >= 1.2.11 | libzlib1g-dev |
There are a few cases when the local library build is preferred:
1. **wxWidgets**: While Audacity on **Linux** uses vanilla version of wxWidgets, we **require** that version **3.1.3** is used. This version is not available in most of the distributives.
2. **portaudio-v19**: Audacity currently uses some private APIs, so using system portaudio is not yet possible.
3. **vamp-host-sdk**: Development packages are not available in Ubuntu 20.04.
4. **libnyquist**, **portmixer**: Libraries is not available in Ubuntu 20.04.
5. **sqlite3**, **libsmbs**: Libraries are very outdated in Ubuntu 20.04.
It is not advised to mix system and local libraries, except for the list above. `ZLib` is very common dependency; it is possible to mix system and local libraries in one build. However, we try to mitigate this issue to some extent.
There is a [`Dockerfile`](linux/build-environment/Dockerfile) that can be used as an example of how to build the Audacity using system libraries:
$ docker build -t audacity_linux_env .\linux\build-environment\
$ docker run --rm -v ${pwd}:/audacity/audacity/ -v ${pwd}/../build/linux-system:/audacity/build -it audacity_linux_env
To find system packages, we rely on `pkg-config`. There are several packages, that have broken `*.pc` or do not use `pkg-config` at all. For the docker image - we mitigate this issue by installing the correct [`pc` files](linux/build-environment/pkgconfig/).


@ -1,10 +1,7 @@
Compilation and install instructions
Compilation instructions for Audacity are provided in the source code:
* Windows: win\build.txt
* macOS: mac/build.txt
* GNU/Linux: linux/build.txt
Compilation instruction for Audacity is available at
You can ask for help with compilation problems at: .


@ -1,92 +0,0 @@
Instructions for Building on Linux
Fuller instructions can be found on our wiki at
In fact you should read those instructions rather than these
once. These ones give less detail.
Some prerequisites:
- Audacity requires gcc 4.9 or later to build.
- CMake ( ) is required to build the local copy of
the libsoxr resampling library used by Audacity.
On a modern Debian distro, e.g. Ubuntu 16.04 (bionic), you would do:
sudo apt-get install build-essential cmake
- libasound and gtk are required. Having gtk2 and gtk3 too
may not be required, but compilation works if both are.
- Auto-tools are also needed.
sudo apt-get install libasound2-dev libgtk2.0-dev libgtk-3-dev
sudo apt-get install autoconf automake
- Since you will be fetching code from git repositories you
will need git.
sudo apt-get install git git-gui gitk
1) Clone wxWidgets and checkout 3.1.3 from the Audacity fork of the
wxWidgets project:
for example
mkdir ./wxWidgets
cd ./wxWidgets
git clone --recurse-submodules
Don't be tempted to use Widgets already installed on Linux because this
will typically be a different version and will cause problems.
IF you forgot the --recurse-submodules, you can correct that later by:
git submodule update --init
2) Follow instructions for building at
mkdir buildgtk
cd buildgtk
../configure --with-gtk
su <type root password>
make install
3) Having got this far, it is well worth trying out building some wxWidgets
examples to confirm that building has worked OK
See our wiki for more detailed build instructions, including how to
install CMake.
1. Make a build directory under the audacity git directory.
cd audacity
mkdir build-cmake
cd build-cmake
2. Generate the makefiles
cmake -DCMAKE_BUILD_TYPE=Release ..
3. Build Audacity
cmake --build .
4. Run
cd bin/Release


@ -1,144 +0,0 @@
Instructions for building on macOS using CMake.
Building on macOS has been made much simpler with the Audacity 2.4.0
release. Still, read this document thoroughly before starting.
1) Get and install the latest Xcode version available your macOS version:
MacOS Xcode Version (as of Mar 2020)
Catalina - 10.15 11.3
Mojave - 10.14 10.3
High Sierra - 10.13 9.4.1
Sierra - 10.12 9.2
El Capitan - 10.11 8.2.1
Yosemite - 10.10 7.2.1
2) Clone the Audacity repository:
git clone
3) Clone wxWidgets 3.1.3:
git clone --recurse-submodules
Ensure that you clone with the "--recurse-submodules" option, and do not
just download the Zip package, otherwise there will be required components
Don't be tempted to use wxWidgets already installed by a package manager
such as Homebrew because this will cause problems.
We have applied some Audacity specific patches to wxWidgets to better
support VoiceOver, so please use the audacity-fixes-3.1.3 branch. It's
the default branch on our GitHub copy:
You can be certain the correct branch is active with:
git checkout audacity-fixes-3.1.3
4) Change directory to the folder where wxWidgets was cloned and build it using:
sudo <path to Audacity source>/mac/scripts/build_wxwidgets
5) The config command should return "3.1.3" if the install was successful:
/usr/local/x86_64/bin/wx-config --version
6) Now that you have wxWidgets installed, edit your ~/.bash_profile or
~/.zprofile and add:
export WX_CONFIG=/usr/local/x86_64/bin/wx-config
Log out and back in again (or reboot) for this to take effect.
7) Download the CMake 3.16.4 DMG from:
8) Double click the DMG, follow the prompts and drag the CMake app to the
Applications folder.
If you will be building from the command line, open the CMake application
and click the "Tools -> How to Install For Command Line Use" menu. It will
give you additional instructions on making CMake available to the command
You are now ready to start building Audacity.
NOTE: Building with the GUI interface will result in the downloading of
another copy of wxWidgets from Audacity.
1) Open the app.
2) Click the "Browse Source..." button and locate the top of your Audacity
source tree, then click the "Open" button.
3) Click the "Browse Build..." button and find the location where you want to
put the build (use the "New Folder" button at the bottom left to create a
new folder).
This folder does not have to be in or even near the source tree, but it
must not be the same as the source tree. However, it is common to make it
a subdirectory of the Audacity source tree.
4) Click the "Configure" button and when the dialog pops up, select "Xcode" for
the generator, then click the "Done" button.
5) Click the "Generate" button to create the Xcode project.
6) Now you can either click the "Open Project" button or go to your "Build" folder in
Finder and open the Xcode project as normal.
1) Change directory to your Audacity source tree.
cd audacity
2) Create the "build" folder (name it anything you like):
mkdir bld
3) Change to the "build" folder:
cd bld
4) Configure and generate the Xcode project:
cmake -G Xcode ..
5) Build Audacity using the CMake command or xcodebuild:
cmake --build . --config Release
xcodebuild --configuration Release
The "" bundle will be in the "bin/Release" subdirectory of your
"build" folder, so you can start it via Finder or:
open bin/Release/
- If you'd like to get a completely clean build, just delete "build" folder
and return to step 2 above.
- Once the Xcode project is generated, you shouldn't have to "configure" or
"generate" again as it will be done for you automatically after pulling
updates and building.
For example:
cd <audacity> directory
git pull
cd bld
cmake --build . --config Release
- Instructions on optional signing of DMGs, showing languages other than English,
and other useful information can be found on our wiki at:


@ -1,136 +0,0 @@
Instructions for building on Windows.
Fuller instructions that include
* Installing CMake
* Portable Settings
* Building an Installer
can be found on our wiki at
1. MSVC 2019: Download and install Microsoft Visual Studio 2019
be sure to include the Desktop Development with C++ Workflow
this build was testing using VS 16.8.5
2. Git: Download and install Git, for example by installing:
Git for Windows:
and optionally GitExtensions:
download and run the .msi installer. GitExtensions has a GUI interface,
includes Git for Windows and has a Git bash command line in the bottom panel
of the screen.
3. Python
We no longer use Python 2.7.18 during the build. Instead we must use Python 3.
You can download Python 3.9.1 from
Select the Python 3.9.1 Windows Installer (32-bit)
4. wxWidgets:
a) Clone wxWidgets and checkout 3.1.3 from the Audacity fork of the
wxWidgets project:
for example, in the git-bash command line:
mkdir wxWidgets
git clone --recurse-submodules
IF you forgot the --recurse-submodules, you can correct that later by:
git submodule update --init
It is instructive to review but do NOT follow the instructions for
building at
b) We (currently) build the 32 bit DLL version,
and Audacity is built 32 bit too.
Set WXWIN environment variable to the appropriate directory where you
installed wxWidgets. This will tell CMake where to find wxWidgets later.
To set WXWIN, click on Settings (the cogwheel icon from the start menu)
Then in the 'find a setting' search box type 'env'.
Choose 'Edit the system environment variables'
Then the 'Environment Variables' button
Then in system variables, for variable and value, add (for example)
WXWIN C:\aud300\wxWidgets
You will be building a dll version with MSVC2019 IDE, so...
In Windows File Manager, right-click on ../wxWidgets/build/msw/wx_vc16.sln,
Select Visual Studio 2019.
In the solutions configurations drop-down list, change "Debug" to
"DLL Release",
Then select Build > Build Solution.
When the build completes, you will get a message such as:
========= Build: 24 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
Close Visual Studio.
You can check this worked also by looking in C:\aud300\wxWidgets\lib\vc_dll
There should be dll files there with _'ud' in their name.
The ud stands for 'unicode debug'. If you only have files with 'u' then
you only have release.
5. Audacity
a) Clone Audacity from the Audacity GitHub project.
for example, in the git-bash command line
mkdir audacity
git clone
b) Open the CMake GUI
Open VS 2019 > "continue without code" > File > Open > CMake
Open CMakeLists.txt in root of audacity source folder you cloned
Wait for the CMake Overview Pages tab to appear (be patient)
Click "Open the CMake Settings Editor" in this new tab
Scroll up to the top of the window and settings
In the Configurations window, click the green "+", then select x86-Release
Set Configuration type: Release
Verify Toolset: msvc_86
Keep Build Root: ${projectDir}\out\build\${name} (default, you can
change it) (this corresponds to CMAKE_BINARY_DIR)
Click on "Show advanced settings" (scroll down).
Change CMake generator: VS 16 2019 (was Ninja)
Click "Save and Generate CMake cache to load variables" once, then
Click "Save and Generate CMake cache to load variables" a second time
or select Project > Generate CMake Cache
c) Switch to the Ouput tab
Wait for "CMake generation finished".
Check the Error List window:
you should have 0 Errors and 0 Warnings.
d) Return to the CMakeSettings.json window
Review CMake variables and cache
Note that:
wxWidgets_LIB_DIR > 'C:/aud300/wxWidgets/lib/vc_dll' (your path
may be slightly different)
wxWidgets_ROOT_DIR > 'C:/aud300/wxWidgets' (your path
may be slightly different)
e) Build
Select Build > Build All
Click on the Output tab and wait for the message "Build All succeeded"
Check the Error List tab. There should be 0 Errors and 17 Warnings.
Check the output directory indicated in step 6 to find