XCSP-Launcher

XCSP-Launcher is a unified tool to install, build, and execute solvers supporting the XCSP3 format.

It provides a streamlined way to manage solvers, automate their compilation, and run constraint programming instances through a standard, extensible interface.

✨ Features

• 🛠️ Solver installation from GitHub, GitLab, or custom URLs
• 🧱 Automatic or manual build (Gradle, CMake, Makefile, Cargo, Maven, etc.)
• 🔖 Solver versioning and multi-version management
• ⚡ Unified execution interface for solving XCSP3 instances
• 📝 Support for solver configuration files (.xsc.yaml) for reproducibility
• 📄 Detailed logging of build and run processes
• 🧩 Extensible: Easily add support for new solvers

📦 Installation

You can install xcsp-launcher via PyPI:

pip install xcsp

Or from source:

git clone https://github.com/CPToolset/xcsp-launcher.git
cd xcsp-launcher
pip install .

sudo dpkg -i xcsp-launcher*.deb

brew tap CPToolset/homebrew-xcsp-launcher
brew install xcsp

🚀 Quick Start

Install a solver

xcsp install --id ace --name ACE --repo xcsp3team/ace --source github.com

This will:

• Clone the solver repository,
• Automatically detect the build system (or use configuration),
• Build the solver,
• Register it in your local solver repository.

Solve an instance

xcsp solve --solver ace --instance path/to/instance.xml

🧰 Example Configuration (.xsc.yaml)

name: "ACE"
id: "fr.cril.xcsp.ace"
git: "https://github.com/xcsp3team/ace"
language: "java"
build:
  mode: manual
  build_command: "gradle build -x test"
command:
  prefix: "java -jar"
  template: "{{executable}} {{instance}} {{options}}"
  always_include_options: "-npc=true -ev"
versions:
  - version: "2.4"
    git_tag: "2.4"
    executable: "build/lib/ACE-2.4.jar"

For more information about the format of the solver-configuration please see the documentation of metrics.

🛠 Supported Build Systems (Auto-detection)

• Gradle (build.gradle)
• Maven (pom.xml)
• CMake (CMakeLists.txt)
• Make (Makefile)
• Rust Cargo (Cargo.toml)
• Python setuptools (setup.py, pyproject.toml)

📚 Other Projects

• xcsp-launcher-homebrew — Homebrew Tap for installing XCSP-Launcher easily on macOS/Linux.
• xcsp-metadata — A metadata repository for XCSP3 instances (domains, categories, etc.).
• metrics-solver — Predefined solver configurations available by default with xcsp-launcher for easy installation and experimentation.

🚀 Projects Using XCSP-Launcher

• metrics — An open-source Python library to automate experimental campaigns and analyze solver performances.

🤝 Contributing

We welcome contributions!
Feel free to open issues, suggest features, or submit pull requests.

Please read CONTRIBUTING.md for guidelines.

⚖️ License

This project is licensed under the LGPL v3+ License.
See LICENSE for details.

🌍 Related Links

• XCSP3 Official Website
• PyCSP3 Python Modeling Library