Building from Source

Complete guide to building OpenTrack from source code on Windows, Linux, and macOS

OpenTrack can be built from source on Windows, Linux, and macOS. The build process uses CMake and requires Qt along with platform-specific build tools.

Prerequisites

Windows

Build Tools

Choose one of the following:

• MinGW-w64 (recommended for cross-platform compatibility)
• Microsoft Visual Studio 2015 Update 3 or newer

Required Dependencies

• CMake 3.13 or later
• Qt 5.x or Qt 6.x
• Git (for cloning the repository)

For detailed Visual Studio setup, refer to the Visual C++ 2015 build instructions in the OpenTrack wiki.

Linux

Build Tools

• GCC (GNU Compiler Collection)
• LLVM/Clang (alternative to GCC)
• CMake 3.13 or later
• Qt 5.x or Qt 6.x development packages
• Git

Install Dependencies (Debian/Ubuntu)

sudo apt-get update
sudo apt-get install build-essential cmake git \
  qtbase5-dev qttools5-dev qttools5-dev-tools \
  libqt5gui5 libqt5widgets5 libqt5core5a \
  libopencv-dev libeigen3-dev

Install Dependencies (Fedora/RHEL)

sudo dnf install gcc-c++ cmake git \
  qt5-qtbase-devel qt5-qttools-devel \
  opencv-devel eigen3-devel

See the Linux build instructions on the OpenTrack wiki for distribution-specific details.

macOS

Build Tools

• Xcode Command Line Tools
• CMake 3.13 or later
• Qt 5.x or Qt 6.x
• Git

Install with Homebrew

brew install cmake qt opencv eigen

macOS support is currently unmaintained. The build may require additional fixes and patches.

Building OpenTrack

1. Clone the Repository

   Clone the OpenTrack source code from GitHub:

   git clone https://github.com/opentrack/opentrack.git
   cd opentrack
   
2. Create Build Directory

   Create a separate build directory (out-of-source build):

   mkdir build
   cd build
   

   CMake enforces out-of-source builds. In-source builds are disabled by the build system.

3. Configure with CMake

   Run CMake to configure the build:

   Release Build

   cmake .. -DCMAKE_BUILD_TYPE=RELEASE
   

   If CMAKE_BUILD_TYPE is not specified, it defaults to RELEASE.

4. Build the Project

   Compile OpenTrack using your build system:

   Make (Linux/macOS)

   make -j$(nproc)
   

   The -j$(nproc) flag enables parallel compilation using all available CPU cores.

5. Install (Optional)

   Install OpenTrack to the configured prefix:

   make install
   

   or on Windows:

   cmake --build . --target install
   

   By default, files are installed to <build-directory>/install.

CMake Configuration Options

OpenTrack’s build system provides several configuration options:

Compiler Flags

The build system sets optimization flags automatically:

Release Flags (GCC)

CMAKE_C_FLAGS_RELEASE="-O3 -march=native"
CMAKE_CXX_FLAGS_RELEASE="-O3 -march=native"

Custom Build Options

# Disable specific trackers or protocols
cmake .. -DCMAKE_BUILD_TYPE=RELEASE \
  -DSDK_ENABLE_HYDRA=OFF \
  -DSDK_ENABLE_RIFT=OFF

# Install debug symbols (MSVC only)
cmake .. -DCMAKE_BUILD_TYPE=RELEASE \
  -Dopentrack_install-debug-info=ON

Build System Architecture

CMake Minimum Version

OpenTrack requires CMake 3.13 or later:

cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
project(opentrack)

Module Organization

The build system uses custom CMake functions defined in cmake/opentrack-boilerplate.cmake:

• otr_module() - Defines a module (plugin, library, or executable)
• otr_glob_sources() - Automatically finds source files
• otr_install_lib() - Handles library installation

Available Translations

OpenTrack supports multiple languages:

set(opentrack_all-translations "de_DE;nl_NL;ru_RU;stub;zh_CN")

Troubleshooting Build Issues

Qt Not Found

Problem: CMake cannot find Qt libraries.

Solution:

Set the CMAKE_PREFIX_PATH to your Qt installation:

cmake .. -DCMAKE_PREFIX_PATH=/path/to/qt5

Or use Qt5_DIR:

cmake .. -DQt5_DIR=/path/to/qt5/lib/cmake/Qt5

OpenCV Not Found

Problem: OpenCV headers or libraries are missing.

Solution:

Install OpenCV development packages or specify the path:

cmake .. -DOpenCV_DIR=/path/to/opencv/cmake

Compiler Version Too Old

Problem: Compiler doesn’t support C++17 features.

Solution:

OpenTrack requires a modern C++ compiler:

• GCC 7.0+
• Clang 5.0+
• MSVC 2015 Update 3+

Update your compiler or install a newer version.

Link Errors on Linux

Problem: Undefined references during linking.

Solution:

Ensure all development packages are installed:

sudo apt-get install libgl1-mesa-dev libglu1-mesa-dev

On Unix systems, the math library is automatically linked:

if(UNIX)
    target_link_libraries(${target} PRIVATE m)
endif()

In-Source Build Error

Problem: CMAKE_DISABLE_IN_SOURCE_BUILD error.

Solution:

OpenTrack enforces out-of-source builds. Delete CMakeCache.txt and CMakeFiles/ from the source directory, then build in a separate directory:

cd /path/to/opentrack
rm -rf CMakeCache.txt CMakeFiles/
mkdir build
cd build
cmake ..

Building Individual Modules

You can build specific targets:

# Build only the main executable
make opentrack

# Build a specific tracker
make opentrack-tracker-aruco

# Build a specific protocol
make opentrack-proto-freetrack

# Clean build artifacts
make clean

# Clean everything including CMake cache
make mrproper

Next Steps

After successfully building OpenTrack:

Plugin Development

Learn how to create custom trackers, filters, and protocols

Contributing

Contribute code, translations, or documentation

Portable Mode

Create a portable USB installation

Troubleshooting

Resolve common runtime issues