libultrahdr CMake Build Instructions
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 Option | Default Value | Notes |
|---|---|---|
CMAKE_BUILD_TYPE | Release | See CMake documentation here. |
BUILD_SHARED_LIBS | ON | See 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_EXAMPLES | ON | Build sample application. This application demonstrates how to use ultrahdr_api.h. |
UHDR_BUILD_TESTS | OFF | Build 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_BENCHMARK | OFF | Build 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. Benchmark tests are not supported on Windows and this parameter is forced to OFF internally while building on WIN32 platforms. |
UHDR_BUILD_FUZZERS | OFF | Build 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_DEPS | OFF | Clone and Build project dependencies and not use pre-installed packages. |
UHDR_BUILD_JAVA | OFF | Build JNI wrapper, Java front-end classes and Java sample application. |
UHDR_ENABLE_LOGS | OFF | Build with verbose logging. |
UHDR_ENABLE_INSTALL | ON | Enable 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_INTRINSICS | ON | Build 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 no SIMD configuration settings of dependencies. |
UHDR_ENABLE_GLES | OFF | Build with GPU acceleration. |
UHDR_ENABLE_WERROR | OFF | Enable -Werror when building. |
UHDR_MAX_DIMENSION | 8192 | Maximum 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_SANITIZE_OPTIONS | OFF | Build 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_PACKAGING | OFF | Build 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
IDE
Compile and Test:
cmake -G "Visual Studio 16 2019" -DUHDR_BUILD_DEPS=1 -DUHDR_BUILD_TESTS=1 ../ cmake --build ./ --config=Release ctest -C Release
Command Line
Compile and Test:
cmake -G "NMake Makefiles" -DUHDR_BUILD_DEPS=1 -DUHDR_BUILD_TESTS=1 ../ 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
uhdr-static.lib - Static link library for the libuhdr API
ultrahdr_app - sample application
ultrahdr_unit_test - unit tests
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 - 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.