diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 000000000..e7b93efa7 --- /dev/null +++ b/BUILDING.md @@ -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`.](https://docs.conan.io/en/latest/installation.html) + +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](https://cmake.org/download/). + +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](https://visualstudio.microsoft.com/vs/community/). 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 https://github.com/audacity/audacity/ + ``` + +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 https://github.com/audacity/audacity/ + ``` + +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 https://github.com/audacity/audacity/ + ``` + +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 + $ 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/). \ No newline at end of file diff --git a/INSTALL b/INSTALL index a80ff06e9..9faa21e58 100644 --- a/INSTALL +++ b/INSTALL @@ -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 https://github.com/audacity/audacity/blob/master/BUILDING.md You can ask for help with compilation problems at: http://forum.audacityteam.org/viewforum.php?f=19 . diff --git a/linux/build.txt b/linux/build.txt deleted file mode 100644 index c1bc9020e..000000000 --- a/linux/build.txt +++ /dev/null @@ -1,92 +0,0 @@ -Instructions for Building on Linux - -Fuller instructions can be found on our wiki at http://wiki.audacityteam.org/wiki/Building_On_Linux. - -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 ( http://www.cmake.org/ ) 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 - - -wxWidgets: - - 1) Clone wxWidgets and checkout 3.1.3 from the Audacity fork of the - wxWidgets project: - https://github.com/audacity/wxWidgets/.... - - for example - mkdir ./wxWidgets - cd ./wxWidgets - git clone --recurse-submodules https://github.com/audacity/wxWidgets/ - - 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 - https://github.com/audacity/wxWidgets/blob/audacity-fixes-3.1.3/docs/gtk/install.md - - So... - - mkdir buildgtk - cd buildgtk - ../configure --with-gtk - make - su - make install - ldconfig - - 3) Having got this far, it is well worth trying out building some wxWidgets - examples to confirm that building has worked OK - -Audacity: - -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 - ./audacity - diff --git a/mac/cmake_build.txt b/mac/cmake_build.txt deleted file mode 100644 index 9a4523730..000000000 --- a/mac/cmake_build.txt +++ /dev/null @@ -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 https://github.com/audacity/audacity - -3) Clone wxWidgets 3.1.3: - - git clone --recurse-submodules https://github.com/audacity/wxWidgets.git - - Ensure that you clone with the "--recurse-submodules" option, and do not - just download the Zip package, otherwise there will be required components - missing. - - 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: - - https://github.com/audacity/wxWidgets/tree/audacity-fixes-3.1.3 - - 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 /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: - - https://cmake.org/download - -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 - line. - - You are now ready to start building Audacity. - -BUILDING USING THE CMAKE GUI - - 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. - -BUILDING FROM THE COMMAND LINE - -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 "Audacity.app" bundle will be in the "bin/Release" subdirectory of your - "build" folder, so you can start it via Finder or: - - open bin/Release/Audacity.app - -Notes: - - - 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 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: - http://wiki.audacityteam.org/wiki/Building_On_Mac - diff --git a/win/build.txt b/win/build.txt deleted file mode 100644 index c32135114..000000000 --- a/win/build.txt +++ /dev/null @@ -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 -http://wiki.audacityteam.org/wiki/Building_On_Windows - - -1. MSVC 2019: Download and install Microsoft Visual Studio 2019 - - https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=16 - 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: https://git-scm.com/download/win - and optionally GitExtensions: http://gitextensions.github.io/ - - 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 https://www.python.org/downloads/windows/ - 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: - https://github.com/audacity/wxWidgets/ - - for example, in the git-bash command line: - mkdir wxWidgets - git clone --recurse-submodules https://github.com/audacity/wxWidgets/ - - 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 - https://github.com/audacity/wxWidgets/blob/audacity-fixes-3.1.3/README-GIT.md - https://github.com/audacity/wxWidgets/blob/audacity-fixes-3.1.3/docs/msw/install.md - - 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. - https://github.com/audacity/audacity/ - - for example, in the git-bash command line - mkdir audacity - git clone https://github.com/audacity/audacity/ - - 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 - `../bin/Release/Audacity.exe` -