Building from Source

Note

This page contains generic build instructions for CosmoScout VR. Alternatively, you can follow a guide specific to your IDE.

CosmoScout VR supports 64 bits only and can be build in debug and release mode on Linux and Windows. You will need a copy of CMake (version 3.22 or greater), Boost (version 1.69 or greater) and a recent C++ compiler (gcc 7, clang 5 or msvc 19). For the compilation of the externals Python is also required.

1. Downloading External Dependencies

   Before you start, it may be necessary to install some additional system packages.

   Windows

   Getting a precompiled version of boost suitable for CosmoScout VR which will be found by CMake can be difficult: Older CMake versions fail to find boost versions which are too new; but on the other hand you need a rather new version if you use a very recent version of MSVC (e.g. 14.2, the one shipped with Visual Studio 2019). The “oldest” precompiled boost which you can get on SourceForge for MSVC 14.2 is version 1.70.0.

   So using version 1.70.0 may work in most cases. You can get it from from https://sourceforge.net/projects/boost/files/boost-binaries/1.70.0

   MSVC	Visual Studio	File	Link
   14.2	2019	boost_1_70_0-unsupported-msvc-14.2-64.exe	download
   14.1	2017	boost_1_70_0-msvc-14.1-64.exe	download
   14.0	2015	boost_1_70_0-msvc-14.0-64.exe	download

   Note

   If you want that CosmoScout VR detects your 3DConnexion Space Navigator, you have to download and install the 3DConnexion SDK. Then you need to add one line to the make_externals.bat but file as described here.

   Linux

   As there are many distributions with varying default libs and available packages, giving an exhaustive list is difficult. Here is an exemplary list for Ubuntu 20.04 which you have to adapt to your specific distribution:

   sudo apt-get install git cmake build-essential xorg-dev libboost-all-dev libglu1-mesa-dev libssl-dev libxkbcommon0

2. Cloning the Repository

   Once these dependencies are installed, you can clone the repository. Open a terminal in a directory where you want to store the source code and execute the following commands:

   git clone https://github.com/cosmoscout/cosmoscout-vr.git
   cd cosmoscout-vr
   git submodule update --init --recursive

   Maximum Path Length on Windows

   During compilation of the externals, files with pretty long names are generated. Since Windows does not support paths longer 260 letters, you have to compile CosmoScout VR quite close to your file system root (e.g. C:\cosmoscout-vr). If you are on Windows 10, you can disable this limit.

3. Building Bundled Dependencies

   This step only has to be done once. It will compile all dependencies which are bundled as git submodules in the build directory and install them to the install directory.

   Tip

   If you wish, you can delete the directories build and install (or their respective subdirectories) at any time in order to force a complete reconfiguration or re-installation.

   Per default, all dependencies are built in release mode using precompiled headers and unity builds where possible. This behavior can be adjusted using some environment variables:

   Variable	Default	Description
   COSMOSCOUT_DEBUG_BUILD	false	Set to true to build everything in debug mode.
   COSMOSCOUT_USE_UNITY_BUILD	true	Set to false to disable unity builds.
   COSMOSCOUT_USE_PCH	true	Set to false to not use precompiled headers.

   You should set these as required before executing the scripts below.

   Windows

   If you are using Visual Studio 2017, you have to replace -G "Visual Studio 16 2019" -A x64 with -G "Visual Studio 15 Win64". All parameters given to make_externals.bat will be forwarded to CMake. For example, you can change the CMake generator this way.

   make_externals.bat -G "Visual Studio 16 2019" -A x64

   Linux

   All parameters given to make_externals.sh will be forwarded to CMake. For example, you can change the CMake generator this way.

   ./make_externals.sh -G "Unix Makefiles"

   Speed up your Builds!

   Windows

   You can use clcache to considerably speed up build times. You just need to call make_externals.bat -G "Visual Studio 15 Win64" -DCMAKE_VS_GLOBALS="CLToolExe=clcache.exe;TrackFileAccess=false".

   Linux

   You can use ccache to considerably speed up build times. You just need to call ./make_externals.sh -G "Unix Makefiles" -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_C_COMPILER_LAUNCHER=ccache.

4. Building CosmoScout VR

   One can either use CMake Presets or build the software manually using CMake. Using CMake Presets is easy and definitely the recommended way.

   Setting variables

   You can override preset variables by simply setting them in the command line after the preset name e.g.:

   cmake --preset <preset-name> -DCOSMOSCOUT_UNIT_TESTS=Off
   cmake --build --preset <preset-name> --parallel 2

   You can also create your own presets by creating CMakeUserPresets.json and inherit from a global preset or define your completely own preset.

   Windows

   set BOOST_ROOT=C:\local\boost_1_70_0
   
   # You can get a list of available configuration
   # presets using the following command:
   cmake --list-presets
   
   # After you decided for a preset you can
   # configure with the following command:
   cmake --preset <preset-name>
   
   # If you want to use clache:
   # cmake --preset <preset-name> -DCMAKE_VS_GLOBALS=CLToolExe"=clcache.exe;TrackFileAccess=false"
   
   # The next step is to build CosmoScout VR.
   # You can also list build presets:
   cmake --build --list-presets
   
   # After you decided for a preset you can build with the following command:
   cmake --build --preset <preset-name>

   Linux

   # You can get a list of available configuration
   # presets using the following command:
   cmake --list-presets
   
   # After you decided for a preset you can
   # configure with the following command:
   cmake --preset <preset-name>
   
   # If you want to use ccache:
   # cmake --preset <preset-name> -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_C_COMPILER_LAUNCHER=ccache
   
   # The next step is to build CosmoScout VR.
   # You can also list build presets:
   cmake --build --list-presets
   
   # After you decided for a preset you can build with the following command:
   cmake --build --preset <preset-name>

   Caution

   Be aware that the configure and build presets need to match!

5. Running CosmoScout VR

   Windows

   install\windows-Release\bin\start.bat

   Linux

   install/linux-Release/bin/start.sh

   The application can be started with the command above. When started for the very first time, some example datasets will be downloaded from the internet. This will take some time! The progress of this operation is shown on the loading screen.

6. Optional: Running Tests

   If you specified -DCOSMOSCOUT_UNIT_TESTS=On at build time, you can now execute the unit tests with:

   Windows

   install\linux-Release\bin\run_tests.bat

   Linux

   install/linux-Release/bin/run_tests.sh
   install/linux-Release/bin/run_graphical_tests.sh