home.md

@@ -2,38 +2,100 @@
 
 ITACoreLibs are a collection of C++ libraries with basic tools for virtual acoustics including real-time audio streaming components for synthesis and reproduction.
 
-## Quick build guide
+# 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*.
 
-The ITA code base uses the build environment of [Vista VR Toolkit](http://www.itc.rwth-aachen.de/cms/IT-Center/Forschung-Projekte/Virtuelle-Realitaet/Infrastruktur/~fgmo/ViSTA-Virtual-Reality-Toolkit/), maintained by the [Virtual Acoustics Reality Group](http://www.itc.rwth-aachen.de/cms/IT-Center/Forschung-Projekte/~eubl/Virtuelle-Realitaet/) of [RWTH Aachen University](http://www.rwth-aachen.de). It is based on [CMake](http://www.cmake.org) with some macro extensions to ease finding external projects that expose a certain folder structure. You will have to download the following before you can start:
+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](https://github.com/cpm-cmake/CPM.cmake).
 
-+ GIT (git for windows and, for convenience, TortoiseGit)
-+ CMake
-+ Development environment such as Visual Studio 2014 with Visual Studio Compiler 12 (vc12)
-+ ViSTA preferably from [GIT](https://devhub.vr.rwth-aachen.de/VR-Group/ViSTA) or alternatively from [sourceforge.org](https://sourceforge.net/projects/vistavrtoolkit/files/)
-+ VistaCMakeCommon preferably from [GIT](https://devhub.vr.rwth-aachen.de/VR-Group/VistaCMakeCommon) or alternatively from [sourceforge](https://sourceforge.net/projects/vistavrtoolkit/files/) (switch to 'develop' or 'ita' branch for newest features)
-+ ExternalLibs (copy from ITA server at share/vr/dev/ExternalLibs or include this resource as a network drive within ITA network)
+## 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](old build system).
 
-### Clone repositories (GIT)
+## Requirements
+### General requirements
 
-Clone the repositories you want to aquire to your local file system. Some projects use submodules, so always **check out recursively** or initialize the submodules afterwards.
+- 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 (only tested with Visual C++ 19)
 
-### Prepare CMake
+In case you are using Visual Studio, you can use the integrated CMake version. See [Windows with Visual Studio](#windows-with-visual-studio) section for further information.
 
-In order to register additional vista macros and to help CMake to find the external libs, please add the following to your system environment variable list:
+External libraries are automatically downloaded and configured for you!
+For exceptions, see [Special requirements](#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.
+
+## 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
+
+1. Open the CMake GUI
+2. Point to the project directory for the source code (e.g. via `Browse Source...`)
+3. 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`.
+4. Press `Configure` and specify your generator (e.g. `Visual Studio 16 2019`)
+5. Press `Generate`
+6. Press `Open Project`
+7. 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
+
+```bash
+mkdir build
+cd build
+cmake ..
+cmake --build
+cmake --install
 ```
-VISTA_CMAKE_COMMON=C:/path/to/VistaCMakeCommon
-VISTA_EXTERNAL_LIBS=C:/path/to/ExternalLibs
-```
 
-Now you can start CMake, set the source code to the project you want to build and create project files, i.e. an ITACoreLibs.sln (Solution file for Visual Studio).
 
-We recommend to use a naming similar to 'build_win32-x64.vc12' for a project file with win64 architecture for the Visual Studio 12 compiler, but any other name such as a simple 'build' is possible.
+## 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](#general-requirements).  
+  Note, that the **C++ CMake Tools for Windows** have to be installed with Visual Studio ([reference](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=msvc-160)).
+
+### Build
+
+1. Start Visual Studio.
+2. Click on `Continue without code`/`Ohne Code fortfahren`.
+3. `File`/`Datei` -> `Open`/`Öffnen` -> `CMake...`.
+4. Choose the top-level `CMakeLists.txt` file.
+5. Wait till the configuration is finished.
+6. `Build`/`Erstellen` -> `Build all`/`Alle erstellen` or `Install "PROJECT NAME"`/`"PROJECT NAME" installieren`.
+7. 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*`
+
 
-### Add-on components
+## Linux
 
-ITACoreLibs requires third-party libraries for a few add-on components. For example, if you want to enable features such as reading WAV files, required external packages have to be found by CMake, in this case `libsndfile`. Follow the instructions from [ViSTA VR Toolkit documentation](https://sourceforge.net/projects/vistavrtoolkit/files/) on how to make your life easier with external libs.
+For now, see [General CMake](#general-cmake).
 
-### Latest updates
+## Apple OSX
 
-Follow the latest updates on the [Akustik-Blog](http://blog.rwth-aachen.de/akustik/category/software).
+For now, see [General CMake](#general-cmake).
\ No newline at end of file