xLights keeps four build systems and one Linux toolchain doc in the same root

Four readme files, and the Linux one is a developer toolchain document

The repository root carries four readme files: `README.txt`, `README.linux`, `README.osx` and `README.windows`. The Linux one is not an overview of the application. It opens by saying xLights can be built and run on Linux, Mac OS/X or Windows, and then states that the document describes how developers should set up their tool chain to build xLights on Linux. Everything after that opening line is a dependency list, a package installation command, and a set of notes about what breaks when a dependency is absent.

End users are pointed elsewhere. Ubuntu packages are provided for users through a Launchpad personal package archive, and the document links to the archive rather than describing how to build a package. So there are two audiences here and only one of them is being served by this file.

The program itself is C++ using wxWidgets as a compatibility layer across operating systems, with a minimum required version of wxWidgets of v3.1.5. SDL2 needs to be 2.0.5 or later. Both can come from packages or from source, and the provided makefile will download and build wxWidgets if it is needed, including applying a small patch from the end of the file to fix the sizing of bitmap buttons. That patch is one of the reasons building from the repository's own recipe is easier than assembling wxWidgets yourself.

Ubuntu 24.04 is the only baseline anyone continuously verifies

The support statement is unusually blunt. Ubuntu 24.04 is the minimum supported release, and the reason given is that 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.

Two distributions are listed as actually tested: Ubuntu 24.04 and Fedora 42. Instructions for other Linux distributions are said to vary, which is an admission rather than a guide.

The package list that follows is specific about why several of them exist. `libgtk-3-dev` and the two GStreamer development packages are plain build inputs. `libegl-dev` is marked as required for Wayland support. `libfreetype-dev`, `libharfbuzz-dev` and `libfontconfig-dev` are grouped as being used for text and shape effect rendering. `libavahi-compat-libdnssd-dev` is marked as being for mDNS and Bonjour controller discovery, with WLED given as the example. `cbp2make` is called optional but recommended if compiling from git, because Code::Blocks project files are how the editor integration is generated.

Fedora users are warned that the package names differ and carry `devel` where Debian carries `dev`.

Skip avahi and controller discovery compiles out with no error at all

This is the sharpest warning in the file, and it is written as a build and runtime pair. Without `libavahi-compat-libdnssd-dev`, the header `dns_sd.h` is unavailable, and mDNS based controller discovery silently compiles out. The stated consequence is that WLED controllers will not be auto-discovered, with no build error.

A silent compile-out is the failure mode worth dwelling on. Nothing in the compiler output changes, the binary links, the application starts, and the only symptom is a controller you expected to appear in a discovery list never appearing. If you are chasing a WLED that does not show up, this dependency is the first thing to check, and the absence of a build error is not evidence that the feature is present.

At runtime the same feature needs a running daemon as well as the header:

sudo apt-get install avahi-daemon
sudo systemctl enable --now avahi-daemon

So controller discovery has two independent failure points, one at compile time and one at service start time, and the document separates them under BUILD and RUNTIME for exactly that reason. Nothing in the application reports back that discovery was compiled out.

Vulkan support needs a build tool and a runtime driver, or you get CPU rendering

The GPU compute backend is described in more detail than any other optional feature. The compute kernels under `src-core/effects/vulkan/shaders/*.comp` are compiled to SPIR-V at build time by `glslc`, which makes it a required build tool in the same way `ispc` is required for the SIMD kernels. The Vulkan headers, the volk loader and VulkanMemoryAllocator are vendored as git submodules fetched by a recursive submodule checkout, and volk loads the driver at runtime, so nothing Vulkan is linked into xLights itself.

The Vulkan Shader effect additionally translates user GLSL at runtime through glslang, which comes from the distribution. The file notes that `glslang-dev` pulls in `spirv-tools`, which it needs because the packaged glslang is built with the SPIR-V optimizer enabled:

sudo apt-get install glslc glslang-dev

There is an escape hatch, and it is explicit: building with `-DXLIGHTS_USE_VULKAN=OFF`, or omitting it in the `.cbp`, skips the GPU compute backend entirely.

At runtime the machine needs a Vulkan loader and an ICD or driver. Without them xLights logs `no Vulkan loader` and falls back to CPU rendering. The install line is `sudo apt-get install libvulkan1 mesa-vulkan-drivers`, with `mesa-vulkan-drivers` covering Intel and AMD, while NVIDIA users get Vulkan from the proprietary driver. It has to be switched on under Preferences, Other, GPU rendering.

Hardware video decode is deliberately link free and fails at runtime

VA-API is handled the opposite way from Vulkan, and the contrast is instructive. There is no build time dependency for it. Decode goes through FFmpeg's generic hwaccel API, using libavcodec and libavutil which are already required for other reasons, and that API resolves VAAPI through the distribution's own libva at runtime. Nothing VAAPI specific is linked by xLights itself.

What that buys is a build that cannot fail because of VAAPI. What it costs is a runtime that can. The machine needs a VA-API driver for the GPU: `intel-media-va-driver` on Intel, or `intel-media-va-driver-non-free` for newer integrated GPUs, and `mesa-va-drivers` on AMD or Mesa. The install line is:

sudo apt-get install vainfo intel-media-va-driver mesa-va-drivers

`vainfo` is the check, and the file says what a good result looks like: `VAProfile` lines printed, meaning the driver initialised, before you rely on decode working. Enabling it is under Preferences, Other, Hardware Video Decoding, and it auto-tries vaapi then vdpau with no manual selection needed.

So the two acceleration paths fail in opposite ways. Vulkan fails at build or logs a fallback line; VA-API fails silently at playback time and is diagnosable with a standalone command.

The package list and the one line apt command do not match

The document gives the dependencies twice, as a bulleted list and as a single command, and the two are not the same set.

Missing from the one-liner are two entries that the list calls for. `libsdl2-dev` appears in the list, and SDL2 2.0.5 or later is stated as a requirement two sections earlier, but the command does not include it. `libswscale-dev` is in the list and not in the command.

Present in the command but absent from the list are seven: `g++`, `gcc`, `libavutil-dev`, `libminizip-dev`, `libxlsxwriter-dev`, `wget`, `git` and `curl`. The first two and the last two are reasonable additions for a toolchain. `libminizip-dev` and `libxlsxwriter-dev` are archive and spreadsheet libraries that the bulleted list never mentions at all, which suggests the command was assembled from a working build environment rather than from the list.

The practical advice is to treat the bulleted list as the documented set and the command as a hint. If you copy the command on its own you may find SDL2 missing at configure time with no explanation on the page for why.

The Fedora command further down has the same shape of drift: it begins an rpmfusion release package install and is where the visible text ends, with the package list for Fedora 42 never completed on this page.

Precompiled liquidfun covers three architectures and one of them is misspelled

Two binary dependencies ship with the source rather than being resolved by your package manager. A precompiled `libliquidfun.a` library named with the output of `uname -p`, plus the QM Vamp plugins, are included for three architectures: `i686`, `x86_64` and `aarm64`.

That third name is spelled with three letters after the leading a, where the architecture is `aarch64`. It appears in the same sentence as the file name template, so it is not a typo in passing but the literal string written into the text. Anyone matching on it programmatically will not match the real output of `uname -p` on an ARM64 machine.

The consequence for anyone outside those three is spelled out: for other platforms it would need to be recompiled from the upstream liquidfun repository at `https://github.com/google/liquidfun`. That is a source build of a physics library, not a package install, and it is a step the Ubuntu and Fedora package lists do not mention because it is not in a distribution repository.

The same paragraph shows the other side of the policy. SDL2 and wxWidgets are treated as ordinary packages with version floors, while liquidfun and the Vamp plugins are treated as vendored binaries. A 32-bit x86 build is still supported by that policy; an ARM64 build is not, on paper.

Four build systems share one root and the wxWidgets tag trails the release

The build entry points are worth listing, because picking the wrong one wastes an afternoon. A root `Makefile` with `SUBDIRS = xLights`. A `CMakeLists.txt`. An Xcode project, `xLights.xcodeproj` with a `macOS/` directory beside it. Two Windows batch files, `VS2022.bat` and `VS2022_vcpkg.bat`, with `vcpkg.json` and `vcpkg-configuration.json` for the dependency manifest. CI is configured twice, through `appveyor.bat` with `appveyor.yml` and through a `.travis.yml`, with `ci_scripts/` and `build_scripts/` holding the logic, and a `snap/` directory for packaging.

The Makefile is the one the Linux document drives, and its variables are informative. `PREFIX` defaults to `/usr`, and it appends to `PKG_CONFIG_PATH` using a conditional so the `:` separator is only added when the variable already has a value. It extends `PATH` with `$(PREFIX)/bin` so that `wx-config` can be found. `WXWIDGETS_TAG` is pinned to `xlights_2026.17c`, `ISPC_VERSION` is 1.31.0, and the ISPC archive and wxWidgets canvas flags are chosen from `uname -m`, with the `aarch64` branch taking a different archive and setting `WXWIDGETS_CANVAS_FLAGS=--enable-glcanvasegl` where every other architecture sets `--enable-glcan`.

That pinned tag is worth noting against the release history. The newest published release is `2026.18`, alongside a rolling `nightly` tag, and the Makefile still references `2026.17c`.

Editorial conclusion

xLights is a serious piece of software for anyone sequencing lights, and the Linux build file is more candid than most. It tells you that skipping `libavahi-compat-libdnssd-dev` gives you a build with no error and no automatic controller discovery, that Vulkan support needs both a build tool and a runtime driver or you get a log line and CPU rendering, and that Ubuntu 24.04 is the only baseline anyone continuously verifies. That candour is worth more than the convenience of a single installer.

What to settle before you build. Follow the bulleted package list rather than the single line apt command on the same page, because the one-liner is missing `libsdl2-dev` and `libswscale-dev` even though SDL2 is stated as a hard requirement above it. Note that the precompiled `libliquidfun.a` and the QM Vamp plugins only exist for i686, x86_64 and a third architecture the file spells `aarm64`, and anything else means recompiling liquidfun from its upstream repository yourself. Check that the pinned `WXWIDGETS_TAG=xlights_2026.17c` in the Makefile is the build you actually want, since the newest published release is `2026.18`.

If you are on Fedora, the ffmpeg situation is the first thing to resolve, because Fedora has defaulted to `ffmpeg-free` and swapping it is a separate step with its own repository. And if you just want to try the build without touching your machine, the container route exists: build the image from the xlights-build-docker repository and run `Recipe` inside it. All four paths build the same C++ program; pick the one that matches your distribution before you start rather than after the first missing header.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes