Environment Setup & Plug-in Build

Qt Upgrade Guide (macOS, Qt 5.15.16 Open Source)

Overview

This guide explains how to upgrade Qt to version 5.15.16 on macOS, supporting both Intel and Apple Silicon (arm64) environments. You can download it directly from official Qt sources or build it from source. We recommend using the official source packages for maximum compatibility.

Prerequisites

  • Administrator privileges

  • Xcode Command Line Tools installed (xcode-select --install)

  • Sufficient disk space (~15–20 GB)

  • (Optional) Homebrew installed for package management (if needed)

  • Build configuration requirement: Plugins must be built in Release.

  • Debug binaries (.dll/.dylib) will not load in CLO.

Obtaining Qt 5.15.16

CLO SDK requires Qt 5.15.16 for building C++ plug-ins.

You can download the Qt installer from the official Qt website: https://www.qt.io/download-open-source

During installation: - Select Qt 5.15.16 (not newer versions such as Qt 6.x) - Include components for your target platform (e.g., macOS, Windows) - Note the installation path (you will reference it in CMake)

Example installation path:

/Users/<username>/Qt/5.15.16/clang_64

After installation, make sure the following environment variable is set:

export Qt5_DIR=/Users/<username>/Qt/5.15.16/clang_64/lib/cmake/Qt5

Setting Environment Variables

Add the following to your ~/.zshrc (or ~/.bash_profile):

export QTDIR=$HOME/Qt-5.15.16
export PATH=$QTDIR/bin:$PATH
export CMAKE_PREFIX_PATH=$QTDIR/lib/cmake:$CMAKE_PREFIX_PATH

Reload the profile:

source ~/.zshrc

CMake Configuration

Configure your project to use the updated Qt:

cmake .. \
  -DQt5_DIR=$QTDIR/lib/cmake/Qt5 \
  -DCMAKE_PREFIX_PATH=$QTDIR/lib/cmake

Cleaning Previous Builds

Always clean your project before rebuilding:

rm -rf build/*
mkdir build && cd build

Then re-run cmake .. and make.

Verifying Qt Installation

Check your Qt version:

qmake --version

or

qtpaths --qt-version

Confirm that you are using version 5.15.16.

Common Problems

Problem

Solution

CMake can’t find Qt5Config.cmake

Verify Qt5_DIR and CMAKE_PREFIX_PATH.

Wrong architecture (arm64 vs x86_64)

Ensure the correct Qt architecture is installed.

Qt Creator still sees an old Qt version

Update Qt paths in Qt Creator Preferences > Kits.

CMake Build

CMake Configuration

  • Windows & macOS with QtDIR environment variable set

cmake -S . -B build

  • macOS with Qt from Homebrew

cmake -S . -D USE_HOMEBREW=ON -B build

Build

cmake --build build --config Release -j 10

IDE supports

CMake supports many IDEs / Text Editors, either as a generator or fully natively. Please refer to online resources for the details. Here we provide a few pages as a starting point.

Plugin Output & Installation

  • Use Release build outputs only. - Windows: build/Release/YourPlugin.dll (Visual Studio: build with --config Release) - macOS: build/Release/libYourPlugin.dylib

  • Place the binary in the CLO plugins directory for your environment. Debug artifacts (e.g., .pdb) are not required, and Debug .dll/.dylib will not load.