Browse Source

update cmake documentation

Nick Appleton 1 year ago
2 changed files with 45 additions and 16 deletions
  1. 43
  2. 2

+ 43
- 15
doc/src/tutorial/compile_cmake.dox View File

@@ -1,29 +1,57 @@
/** @page compile_cmake Creating MSVC Build Files via CMake
/** @page compile_cmake PortAudio on Windows, OS X or Linux via. CMake
@ingroup tutorial

This is a simple "How-to" for creating build files for Microsoft Visual C++ via CMake and the CMakeLists.txt file
@section cmake_building Building PortAudio stand-alone on Windows, OS X or Linux

1. Install CMake if you haven't got it already ([], minimum version required is 2.8).
CMake can be used to generate Visual Studio solutions on Windows, Makefiles (on Linux and OS X) and build metadata for other build systems for PortAudio. You should obtain a recent version of CMake from [] if you do not have one already. If you are unfamiliar with CMake, this section will provide some information on using CMake to build PortAudio.

2. If you want ASIO support you need to D/L the ASIO2 SDK from Steinberg, and place it according to \ref compile_windows_asio_msvc
On Linux, CMake serves a very similar purpose to an autotools "configure" script - except it can generate build metadata apart from Makefiles. The equivalent of the following on POSIX'y systems:

3. Run the CMake GUI application and browse to <b>source files</b> directory and <b>build</b> directory:
a. The <b>source files</b> directory (<i>"Where is the source code"</i>) is where the portaudio CMakeLists.txt file is located.
b. The <b>build</b> directory (<i>"Where to build the binaries"</i>) is pretty much anywhere you like. A common practice though is to have the build directory located <b>outside</b> the
source files tree (a so called "out-of-source build")
build_path> {portaudio path}/configure --prefix=/install_location
build_path> make
build_path> make install

4. Click <i>Configure</i>. This will prompt you to select which build files to generate. <b>Note</b> Only Microsoft Visual C++ build files currently supported!
Would be:

5. In the CMake option list, enable the PORTAUDIO_xxx options you need, then click <i>Configure</i> again (Note that after this there are no options marked with red color)
build_path> cmake {portaudio path} -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/install_location
build_path> make
build_path> make install

6. Click <i>Generate</i> and you'll now (hopefully) have your VS build files in your previously defined <b>build</b> directory.
The "-G" option specifies the type of build metadata which will be generated. You can obtain a list of supported build metadata formats by invoking (on any platform):

Both ASIO and DirectX SDK are automatically searched for by the CMake script, so if you have DirectX SDK installed and have placed the ASIO2 SDK according to point 2 above, you should be able to build portaudio with !DirectSound and ASIO support.
cmake -G

Should you later on decide to change a portaudio option, just jump in at step 5 above (MSVC will then prompt you to reload projects/solutions/workspace)
"make install" should install the same set of files that are installed using the usual configure script included with PortAudio along with a few extra files (similar to pkg-config metadata files) which make it easier for other CMake projects to use the installed libraries.

--- Robert Bielik
On Windows, you can use CMake to generate Visual Studio project files which can be used to create the PortAudio libraries. The following serves as an example (and should be done from a directory outside the PortAudio tree) which will create Visual Studio 2015 project files targetting a 64-bit build:

Back to the Tutorial: \ref tutorial_start
C:\PABUILD> cmake {portaudio path} -G "Visual Studio 14 2015 Win64"

After executing the above, you can either open the generated solution with Visual Studio or use CMake to invoke the build process. The following shows an example of how to build a release configuration (assuming the above command was executed previously in the same directory):

C:\PABUILD> cmake --build . --config Release

If you want ASIO support you need to obtain the ASIO2 SDK from Steinberg and place it according to \ref compile_windows_asio_msvc. Both ASIO and the DirectX SDK are automatically searched for by the CMake script - if they are found, they will be enabled by default.

@section cmake_using Using PortAudio in your CMake project

PortAudio defines the following CMake targets:

- "portaudio_static" for a static library and
- "portaudio" for a dynamic library

If you installed PortAudio as described above in \ref cmake_building and the install prefix you used (CMAKE_INSTALL_PREFIX) is in your system PATH or CMAKE_MODULE_PATH CMake variable, you should be able to use:


To define the "portaudio_static" and "portaudio" targets in your CMake project.

If you do not want to install portaudio into your system but would rather just have it get built as part of your own project (which may be particularly convenient on Windows), you may also use:

add_subdirectory("path to PortAudio location" "some binary directory" EXCLUDE_FROM_ALL)

EXCLUDE_FROM_ALL is not strictly necessary, but will ensure that targets which you don't use in your project won't get built.

Back to \ref tutorial_start


+ 2
- 1
doc/src/tutorial/tutorial_start.dox View File

@@ -15,12 +15,13 @@ Once you've downloaded PortAudio you'll need to compile it, which of course, dep
- \ref compile_windows
- \ref compile_windows_mingw
- \ref compile_windows_asio_msvc
- \ref compile_cmake
- Mac OS X
- \ref compile_mac_coreaudio
- \ref compile_linux

You can also use CMake to generate project files for PortAudio on Windows, OS X or Linux or include PortAudio easily in your own CMake project. See \ref compile_cmake.

Many platforms with GCC/make can use the simple ./configure && make combination and simply use the resulting libraries in their code.

@section tut_start3 Programming with PortAudio