Appveyor Windows Build Orchestration

---
name: appveyor-windows-build-orchestration
description: Use when you are building a Qt5-based desktop application with cross-platform
  (macOS/Windows/Linux) distribution requirements and need to automate Windows executable
  generation as part of a CI/CD pipeline.
license: CC-BY-4.0
metadata:
  edam_topics: []
  tools:
  - Maven GUI
  - git
  - qmake
  - make
  - Qt5
  - Appveyor
  - MSYS2
  - Homebrew
  - pacman
  - AppVeyor
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.3390/metabo12080684
  title: MAVEN2
evidence_spans:
- 'Maven GUI: Metabolomics Analysis and Visualization Engine'
- git clone --recursive [redacted-email]:eugenemel/maven.git maven
- qmake -r build.pro
- make -j4
- Install the qt5 package
- Builds for Windows are run via Appveyor
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_maven2_cq
    doi: 10.3390/metabo12080684
    title: MAVEN2
  dedup_kept_from: coll_maven2_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.3390/metabo12080684
  all_source_dois:
  - 10.3390/metabo12080684
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# appveyor-windows-build-orchestration

## Summary

Configuring and executing reproducible Windows executable builds for Qt5-based GUI applications via AppVeyor CI/CD, ensuring consistent compilation across developer machines and automated release pipelines. This skill is essential when distributing cross-platform desktop metabolomics software that must produce signed, versioned Windows binaries as part of a coordinated multi-platform release.

## When to use

You are building a Qt5-based desktop application with cross-platform (macOS/Windows/Linux) distribution requirements and need to automate Windows executable generation as part of a CI/CD pipeline. Specifically: when you have committed code to a GitHub repository that is tracked by AppVeyor, when you need to produce distributable Windows .exe artifacts (not just compile-check), or when you are preparing a versioned release that must include both macOS and Windows executables generated by the same orchestrator (as of Nov 2024, both are produced by AppVeyor, not separate CI systems).

## When NOT to use

- Your project does not use Qt5 or qmake; AppVeyor configuration is specific to Qt/qmake workflows and will require substantial adaptation for other build systems (e.g. CMake, Visual Studio msbuild).
- You need to produce Linux executables; as of November 2024, Linux builds have been retired from the AppVeyor pipeline and must be handled by a separate CI system (e.g., Travis or GitHub Actions).
- You are only compiling locally or need ad-hoc debugging builds; AppVeyor is intended for automated, reproducible release builds integrated with GitHub; local `qmake -r && make -j4` on a developer machine is faster for iteration.

## Inputs

- GitHub repository (eugenemel/maven or equivalent Qt5 project)
- qmake project file (build.pro)
- AppVeyor CI configuration file (.appveyor.yml or equivalent)
- Source code committed to branch (master or prepare_release_<version>)

## Outputs

- Windows executable artifact (maven_dev_*.exe)
- Distributable package ready for GitHub Releases
- AppVeyor build log and pass/fail status
- Release-ready binary suitable for end-user distribution

## How to apply

Set up AppVeyor by linking the GitHub repository (eugenemel/maven pattern) so that push and pull-request events trigger automated builds. In the build environment, install Qt5 and MSYS2 (mingw64 toolchain) via pacman package manager; configure the qmake project file with `qmake -r build.pro`, then compile with `make -j4` to parallelize across cores. After successful compilation, package the distributable by running `make INSTALL_ROOT=appdir install` followed by the platform-specific script `make_dist_win32.sh`, which produces the final maven_dev_*.exe artifact. Verify success by confirming AppVeyor's build stage completes without errors and that the executable artifact is available in the release artifacts section; use the build badge and project status page to monitor ongoing builds and catch regressions before merge.

## Related tools

- **AppVeyor** (CI/CD orchestrator that automatically triggers builds on GitHub push/PR events, executes qmake + make compilation, and artifacts Windows executables (maven_dev_*.exe)) — https://ci.appveyor.com
- **qmake** (Qt project configuration and Makefile generator; invoked as `qmake -r build.pro` to parse the Qt project and emit platform-specific build rules) — https://doc.qt.io/qt-5/qmake-manual.html
- **make** (Build executor that compiles source files in parallel (`make -j4`) using the Makefile generated by qmake) — https://www.gnu.org/software/make/
- **MSYS2** (Windows development environment providing mingw64 toolchain (gcc, g++), Qt5, zlib, sqlite3 libraries, and pacman package manager for dependency installation) — http://www.msys2.org/
- **Qt5** (Cross-platform GUI framework providing qmake, Qt libraries, and runtime dependencies required to compile and link Maven GUI on Windows) — https://www.qt.io/download
- **git** (Version control client; used to clone the GitHub repository recursively (`git clone --recursive [redacted-email]:eugenemel/maven.git maven`) and manage branch/tag operations for releases) — https://github.com/eugenemel/maven
- **Maven GUI** (Target application being built; metabolomics analysis and visualization engine written in Qt5, compiled via AppVeyor to produce Windows executables) — https://github.com/eugenemel/maven

## Examples

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

## Evaluation signals

- AppVeyor build log shows no errors or warnings in the qmake configuration step (`qmake -r build.pro` exits with code 0).
- Compilation completes successfully with `make -j4` producing .o object files and no linker errors.
- Packaging step executes without errors (`make INSTALL_ROOT=appdir install && make_dist_win32.sh`) and produces a named executable artifact (maven_dev_*.exe) in the release directory.
- AppVeyor project status badge shows green/passing for the latest commit on master or prepare_release_* branch.
- The produced .exe file is executable and can be launched on a Windows test machine (or via AppVeyor's artifact download), confirming that Qt5 runtime dependencies and application code are correctly linked.

## Limitations

- As of November 2024, Linux builds have been retired from AppVeyor; projects requiring Linux executables must use a separate CI system (Travis, GitHub Actions, etc.), complicating multi-platform release orchestration.
- AppVeyor depends on GitHub integration; if the GitHub repository is unreachable, in private mode, or has permission/token issues, AppVeyor will not trigger or will fail silently.
- MSYS2 packages on Windows have known bugs (e.g., issue with envsubst.exe causing 'not a valid identifier' errors during git operations); workarounds are required and may fail on future MSYS2 updates, necessitating manual intervention.
- The build is tightly coupled to the AppVeyor Windows image version; updates to the base image (e.g., Qt5 minor version, mingw64 toolchain) can break builds without code changes, requiring explicit .appveyor.yml version pinning.
- Cross-compilation or building on a fresh Windows machine requires all dependencies (Qt5, zlib, sqlite3, make, gcc) to be correctly installed via pacman in MSYS2; missing or mismatched versions will silently fail or produce incompatible binaries.

## 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] qmake -r build.pro and make -j4 are the canonical compilation steps: "qmake -r build.pro
make -j4"
- [other] make INSTALL_ROOT=appdir install and make_dist_[platform].sh produce distributable packages: "make INSTALL_ROOT=appdir install
make_dist_[platform].sh"
- [readme] MSYS2 provides the Windows build environment with mingw64 toolchain: "Install the MSYS2 platform for Windows"
- [readme] AppVeyor is the CI/CD platform orchestrating Windows builds post-November 2024: "Builds for Windows are run via Appveyor"
- [other] Git is used to clone the Maven repository recursively from GitHub: "git clone --recursive  [redacted-email]:eugenemel/maven.git maven"
- [readme] Qt5 is the core GUI framework dependency for Maven: "Install the qt5 package"
- [readme] MSYS2 bug workaround required for git operations on Windows: "There is a bug in MSYS2 packages that causes the following error"