ITACoreLibs Wiki
ITACoreLibs are a collection of C++ libraries with basic tools for virtual acoustics including real-time audio streaming components for synthesis and reproduction.
Build guide
This tutorial explains how to build (most of) the C++ libraries of the Institute for Hearing Technology and Acoustics at RWTH Aachen University.
Our projects use CMake as a build system generator. To ease the build process, most external libraries are downloaded during the configuration and build with the main project. This is done using the CMake Package Manager.
Build system rework
This guide is for the new version of the build system, which was reworked in the beginning of 2022. If you work with code versions from 2021 or before, please refer to the old build guide.
Requirements
General requirements
- git Version 2.29 or higher (Version 2.26 and lower does not work)
- CMake Version 3.20.6 or higher
- C++11 compatible compiler (tested with Visual C++ 2019 & 2022)
In case you are using Visual Studio, you can use the integrated CMake version. See Windows with Visual Studio section for further information.
External libraries are automatically downloaded and configured for you! For exceptions, see Special requirements.
Special requirements
For certain modules, additional external libraries have to be manually included:
- For VAMatlab and ARTMatlab: Matlab (recently modern version)
CMake option to disable VAMatlab:ITA_VA_WITH_BINDING_MATLAB
Default:OFF
CMake option to disable ARTMatlab:ITA_GEOMETRICAL_ACOUSTICS_WITH_APPS_MATLAB
Default:OFF
- For VAPython: Python (>= 3.7)
CMake option to disable module:ITA_VA_WITH_BINDING_PYTHON
Default:OFF
- For ITAGeometricalAcoustics/ITAGeo: SketchUp SDK, minimum version 2019
Cannot be disabled if dependency towards ITAGeo exists - For pigeon application: Qt, version 5.15.2
CMake option to disable module:ITA_GEOMETRICAL_ACOUSTICS_WITH_APPS_QT
Default:OFF
These dependencies have to be downloaded separately and made known to CMake. This is done via the CMake variables SketchUpAPI_DIR
and Qt5_DIR
. Note, that these variables can also be environment variables to work. For Qt, Qt5_DIR
should point to *Qt Version*\*Compiler*\lib\cmake\Qt5
. For SketchUp, SketchUpAPI_DIR
should point to the sketchup-yyyy
directory, e.g. D:/ExternalLibs/SketchUp/sketchup-2021
.
In case you are working at our institute, these libraries can be found on our server.
Optional requirements
These are optional requirements that can be useful when developing any of the IHTA projects.
-
doxygen: Used for generating documentation for some projects.
- dot, from graphviz: Used for generating inheritance diagrams for doxygen.
- OpenCppCoverage: When installed, coverage reports will be generated for the unit test.
- ccache: Can be used to speed up compilation, see Speed up options for more info.
Known issues
CMake has a character limit for its build paths. This means, that the path to some source files can be too long. In these cases CMake will issue a warning. If this happens, try to move the top-level source folder up in your directory tree. A safe place should be the main drive folder, e.g. D:\
.
General CMake
Build via CMake GUI
- Open the CMake GUI
- Point to the project directory for the source code (e.g. via
Browse Source...
) - As build directory, specify a direct subfolder of the project directory. The folder name should start with or being called
build
, e.g.D:/Development/ITACoreLibs/build
. - Press
Configure
and specify your generator (e.g.Visual Studio 16 2019
) - Press
Generate
- Press
Open Project
- Done!
You can use the CMake variables to configure the project. For example, it is possible to de-/activate certain modules.
Build via command line
mkdir build
cd build
cmake ..
cmake --build
cmake --install
Windows with Visual Studio
Another way to build this project on windows. Does not require a separate installation of CMake. However, CMake configuration can be tricky sometimes.
Visual Studio version
- Visual Studio 2019, Version 16.10.4 and above; lower versions will also work.
The limiting factor is the bundled CMake version, which should match the general requirements.
Note, that the C++ CMake Tools for Windows have to be installed with Visual Studio (reference).
Build
- Start Visual Studio.
- Click on
Continue without code
/Ohne Code fortfahren
. -
File
/Datei
->Open
/Öffnen
->CMake...
. - Choose the top-level
CMakeLists.txt
file. - Wait till the configuration is finished.
-
Build
/Erstellen
->Build all
/Alle erstellen
orInstall "PROJECT NAME"
/"PROJECT NAME" installieren
. - And you are done.
The build results can be found in
*project_folder*/out/build/*build_configuration*/[Debug|Release|...]
While the install results can be found in*project_folder*/out/install/*build_configuration*
Linux
For now, see General CMake.
Apple OSX
For now, see General CMake.
Speed up options
There are a few options for speeding up both the compilation and the configuration of the projects through caching. When used in combination, it can speed up the compilation even further. Some information can be found here.
CPM cache
CPM offers the option to cache any call to CPMAddPackage
.
When this is done, any external package only needs to be downloaded once.
Any later call, i.e. another configuration, does not download anything, speeding up the configuration set significantly.
To use this, pass -DCPM_SOURCE_CACHE=<path to an external download directory>
to CMake when configuring.
Preferably use an absolute path.
Then the cache can be easily shared between projects.
The CMake variable can also be set as an environment variable, see this for further info.
ccache
Similar to CPM ccache caches the compiler invocations. When the same invocation is found, the cached object file is used.
In order to enable ccache, some further options have to be passed to CMake when configuring:
-
-G Ninja
or-G Ninja Multi-Config
, the ccache can only be invoked when using makefile or ninja generators. -
-DCMAKE_CXX_COMPILER_LAUNCHER=ccache
actually use ccache when compilingcpp
files -
-DCMAKE_C_COMPILER_LAUNCHER=ccache
same forc
files. -
-DCMAKE_MSVC_DEBUG_INFORMATION_FORMAT=Embedded
when using msvc, the default compiler invocation uses the/Zi
flag (store debug info inpdb
file). This flag is not supported ccache at the moment. As a result, no invocation can be stored. By setting theCMAKE_MSVC_DEBUG_INFORMATION_FORMAT
toEmbedded
, the flag-Z7
will be used which is supported by ccache (see this for further info;-Z7
stores debug info in object file, making it a bit bigger). Sadly, this is a newer feature of CMake and requires at least version 3.25. In addition, the following option also has to be passed to CMake. -
-DCMAKE_POLICY_DEFAULT_CMP0141=NEW
enablesCMAKE_MSVC_DEBUG_INFORMATION_FORMAT
feature.
The whole list is:
-DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_MSVC_DEBUG_INFORMATION_FORMAT=Embedded -DCMAKE_POLICY_DEFAULT_CMP0141=NEW
ccache can be configured using conf
files.
The documentation can be found here.
The global config file should be placed in C:\ProgramData\ccache\ccache.conf
.