Solvitaire: A general solver for perfect-information solitaire games

Building and Running

Solvitaire requires a C++14 compiler, CMake 3.14+, and the Boost libraries. The compiled Boost component needed is program_options; several header-only components (multi_index, optional, pool, property_tree, random) are also used and are included automatically with any standard Boost installation. The primary development branch is dev, which is tested on macOS (Apple Silicon) and Linux (x86_64 / arm64).

---

(a) macOS

Prerequisites (Homebrew):

brew install cmake boost

Build and test:

./build.sh                            # release build (default)
python3 scripts/run_tests.py          # all 3 gates (release/trace/debug)
python3 scripts/run_tests.py --quick  # unit tests only (~5 min)

Run:

./cmake-build-release/bin/solvitaire --type klondike --random 42

---

(b) Linux

Prerequisites (Ubuntu 22.04 / Debian):

sudo apt-get install build-essential cmake libboost-program-options-dev git python3

Build and test:

./build.sh                            # release build (default)
python3 scripts/run_tests.py          # all 3 gates (release/trace/debug)
python3 scripts/run_tests.py --quick  # unit tests only (~5 min)

Run:

./cmake-build-release/bin/solvitaire --type klondike --random 42

---

(c) Container (Linux build on macOS or any host)

Requires the Apple container CLI, Docker, or Podman.

Build image and run unit tests:

./scripts/container-build.sh --test

Build image and run Level 1 regression suite:

./scripts/container-build.sh --regression

Build image only:

./scripts/container-build.sh

Interactive shell inside the container:

container run --rm -it solvitaire-dev bash

By default the script forces a clean build on every run (to avoid stale-cache issues with container CLI v0.9). Pass --use-cache to reuse the apt install layer when on a slow network.

---

Usage

List supported game types:

./cmake-build-release/bin/solvitaire --available-game-types

Solve a random Klondike deal (seed 42):

./cmake-build-release/bin/solvitaire --type klondike --random 42

Solve from a JSON deal file:

./cmake-build-release/bin/solvitaire --type free-cell path/to/deal.json

Key options: --type, --random <seed>, --json, --timeout <ms>, --cache-capacity <n>, --streamliners {none|auto-foundations|suit-symmetry|both|smart}, --solvability <N>.

---

Testing

The project uses a 3-gate testing model (release, trace, debug). All three gates must pass before committing. See docs/testing-quickstart.md for a quick introduction and docs/testing-guide.md for the comprehensive reference.

python3 scripts/run_tests.py          # all 3 gates — required before every commit
python3 scripts/run_tests.py --quick  # unit tests only, all 3 configs
python3 scripts/run_tests.py --gate release --skip-build  # single gate, pre-built

Help

If you have any problems, please open an issue on GitHub.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Charlie Blake 💻 🎨 🤔

Ian Gent 💻 🎨 🤔

Shlomi Fish 💻

Gal Cohensius 📖

This project follows the all-contributors specification. Contributions of any kind welcome!