Building¶

This document provides detailed build instructions for all supported platforms.

📋 Dependency Reference: All package names for each platform are defined in .github/dependencies.yml — the single source of truth used by both CI pipelines and this documentation.

Prerequisites¶

Compiler Requirements¶

Platform	Minimum Compiler
Linux	GCC 9+ or Clang 10+
Windows	MSVC 2019 (v142) or later
macOS	Xcode 12+ (Apple Clang 12+)

Required Tools¶

CMake 3.16 or later
Git (for cloning and submodules)
Doxygen (optional, for documentation)
pkg-config (Linux, required when not using vcpkg to locate LZ4/ZSTD)

Installation Methods¶

This project supports two methods for dependency management:

Option A: vcpkg (Recommended) - Automatic dependency management
Option B: Manual - System package managers or manual installation

Build Policy and Linkage Expectations¶

Build/test policy in this repository:

base (manual/system packages) is a compatibility path and CI smoke-check, not the preferred packaging path.
vcpkg is the recommended default on Linux/macOS and the standard path on Windows for executable-focused development.
vcpkg-windows-static-md is an optional Windows preset for packaging scenarios that prefer static libraries with dynamic MSVC runtime.

Linkage expectations:

Configuration	Intent	Protobuf expectation
`base` + system packages (Linux)	Compatibility validation	Often shared (`.so`)
`vcpkg` (Linux/macOS)	Preferred/release-oriented dependency model	Static (`.a`)
`vcpkg` (Windows)	General executable-focused development	Triplet-dependent
`vcpkg-windows-static-md` (Windows)	Packaging/static-linkage-oriented workflows	Static triplet model
`vcpkg-shared-linux` (Linux)	Shared OSI library for plugin architectures	`x64-linux-dynamic` triplet; all deps shared
`vcpkg-shared-macos` (macOS)	Shared OSI library for plugin architectures	`arm64-osx-dynamic` triplet; all deps shared

Build Flag Matrix¶

Flag	Default	Effect
`BUILD_TESTING`	`OFF`	Builds unit tests (`cpp/tests/`).
`OSIUTILITIES_RUN_TESTS`	`OFF`	Runs tests after build (implies `BUILD_TESTING=ON`).
`BUILD_DOCS`	`OFF`	Builds documentation (Doxygen XML + Sphinx HTML).
`BUILD_EXAMPLES`	`ON`	Builds example programs (`cpp/examples/`).
`OSIUTILITIES_DOCS_ONLY`	`OFF`	Docs-only build (skips library/examples/tests).
`LINK_WITH_SHARED_OSI`	`OFF`	Link utils with shared OSI library instead of static.

Notes:

cmake --preset vcpkg is equivalent to explicitly setting -DBUILD_TESTING=OFF -DOSIUTILITIES_RUN_TESTS=OFF as long as you start from a clean build directory.
If you enable tests with vcpkg, also pass -DVCPKG_MANIFEST_FEATURES=tests so GTest is installed.

Documentation (Doxygen + Sphinx)¶

Documentation is generated by a CMake target named library_api_doc. It runs Doxygen (XML output) followed by Sphinx with Breathe to produce unified HTML covering both the C++ and Python APIs. It is not part of the default build and requires additional dependencies; enable it with BUILD_DOCS=ON. For a docs-only configuration (skips library, examples, and tests), use OSIUTILITIES_DOCS_ONLY=ON.

The simplest way to build docs locally is via the root Makefile:

make docs build

This creates a Python virtual environment, installs Sphinx dependencies, runs Doxygen and Sphinx, and writes HTML to doc/html/index.html.

To build and immediately preview in a browser:

make run docs

This builds the docs (if needed) and starts a local HTTP server at http://localhost:8000.

Alternatively, using CMake directly:

git submodule update --init --recursive
cmake --preset base -DBUILD_DOCS=ON
cmake --build --preset base --target library_api_doc

Generated HTML is written to doc/html/index.html.

If you use vcpkg, install docs tools with the docs feature (for example, set VCPKG_MANIFEST_FEATURES=docs).

Linux¶

Option A (Linux): Using vcpkg (Recommended)¶

(Linux) 1. Install Build Tools¶

Debian/Ubuntu:

sudo apt update
sudo apt install -y yq
yq -r '.dependencies.vcpkg_host.apt | unique | .[]' .github/dependencies.yml | \
    xargs sudo apt install -y

Fedora/RHEL:

sudo dnf install -y yq
yq -r '.dependencies.vcpkg_host.dnf | unique | .[]' .github/dependencies.yml | \
    xargs sudo dnf install -y

When using vcpkg, avoid installing system protobuf/lz4/zstd packages to prevent mixing toolchains. vcpkg will provide those dependencies.

Optional extras:

# Docs tools
yq -r '.dependencies.docs.apt | unique | .[]' .github/dependencies.yml | xargs sudo apt install -y

# Docs tools (dnf)
yq -r '.dependencies.docs.dnf | unique | .[]' .github/dependencies.yml | xargs sudo dnf install -y

(Linux) 2. Install vcpkg¶

git clone https://github.com/microsoft/vcpkg ~/vcpkg
~/vcpkg/bootstrap-vcpkg.sh
echo 'export VCPKG_ROOT="$HOME/vcpkg"' >> ~/.bashrc
source ~/.bashrc

(Linux) 3. Clone and Build¶

git clone --recurse-submodules https://github.com/lichtblick-suite/asam-osi-utilities.git
cd asam-osi-utilities
cmake --preset vcpkg
cmake --build --preset vcpkg --parallel $(nproc)

(Linux) 3b. Build & Install the Python SDK¶

The Python SDK is built separately from the C++ library using pip:

pip install ./python            # install from source
pip install ./python[dev]       # install with development extras (pytest, ruff, mypy)

Or via the Makefile (creates a virtual environment automatically):

make setup      # create venv + editable install with dev extras
make test python  # run Python tests

(Linux) 4. Run Tests¶

Configure with -DBUILD_TESTING=ON first (for vcpkg, set VCPKG_MANIFEST_FEATURES=tests).

ctest --test-dir build-vcpkg --output-on-failure -j$(nproc)

Option B (Linux): Manual Dependencies¶

(Linux) 1. Install All Dependencies¶

Debian/Ubuntu:

sudo apt update
sudo apt install -y yq
yq -r '.dependencies.build.apt | unique | .[]' .github/dependencies.yml | \
    xargs sudo apt install -y

Fedora/RHEL:

sudo dnf install -y yq
yq -r '.dependencies.build.dnf | unique | .[]' .github/dependencies.yml | \
    xargs sudo dnf install -y

Optional extras:

# Test dependencies
yq -r '.dependencies.test.apt | unique | .[]' .github/dependencies.yml | xargs sudo apt install -y
yq -r '.dependencies.test.dnf | unique | .[]' .github/dependencies.yml | xargs sudo dnf install -y

# Docs tools
yq -r '.dependencies.docs.apt | unique | .[]' .github/dependencies.yml | xargs sudo apt install -y
yq -r '.dependencies.docs.dnf | unique | .[]' .github/dependencies.yml | xargs sudo dnf install -y

(Linux) 2. Clone and Build¶

git clone --recurse-submodules https://github.com/lichtblick-suite/asam-osi-utilities.git
cd asam-osi-utilities
cmake --preset base
cmake --build --preset base --parallel $(nproc)

Windows¶

Option A (Windows): Using vcpkg (Recommended)¶

(Windows) 1. Install Build Tools¶

Using winget (Windows Package Manager):

Note: If winget fails while searching the msstore source (e.g. certificate/proxy issues), force the community repository with --source winget or disable the store source:

winget source disable msstore

Then re-run the install command.

# PowerShell 7 (recommended for vcpkg)
winget install --id Microsoft.PowerShell --source winget

# yq (used to read .github/dependencies.yml)
winget install --id MikeFarah.yq --source winget

# Install from .github/dependencies.yml
yq -r '.dependencies.vcpkg_host.winget | unique | .[]' .github/dependencies.yml |
    ForEach-Object { winget install --id $_ --source winget }

# Visual Studio 2022 Build Tools (workload override)
winget install --id Microsoft.VisualStudio.2022.BuildTools --source winget `
    --override "--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

Note: Open a new terminal after installation to pick up PATH changes.

Graphviz on Windows (troubleshooting): dot.exe must be runnable for Doxygen diagrams. Verify in PowerShell: dot -V.

If dot -V works in PowerShell but fails in Git Bash/MSYS with an error like error while loading shared libraries and a missing libltdl-7.dll, install MSYS2 and the missing runtime, then add the MinGW runtime folder to your PATH:

Install MSYS2: winget install --id MSYS2.MSYS2 --source winget

In the MSYS2 MinGW x64 shell:

pacman -Syu

pacman -S --needed mingw-w64-x86_64-libtool

Add C:\msys64\mingw64\bin to PATH (or copy libltdl-7.dll next to dot.exe).

Optional docs tools:

yq -r '.dependencies.docs.winget | unique | .[]' .github/dependencies.yml |
    ForEach-Object { winget install --id $_ --source winget }

(Windows) 2. Install vcpkg¶

git clone https://github.com/microsoft/vcpkg C:\vcpkg
C:\vcpkg\bootstrap-vcpkg.bat
[System.Environment]::SetEnvironmentVariable('VCPKG_ROOT', 'C:\vcpkg', 'User')

Open a new terminal to pick up the environment variable.

(Windows) 3. Clone and Build¶

git clone --recurse-submodules https://github.com/lichtblick-suite/asam-osi-utilities.git
cd asam-osi-utilities
cmake --preset vcpkg
cmake --build --preset vcpkg --parallel

If you need static-library-oriented packaging behavior on Windows, use:

cmake --preset vcpkg-windows-static-md
cmake --build --preset vcpkg-windows-static-md --parallel

(Windows) 4. Run Tests¶

Configure with -DBUILD_TESTING=ON first (for vcpkg, set VCPKG_MANIFEST_FEATURES=tests).

ctest --test-dir build-vcpkg -C Release --output-on-failure

Option B (Windows): Manual Dependencies¶

Manual dependency installation on Windows without vcpkg is significantly more complex and not recommended. You would need to:

Build protobuf from source
Build lz4 from source
Build zstd from source
Build googletest from source
Configure CMake to find all libraries

If you must use this approach, consider using Conan or building with CMake’s FetchContent.

macOS¶

macOS builds are supported only via vcpkg. Homebrew/system dependency builds are not supported.

Follow the Linux vcpkg instructions:

git clone https://github.com/microsoft/vcpkg ~/vcpkg
~/vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT="$HOME/vcpkg"
cmake --preset vcpkg
cmake --build --preset vcpkg --parallel $(sysctl -n hw.ncpu)

Configure with -DBUILD_TESTING=ON first (for vcpkg, set VCPKG_MANIFEST_FEATURES=tests).

Generating Test Fixtures¶

Some tests (e.g. NCAP scenario and esmini fixture tests) require binary .osi and .mcap trace files that are checked into the repository via Git LFS. If you need to regenerate them locally, a script downloads esmini and runs headless simulations.

Prerequisites: Build the project with examples enabled first, then run the script:

# Build with examples (needed for convert_gt2sv and convert_osi2mcap)
cmake --preset vcpkg -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON -DVCPKG_MANIFEST_FEATURES=tests
cmake --build --preset vcpkg --parallel

# Generate fixtures (downloads esmini + NCAP scenarios into a temp dir)
./scripts/generate_test_traces.sh

The script produces 11 fixture files in test-data/ (tracked via Git LFS). Without these files the fixture-based tests will skip gracefully via GTEST_SKIP.

CMake Presets¶

The project includes CMake presets for common configurations:

Preset	Description
`base`	Standard build without vcpkg (manual dependencies needed)
`vcpkg`	Build with vcpkg (`VCPKG_ROOT` required), default for Linux/macOS and common Windows executable workflows
`vcpkg-windows-static-md`	Windows vcpkg build for static-library-oriented packaging with dynamic MSVC runtime

Use presets with:

cmake --preset <preset-name>
cmake --build --preset <preset-name>

CMake Options¶

Option	Default	Description
`BUILD_EXAMPLES`	`ON`	Build example programs
`BUILD_DOCS`	`OFF`	Enable the `library_api_doc` target
`OSIUTILITIES_DOCS_ONLY`	`OFF`	Build docs only (implies `BUILD_DOCS=ON`, disables tests/examples)
`BUILD_TESTING`	`OFF`	Build unit tests
`OSIUTILITIES_RUN_TESTS`	`OFF`	Run tests as part of the default build (implies `BUILD_TESTING`)
`CODE_COVERAGE`	`OFF`	Enable code coverage (GCC only)

Example:

cmake --preset base -DBUILD_EXAMPLES=OFF -DBUILD_TESTING=ON

When using vcpkg and BUILD_TESTING=ON, enable the tests manifest feature (for example, set VCPKG_MANIFEST_FEATURES=tests) to install GTest.

Dependency mapping (system packages vs vcpkg):

System-package builds (no vcpkg): use dependencies.build.*, plus dependencies.test.* and/or dependencies.docs.* as needed.
vcpkg builds: install only dependencies.vcpkg_host.* (tools). Library deps (protobuf/lz4/zstd/gtest) come from vcpkg.json. Enable vcpkg features like tests/docs via VCPKG_MANIFEST_FEATURES.

Build combinations (what you actually install):

Linux system build (cmake --preset base): dependencies.build.apt|dnf
Add dependencies.test.* for tests, dependencies.docs.* for docs, dependencies.lint.* for clang-tidy, and dependencies.coverage.* for coverage.
vcpkg build (Linux/macOS/Windows): dependencies.vcpkg_host.* only (CMake, git, curl, zip/unzip, pkg-config).
All C/C++ libraries (protobuf, lz4, zstd, gtest) come from vcpkg.json.
CI note: Ubuntu system-package jobs install from ci_jobs.*.apt. vcpkg jobs do not install protobuf/lz4/zstd via apt/dnf.

Troubleshooting¶

vcpkg: First Build is Slow¶

The first build with vcpkg takes 10-15 minutes because it compiles protobuf, abseil, and other dependencies from source. Subsequent builds use vcpkg’s binary cache.

vcpkg: Configure Fails on Windows¶

If cmake configure fails, try:

Delete the build folder completely
Open a new terminal (ensure VCPKG_ROOT is set)
Run cmake configure again

Remove-Item -Recurse -Force build-vcpkg
cmake --preset vcpkg

If you are using the static-md path, rerun configure with cmake --preset vcpkg-windows-static-md.

Corporate Proxy Issues¶

If vcpkg downloads fail behind a proxy:

Windows:

netsh winhttp import proxy source=ie

Linux/macOS:

export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

Protobuf Version Mismatch¶

If you see protobuf-related errors, ensure you’re not mixing system protobuf with vcpkg protobuf. Use one method consistently.

Submodules Not Initialized¶

If you see missing file errors:

git submodule update --init --recursive

Next Steps¶

Integration Guide - Use OSIUtilities in your downstream project
Development Setup - Configure your development environment
Examples - Learn how to use the library