gecode

CMake build and package reference

This reference covers CMake builds, installation, and downstream packages. For modelling and search, use MPG and the API reference linked from the README.

Requirements

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. Autoconf builds require uv on PATH.
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

Quick Start

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

Visual Studio + vcpkg (MPFR)

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.

Test Targets

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 Conventions and Key Options

Common CMake options

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.
GECODE_INSTALL: controls install and export rules; defaults to ON for top-level builds and OFF for subprojects.
CMAKE_BUILD_TYPE / multi-config --config: standard build mode control

Autoconf and CMake options

CMake exposes options aligned with the Autoconf switches:

Autoconf switch	CMake option / mechanism	Status	Notes
`--enable-shared`	`GECODE_BUILD_SHARED`	Supported directly	Default `ON`
`--enable-static`	`GECODE_BUILD_STATIC`	Supported directly	Default `OFF`
`--enable-thread`	`GECODE_ENABLE_THREAD`	Supported directly	Default `ON`
`--enable-osx-unfair-mutex`	`GECODE_ENABLE_OSX_UNFAIR_MUTEX`	Supported directly	Default `ON`
`--enable-qt`	`GECODE_ENABLE_QT`	Supported directly	`AUTO` by default; Qt 6 preferred; Qt 5.15+ supported
`--enable-gist`	`GECODE_ENABLE_GIST`	Supported directly	`AUTO` by default except macOS; disabled automatically if Qt GUI support is unavailable
`--enable-cpprofiler`	`GECODE_ENABLE_CPPROFILER`	Supported directly	Default `ON`
`--enable-cbs`	`GECODE_ENABLE_CBS`	Supported directly	Default `OFF`
`--enable-examples`	`GECODE_ENABLE_EXAMPLES`	Supported directly	Default `ON` for top-level builds, `OFF` for subprojects
`--enable-experimental`	`GECODE_ENABLE_EXPERIMENTAL`	Supported directly	Default `OFF`; enables preview APIs
`--enable-search`	`GECODE_ENABLE_SEARCH`	Supported directly	Default `ON`
`--enable-int-vars`	`GECODE_ENABLE_INT_VARS`	Supported directly	Default `ON`
`--enable-set-vars`	`GECODE_ENABLE_SET_VARS`	Supported directly	Default `ON`
`--enable-float-vars`	`GECODE_ENABLE_FLOAT_VARS`	Supported directly	Default `ON`
`--enable-minimodel`	`GECODE_ENABLE_MINIMODEL`	Supported directly	Default `ON`
`--enable-instance`	`GECODE_ENABLE_INSTANCE`	Supported directly	Default `ON`; enabled with the driver
`--enable-driver`	`GECODE_ENABLE_DRIVER`	Supported directly	Default `ON`
`--enable-flatzinc`	`GECODE_ENABLE_FLATZINC`	Supported directly	Default `ON`
`--enable-mpfr`	`GECODE_ENABLE_MPFR`	Supported directly	Default `ON`; uses `find_package(MPFR)`
`--enable-allocator`	`GECODE_ENABLE_ALLOCATOR`	Supported directly	Default `ON`
`--enable-audit`	`GECODE_ENABLE_AUDIT`	Supported directly	Default `OFF`
None	`GECODE_ENABLE_FAULT_INJECTION`	CMake-only	Test-only, process-global failpoints in an isolated single-threaded `check-fault` suite; default `OFF`
None	`GECODE_SANITIZER`	CMake-only	`address`, `undefined`, `address-undefined`, or `thread`; currently requires GCC/Clang-style flags
`--enable-gcc-visibility`	`GECODE_ENABLE_GCC_VISIBILITY`	Supported directly	Default `ON`
`--with-freelist32-size-max`	`GECODE_FREELIST32_SIZE_MAX`	Supported directly	Cache string
`--with-freelist64-size-max`	`GECODE_FREELIST64_SIZE_MAX`	Supported directly	Cache string
`--with-vis`	`GECODE_WITH_VIS`	Supported directly	Comma-separated list
`--with-lib-prefix`	`GECODE_LIB_PREFIX`	Supported directly	Prefixes generated library basenames
`--with-lib-suffix`	`GECODE_LIB_SUFFIX`	Supported directly	Suffixes generated library basenames
`--enable-debug`	`CMAKE_BUILD_TYPE=Debug` (or multi-config `Debug`)	Mapped to native CMake mechanism	Use standard CMake build-type workflows
`--enable-small-codesize`	`CMAKE_BUILD_TYPE=MinSizeRel` or compiler size flags	Mapped to native CMake mechanism	Use standard size-optimized build settings
`--enable-leak-debug`	None	Not supported in CMake	No CMake option enables the `GECODE_HAS_MTRACE` test hook
`--enable-profile`	Toolchain/CMake compile+link flags	Mapped to native CMake mechanism	Configure profiling via standard compiler flags
`--enable-gcov`	Toolchain/CMake coverage flags	Mapped to native CMake mechanism	Configure coverage instrumentation via compiler/linker flags
`--with-mpfr-include`, `--with-mpfr-lib`	`CMAKE_PREFIX_PATH`, `MPFR_ROOT`, toolchain include/link paths	Mapped to native CMake mechanism	Use CMake package and toolchain discovery
`--with-gmp-include`, `--with-gmp-lib`	Toolchain include/link paths	Mapped to native CMake mechanism	GMP is resolved through MPFR/toolchain linkage
`--with-host-os`	None	Not supported in CMake	Generator/toolchain already determine host/target platform
`--with-compiler-vendor`	None	Not supported in CMake	Compiler is selected through toolchain and generator
`--with-sdk`, `--with-macosx-version-min`, `--with-architectures`	None	Not supported in CMake	Use native CMake/macOS toolchain settings
`--enable-framework`	None	Not supported in CMake	No framework-bundle generator path is implemented
`--enable-resource`	None	Not supported in CMake	No autoconf-style resource toggle in CMake
`--enable-peakheap`	None	Not supported in CMake	No CMake option defines the peak-heap tracking macros
`--enable-doc-dot`, `--enable-doc-search`, `--enable-doc-tagfile`	`GECODE_DOC_DOT`, `GECODE_DOC_SEARCH`, `GECODE_DOC_TAGFILE`	Supported by `doc` target	Requires Doxygen 1.18.0 or newer; helper pages require `uv`
None	`GECODE_ENABLE_MIMALLOC`	CMake-only	Default `OFF`; private allocator backend

Higher-level modules enable the lower-level modules they require. Examples and FlatZinc require the core modelling modules; minimodel requires int and search support.

GECODE_ENABLE_QT and GECODE_ENABLE_GIST accept AUTO, ON, and OFF. ON requires their dependencies; AUTO uses them when available. Enabling Qt-backed FlatZinc plugin support can add a public Qt Core dependency to Gecode::gecodeflatzinc.

GECODE_ENABLE_EXPERIMENTAL=ON enables preview APIs, including AStar and CABS. It is disabled by default. Preview APIs may change or be removed in future feature releases.

Allocator, testing, and documentation options

GECODE_ENABLE_MIMALLOC: downloads and embeds mimalloc 3.5.3 for Gecode heap and space storage in shared and static libraries. Default OFF. Requires GECODE_ENABLE_ALLOCATOR=ON; incompatible with GECODE_SANITIZER and GECODE_PEAKHEAP. Application malloc and new are unaffected. Embedded mimalloc symbols use a gecode_ prefix to avoid conflicts with an application’s own mimalloc; they remain hidden in shared libraries. Rebuild consumers when changing backends.
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.18.0 or newer and uv; Graphviz dot is used when available and GECODE_DOC_DOT=ON.

A directly set GECODE_BUILD_SHARED or GECODE_BUILD_STATIC overrides the BUILD_SHARED_LIBS default. Configuration reports the enabled and disabled features after dependency discovery. For Qt, Gist, MPFR, visibility, macOS mutexes, Graphviz, and tests, it also reports the requested setting.

CMake uses the checked-in gecode/kernel/var-type.hpp and var-imp.hpp by default. GECODE_REGENERATE_VARIMP=ON regenerates them. A nonempty GECODE_WITH_VIS list enables regeneration automatically; relative specification paths are resolved from the source directory.

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 and sanitizers

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

Using Gecode From Other CMake Projects

Recommended aggregate target

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)

Component targets

Canonical component names:

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

Example:

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

Test component for custom propagators

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, gecodeinstance, gecodedriver, gecodeflatzinc, gecodegist

Package location hints

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

Version checks

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.

Migration Notes

Deprecated cache variable aliases

Deprecated	Replacement
`ENABLE_THREADS`	`GECODE_ENABLE_THREAD`
`ENABLE_GIST`	`GECODE_ENABLE_GIST`
`BUILD_EXAMPLES`	`GECODE_ENABLE_EXAMPLES`
`ENABLE_CPPROFILER`	`GECODE_ENABLE_CPPROFILER`

Deprecation horizon:

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

Troubleshooting

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.

This site is open source. Improve this page.