Complete build, install, and downstream-integration guide.

This page is the canonical reference for building libpromeki from source, configuring its feature flags, running its tests, installing it, and consuming it from a downstream CMake project. Every user-facing CMake option is documented here.

Requirements

A C++20 compiler (GCC 11+ or Clang 14+ recommended)
CMake 3.22 or newer
git (required — the build clones vendored dependencies via submodules)

Some vendored libraries (libjpeg-turbo, SVT-JPEG-XS) contain hand-written SIMD assembly. When nasm or yasm is on PATH those libraries build their accelerated code paths; without an assembler they still build, but without the SIMD fast paths.

Optional host tooling picked up automatically when present:

Tool	Purpose
`ccache`	Compiler launcher — near-zero cost cache hits on branch switches and whitespace edits
`/usr/bin/time` (GNU)	Records per-TU compile wall-time and peak RSS (`PROMEKI_BUILD_STATS`)
`doxygen`	Builds this documentation (`PROMEKI_BUILD_DOCS`)
CUDA Toolkit	Enables GPU MemSpaces and is required for NVENC / NVDEC
NVIDIA Video Codec SDK	Enables NVENC / NVDEC — see NVENC setup

Quick Start

git clone --recurse-submodules https://github.com/jthwho/libpromeki.git
cd libpromeki
cmake -B build
cmake --build build -j$(nproc)

This produces libpromeki.so, libpromeki-tui.so, the unit-test binaries, the demos, and the utility programs under build/ using the default DevRelease build type.

Build Types

libpromeki recognises three CMake build types. The build type controls optimisation, debug symbols, and whether per-module debug logging (promekiDebug()) is compiled in. See Debugging andDiagnostics" for the full discussion; the short version is: <table class="markdownTable"> <tr class="markdownTableHead"> <th class="markdownTableHeadNone"> Build type

Optimisation

Debug symbols

promekiDebug()

Typical use

Debug

-O0

Yes

Compiled in

Step-through debugging, sanitizers

DevRelease (default)

-O3

Yes (-g)

Compiled in

Day-to-day development, CI, profiling

Release

-O3

No

Compiled out

Distribution / final packaging

cmake -B build -DCMAKE_BUILD_TYPE=Release

Feature Flags

Feature flags control what gets compiled into libpromeki.so. Disabling a feature removes its sources, its headers, and (when it is the only consumer) its vendored third-party dependency. All flags are exposed in the generated include/promeki/config.h so consuming code can conditionally compile against a custom build.

Option	Default	Description
`PROMEKI_ENABLE_NETWORK`	`ON`	Networking (sockets, RTP, SDP)
`PROMEKI_ENABLE_PROAV`	`ON`	Pro A/V (image, audio, color, pipeline)
`PROMEKI_ENABLE_MUSIC`	`ON`	Music / MIDI support
`PROMEKI_ENABLE_PNG`	`ON`	PNG image I/O (libspng)
`PROMEKI_ENABLE_JPEG`	`ON`	JPEG codec (libjpeg-turbo)
`PROMEKI_ENABLE_JPEGXS`	auto	JPEG XS codec (SVT-JPEG-XS; auto-enabled on x86-64 when nasm/yasm is present)
`PROMEKI_ENABLE_FREETYPE`	`ON`	FreeType font rendering
`PROMEKI_ENABLE_AUDIO`	`ON`	Audio file I/O (libsndfile)
`PROMEKI_ENABLE_SRC`	`ON`	Audio sample-rate conversion (libsamplerate)
`PROMEKI_ENABLE_CSC`	`ON`	SIMD color-space conversion (Highway)
`PROMEKI_ENABLE_CIRF`	`ON`	Compiled-in resource filesystem (`:/.PROMEKI/...`)
`PROMEKI_ENABLE_V4L2`	auto	V4L2 video capture + ALSA audio capture (Linux only; auto-enabled when the headers are present)
`PROMEKI_ENABLE_CUDA`	auto	CUDA support (device / pinned-host memspaces; prerequisite for NVENC / NVDEC)
`PROMEKI_ENABLE_NVENC`	auto	NVIDIA NVENC H.264 / HEVC encoder — see NVENC setup
`PROMEKI_ENABLE_NVDEC`	auto	NVIDIA NVDEC H.264 / HEVC decoder — see NVENC setup

Flags marked auto default ON when their prerequisites are detected and OFF otherwise. Pass an explicit -DPROMEKI_ENABLE_X=ON / OFF on the command line to override the probe.

Vendored vs. System Dependencies

All third-party libraries are vendored as git submodules under thirdparty/ and linked statically with -fPIC into libpromeki.so. This is the default and the recommended configuration — a single shared library with no transitive dependency surprises.

Each vendored dependency can individually be switched to a system-installed copy:

Option	Default	Library
`PROMEKI_USE_SYSTEM_ZLIB`	`OFF`	zlib / zlib-ng
`PROMEKI_USE_SYSTEM_LIBSPNG`	`OFF`	libspng
`PROMEKI_USE_SYSTEM_LIBJPEG`	`OFF`	libjpeg-turbo
`PROMEKI_USE_SYSTEM_SVT_JPEG_XS`	`OFF`	SVT-JPEG-XS
`PROMEKI_USE_SYSTEM_FREETYPE`	`OFF`	FreeType
`PROMEKI_USE_SYSTEM_SNDFILE`	`OFF`	libsndfile
`PROMEKI_USE_SYSTEM_SAMPLERATE`	`OFF`	libsamplerate
`PROMEKI_USE_SYSTEM_NLOHMANN_JSON`	`OFF`	nlohmann/json
`PROMEKI_USE_SYSTEM_VTC`	`OFF`	libvtc
`PROMEKI_USE_SYSTEM_HIGHWAY`	`OFF`	Highway
`PROMEKI_USE_SYSTEM_CIRF`	`OFF`	cirf

Vendored dependencies currently in the tree: zlib-ng, libspng, libjpeg-turbo, SVT-JPEG-XS, FreeType, libsndfile, libsamplerate, nlohmann/json, libvtc, Highway, cirf, doctest.

Build Targets

Option	Default	Description
`PROMEKI_BUILD_TUI`	`ON`	Build the `promeki-tui` library
`PROMEKI_BUILD_SDL`	auto	Build the `promeki-sdl` library (auto-enabled when SDL3 is found)
`PROMEKI_BUILD_TESTS`	`ON`	Build the unit-test executables
`PROMEKI_BUILD_UTILS`	`ON`	Build the utility applications (`promeki-info`, `mediaplay`, `imgtest`, ...)
`PROMEKI_BUILD_DEMOS`	`ON`	Build the demonstration applications
`PROMEKI_BUILD_BENCHMARKS`	`ON`	Build the `promeki-bench` driver
`PROMEKI_BUILD_DOCS`	`OFF`	Add the generated documentation to the `all` target

Three test executables are produced: unittest-promeki, unittest-tui, and unittest-sdl. See Running Tests.

Build Performance Options

These flags don't affect the produced binary — they trade disk space and first-build time for faster incremental rebuilds.

Option	Default	Effect
`PROMEKI_USE_CCACHE`	`ON`	Use `ccache` as a compiler launcher when it is on `PATH`; silently skipped otherwise
`PROMEKI_USE_PCH`	`ON`	Precompile the hot stable headers (stdlib + promeki infrastructure) to skip re-parsing them on every TU
`PROMEKI_BUILD_STATS`	`ON`	Record per-TU compile wall-time and peak RSS to `build/promeki-build-stats.log` (requires GNU `/usr/bin/time`)

The build-stats log can be summarised with scripts/build-stats-report.sh for identifying the slowest / heaviest translation units. The two options compose cleanly — with ccache enabled, a cache hit logs near-zero wall time and a small peak RSS so the report distinguishes real compiles from cached ones.

Common Configurations

Minimal core-only build

Drops Pro A/V, networking, and music for a lean core-only library suitable for command-line tools that just need the container / I/O / string infrastructure:

cmake -B build \
    -DPROMEKI_ENABLE_PROAV=OFF \
    -DPROMEKI_ENABLE_NETWORK=OFF \
    -DPROMEKI_ENABLE_MUSIC=OFF

System dependencies

Use distro-packaged versions of the third-party libraries instead of the vendored copies:

cmake -B build \
    -DPROMEKI_USE_SYSTEM_ZLIB=ON \
    -DPROMEKI_USE_SYSTEM_LIBSPNG=ON \
    -DPROMEKI_USE_SYSTEM_FREETYPE=ON \
    -DPROMEKI_USE_SYSTEM_SNDFILE=ON \
    -DPROMEKI_USE_SYSTEM_LIBJPEG=ON

Release packaging

Full optimisation, no debug symbols, no promekiDebug() overhead:

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
cmake --install build --prefix /opt/promeki

Cleaning

Two clean targets are provided:

libclean removes only the promeki library objects, test executables, and utilities while preserving the third-party build output. This is the right target for routine development — the vendored dependencies rarely change and rebuilding them is slow:

cmake --build build --target libclean

The standard clean target removes everything, including the third-party builds:

cmake --build build --target clean

Running Tests

Three test executables are produced, one per shared library:

cd build

ctest --output-on-failure

Or run them individually:

./build/unittest-promeki
./build/unittest-tui
./build/unittest-sdl

All three are built on doctest. Per-test filtering is available via doctest's --test-case= filter.

Installing

cmake --install build
# or to a custom prefix:
cmake --install build --prefix /opt/promeki

The install tree contains:

lib/libpromeki.so (versioned, with SONAME), plus libpromeki-tui.so and libpromeki-sdl.so when enabled
include/promeki/ — all public headers, including the generated config.h that records which features were compiled in
include/promeki/thirdparty/ — bundled third-party headers (when the corresponding dependency was vendored)
lib/cmake/promeki/ — CMake package-config files for find_package(promeki)
share/doc/promeki/ — license and third-party attribution notices

Using libpromeki in Your Project

After installing, add this to your project's CMakeLists.txt:

find_package(promeki REQUIRED)
 
# Link against the main library:
target_link_libraries(myapp PRIVATE promeki::promeki)
 
# For TUI applications:
target_link_libraries(myapp PRIVATE promeki::tui)
 
# For SDL applications:
target_link_libraries(myapp PRIVATE promeki::sdl)

If you installed to a non-standard prefix, tell CMake where to find it:

cmake -B build -DCMAKE_PREFIX_PATH=/opt/promeki

Include Conventions

All promeki headers live under the promeki/ namespace:

#include <promeki/string.h>
#include <promeki/timecode.h>
#include <promeki/imagedesc.h>

Bundled third-party headers use their canonical include paths:

#include <nlohmann/json.hpp>
#include <spng.h>
#include <ft2build.h>

Everything in promeki is in the promeki namespace:

using namespace promeki;
 
String name("hello");
Timecode tc(1, 2, 3, 4, FrameRate::fps24());
UUID id = UUID::generate();

Building the Documentation

The documentation you are reading is generated from the sources by Doxygen. To build it locally:

cmake -B build -DPROMEKI_BUILD_DOCS=ON

cmake --build build --target docs

The HTML output is written to build/doxygen/html/; open build/doxygen/html/index.html in a browser. A hosted copy of the main branch is available at https://jthwho.github.io/libpromeki/main/.

The output directory can be overridden with -DPROMEKI_DOCS_OUTPUT_DIR=/some/path at configure time.