xLights Linux build instructions
xLights can be built and run on Linux, Mac OS/X, or Windows. This
document describes how developers should set up their tool chain to build
xLights on Linux.
Ubuntu packages are provided for users at https://code.launchpad.net/~chris-debenham/+archive/ubuntu/xlights
xLights is written in C++ and uses the wxWidgets library as a
compatibility layer across operating systems. The minimum required version
of wxWidgets for xLights is v3.1.5. This can be compiled from
source or installed via packages if they are available for your distribution.
The provided makefile will download and build wxWidgets if needed - including
application of a small patch from the end of this file to fix the sizing of
bitmap buttons.
SDL2 needs to be 2.0.5 or later.
A precompiled libliquidfun.a.uname -p library and QM Vamp plugins are included for
i686, x86_64 and aarm64 - for other platforms it would need to be recompiled from
https://github.com/google/liquidfun
== Building for linux via docker container ==
If you wish to build for linux from other platforms or without having to touch your local install you can use Docker to test building
To setup the nessecary docker image you can checkout the build file from git and build directly via:
docker build -t xlights-build https://github.com/xLightsSequencer/xlights-build-docker.git
This will leave you with a suitable base image
Once this is setup you can build xLights via:
docker run --name buildvm xlights-build /bin/bash Recipe
If you want to build the appimage you can use:
docker run --name buildvm xlights-build /bin/bash Recipe.appimage
If you want to create a fresh build then the container can be removed with:
docker rm buildvm
== Building locally from source ==
Ubuntu 24.04 is the minimum supported release. It is what the official
builds and the CI are compiled on, so it is the only baseline that is
continuously verified. Older releases may happen to work, but are not
tested and are not supported.
These instructions have been tested on the following distributions:
Instructions for other Linux distributions will vary.
a) Using Software Manager (or apt-get or rpm), install the following packages.
(Fedora packages will be named differently and have 'devel' instead of 'dev'
in their name)
build-essential
libgtk-3-dev
libgstreamer1.0-dev
libgstreamer-plugins-base1.0-dev
freeglut3-dev
libavcodec-dev
libavformat-dev
libavfilter-dev
libswscale-dev
libsdl2-dev
libzstd-dev
libcurl4-openssl-dev
liblua5.3-dev
libwebp-dev
libsecret-1-dev
libegl-dev (required for Wayland support)
libfreetype-dev (used for text/shape effect rendering)
libharfbuzz-dev (used for text/shape effect rendering)
libfontconfig-dev (used for text/shape effect rendering)
libavahi-compat-libdnssd-dev (mDNS/Bonjour controller discovery, e.g. WLED)
cbp2make (optional but recommended if compiling from git)
Example command to install packages on Ubuntu
sudo apt-get install g++ gcc build-essential libgtk-3-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev freeglut3-dev libavcodec-dev libavformat-dev libswscale-dev libsdl2-dev libavutil-dev libavfilter-dev libzstd-dev libwebp-dev libcurl4-openssl-dev liblua5.3-dev libminizip-dev libxlsxwriter-dev libegl-dev libfreetype-dev libharfbuzz-dev libfontconfig-dev libavahi-compat-libdnssd-dev wget git cbp2make curl libsecret-1-dev
mDNS/Bonjour controller discovery (WLED and similar):
BUILD: without libavahi-compat-libdnssd-dev, <dns_sd.h> is unavailable
and mDNS-based controller discovery silently compiles out (WLED
controllers will not be auto-discovered), with no build error.
RUNTIME: also requires the avahi-daemon service running:
sudo apt-get install avahi-daemon
sudo systemctl enable --now avahi-daemon
GPU-accelerated rendering (Vulkan):
BUILD: the compute kernels (src-core/effects/vulkan/shaders/*.comp) are
compiled to SPIR-V at build time by glslc, so glslc is a required build
tool (like ispc for the SIMD kernels). The Vulkan headers, volk loader,
and VulkanMemoryAllocator are vendored as git submodules (fetched by the
recursive submodule checkout) and volk loads the driver at runtime, so
nothing Vulkan is linked. The Vulkan Shader effect additionally
translates user GLSL at runtime via glslang, which comes from the
distro: glslang-dev pulls in spirv-tools, which it needs because
the packaged glslang is built with the SPIR-V optimizer enabled.
Install glslc and glslang:
sudo apt-get install glslc glslang-dev
(or build with -DXLIGHTS_USE_VULKAN=OFF / omit it in the .cbp to skip the
GPU compute backend entirely.)
RUNTIME: to actually USE GPU acceleration the machine needs a Vulkan
loader and an ICD/driver; without them xLights logs "no Vulkan loader"
and falls back to CPU rendering:
sudo apt-get install libvulkan1 mesa-vulkan-drivers
(mesa-vulkan-drivers covers Intel/AMD; NVIDIA users get Vulkan from the
proprietary driver. Enable it under Preferences > Other > GPU rendering.)
Hardware video decode (VA-API):
No build-time dependency — decode goes through FFmpeg's generic
hwaccel API (libavcodec/libavutil, already required above), which
resolves VAAPI via the distro's own libva at runtime; nothing
VAAPI-specific is linked by xLights itself.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
