compile.txt

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

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


========================================================================
This document is for Audacity version 2.3.0 

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

WE ARE MOVING FROM WXWIDGETS 3.0.2 to 3.1.1 AND FROM MSVC 2013 to 
MSVC 2017.  CURRENTLY THIS DOCUMENT MAY HAVE A FEW ERRORS AND OMISSIONS 
RELATING TO THAT.  THESE SHOULD BE FIXED BY MAY 12TH 2018.  DETAILS?
ASK ON 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.


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

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

Audacity 2.3.0 can on windows use wxWidgets 3.1.1 without patches.

For versions of Audacity that need a patched wxWidgets,
download our patched wxWidgets from the 'audacity-fixes-3.1.1'
branch of https://github.com/audacity/wxWidgets

------------------------------------------------------------------------
MSVC++ STEP 2:  Download source code for Audacity
------------------------------------------------------------------------

Checkout the latest Audacity code from our GitHub repository 
at https://github.com/audacity/audacity/ (see GitHub for help).


------------------------------------------------------------------------
MSVC++ STEP 3:  Build wxWidgets
------------------------------------------------------------------------
These steps assume the wxWidgets source code was extracted to
the root of C:\ and renamed "C:\wxWidgets-3.1.1\".

3.1. Open "C:\wxWidgets-3.1.1\build\msw\wx_XXX.sln" with 
   Microsoft Visual Studio, where XXX is the version for your compiler.
   XXX is 12 for MSVC 2013.
 
3.2. Build wxWidgets for all configurations of Audacity that you want.

   * Use the "DLL Release" configuration to use in a 
     "Release" version of Audacity.
   * Build "DLL Debug" configuration to use in a
     "Debug" version of Audacity.

You're encouraged to try out the samples in wxWidgets to check that 
wxWidgets is built and working.
     
------------------------------------------------------------------------
MSVC++ STEP 4:  Set wxWidgets location for Audacity
------------------------------------------------------------------------

The Audacity Visual Studio project has been set up to use environment
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-3.1.1")
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-3.1.1

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. 

If you are in a hurry, you can skip step 5.

------------------------------------------------------------------------
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
https://sourceforge.net/projects/cppcms/files/boost_locale/gettext_for_windows/
 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://audacityteam.org/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:\ASIOSDK


------------------------------------------------------------------------
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-3.1.1\lib\vc_dll":

	wxbase311*_net_vc_custom.dll
	wxbase311*_vc_custom.dll
	wxmsw311*_adv_vc_custom.dll
	wxmsw311*_core_vc_custom.dll
	wxmsw311*_html_vc_custom.dll
        wxbase311*_xml_vc_custom.dll
        wxmsw311*_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:  

	wxbase311ud_net_vc_custom.dll
	wxbase311ud_vc_custom.dll
	wxmsw311ud_adv_vc_custom.dll
	wxmsw311ud_core_vc_custom.dll
	wxmsw311ud_html_vc_custom.dll
        wxbase311ud_xml_vc_custom.dll
        wxmsw311ud_qa_vc_custom.dll	
        
in the "audacity\win\Debug" directory.


------------------------------------------------------------------------
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 and our windows project file ONLY has 
DLL linkage, so we think this problem has gone.  If it does happen, check the
following:

In MSVC 2013, select the Audacity project. Then 
   Project > Properties > Configuration 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.

If you still receive errors, it often helps to try it again with 
a clean installation of the wxWidgets sources and the latest Audacity
source from GitHub. Also check "Common compilation errors" on:   
http://wiki.audacityteam.org/wiki/Developing_On_Windows#common
for more assistance.