audacity/win/compile.txt

Building Audacity(R) for Microsoft Windows(R)
Copyright (c) 1999-2015 Audacity Team

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

========================================================================
This document is for Audacity version 2.1.2.

If the advice here is inaccurate or incomplete, 
email audacity-devel@lists.sourceforge.net.
========================================================================

Audacity releases for Windows are currently built with Microsoft Visual 
Studio 2013 C++. Most of us use the Express edition, which is free. 

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.

For instructions on compiling Audacity under the Cygwin 
UNIX Emulation Layer, see the "Compiling Audacity under 
Cygwin" section below. This is not maintained (for a very long time!).


------------------------------------------------------------------------
MSVC++ STEP 1:  Download and Install wxWidgets
------------------------------------------------------------------------

To simplify the implementation of a near-identical user
interface across platforms, Audacity uses wxWidgets, a  
GUI framework. 

Audacity 2.1.2 currently requires wxWidgets 2.8.12.
(we're transitioning to wxWidgets 3.0.2. during this release...)

To be able to build Audacity for Windows, download and install 
wxWidgets from http://www.wxwidgets.org/.


------------------------------------------------------------------------
MSVC++ STEP 2:  Build wxWidgets
------------------------------------------------------------------------

2.1. Open "C:\wxWidgets-2.8.12\build\msw\wx_dll.dsw" with 
   Microsoft Visual Studio. 
   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.


2.2. If you want to use the wxWidgets accessibility features, we have 
   modified one of the wxWidgets files. Rather than provide a patch, 
   we store the modified file in the Audacity code repository, and you 
   can replace the corresponding wxWidgets file. You will need to 
   download Audacity (next step) to get these. 

   In "audacity\win\wxWidgets_additions" is one .h file. 
   You may want to make a backup of the wxWidgets original of it, 
   in "C:\wxWidgets-2.8.12\include\wx\msw\setup.h", 
   e.g., by renaming it "setup.h.bak" before copying the replacement, 
   in case you also build without these accessibility features. 

   Copy "audacity\win\wxWidgets_additions\setup.h" to 
   "C:\wxWidgets-2.8.12\include\wx\msw\setup.h".

   Audacity releases are built with these accessibility features.


2.3. Build wxWidgets for all configurations of Audacity that you want.

   With Visual Studio 2013 C++ and wxWidgets 2.8.12, 
   you will get an error for a missing pbt.h header. 
   You can (apparently safely) comment that out. 
   In audacity-src\win\wxWidgets_additions, we have a copy of 
   the file with this change already made. 
   As above, you may want to save the original by renaming 
   "C:\wxWidgets-2.8.12\src\msw\window.cpp" to 
   "C:\wxWidgets-2.8.12\src\msw\window.cpp.bak". 
   Then copy "audacity-src\win\wxWidgets_additions\window.cpp" to 
   "C:\wxWidgets-2.8.12\src\msw\window.cpp".
   
   * Use the "DLL Unicode Release" configuration to use in a 
     "Release" version of Audacity.
   * Build "DLL Unicode Debug" configuration to use in a
     "Debug" version of Audacity.

   See "MSVC++ STEP 6:  Build Audacity" for the differences
   between these versions of Audacity.

   For Audacity, you need only the following seven projects 
   to build (not the whole solution) for each configuration:
      * adv
      * base
      * core
      * html
      * net
      * qa
      * xml
   Building only these will give you a faster build, and 
   possibly smaller wxWidgets DLLs. 
   To do this, Ctrl-select those 7 projects in the Solution Explorer. 
   Then right-click and choose Build Selection (or Rebuild Selection).

   Because of dependencies, this should also build the 
   following projects.
   But on some computer configurations, they may not on VS2013, 
   so you might have to explicityly build these as well:
      * wxexpat
      * wxjpeg
      * wxpng
      * wxregex
      * wxtiff
      * wxzlib
   To be certain about this, you can just Ctrl-select them with the 
   others above, and build them all together. 

   If you build the whole solution, ignore the linker errors for 
   wxbase28*_odbc*.* dbgrid.


------------------------------------------------------------------------
MSVC++ STEP 3:  Download and Install Audacity
------------------------------------------------------------------------

To check out the latest source code from SVN, see the instructions at 
"http://audacity.sourceforge.net/community/developers". 


------------------------------------------------------------------------
MSVC++ STEP 4:  Set wxWidgets location for Audacity
------------------------------------------------------------------------

The Audacity Visual Studio project has been set up to use enviornment
variables to locate all externally referenced SDKs.  For wxWidgets, it
uses the "WXWIN" environment variable.

Before you can build Audacity, you must set the variable.  This process
can vary depending on the version of Windows you're using.  The following
is based on Windows 7, so you may need to make adjustments.

4.1. Open the "Control Panel"
4.2. Click the "System" app
4.3. Click the "Advanced system settings" link
4.4. On the "Advanced" tab, click the "Environment Variables..." button
4.5. Click "New..." in the "System variables" group
4.6. Set the "Variable name" to "WXWIN" (without the quotes)
4.7. Set the "Variable value" to the full path of where you installed
     wxWidgets (typically "C:\wxWidgets-2.8.12")
4.8. Click "OK" until you exit the "System Properties" app

An alternative way to do it, that's available on all versions of Windows, 
is to open a cmd.exe window, and type: 
   set WXWIN =C:\wxWidgets-2.8.12

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

Note that if you currently have the Audacity Solution open in Visual
Studio, you must restart Visual Studio for it to recognize the new
environment variables.

In some cases, you may need to reboot the computer to ensure 
the variables are read correctly. 


------------------------------------------------------------------------
MSVC++ STEP 5:  Consider and Configure Optional Features
------------------------------------------------------------------------

5.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, "MSVC++ STEP 4:  Set wxWidgets location for Audacity".

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.


5.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.


5.3. Some functionality in Audacity is currently turned on in its default
configuration, but requires that extra libraries be downloaded
separately to use it. 

To change the libraries enabled in Audacity, edit  
"win\configwin.h" and comment or uncomment the entries.


5.4. To add support for ASIO:

ASIO (from Steinberg) is a sound card interface protocol that is faster
than standard WMME. Unlike WMME, not all soundcard drivers support it.

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. 

For ASIO support, get the ASIO SDK from Steinberg 
(http://www.steinberg.net/en/company/developers.html), 
install at C:\ASIOSDK, then define an environment variable called
ASIOSDK_DIR.

The value should be the full path to the base directory of the
ASIO SDK, e.g.,

   set ASIOSDK_DIR=C:\ASIOSDK2


------------------------------------------------------------------------
MSVC++ STEP 6:  Build Audacity
------------------------------------------------------------------------

Run Visual C++ and load the Audacity solution, 
"audacity\win\audacity.sln".

Select the configuration that you wish to build:
* "Release" for Unicode-based, general use 
* "Debug" for a Unicode-based, slower, debuggable 
   executable

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.


------------------------------------------------------------------------
MSVC++ STEP 7:  Provide Access to the wxWidgets DLLs
------------------------------------------------------------------------

Each Audacity executable needs access to seven 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":

	wxbase28*_net_vc_custom.dll
	wxbase28*_vc_custom.dll
	wxmsw28*_adv_vc_custom.dll
	wxmsw28*_core_vc_custom.dll
	wxmsw28*_html_vc_custom.dll
        wxbase28*_xml_vc_custom.dll
        wxmsw28*_qa_vc_custom.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: 

	"u" for "Unicode Release" versions 
	"ud" for "Unicode Debug" versions

So for instance, a Debug version of Audacity should have:  

	wxbase28ud_net_vc_custom.dll
	wxbase28ud_vc_custom.dll
	wxmsw28ud_adv_vc_custom.dll
	wxmsw28ud_core_vc_custom.dll
	wxmsw28ud_html_vc_custom.dll
        wxbase28ud_xml_vc_custom.dll
        wxmsw28ud_qa_vc_custom.dll	
        
in the "audacity\win\Debug" directory.

If this procedure doesn't work, check the "Common Compilation 
Errors" section on 
http://audacityteam.org/wiki/index.php?title=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 builds, 
or 
   "Multi-threaded DLL (/MD)" for 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:

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
"msvcrt.lib" if you were attempting to perform a
Release build, or "msvcrtd.lib" for a Debug build.

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.


========================================================================

-------------------------------
Compiling Audacity under Cygwin
-------------------------------

Compiling Audacity under Cygwin is considered "experimental" 
at this time, and you may notice a few problems when you do so. 
Please be patient, and make sure to submit bug reports to the 
development team. If you follow these instructions closely, you
*should* be able to build Audacity.

These instructions will attempt to help you to compile using 
the experimental additions that appeared sometime around the 1.2 
release. They will also attempt to help you to compile Audacity 
yourself without the aforementioned support. Make sure to read 
the instructions in their entirety before beginning, because no 
matter which source tree you wind up using, all of these 
instructions are likely to assist you.

If you have problems building, make sure you've read all of 
these instructions. At the bottom there is a list of known 
bugs. If the problem you encounter is on this list, then there 
is also a workaround. Just remember to be patient, and that I 
(Dave Fancella) have successfully built Audacity on 3 different 
Windows installations with 2 different versions of Windows (XP 
and 2000 Pro). Knowing that it can be done is most of the battle.


---------------------------------
Cygwin STEP 1:  Installing Cygwin
---------------------------------

1. Install Cygwin (from "http://www.cygwin.com"). If you have 
   plenty of bandwidth available, you should use the net 
   installer.  Otherwise, you might be better off ordering a CD.

2. If you already have Cygwin installed, you should fire up 
   the installer again and compare your installed packages to 
   the list of packages needed.

3. Install the following packages: 
   (This is probably not a complete list. If you find that
   you have to install more than this, make sure to let us know 
   which ones, so they can be added to this list)
    Autoconf
  Autoconf-devel (Autoconf 2.53 is required if you need to rebuild 'configure')
  gettext-devel (for building the translation files.  If you don't want to build these,
                 you don't need this package)
  Automake
  Automake-devel
  binutils
  gcc (only tested version is 3.3.1)
  gcc-mingw
  make
  mingw-runtime
  zip (required by configure, although gzip is actually used)
  w32api


---------------------------------------
Cygwin STEP 2:  Download and install wxWidgets
---------------------------------------

1.  Go to http://www.wxwidgets.org/ and download wxWidgets v2.8.12 or greater.  Make
sure you download the "wxAll" package that contains source code for all ports.  The
Win32 port will not work for compiling Audacity, since it was compiled and installed
to work with MS Visual C++.

2.  Untar the archive from the Cygwin command line, using a command like:
tar -xzvf (wxwindows).

3.  From the top-level of the wxWidgets source tree, type './configure'.
** For some reason, I haven't been able to get Audacity to link to wxWidgets statically
under Cygwin.  Since there are bigger fish to fry right now, I haven't dealt with it.  I
would appreciate if someone gets it to work if you let me know what you did.  To try this,
use './configure --disable-shared' for wxWidgets configuration.

When complete, type "make".  When that's complete, "make install".  If all goes well,
you will have wxWidgets installed in your Cygwin installation!


---------------------------------
Cygwin STEP 3:  Download Audacity
---------------------------------

1.  Go to http://audacity.sourceforge.net/ and download the Audacity source distribution.
Cygwin is currently experimental in the 1.2 branch and SVN head, but you must have at least
Audacity v1.2.0 sources.

2.  From a cygwin prompt, go to the tarball that you downloaded and use a command like
'tar -xzvf (audacity tarball)' to open it.


-----------------------------------------
Cygwin STEP 4:  Enable Ogg Vorbis Support
-----------------------------------------

Under Cygwin, Audacity does not compile out-of-the-box with Ogg Vorbis support.  You have
a couple of hoops to jump through if you want this.  Note, if you don't do this, you will
not have any audio codec available to Audacity!  Lame is untested at this time and is
assumed not to work.  If you try it with Lame, tell us!

By default, libogg and libvorbis configure with /usr/local as the prefix.  For some
weird and inexplicable reason (i.e. I haven't figured it out yet) this doesn't work!
GCC will not find the libogg headers when you go to compile libvorbis if you install it
in the default location.  On that token, GCC will not find libvorbis headers either, so
make sure you follow these instructions explicitly.

1.  First you have to compile libogg.  From the audacity source tree root, type
'cd lib-src/libogg'.

2.  ./configure --prefix=/usr

3.  make

4.  make install

5.  cd ../libvorbis  # yep, now we have to compile vorbis

6.  ./configure --prefix=/usr

7.  make

8.  make install

If all goes well, you will have Ogg Vorbis support in your Audacity executable.


------------------------------
Cygwin STEP 5:  Build Audacity
------------------------------

This is the tricky part.  :)

Audacity comes bundled with a number of libraries that it depends on.  Usually you will
compile with those rather than any system installed libraries.  If you would prefer to use
a system installed library, you'll have to pass --with-library=/path/to/library to configure.
There are two libraries that currently do not compile in cygwin.  Those are Nyquist and
libid3tag.  If you manage to build them, please send a patch (or instructions on how you
did it)!

If you didn't enable Ogg Vorbis support as described in the previous step, you will have to
pass --without-vorbis to configure, as shown.

1.  ./configure --without-nyquist --without-id3tag [--without-vorbis]
2.  make
3.  ./audacity
4.  If you have any problems or errors, read the next section.


--------------------------------------
Notes on building Audacity with Cygwin
--------------------------------------

These notes are provided because Cygwin support is experimental, and if you run into problems,
it might help to know what was needed to make it work on my computer.

The problems that appear when compiling Audacity under Cygwin are pretty consistent in how
they appear.  The win32 port is written under the assumption that MSVC++ will be the
compiler used, and is the current standard and supported method of building Audacity.
Therefore, the problems that appear are mostly related to various symbols defined to make
Audacity compile out of the box on MSVC++.  Other problems that surface will likely
be based on the fact that Cygwin passes itself to configure as a UNIX variant, and there
are various other symbols defined for UNIX variants.  GNU/Linux is the standard UNIX variant
supported by Audacity, so you will have problems similar to what someone using OpenBSD might
encounter.  The exception is Mac OS X, which is well-supported already.

Audacity uses a series of libraries that are either required or optional, and can be set
at compile time.  The ones that are optional have --without switches for configure, the others
do not.  So if a bundled library doesn't compile, your best bet is to try disabling the library
in your configure command line.  If that doesn't work, you'll have to investigate the library
to see why it's not compiling.

PortAudio is required, and a Makefile is provided with Audacity to build it.  PortMixer is not
required, but is recommended.  This Makefile is also provided with Audacity.  Note: to my
knowledge, the Makefile for PortAudio provided with Audacity is not present in the PortAudio
distribution.  The one used with Audacity compiles PortAudio as a static library, and the
current Cygwin Makefile in the PortAudio distribution compiles as a dynamic library.  Audacity
will compile with either one, but if you use the one provided with PortAudio you will have to
make sure the PortAudio dll is in Audacity's path.  Of course, you shouldn't have any problems,
so this is probably more information than you need.  :)

Expat should compile out of the box.  If not, you might be better off trying to install the version
of expat that ships with Cygwin.  If configure fails to detect a system installed expat, this
is probably a bug and should be submitted to the Audacity developers.  You can use the system-installed
expat by passing --with-expat=system to ./configure.

Any other libraries are probably not required, and if they fail to compile you should be able
to --disable them with configure.


-----------
Configwin.h
-----------

Configwin.h is a file that exists in the win directory from the root of Audacity's source tree.
You have three options for getting gcc to find this file.  You can modify Audacity's Makefile to
include -I../win (or whatever a good path is that will point at the directory).  You can copy
or move the configwin.h file to Audacity's source directory.  Preferably, you will modify
configure.ac to generate configwin.h in exactly the same fashion and location that it already
generates configunix.h.

A fourth option is to not use Configwin.h at all, but to modify the appropriate header files to
use configunix.h.  Since this might be similar to opening a can of worms, I don't recommend this
approach.


---------------------
Dealing with #defines
---------------------

While working with this build system, there were a few files that failed to compile.  Whenever
make bombs on a file, you need to carefully note the line it made the error on and open the
source file in a good syntax highlighting editor, or you can use Wordpad, which is neither good
nor syntax highlighting.  Find the appropriate line on which the error occurred.  Then scroll
up.  Chances are very good that the line that triggered the error is wrapped in a #ifndef,
#if defined, or #ifdef block.  The #define symbol is usually __WIN32__.  You will be able to
get it to compile by making the line read something like this:

#if defined(__WIN32__) && !defined(__CYGWIN__)

In order for that to work, you will need to make sure that configure sets the __CYGWIN__ symbol to
be defined.  You may be able to just add it to Audacity's Makefile, however.  If you chose to use
the existing Configwin.h file and not have it generated by configure, then you should be able
to add a #define in it that defines __CYGWIN__.

Ultimately, if you find any of these options too difficult or time-consuming, you might consider
just deleting the entire block of code that is afflicted.  Since that route will likely wind up
making the job hundreds of times more difficult than it actually is, it is not recommended.


-----------------
Linking Audacity
-----------------

The normal Unix flags for linking will not work with Audacity.  Well, they will but they won't
include everything that needs to be linked.  Before discussing what actually needs to be linked,
it would be beneficial to discuss the win32api and Cygwin.  This discussion is surrounded on top
and bottom by **********'s, so if you already know this information you can easily skip it.

************************************************************

Cygwin is capable of compiling Windows programs that do not depend on the Cygwin runtime.  It
does this by using the Mingw libraries and header files, which are available under the GPL.
However, in order to make these libraries available to GCC, which operates thinking that it's
running on a Unix system, the libraries must be stored and named in a location that GCC (or more
specifically, LD, the linker) will understand.

On GNU systems, and likely on proprietary Unix systems as well (although I don't know this as a
fact), a library that is to be linked dynamically will have the extension .so.  A library that is
to be linked statically has the extension .a.  Furthermore, in either case the text "lib" is
prepended to the library.  When you pass a -l switch to GCC, GCC transparently passes this switch
to ld, the linker.  The text associated with -l will name the library.  For example:  If you pass
-lfoobar, ld will receive it.  In order to actually find the library, ld must prepend "lib" and
append ".a", and then search in its known library locations.  So it will search for a file called
"libfoobar.a" in its known library locations.

The known library locations vary from system to system.  On some GNU/Linux systems, the known
library locations are stored in a special file called "ldconfig".  Cygwin does not, however.  It
appears to know by magic where the libraries are stored.  You will find them in /usr/lib,
/usr/local/lib, /usr/share/lib, and ~/.lib.  If you look around your Cygwin installation, you'll
find a directory /usr/lib/w32api.  In this directory is stored all of the Mingw libraries that
allow you to link to the win32api.  If you've ever worked with MSVC++, you'll probably recognize
the names of these libraries.  There's kernel32, odbc32, winmm, and the rest.  But they're named
with ld's peculiar naming convention, libkernel32.a, libodbc32.a, and libwinmm.a respectively in
this example.

*************************************************************

From the MSVC++ project file, here are the libraries that need to be linked statically for
Audacity to successfully build.

kernel32.lib user32.lib gdi32.lib winspool.lib
comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib
odbc32.lib odbccp32.lib wsock32.lib winmm.lib

You can also obtain this list by modifying the Audacity Makefile to use
`wx-config --static --libs` instead of `wx-config --libs` which it already uses.  Currently,
Audacity will not build with `wx-config --static --libs`.  If you get it to work, let us know!

----------
Known Bugs
----------

First of all, expect your resulting build to work differently in little ways than a build made with
MSVC++.

Here is a list of currently known bugs in Audacity's build and the resulting executable.  Any help
fixing these bugs would be greatly appreciated.

*  Zoom does not center around cursor
*  Audacity does not associate itself with filetypes  (It's #if !defined out, the code works in
MSVC++)
*  libsndfile fails to configure on some systems.  If this happens, the known workaround is to
configure libsndfile manually and then configure audacity again.