> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opentrack/opentrack/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="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)

    <Note>
      For detailed Visual Studio setup, refer to the [Visual C++ 2015 build instructions](https://github.com/opentrack/opentrack/wiki/Building-under-MS-Visual-C---2017-and-later) in the OpenTrack wiki.
    </Note>
  </Tab>

  <Tab title="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)

    ```bash theme={null}
    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)

    ```bash theme={null}
    sudo dnf install gcc-c++ cmake git \
      qt5-qtbase-devel qt5-qttools-devel \
      opencv-devel eigen3-devel
    ```

    <Note>
      See the [Linux build instructions](https://github.com/opentrack/opentrack/wiki/Building-on-Linux) on the OpenTrack wiki for distribution-specific details.
    </Note>
  </Tab>

  <Tab title="macOS">
    ### Build Tools

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

    ### Install with Homebrew

    ```bash theme={null}
    brew install cmake qt opencv eigen
    ```

    <Warning>
      macOS support is currently **unmaintained**. The build may require additional fixes and patches.
    </Warning>
  </Tab>
</Tabs>

## Building OpenTrack

<Steps>
  <Step title="Clone the Repository">
    Clone the OpenTrack source code from GitHub:

    ```bash theme={null}
    git clone https://github.com/opentrack/opentrack.git
    cd opentrack
    ```
  </Step>

  <Step title="Create Build Directory">
    Create a separate build directory (out-of-source build):

    ```bash theme={null}
    mkdir build
    cd build
    ```

    <Note>
      CMake enforces out-of-source builds. In-source builds are disabled by the build system.
    </Note>
  </Step>

  <Step title="Configure with CMake">
    Run CMake to configure the build:

    <CodeGroup>
      ```bash Release Build theme={null}
      cmake .. -DCMAKE_BUILD_TYPE=RELEASE
      ```

      ```bash Debug Build theme={null}
      cmake .. -DCMAKE_BUILD_TYPE=DEBUG
      ```

      ```bash Custom Install Path theme={null}
      cmake .. -DCMAKE_BUILD_TYPE=RELEASE \
        -DCMAKE_INSTALL_PREFIX=/custom/path
      ```
    </CodeGroup>

    <Note>
      If `CMAKE_BUILD_TYPE` is not specified, it defaults to `RELEASE`.
    </Note>
  </Step>

  <Step title="Build the Project">
    Compile OpenTrack using your build system:

    <CodeGroup>
      ```bash Make (Linux/macOS) theme={null}
      make -j$(nproc)
      ```

      ```bash Ninja theme={null}
      ninja
      ```

      ```bash MSBuild (Visual Studio) theme={null}
      msbuild opentrack.sln /p:Configuration=Release
      ```
    </CodeGroup>

    The `-j$(nproc)` flag enables parallel compilation using all available CPU cores.
  </Step>

  <Step title="Install (Optional)">
    Install OpenTrack to the configured prefix:

    ```bash theme={null}
    make install
    ```

    or on Windows:

    ```bash theme={null}
    cmake --build . --target install
    ```

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

## CMake Configuration Options

OpenTrack's build system provides several configuration options:

### Compiler Flags

The build system sets optimization flags automatically:

<CodeGroup>
  ```cmake Release Flags (GCC) theme={null}
  CMAKE_C_FLAGS_RELEASE="-O3 -march=native"
  CMAKE_CXX_FLAGS_RELEASE="-O3 -march=native"
  ```

  ```cmake Debug Flags (GCC) theme={null}
  CMAKE_C_FLAGS="-ggdb -Wall -Wextra -Wpedantic"
  CMAKE_CXX_FLAGS="-ggdb -Wall -Wextra -Wpedantic"
  ```
</CodeGroup>

### Custom Build Options

```cmake theme={null}
# 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 theme={null}
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:

```cmake theme={null}
set(opentrack_all-translations "de_DE;nl_NL;ru_RU;stub;zh_CN")
```

## Troubleshooting Build Issues

<AccordionGroup>
  <Accordion title="Qt Not Found">
    **Problem:** CMake cannot find Qt libraries.

    **Solution:**

    Set the `CMAKE_PREFIX_PATH` to your Qt installation:

    ```bash theme={null}
    cmake .. -DCMAKE_PREFIX_PATH=/path/to/qt5
    ```

    Or use `Qt5_DIR`:

    ```bash theme={null}
    cmake .. -DQt5_DIR=/path/to/qt5/lib/cmake/Qt5
    ```
  </Accordion>

  <Accordion title="OpenCV Not Found">
    **Problem:** OpenCV headers or libraries are missing.

    **Solution:**

    Install OpenCV development packages or specify the path:

    ```bash theme={null}
    cmake .. -DOpenCV_DIR=/path/to/opencv/cmake
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Link Errors on Linux">
    **Problem:** Undefined references during linking.

    **Solution:**

    Ensure all development packages are installed:

    ```bash theme={null}
    sudo apt-get install libgl1-mesa-dev libglu1-mesa-dev
    ```

    On Unix systems, the math library is automatically linked:

    ```cmake theme={null}
    if(UNIX)
        target_link_libraries(${target} PRIVATE m)
    endif()
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    cd /path/to/opentrack
    rm -rf CMakeCache.txt CMakeFiles/
    mkdir build
    cd build
    cmake ..
    ```
  </Accordion>
</AccordionGroup>

## Building Individual Modules

You can build specific targets:

```bash theme={null}
# 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:

<CardGroup cols={2}>
  <Card title="Plugin Development" icon="puzzle-piece" href="/advanced/plugin-development">
    Learn how to create custom trackers, filters, and protocols
  </Card>

  <Card title="Contributing" icon="code-pull-request" href="/advanced/contributing">
    Contribute code, translations, or documentation
  </Card>

  <Card title="Portable Mode" icon="usb-drive" href="/advanced/portable-mode">
    Create a portable USB installation
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/advanced/troubleshooting">
    Resolve common runtime issues
  </Card>
</CardGroup>