Skip to content
Awawa edited this page Jul 5, 2025 · 106 revisions

Available methods to build HyperHDR:

Available CMake HyperHDR configuration options:

Use -D prefix when configuring the build.

  • LED DEVICES

    • ENABLE_SPIDEV = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables SPI LED devices on supported systems
    • ENABLE_SPI_FTDI = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables SPI libFTDI/FTDI controller on supported systems
    • ENABLE_WS281XPWM = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables WS281x LED library on supported systems
  • SOFTWARE GRABBERS

    • ENABLE_DX = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the DirectX11 software grabber (Windows)
    • ENABLE_FRAMEBUFFER = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the Framebuffer software grabber (Linux)
    • ENABLE_MAC_SYSTEM = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the macOS software grabber (macOS)
    • ENABLE_PIPEWIRE = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the Pipewire software grabber (Linux)
    • ENABLE_PIPEWIRE_EGL = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables EGL for the Pipewire grabber (Linux)
    • ENABLE_X11 = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the X11 software grabber (Linux)
    • ENABLE_AMLOGIC = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, forces the Amlogic software grabber (Linux)
  • HARDWARE GRABBERS

    • ENABLE_AVF = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the AVF USB grabber support (macOS)
    • ENABLE_MF = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the MediaFoundation USB grabber support (Windows)
    • ENABLE_V4L2 = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the V4L2 USB grabber support (Linux)
  • SOUND CAPTURING

    • ENABLE_SOUNDCAPLINUX = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the ALSA sound grabber (Linux)
    • ENABLE_SOUNDCAPMACOS = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the sound grabber (macOS)
    • ENABLE_SOUNDCAPWINDOWS = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the sound grabber (Windows)
  • SERVICE SUPPORT

    • ENABLE_BONJOUR = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables mDNS (do not disable unless required)
    • ENABLE_CEC = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the HDMI-CEC support (Linux)
    • ENABLE_MQTT = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the MQTT support
    • ENABLE_POWER_MANAGEMENT = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables sleep/wake up OS events support
    • ENABLE_PROTOBUF = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables Proto-Buffer server
    • ENABLE_SYSTRAY = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables the systray-widget
    • ENABLE_ZSTD = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enables ZSTD support for LUT decompression
  • BUILD FEATURES

    • USE_SHARED_LIBS = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, if disabled, build the application as monolithic
    • USE_EMBEDDED_WEB_RESOURCES = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, if enable, embed web content into the application
    • USE_PRECOMPILED_HEADERS = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, use pre-compiled headers when building
    • USE_CCACHE_CACHING = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, enable CCache support if available
    • USE_SYSTEM_MQTT_LIBS = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, prefer system qMQTT libs
    • USE_SYSTEM_FLATBUFFERS_LIBS = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, prefer system Flatbuffers libs
    • USE_SYSTEM_SDBUS_CPP_LIBS = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, prefer system sdbus_c++ libs
    • USE_SYSTEM_LUNASVG_LIBS = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, prefer system lunasvg libs
    • USE_SYSTEM_NANOPB_LIBS = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, prefer system nanopb libs
    • USE_SYSTEM_STB_LIBS = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, prefer system stb libs
    • USE_STATIC_QT_PLUGINS = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, embed static QT-plugins into the application
    • USE_STANDARD_INSTALLER_NAME = ${\textsf{\color{green}ON}}$ | ${\textsf{\color{red}OFF}}$, use standard Linux package naming

Native build

Preparing build environment

Debian/Ubuntu

sudo apt-get update

sudo apt-get install build-essential cmake flatbuffers-compiler git libasound2-dev libayatana-appindicator3-dev libegl-dev libflatbuffers-dev libftdi1-dev libgl-dev libglvnd-dev libgtk-3-dev liblzma-dev libpipewire-0.3-dev libssl-dev libsystemd-dev libturbojpeg0-dev libusb-1.0-0-dev libx11-dev libzstd-dev ninja-build patchelf pkg-config python3 qt6-serialport-dev qt6-base-dev unzip wget

For Raspberry Pi CEC support (optional)

sudo apt-get install libcec-dev libp8-platform-dev libudev-dev

Fedora

sudo dnf -y install alsa-lib-devel chrpath cmake fedora-packager flatbuffers-compiler flatbuffers-devel gcc gcc-c++ git gtk3-devel libX11-devel libayatana-appindicator-gtk3-devel libftdi-c++-devel libglvnd-devel libusb1-devel libzstd-devel mesa-libEGL-devel mesa-libGL-devel ninja-build openssl-devel pipewire-devel pkg-config qt6-qtbase-devel qt6-qtserialport-devel systemd-devel turbojpeg-devel unzip wget xz-devel

Arch Linux

sudo pacman -Syy

sudo pacman -S alsa-lib base-devel bash binutils chrpath cmake dpkg fakeroot flatbuffers freetds git gtk3 libayatana-appindicator libfbclient libftdi libglvnd libjpeg-turbo libx11 mariadb-libs mesa ninja openssl pipewire pkgfile postgresql-libs python qt6-base qt6-serialport sdbus-cpp systemd-libs unzip wayland wget xz

Windows

We assume a 64bit Windows 10. Install the following;

  • Git (Check during installation: Add to PATH)
  • CMake (Windows win64-x64 Installer) (Check during installation: Add to PATH)
  • Visual Studio 2022 Community Edition
    • Select 'Desktop development with C++'
    • On the right, just select MSVC v143 VS 2022 C++ x64/x86-Buildtools and latest Windows 10 SDK. Everything else is not needed, but you can stay with default selection.
  • OpenSSL (for QT5.15-6.2: OpenSSL v1.1.1, for QT6: OpenSSL 3)
  • libjpeg-turbo
  • Python 3 (Windows x86-64 executable installer) (Check during installation: Add to PATH and Debug Symbols)
    • Open a console window and execute pip install aqtinstall.
    • Now we can download Qt to C:\Qt mkdir c:\Qt && aqt install -O c:\Qt 6.8.3 windows desktop win64_msvc2022_64 -m qtserialport
    • May need to add QT6 path before compiling, for example: set CMAKE_PREFIX_PATH=C:\Qt\6.8.3\msvc2022_64\lib\cmake\ or for older QT5 set Qt5_Dir=C:\Qt\5.15.2\msvc2019_64\lib\cmake\Qt5\
  • Optional for creating installer packages: NSIS 3.x (direct link)

Hint: after you execute the configuration command in the build folder (for example cmake -DCMAKE_BUILD_TYPE=Release ..) you should receive *.sln solution project file that can be opened in Visual Studio. Select hyperhdr project as default for the solution to run it after compilation.

macOS

First install brew manager.
Next: brew install qt@6 cmake xz pkg-config

Compiling and installing HyperHDR

Linux/macOS: the general quick & recommended way

git clone --recursive https://github.com/awawa-dev/HyperHDR.git hyperhdr
cd hyperhdr
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j $(nproc)

# if this get stucked and dmesg says out of memory try:
make -j 2

# Run it from the build directory
bin/hyperhdr -d

# BUILD INSTALLERS (recommended method to install HyperHDR, doesnt work for ArchLinux: use build.sh script )
cpack
# or compile and build the package using one command
cmake --build . --target package --config Release

Windows: the general quick & recommended way

git clone --recursive https://github.com/awawa-dev/HyperHDR.git hyperhdr
cd hyperhdr
mkdir build
cd build
# You might need to setup MSVC env first
call "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"
# Maintainers: to build the HyperHDR installer, install NSIS and define environment variable:  
# set VCINSTALLDIR="C:\Program Files\Microsoft Visual Studio\2022\Community\VC"
cmake -DPLATFORM=windows -G "Visual Studio 17 2022" -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --config Release -- -maxcpucount

# Run it from the build directory
bin/Release/hyperhdr -d

LibreELEC

You can find the add-on sources here on branches of my LibreELEC fork: https://github.com/awawa-dev/LibreELEC.tv/ For example libreelec-11.0-hyperhdr branch. Adjust HyperHDR package properties in packages/addons/service/hyperhdr/package.mk Follow LibreELEC's manual on how to build the image. For example:

LibreELEC 11/RPi:

PROJECT=RPi ARCH=arm DEVICE=RPi4 make image
PROJECT=RPi DEVICE=RPi4 ARCH=arm ./scripts/create_addon hyperhdr

LibreELEC 12/RPi:

PROJECT=RPi ARCH=aarch64 DEVICE=RPi4 make image
PROJECT=RPi DEVICE=RPi4 ARCH=aarch64 ./scripts/create_addon hyperhdr

PC(x86_64):

PROJECT=Generic ARCH=x86_64 DEVICE=Generic make image
PROJECT=Generic DEVICE=Generic ARCH=x86_64 ./scripts/create_addon hyperhdr

Build a HyperHDR installer for any supported Linux system on any system using Docker

All you need is Docker and bash, which is available on every supported system, even on Windows where you only need to enable "Windows Subsystem for Linux". You don't need to install any packages to build HyperHDR because the script uses Docker images provided by https://github.com/awawa-dev/HyperDockerBuilder which contain everything you need to build the installer. Thanks to this, you can compile eg. the aarch64 HyperHDR installer for Raspberry Pi even on a PC. Run the build.sh script in the main directory.

pi@ubuntu:~/hyperhdr$ ./build.sh 

Required environmental options:
PLATFORM - one of the supported targets: osx|windows|linux|rpi
DISTRO_NAME  | DISTRO_VERSION | ARCHITECTURE - these are only for linux targets
   debian    | bullseye       | armhf
   debian    | bullseye       | arm64
   debian    | bullseye       | amd64
   debian    | bookworm       | armhf
   debian    | bookworm       | arm64
   debian    | bookworm       | amd64
   ubuntu    | jammy          | amd64
   ubuntu    | noble          | amd64
   ubuntu    | plucky         | amd64
   fedora    | 42             | amd64
   archlinux | rolling        | amd64

Optional environmental options:
BUILD_TYPE - Release|Debug, default is Release version
BUILD_ARCHIVES - false|true, cpack will build ZIP package
USE_STANDARD_INSTALLER_NAME - false|true, use standard Linux package naming
USE_CCACHE - false|true, use ccache if available
RESET_CACHE - false|true, reset ccache storage

Example of usage:
PLATFORM=rpi DISTRO_NAME=debian DISTRO_VERSION=bullseye ARCHITECTURE=arm64 ./build.sh
Installers from Docker builds will be ready in the deploy folder

The build.sh script can also be used to natively build macOS/Windows installers as an alternative to the method described in the previous point. Of course, then you must have all the necessary packages installed.


Github Action (online - easiest)

Fork HyperHDR project. Now you must enable project's Settings β†’ Actions β†’ Actions permissions β†’ Allow all actions and reusable workflows and save it. Once you've done this, any change, even using the Github online editor, will immediately trigger the build in the Actions tab. If this did not happen, you probably did not enable the option described or did it later after making the changes.

Clone this wiki locally