This document describes the CMake build, install, and package-consumption flow for Gecode.

• CMake 3.21 or newer
• A C++17-capable compiler
• uv on PATH for generated-script paths: documentation generation, GECODE_REGENERATE_VARIMP=ON, and manual helper execution. Ordinary CMake builds can use the checked-in generated headers without uv.
• Python 3.11 or newer for helper scripts run through uv.
• Optional dependencies based on enabled modules:
  • MPFR for float support with MPFR
  • Qt 6 Core, or Qt 5.15+ Core, for FlatZinc plugin support when Qt support is enabled or auto-detected
  • Qt 6 Gui, Widgets, and PrintSupport, or the matching Qt 5.15+ components, for Gist

Single-config generators (Unix Makefiles / Ninja):

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
cmake --build build --target check
cmake --install build --prefix /path/to/install

Multi-config generators (Visual Studio / Xcode):

cmake -S . -B build
cmake --build build --config Release
cmake --build build --config Release --target check
cmake --install build --config Release --prefix /path/to/install

This repository includes a vcpkg manifest (vcpkg.json) and CMake presets for a ready-to-run Visual Studio path with MPFR enabled.

Prerequisites:

• Visual Studio 2022 with C++ toolchain
• CMake 3.21 or newer
• VCPKG_ROOT set to your vcpkg checkout

Preset flow:

cmake --preset vs2022-vcpkg
cmake --build --preset vs2022-vcpkg-release
cmake --build --preset vs2022-vcpkg-check

Equivalent command-line flow (without presets):

cmake -S . -B build/vs2022-vcpkg -G "Visual Studio 17 2022" -A x64 `
  -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" `
  -DVCPKG_TARGET_TRIPLET=x64-windows `
  -DGECODE_ENABLE_MPFR=ON -DGECODE_ENABLE_QT=OFF -DGECODE_ENABLE_GIST=OFF
cmake --build build/vs2022-vcpkg --config Release
cmake --build build/vs2022-vcpkg --config Release --target check
cmake --install build/vs2022-vcpkg --config Release --prefix C:/path/to/install

Visual Studio is a multi-config generator, so use --config Release (or Debug) for build/install/check commands rather than CMAKE_BUILD_TYPE.

When BUILD_TESTING=ON, CMake builds the gecode-test test runner on demand. The standard check target runs the basic integrity suite:

cmake --build build --target check

Two additional targets expose broader tag-based suites:

cmake --build build --target check-standard
cmake --build build --target check-sweep

check-standard runs the standard test suite. check-sweep runs tests tagged as heavy sweep tests and is intended for deliberate, longer-running validation.

Use gecode-test -help for runner options and gecode-test -list-with-tags to inspect test assignments.

• BUILD_SHARED_LIBS: conventional default selector
  • ON default behavior: GECODE_BUILD_SHARED=ON, GECODE_BUILD_STATIC=OFF
  • OFF default behavior: GECODE_BUILD_SHARED=OFF, GECODE_BUILD_STATIC=ON
• BUILD_TESTING: controls whether gecode-test is built and whether check runs the test subset. The check target still exists when tests are disabled, but reports that checks are skipped.
• CMAKE_BUILD_TYPE / multi-config --config: standard build mode control

• GECODE_BUILD_SHARED, GECODE_BUILD_STATIC: explicit library variants
  • If set directly, these override BUILD_SHARED_LIBS-based defaults.
• GECODE_INSTALL: enables install/export/package rules
  • Defaults to ON when Gecode is top-level; defaults to OFF as subproject.
• GECODE_ENABLE_*: module toggles (search/int/set/float/minimodel/driver/flatzinc/gist, etc.)
  • Higher-level modules force their required lower-level modules on. For example, examples and FlatZinc require the core modeling modules, and minimodel requires int, set, and search support.
  • GECODE_REGENERATE_VARIMP: regenerate checked-in var-imp headers during build
• GECODE_ENABLE_QT: AUTO, ON, or OFF. AUTO uses Qt-backed FlatZinc plugin support when Qt Core is found. ON requires Qt and fails configuration if supported Qt is missing. OFF disables Qt. Qt 6 is preferred; Qt 5.15 or newer is accepted for legacy environments. This can add a public Qt Core dependency to Gecode::gecodeflatzinc.
• GECODE_ENABLE_GIST: AUTO, ON, or OFF. AUTO builds Gist when a usable Qt GUI stack is available. ON requires Gist dependencies and fails configuration if they are unavailable. Gist requires Qt Gui, Widgets, and PrintSupport in addition to Qt Core.
• GECODE_ENABLE_FAULT_INJECTION: builds deterministic allocation and copy failpoints together with the Fault::* regression suite. This facility is test-only, process-global, isolated to the dedicated single-threaded fault test executable, CMake-only, and disabled by default.
• GECODE_SANITIZER: selects address, undefined, address-undefined, or thread instrumentation. These modes currently require a compiler that accepts GCC/Clang sanitizer flags.
• GECODE_DOC_DOT, GECODE_DOC_SEARCH, GECODE_DOC_TAGFILE: configure the Doxygen doc target. Building docs requires Doxygen 1.17.0 or newer and uv; Graphviz dot is used when available and GECODE_DOC_DOT=ON.

Top-level defaults:

• GECODE_ENABLE_EXAMPLES=ON
• BUILD_TESTING=ON
• GECODE_INSTALL=ON

Subproject defaults (add_subdirectory):

• GECODE_ENABLE_EXAMPLES=OFF
• BUILD_TESTING=OFF (unless enabled by parent project)
• GECODE_INSTALL=OFF

Fault injection is test-only and process-global. Its tests run in a dedicated, isolated single-threaded executable and must not share a test process with ordinary tests. The CMake targets enforce this:

cmake -S . -B build-fault -DGECODE_ENABLE_FAULT_INJECTION=ON
cmake --build build-fault --target check-fault

The ordinary check target also runs check-fault when fault injection is enabled. CTest registers the fault suite as a separate process with -threads 1 and serializes it with the fault-injection resource lock. The FailPoint facility is not a supported application API.

For a sanitizer build, configure a separate build directory. For example:

cmake -S . -B build-asan-ubsan \
  -DGECODE_SANITIZER=address-undefined
cmake --build build-asan-ubsan --target check

Gecode::gecode links the exported aggregate target. Use it unless the consumer needs explicit module linkage.

find_package(Gecode CONFIG REQUIRED)
add_executable(app main.cpp)
target_link_libraries(app PRIVATE Gecode::gecode)

Canonical component names:

• support, kernel, search, int, set, float, minimodel, driver, flatzinc, gist, test

Example:

find_package(Gecode CONFIG REQUIRED COMPONENTS driver)
add_executable(app main.cpp)
target_link_libraries(app PRIVATE Gecode::gecodedriver)

A Gecode installation configured with BUILD_TESTING=ON exports the test component. It lets downstream projects check custom integer, Boolean, set, and float propagators with Gecode's test runner.

• Always available targets: Gecode::gecodetest, Gecode::gecodetestint
• Set target when configured: Gecode::gecodetestset
• Float target when configured: Gecode::gecodetestfloat
• Installed headers follow the same configuration: test/test.*, test/int.*, test/set.*, and test/float.*

find_package(Gecode CONFIG REQUIRED COMPONENTS test)
add_executable(custom-propagator-test custom-propagator-test.cpp)
target_link_libraries(custom-propagator-test PRIVATE Gecode::gecodetestint)

Use Gecode::gecodetestset or Gecode::gecodetestfloat for those variable families. The targets supply the runner and their Gecode dependencies. With add_subdirectory or FetchContent, enable BUILD_TESTING before adding Gecode. When both library variants are installed, targets ending in _shared or _static select a variant explicitly. Use one variant throughout the test executable so registration and execution share the same registry.

See the test API in test/int.hh and test/test.hh for an example, consistency controls, and Test::run_registered_tests. The runner's -help lists execution and replay options.

Autoconf also installs the configured test helpers when search and integer variables are enabled. For direct linking, list the used helpers before their Gecode dependencies, for example:

c++ -std=c++17 -I<prefix>/include custom-propagator-test.cpp \
  -L<prefix>/lib -lgecodetestint -lgecodetest -lgecodesearch \
  -lgecodeint -lgecodekernel -lgecodesupport

Use the installation's configured library directory. Set and float helpers also require their corresponding Gecode libraries.

Legacy component spellings are also accepted in COMPONENTS:

• gecodesupport, gecodekernel, gecodesearch, gecodeint, gecodeset, gecodefloat, gecodeminimodel, gecodedriver, gecodeflatzinc, gecodegist

Use one of:

• -DCMAKE_PREFIX_PATH=/path/to/install
• -DGecode_ROOT=/path/to/install

Packagers that want to avoid any Qt dependency in the exported package should configure with:

cmake -S . -B build -DGECODE_ENABLE_QT=OFF -DGECODE_ENABLE_GIST=OFF

Use Gecode_VERSION from package config:

find_package(Gecode CONFIG REQUIRED)
message(STATUS "Gecode version: ${Gecode_VERSION}")

Do not rely on parsing installed headers such as config.hpp for version checks.

Deprecation horizon:

• These aliases are accepted for the 6.x line to preserve migration compatibility.
• New configurations should use the GECODE_* names.

• Target "..." links to Gecode::gecode but the target was not found:
  • Ensure you are using an installation built with this CMake export layout.
  • Check CMAKE_PREFIX_PATH / Gecode_ROOT points to the intended install.
• find_package(Gecode COMPONENTS ...) fails:
  • Verify requested component is enabled in the installed build.
  • For optional modules (flatzinc, gist, float with MPFR), ensure dependencies were available.
  • The test component requires BUILD_TESTING to be true in the installed package's configuration.
• Qt/Gist issues:
  • GECODE_ENABLE_QT=ON and GECODE_ENABLE_GIST=ON are requirement modes; use AUTO when dependency discovery should be best-effort.
  • GECODE_ENABLE_GIST=ON requires Qt discovery and a usable Qt link interface.
  • Gecode requires Qt 5.15 or newer. Qt 6 is preferred for new builds.
  • On macOS, Gist defaults to OFF; enable it explicitly once the local Qt/OpenGL framework setup is known to link. Current macOS SDKs require a current Qt 6 build; older Qt packages can still reference removed system frameworks.
• MPFR issues:
  • Use CMAKE_PREFIX_PATH, MPFR_ROOT, or toolchain include/link paths so find_package(MPFR) succeeds.
  • Installed packages built with MPFR first try config-mode MPFR discovery, then the installed FindMPFR.cmake. vcpkg consumers can rely on the active vcpkg toolchain or VCPKG_ROOT/VCPKG_TARGET_TRIPLET to provide the MPFR and GMP roots.