Windows compilation notes

Compiling Audacity(R) for Microsoft Windows(TM) copyright (c) 1999-2011 Audacity Team

Authors: Asger Ottar Alstrup, Vince Busam, Dave Fancella, Vaughan Johnson, Steve Jolly, Leland Lucius, Markus Meyer, Shane Mueller, Lynn Allan, Martyn Shaw

======================================================================== This version is currently accurate for Audacity version 1.3.14. If you find the advice here inaccurate or incomplete, please e-mail feedback@audacityteam.org. ========================================================================

Audacity releases are now built with Microsoft Visual C++ 9 (a.k.a Visual C++ 2008) generically known as "VC9".

Note that Audacity uses VC++'s multithreaded DLL runtime libraries. If you have MSVC installed, these are in your PATH, but users to whom you distribute your builds may not have them, so you may have to distribute them, as described for the wxWidgets DLLs, below.

Download wxWidgets
To simplify the implementation of a near-identical user interface across platforms, Audacity uses classes and resources from wxWidgets, a portable GUI framework for C++ (and Python). You must download and build wxWidgets before attempting to compile Audacity, or nothing will work!

wxWidgets is available at "http://www.wxwidgets.org/".

Audacity 1.3.14 requires wxWidgets 2.8.12.

To build on Windows only, download the wxMSW package (installer or zip).

Build wxWidgets
When you have downloaded and installed wxWidgets, the next step is to build it.

Open "C:\wxWidgets-2.8.12\build\msw\wx_dll.dsw" with Visual Studio 2008 (for VC9). Make sure to use wx_dll.dsw, not wx.dsw, because wx.dsw does not have the correct dependencies for the DLL builds. When you open wx_dll.dsw, Visual Studio will prompt whether to convert. Click "Yes To All". Next time you open a Visual Studio session, you can avoid this prompt by opening "C\wxWidgets-2.8.12\build\msw\wx_dll.sln" instead of wx_dll.dsw.

If you want to use the accessibility features, we have modified one of the wxWidgets files. Rather than provide a patch, we   store any modified files in the Audacity code repository, and you can replace the corresponding wxWidgets files.

In "audacity\win\wxWidgets_additions" is one ".h" file. You may want to make backups of the wxWidgets original of it, in case you also build without these accessibility features. Audacity releases are built with these accessibility features.
 * Copy "setup.h</tt>" to "C:\wxWidgets-2.8.12\include\wx\msw\</tt>".

Build wxWidgets for all configurations of Audacity that you want. See " for the differences between these versions of Audacity.
 * Build "DLL Release" to use in a "Release" version of Audacity.
 * Build "DLL Unicode Release" to use in a "Unicode Release" version of Audacity.
 * Build "DLL Debug" to use in a "Debug" version of Audacity.
 * Build "DLL Unicode Debug" to use in a "Unicode Debug" version of Audacity.

If you use "Batch Build" under the "Build" menu, you need select only the following five projects to build (not the whole solution) for each configuration:
 * adv
 * base
 * core
 * html
 * net

Because of dependencies, this should also build these projects: If you build the whole solution, ignore the linker errors for wxbase28*_odbc*.* dbgrid.
 * wxexpat
 * wxjpeg
 * wxpng
 * wxregex
 * wxtiff
 * wxzlib

Download Audacity
Now you can download Audacity. To check out the latest source code from SVN, see the instructions at "http://audacity.sourceforge.net/community/developers".

Set wxWidgets location for Audacity
Before you can start the build process, you must update the project settings to tell Visual C++ where to find wxWidgets. There are three settings that need changing: Fortunately, this is parameterized, using a Windows system environment variable. There are various ways to set these, so look in the Windows help system. You want to create an environment variable WXWIN, set to the top-level directory where you installed wxWidgets. For example, in your "autoexec.bat" file, you might have a line: set WXWIN=C:\wxWidgets-2.8.12 Note that you don't want a trailing backslash on that.
 * 1) Include Directory (e.g., "C:\wxWidgets-2.8.12\include")
 * 2) Resource Directory (e.g., "C:\wxWidgets-2.8.12\include")
 * 3) Library Directory (e.g., "C:\wxWidgets-2.8.12\lib")

On newer version of Windows, the settings for environment variables can be found in the system control panel. Click the "System" option, then the "Extended" or "Advanced" tab, then "Environment variables". In the Audacity project file, there are declarations like $(WXWIN)\include that get interpreted as, e.g., "C:\wxWidgets-2.8.12\include".

Once you have set the WXWIN environment variable correctly, the Audacity project file's declarations will do the rest.

Note that you have at least to restart the IDE so it picks up changes in the environment variables. It is safer to reboot the computer to ensure the variables are read correctly.

Consider and Configure Optional Features
1. Locally installed help is optional, but required for a full Release build. (The "help" folder is included in the installer, but removed from the zip distribution.) The Python library is required, obtainable from http://www.python.org/download/. Add the location of the top-level directory where you installed Python to your Path environment variable. For instructions on setting environment variables, see the previous section, "".

Build the "help" project by enabling it in the MS Visual Studio Configuration Manager (Build menu). This will download a copy of the Manual wiki onto your machine and copy it to the correct place for your build. If the local copy needs to be updated, run
 * audacity\scripts\mw2html_audacity\wiki2htm.bat

and re-build the "help" project.

2. To support languages other than English in your build of Audacity, you must enable and build the optional "locale" project. This is required for a full release. You will need to obtain msgfmt.exe from
 * http://audacity.sourceforge.net/files/msgfmt.zip

Add the location of the directory containing msgfmt.exe to your Path environment variable. Alternatively, put msgfmt.exe somewhere already in the Path, e.g., C:\Windows.

3. Some functionality in Audacity is currently turned on its default configuration, but requires that extra libraries be downloaded separately to use it.
 * To allow export of MP3 files, download LAME:
 * http://manual.audacityteam.org/index.php?title=FAQ:Installation_and_Plug-Ins#lame


 * To allow import and export of a much wider range of audio formats (including WMA, M4A and AC3), and to import audio from video files, download FFmpeg:
 * http://www.audacityteam.org/manual/index.php?title=FAQ:Installation_and_Plug-Ins#installffmpeg

To change the libraries that are enabled in Audacity, open the file "win\configwin.h" and comment or uncomment the libraries as desired.

4. DirectSound (Microsoft) and ASIO (Steinberg) are sound card interface protocols that are more efficient than the standard WMME. Unlike WMME, not all sound card drivers support them.

TO ADD SUPPORT FOR DIRECTSOUND
Install the DirectX SDK from Microsoft (http://msdn.microsoft.com/directx). The installation will automatically define the DXSDK_DIR environment variable and its presence will cause DirectSound support to be automatically included when Audacity is built. Audacity releases from 1.3.7 onwards include DirectSound support.

TO ADD SUPPORT FOR ASIO
Because ASIO is a PROPRIETARY, closed standard, we (or any third party) cannot distribute its SDK. That means we cannot distribute builds of Audacity that support ASIO, because Audacity is licensed under the GPL (http://audacity.sourceforge.net/about/license), which requires we distribute all source code.

So, although you can build your own copies of Audacity with ASIO support, for personal use, you cannot distribute them without violating the Audacity license and the ASIO license. If you build ASIO support into Audacity, do not distribute that build.

If you would like ASIO support, install the ASIO SDK from Steinberg (http://www.steinberg.net ... select Company, then Developer), install at C:\ASIOSDK, then define an environment variable called ASIOSDK_DIR, as for WXWIN, above. The value should be the full path to the base directory of the ASIO SDK, e.g.,
 * set ASIOSDK_DIR=C:\ASIOSDK2

Build Audacity
Run Visual C++ and load the Audacity solution, "audacity\win\audacity.sln". Select the configuration that you wish to build: You can select the configuration from the Solution Configurations pull-down menu, or select it from the "Build" menu > "Configuration Manager..." dialog box. Build Audacity by giving the "Build" menu > "Rebuild Solution" command.
 * "Release" for general use
 * "Unicode Release" for Unicode-based, general use
 * "Debug" for a slower but debuggable executable
 * "Unicode Debug" for a Unicode-based, slower, debuggable executable

Provide Access to the wxWidgets DLLs
Each Audacity executable needs access to five specific wxWidgets DLLs from those you built in "MSVC++ STEP 2: Build wxWidgets"  above. You can copy them to your Windows PATH, or more simply, to the same directory as the executable. If you are building Audacity for public release using the *.iss installer script, you must copy them to the executable directory. The DLLs required are at "C:\wxWidgets-2.8.12\lib\vc_dll": The "*" in the file names above is replaced in the actual files by a suffix specific to its Widgets configuration. You can identify the DLLs needed for each Audacity version as follows: So for instance, a Unicode Debug version of Audacity should have: in the "audacity\win\unicode debug" directory.
 * wxbase28*_net_vc_custom.dll
 * wxbase28*_vc_custom.dll
 * wxmsw28*_adv_vc_custom.dll
 * wxmsw28*_core_vc_custom.dll
 * wxmsw28*_html_vc_custom.dll
 * "" (no suffix) for "Release" versions
 * "u" for "Unicode Release" versions
 * "d" for "Debug" versions
 * "ud" for "Unicode Debug" versions
 * wxbase28ud_net_vc_custom.dll
 * wxbase28ud_vc_custom.dll
 * wxmsw28ud_adv_vc_custom.dll
 * wxmsw28ud_core_vc_custom.dll
 * wxmsw28ud_html_vc_custom.dll

If this procedure doesn't work, check the "Common Compilation Errors" section on Developing_On_Windows.

If you still need help after that, please ask on the "Compiling Audacity" board at http://forum.audacityteam.org/. However, the first suggestion there is likely to be "try it again with a clean installation of the wxWidgets source and the latest Audacity source from SVN". So if that's not what you attempted, please try that first.

HELP! I get linker errors!
In some cases, Audacity does compile, but during the linking process you get a bunch of error messages like this:
 * LIBCMTD.lib(LIBCMTD.dll) : error LNK2005: _free already defined in MSVCRTD.lib(dbgheap.obj)

This is usually caused by conflicting runtime library settings. Audacity is now linked with DLL linkage. In VC9, select the Audacity project. Then Project > Properties > C/C++ > Code Generation > Runtime Library should be
 * "Multi-threaded Debug DLL (/MDd)" for Debug or Unicode Debug builds,

or
 * "Multi-threaded DLL (/MD)" for Release or Unicode Release builds.

Make sure you set the correct library type for all corresponding build configurations. Also make sure you check all other libraries, like the Ogg Vorbis libraries, if you have them installed.

You may want to use the /VERBOSE:LIB linker parameter to get information about which library is causing the conflict.

If all else fails, use the following procedure to force Audacity to link to the correct library: "msvcrt.lib" if you were attempting to perform a Release build, or "msvcrtd.lib" for a Debug build.
 * Select the Audacity project in Solution Explorer.
 * Then choose Project > Properties.
 * Select the desired configuration (e.g., "Debug" or "Release").
 * Select the "Linker" folder in the tree on the left, and the "Input" item. In the "Ignore Specific Library" field, enter

On some systems, you will need to ignore "libcmt.lib" or "libcmtd.lib" instead of "msvcrt.lib" or "msvcrtd.lib", depending on the library which actually causes the conflict.

Note that if you have configured all libraries correctly, none of the above should actually be necessary.