xLights macOS build instructions


This document describes how **developers** should set up their tool chain to build
xLights on macOS.

xLights is written in C++ and uses the wxWidgets library as a
compatibility layer across operating systems.

On macOS, compilation is done using Xcode. Code::Blocks is not used.
Xcode can be downloaded from the Apple developer web site or the App Store. Make
sure you install the version of Xcode that matches your version of
macOS. For example, I use macOS Tahoe (26), so I installed Xcode 26.


Dependencies
============

Third-party libraries (wxWidgets, ffmpeg, SDL2, lua, zstd, etc.) are built
separately via the scripts in the xLights-macOS-dependencies repository:
https://github.com/xLightsSequencer/xLights-macOS-dependencies

Current dependency version: xlights_2026.06

There are two ways to set up the dependencies:

Option 1: Automatic download (recommended)
-------------------------------------------
If /opt/local does NOT exist (or does not contain the dependencies), Xcode will
automatically download the pre-built dependencies when you build. This requires
no manual setup -- just open the project and build. The downloaded dependencies
are cached locally and will be re-downloaded only when the dependency version
changes.

Option 2: Build dependencies yourself
--------------------------------------
Clone the xLights-macOS-dependencies repository and run build.sh to compile all
dependencies locally:

  git clone https://github.com/xLightsSequencer/xLights-macOS-dependencies
  cd xLights-macOS-dependencies
  ./build.sh

Then either:
  - Symlink /opt/local to the build output:
      sudo ln -sf /path/to/xLights-macOS-dependencies /opt/local
  - Or install directly to /opt/local (see the repository README for details)

When /opt/local/include/lualib.h exists, Xcode will use the local dependencies
instead of downloading them.