Automated Executable Distribution Generation

automated-executable-distribution-generation

Summary

Automating the compilation and packaging of cross-platform GUI executables (macOS .app, Windows .exe, Linux binaries) using CI/CD pipelines (Appveyor, Travis) and platform-specific build tools (qmake, make, Qt5). This skill ensures reproducible, versioned distribution artifacts are generated consistently without manual intervention.

When to use

Use this skill when you need to produce final distributable executable artifacts for a Qt5-based C++ application across multiple platforms (macOS, Windows, Linux), and you want to avoid manual build–package–release steps. Triggers include: preparing a new release version, ensuring platform parity in executable features, or reducing manual packaging errors in a multi-platform project.

When NOT to use

• Your project does not use Qt5 or qmake-based build configuration; use platform-native build systems (CMake, Gradle, xcode) instead.
• You need real-time or on-demand builds; CI/CD pipelines are optimized for event-triggered (commit/tag) workflows, not interactive builds.
• Your target platforms are not Windows, macOS, or Linux; custom platforms require custom CI/CD agents or cross-compilation toolchains.

Inputs

• Git repository URL (e.g., github.com/eugenemel/maven)
• build.pro (Qt project file)
• Platform-specific make_dist_*.sh scripts
• Source code (C++ with Qt5 dependencies)

Outputs

• Windows executable (.exe file, e.g., maven_dev_*.exe)
• macOS application bundle (.app directory, e.g., Maven.app)
• Linux binary (if pipeline includes Linux; currently retired)
• Build log and CI/CD job artifacts

How to apply

Configure a CI/CD pipeline (Appveyor for Windows/macOS, Travis for Linux) to monitor your repository for commits or tags. For each target platform, clone the repository recursively, install platform-specific build dependencies (Qt5 via Homebrew on macOS, MSYS2 on Windows, apt on Linux), configure the build with qmake -r build.pro, compile with make -j4, then generate a distributable package by running make INSTALL_ROOT=appdir install followed by a platform-specific shell script (e.g., make_dist_win32.sh, make_dist_osx.sh). Verify that the CI/CD service completes all stages and produces the final executable artifacts (e.g., maven_dev_*.exe for Windows, Maven.app for macOS). As of November 2024, macOS and Windows builds are produced by Appveyor; Linux builds have been retired from the automated pipeline.

Related tools

• Appveyor (CI/CD platform that triggers, compiles, and packages Windows and macOS executables on each commit or tag) — https://ci.appveyor.com/project/eugenemel/maven
• Travis CI (CI/CD platform for Linux builds (now retired as of November 2024, but historically used)) — https://travis-ci.org/eugenemel/maven_core
• qmake (Qt build configuration tool; generates platform-specific Makefiles from .pro files)
• make (Build orchestration; compiles source code using generated Makefiles with parallel jobs (-j4))
• Qt5 (Cross-platform GUI framework; provides the core libraries and runtime dependencies for executable)
• MSYS2 (Windows development environment; provides MinGW toolchain, pacman package manager, and Qt5 packages for Windows builds) — http://www.msys2.org/
• Homebrew (macOS package manager; installs Qt5 and build tools on macOS build agents) — https://brew.sh
• git (Version control; clones repository recursively to fetch source and submodules) — https://github.com/eugenemel/maven

Examples

qmake -r build.pro && make -j4 && make INSTALL_ROOT=appdir install && ./make_dist_win32.sh

Evaluation signals

• CI/CD pipeline log shows all stages (install dependencies, configure, compile, package) completing successfully with exit code 0.
• Executable artifacts exist at expected paths and are non-empty: Windows (.exe file > 10 MB typical), macOS (.app bundle directory with executable bit set), Linux (ELF binary with execute permissions).
• Executable can be launched and responds to basic GUI initialization (no segfault or missing library errors on first run).
• Build artifacts are tagged with version identifier matching the Git tag or commit SHA, and appear in the repository's release page or CI/CD artifact store.
• Dependency tree is clean: ldd (Linux) or otool -L (macOS) or dependency walker (Windows) shows only expected Qt5 libraries and system dependencies, no broken links.

Limitations

• Linux builds have been retired as of November 5, 2024; only Windows and macOS are currently automated. Future Linux support would require re-enabling Travis CI or switching to a unified multi-platform CI/CD service.
• qmake and Qt5 versions must match across the repository and CI/CD build agents; version mismatches can cause silent build failures or runtime incompatibilities.
• Platform-specific shell scripts (make_dist_*.sh) are not version-controlled centrally; changes to packaging logic require manual updates and testing on each platform.
• No built-in rollback or staging mechanism; failed builds may leave stale artifacts in the release pipeline, requiring manual cleanup.
• Cross-compilation (e.g., building Windows .exe on macOS) is not supported in this workflow; each platform must build on its native CI/CD agent.

Evidence

• [readme] 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] Clone repository, install build environment (Qt5, qmake, make), configure with qmake, compile with make -j4, create distributable package with make INSTALL_ROOT=appdir install and platform-specific script: "Configure the build using qmake -r build.pro. 4. Compile the project using make -j4 with parallel jobs. 5. Create a distributable package by running make INSTALL_ROOT=appdir install followed by the"
• [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)"
• [readme] Windows requires MSYS2 platform with Qt5, zlib, sqlite; macOS requires Homebrew with Qt5; Linux requires PPA and Qt5.8, OpenGL, sqlite3: "Install the MSYS2 platform for Windows. 2. From a mingw64 prompt, install 64-bit QT, zlib, and sqlite. Install the Homebrew package management system. 2. Install the qt5 package"
• [readme] Git clone repository recursively to include submodules like maven_core: "git clone --recursive [redacted-email]:eugenemel/maven.git maven. Cloning into 'maven_core'... https://github.com/eugenemel/maven_core/"
• [other] Release workflow: create branch, update CHANGELOG, merge PR, tag version, ensure CI/CD passes: "Once other members agree to release, merge the PR and ensure Travis and Appveyor pass. Tag with new version"