building.md

September 5, 2025 ยท View on GitHub

libultrahdr CMake Build Instructions

Build Status Build Status Build Status Build Status Fuzz Status

Requirements

  • CMake v3.15 or later
  • C++ compiler, supporting at least C++17.
  • libultrahdr uses jpeg compression format to store sdr image and gainmap quotient. So, libjpeg or any other jpeg codec that is ABI and API compatible with libjpeg.

The library offers a way to skip installing libjpeg by passing UHDR_BUILD_DEPS=1 at the time of configure. That is, cmake -DUHDR_BUILD_DEPS=1 will clone jpeg codec from link and include it in the build process. This is however not recommended.

If jpeg is included in the build process then,

  • C compiler
  • For building x86/x86_64 SIMD optimizations, NASM or Yasm.
    • If using NASM, 2.13 or later is required.
    • If using Yasm, 1.2.0 or later is required.

CMake Options

There are a few options that can be passed to CMake to modify how the code is built.
To set these options and parameters, use -D<Parameter_name>=<value>.

All CMake options are passed at configure time, i.e., by running cmake -DOPTION_ONE=1 -DOPTION_TWO=0 ...
before running cmake --build ...

For example, to build unit tests in a new subdirectory called 'build', run:

cmake -G "Unix Makefiles" -S. -Bbuild -DUHDR_BUILD_TESTS=1 ../

and then build with:

cmake --build build

Following is a list of available options:

CMake OptionDefault ValueNotes
CMAKE_BUILD_TYPEReleaseSee CMake documentation here.
BUILD_SHARED_LIBSONSee CMake documentation here.
  • If BUILD_SHARED_LIBS is OFF, in the linking phase, static versions of dependencies are chosen. However, the executable targets are not purely static because the system libraries used are still dynamic.
UHDR_BUILD_EXAMPLESONBuild sample application. This application demonstrates how to use ultrahdr_api.h.
UHDR_BUILD_TESTSOFFBuild Unit Tests. Mostly for Devs. During development, different modules of libuhdr library are validated using GoogleTest framework. Developers after making changes to library are expected to run these tests to ensure every thing is functional.
UHDR_BUILD_BENCHMARKOFFBuild Benchmark Tests. These are for profiling libuhdr encode/decode API. Resources used by benchmark tests are shared here. These are downloaded and extracted automatically during the build process for later benchmarking.
UHDR_BUILD_FUZZERSOFFBuild Fuzz Test Applications. Mostly for Devs.
  • Fuzz applications are built by instrumenting the entire software suite. This includes dependency libraries. This is done by forcing UHDR_BUILD_DEPS to ON internally.
UHDR_BUILD_DEPSOFFClone and Build project dependencies and not use pre-installed packages.
UHDR_BUILD_JAVAOFFBuild JNI wrapper, Java front-end classes and Java sample application.
UHDR_ENABLE_LOGSOFFBuild with verbose logging.
UHDR_ENABLE_INSTALLONEnable install and uninstall targets for libuhdr package.
  • For system wide installation it is best if dependencies are acquired from OS package manager instead of building from source. This is to avoid conflicts with software that is using a different version of the said dependency and also links to libuhdr. So if UHDR_BUILD_DEPS is ON then UHDR_ENABLE_INSTALL is forced to OFF internally.
UHDR_ENABLE_INTRINSICSONBuild with SIMD acceleration. Sections of libuhdr are accelerated for Arm Neon architectures and these are enabled.
  • For x86/x86_64 architectures currently no SIMD acceleration is present. Consequently this option has no effect.
  • This parameter has no effect on SIMD configuration settings of dependencies.
UHDR_ENABLE_GLESOFFBuild with GPU acceleration.
UHDR_ENABLE_WERROROFFEnable -Werror when building.
UHDR_MAX_DIMENSION8192Maximum dimension supported by the library. The library defaults to handling images upto resolution 8192x8192. For different resolution needs use this option. For example, -DUHDR_MAX_DIMENSION=4096.
UHDR_WRITE_XMPOFFEnable writing gainmap metadata in XMP packet.
  • Current implementation of XMP format supports writing only single channel gainmap metadata. To support encoding multi channel gainmap metadata, XMP format encoding is disabled by default. If enabled, metadata of all channels of gainmap image is merged into one and signalled.
UHDR_WRITE_ISOONEnable writing gainmap metadata in ISO 21496-1 format.
UHDR_SANITIZE_OPTIONSOFFBuild library with sanitize options. Values set to this parameter are passed to directly to compilation option -fsanitize. For example, -DUHDR_SANITIZE_OPTIONS=address,undefined adds -fsanitize=address,undefined to the list of compilation options. CMake configuration errors are raised if the compiler does not support these flags. This is useful during fuzz testing.
  • As -fsanitize is an instrumentation option, dependencies are also built from source instead of using pre-builts. This is done by forcing UHDR_BUILD_DEPS to ON internally.
UHDR_BUILD_PACKAGINGOFFBuild distribution packages using CPack.

Generator

The CMake generator preferred is ninja. Consequently, ninja is added to the list of prerequisite packages. This need not be the case. If the platform is equipped with a different generator, it can be tried and ninja installation can be skipped.

Build Steps

Check out the source code:

git clone https://github.com/google/libultrahdr.git
cd libultrahdr
mkdir build_directory
cd build_directory

Linux Platform

Install the prerequisite packages before building:

sudo apt install cmake pkg-config libjpeg-dev ninja-build

Compile and Test:

cmake -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DUHDR_BUILD_TESTS=1 ../
ninja
ctest

This will generate the following files under build_directory:

libuhdr.so.{version} - Shared library for the libuhdr API
libuhdr.so - Symlink to shared library
libuhdr.a - Static link library for the libuhdr API
libuhdr.pc - libuhdr pkg-config file
ultrahdr_app - sample application
ultrahdr_unit_test - unit tests

Installation:

sudo ninja install

This installs the headers, pkg-config, and shared libraries. By default the headers are put in /usr/local/include/, libraries in /usr/local/lib/ and pkg-config file in /usr/local/lib/pkgconfig/. You may need to add path /usr/local/lib/ to LD_LIBRARY_PATH if binaries linking with ultrahdr library are unable to load it at run time. e.g. export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/.

Uninstallation:

sudo ninja uninstall

macOS Platform

Install the prerequisite packages before building:

brew install cmake pkg-config jpeg ninja

Compile and Test:

cmake -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DUHDR_BUILD_TESTS=1 ../
ninja
ctest

This will generate the following files under build_directory:

libuhdr.{version}.dylib - Shared library for the libuhdr API
libuhdr.dylib - Symlink to shared library
libuhdr.a - Static link library for the libuhdr API
libuhdr.pc - libuhdr pkg-config file
ultrahdr_app - sample application
ultrahdr_unit_test - unit tests

Installation:

sudo ninja install

This installs the headers, pkg-config, and shared libraries. By default the headers are put in /usr/local/include/, libraries in /usr/local/lib/ and pkg-config file in /usr/local/lib/pkgconfig/. You may need to add path /usr/local/lib/ to DYLD_FALLBACK_LIBRARY_PATH if binaries are unable to load uhdr library e.g. export DYLD_FALLBACK_LIBRARY_PATH=$DYLD_FALLBACK_LIBRARY_PATH:/usr/local/lib/.

Uninstallation:

sudo ninja uninstall

Windows Platform - MSYS2 Env

Install the prerequisite packages before building:

pacman -S mingw-w64-ucrt-x86_64-libjpeg-turbo mingw-w64-ucrt-x86_64-ninja

Compile and Test:

cmake -G Ninja -DUHDR_BUILD_TESTS=1 ../
ninja
ctest

This will generate the following files under build_directory:

libuhdr.dll - Shared library for the libuhdr API
libuhdr.dll.a - Import library for the libuhdr API
libuhdr.a - Static link library for the libuhdr API
libuhdr.pc - libuhdr pkg-config file
ultrahdr_app - sample application
ultrahdr_unit_test - unit tests

Windows Platform - MSVC Env

Install the prerequisite packages before building:

git clone https://github.com/libjpeg-turbo/libjpeg-turbo.git
cd libjpeg-turbo
cmake -G "Visual Studio 16 2019" -DCMAKE_INSTALL_PREFIX=/c/msvcinstalls/ -S. -Bbuild
cmake --build ./build --config=Release --target install

IDE

Compile and Test:

cmake -G "Visual Studio 16 2019" -DCMAKE_PREFIX_PATH=/c/msvcinstalls/ -DCMAKE_INSTALL_PREFIX=/c/msvcinstalls/ ../
cmake --build ./ --config=Release
ctest -C Release

Command Line

Compile and Test:

cmake -G "NMake Makefiles" -DCMAKE_PREFIX_PATH=/c/msvcinstalls/ -DCMAKE_INSTALL_PREFIX=/c/msvcinstalls/ ../
cmake --build ./
ctest

This will generate the following files under build_directory:

uhdr.dll - Shared library for the libuhdr API
uhdr.lib - Import library for the libuhdr API
ultrahdr_app - sample application

Cross-Compilation - Build System Linux

Target - Linux Platform - Armv7 Arch

Install the prerequisite packages before building:

sudo apt install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf

Compile:

cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/arm-linux-gnueabihf.cmake -DUHDR_BUILD_DEPS=1 ../
ninja

Target - Linux Platform - Armv8 Arch

Install the prerequisite packages before building:

sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

Compile:

cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/aarch64-linux-gnu.cmake -DUHDR_BUILD_DEPS=1 ../
ninja

Target - Linux Platform - RISC-V Arch (64 bit)

Install the prerequisite packages before building:

sudo apt install gcc-riscv64-linux-gnu g++-riscv64-linux-gnu

Compile:

cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/riscv64-linux-gnu.cmake -DUHDR_BUILD_DEPS=1 ../
ninja

This will generate the following files under build_directory:

libuhdr.so.{version} - Shared library for the libuhdr API
libuhdr.so - Symlink to shared library
libuhdr.a - Static link library for the libuhdr API
ultrahdr_app - sample application
ultrahdr_unit_test - unit tests

Target - Linux Platform - RISC-V Arch (32 bit)

Install the prerequisite packages before building:

# Download from https://github.com/riscv-collab/riscv-gnu-toolchain/releases
sudo ln -s {your_dir}/riscv/bin/riscv32-unknown-linux-gnu-g++ /usr/bin/riscv32-linux-gnu-g++
sudo ln -s {your_dir}/riscv/bin/riscv32-unknown-linux-gnu-gcc /usr/bin/riscv32-linux-gnu-gcc

Compile:

cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/riscv32-linux-gnu.cmake -DUHDR_BUILD_DEPS=1 ../
ninja

This will generate the following files under build_directory:

libuhdr.so.{version} - Shared library for the libuhdr API
libuhdr.so - Symlink to shared library
libuhdr.a - Static link library for the libuhdr API
ultrahdr_app - sample application
ultrahdr_unit_test - unit tests

Target - Linux Platform - LOONG Arch (64 bit)

Install the prerequisite packages before building:

sudo apt install gcc-loongarch64-linux-gnu g++-loongarch64-linux-gnu

Compile:

cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/loong64-linux-gnu.cmake -DUHDR_BUILD_DEPS=1 ../
ninja

Target - Android Platform

Install the prerequisite packages before building:

wget https://dl.google.com/android/repository/android-ndk-r26d-linux.zip
unzip android-ndk-r26d-linux.zip

Choose target architecture with -DANDROID_ABI={armeabi-v7a, arm64-v8a, x86, x86_64}

Compile:

cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/android.cmake -DUHDR_ANDROID_NDK_PATH=/opt/android-ndk-r26d/ -DUHDR_BUILD_DEPS=1 -DANDROID_ABI="Selected Architecture" -DANDROID_PLATFORM=android-23 ../
ninja

This will generate the following files under build_directory:

libuhdr.so - Shared library for the libuhdr API
libuhdr.a - Static link library for the libuhdr API
ultrahdr_app - sample application
ultrahdr_unit_test - unit tests

Target - Wasm

Install the prerequisite packages before building: Follow the instructions given here.

Compile:

emcmake cmake -G Ninja ../
ninja

This will generate the following files under build_directory:

ultrahdr_app.wasm - wasm module
ultrahdr_app.js - sample application

Building Fuzzers

Refer to fuzzers.md for complete instructions.