Qt application compilation and packaging

Qt Application Compilation and Packaging

Summary

This skill automates the compilation and distribution of Qt-based GUI applications across multiple platforms (macOS, Windows, Linux) using qmake, make, and platform-specific packaging scripts. It is essential for creating reproducible, distributable binaries from Qt source code within a CI/CD environment.

When to use

Apply this skill when you have a Qt5-based C++ GUI application source tree (e.g., Maven GUI) that must be compiled and packaged for end-user distribution across macOS and Windows platforms, especially when automated builds are managed by CI/CD services (AppVeyor, Travis). Use it when the project uses qmake as its build configuration tool and requires both platform-specific executables (.exe for Windows, .app for macOS) and distributable packages.

When NOT to use

• When the Qt application uses CMake instead of qmake as the primary build system—adapt the configuration step accordingly.
• When targeting platforms for which automated CI/CD builds have been retired (e.g., Linux builds for Maven GUI as of November 2024), unless you manually configure a new CI/CD platform or build locally.
• When the application lacks platform-specific distribution scripts (make_dist_*.sh) or when the build environment cannot satisfy Qt5 and compiler dependencies for the target platform.

Inputs

• Qt5 C++ source tree with qmake project files (build.pro, .pro files)
• Linked git submodules or dependencies (e.g., maven_core library)
• Platform-specific environment (macOS with Homebrew, Windows with MSYS2/mingw64, or Linux with Qt5 PPA)

Outputs

• Platform-specific executable (maven_dev_*.exe for Windows, Maven.app for macOS)
• Distributable package archive or installer
• Build artifacts verified by CI/CD platform (AppVeyor, Travis)

How to apply

First, clone the Qt application repository recursively (e.g., git clone --recursive [redacted-email]:eugenemel/maven.git maven) to obtain the main project and all linked dependencies. Set up the build environment by installing Qt5 development libraries and build tools appropriate to the target platform: on macOS use Homebrew (e.g., brew install qt5); on Windows use MSYS2 with mingw64 packages (e.g., pacman -S mingw-w64-x86_64-qt-creator). Configure the build by invoking qmake -r build.pro to generate platform-specific Makefiles, then compile using make -j4 with parallel jobs for speed. Finally, create a distributable package by installing to a temporary root directory (make INSTALL_ROOT=appdir install) and running the platform-specific distribution script (e.g., make_dist_osx.sh or make_dist_win32.sh), which generates the final executable artifact (Maven.app for macOS or maven_dev_*.exe for Windows). Verify successful build completion by checking that the CI/CD platform (AppVeyor as of November 2024 for Maven GUI) reports a passed build stage and produces the expected binary artifact.

Related tools

• qmake (Qt build configuration generator; invoked to translate .pro files into platform-specific Makefiles) — http://doc.qt.io/
• make (GNU build automation tool; executes Makefile targets to compile source and install artifacts)
• git (Version control and recursive repository cloning for obtaining Qt application source and linked submodules) — https://github.com
• Qt5 (C++ framework and libraries providing GUI components, signals/slots, and cross-platform abstractions for the application) — https://www.qt.io/
• Homebrew (Package manager for macOS; used to install Qt5 development libraries and build tools (qmake, make)) — https://brew.sh/
• MSYS2 (Unix-like environment and package manager for Windows; provides mingw64 toolchain, Qt5, zlib, sqlite3, and build utilities) — https://www.msys2.org/
• Appveyor (CI/CD platform responsible for automated compilation and packaging of macOS and Windows executables) — https://ci.appveyor.com/project/eugenemel/maven
• Travis (Legacy CI/CD platform (retired for Maven GUI as of Nov 2024) previously used for Linux builds) — https://travis-ci.org/eugenemel/maven_core

Examples

git clone --recursive [redacted-email]:eugenemel/maven.git maven && cd maven && qmake -r build.pro && make -j4 && make INSTALL_ROOT=appdir install && ./make_dist_osx.sh

Evaluation signals

• CI/CD platform (AppVeyor) build stage completes successfully with no compilation or linking errors.
• Expected executable artifacts are produced: Maven.app (macOS) or maven_dev_*.exe (Windows) in the specified output directory.
• The final package passes verification checks performed by the CI/CD platform, confirming the binary is ready for distribution.
• Recursive git clone and qmake configuration complete without dependency or environment setup errors on each target platform.
• Platform-specific distribution scripts execute without error and produce a distributable package (not just raw binaries) suitable for end-user installation.

Limitations

• Linux automated builds for Maven GUI have been retired as of November 5, 2024; only macOS and Windows are currently supported via AppVeyor CI/CD.
• MSYS2 on Windows has a known bug (issue #735) that can cause git operations to fail with an 'not a valid identifier' error during environment variable export; requires manual workaround (e.g., moving envsubst.exe and installing gettext).
• Build success depends on platform-specific availability of Qt5 development libraries; different package managers and versions (Homebrew on macOS, pacman on MSYS2, apt on Linux Ubuntu) introduce platform-specific configuration overhead.

Evidence

• [intro] As of 20241105, linux builds have been retired, and both mac os and windows executable are now produced by Appveyor: "As of 20241105, linux builds have been retired, and both mac os and windows executable are now produced by Appveyor"
• [other] git clone --recursive [redacted-email]:eugenemel/maven.git maven; qmake -r build.pro; make -j4: "git clone --recursive [redacted-email]:eugenemel/maven.git maven"
• [other] qmake -r build.pro; make -j4 compilation workflow: "qmake -r build.pro make -j4"
• [other] make INSTALL_ROOT=appdir install; make_dist_[platform].sh distribution script invocation: "make INSTALL_ROOT=appdir install make_dist_[platform].sh"
• [readme] Install Qt5, qmake, and make on target platform via Homebrew or MSYS2: "Install the qt5 package"
• [readme] MSYS2 known bug causing environment variable identifier error during git operations: "There is a bug in MSYS2 packages that causes the following error"
• [other] Verify AppVeyor successfully completes build stage and produces final executable artifacts: "Verify that AppVeyor successfully completes the build stage and produces the final executable artifacts (maven_dev_*.exe for Windows or Maven.app for macOS)"