How to Build Zappy¶

This page explains everything you need to install to build and run the Zappy project. It is structured into sections for:

Minimal delivery (AI / Server / GUI)
Runner
Documentation
Development (extra)

Where possible, two approaches are described:

Using Nix (recommended for reproducibility)
Traditional/manual install (for portability)

Minimal delivery (AI / Server / GUI)¶

These are the core components needed to run or develop the server, AI, and GUI separately.

Using Nix (recommended)

If you have Nix installed:

nix develop

This will enter a shell with all dependencies available for building the server, AI, and GUI.

Traditional (manual) install

You’ll need to install these system packages yourself:

Common build tools: - bash - coreutils - gnugrep - findutils - GNU Make - pkg-config
Server: - gcc - glibc (with math libraries)
AI: - Python 3.13 (or compatible) with pip - virtualenv or Python’s built-in venv module - pip packages:
- setuptools
- hatching
GUI: - g++ (with libstdc++) - SDL2 - SDL2_image - glew - GL, GLU - glm - mesa
Optional: - ncurses (for pretty Makefile logs)

Runner¶

The runner tool (to coordinate AI, server, GUI in one command) requires:

Using Nix (recommended)

Nix is the only requirement:

nix run github:Sigmapitech/zappy/zappy-runner

This will handle all other builds and dependencies automatically.

Traditional (manual) install

There is no non-Nix delivery for the runner. If you want to avoid Nix entirely, you’ll have to run the server, AI, and GUI manually in separate terminals, using the minimal delivery setup above.

Documentation¶

To build the Sphinx documentation:

Using Nix

All packages are included in the dev shell:

nix develop
make -C docs html

Traditional install

You’ll need:

System - doxygen - libxml
Python packages (install via pip) - sphinx - furo - breathe - exhale - beautifulsoup4 - six - linkify-it-py - myst-parser - sphinx-copybutton - sphinx-design - sphinx-notfound-page - sphinx-sitemap

Example:

pip install sphinx furo breathe exhale beautifulsoup4 six linkify-it-py myst-parser \
    sphinx-copybutton sphinx-design sphinx-notfound-page sphinx-sitemap

Then:

doxygen
make -C docs html

Development (extra)¶

Additional tools recommended for testing, coverage, linting, and advanced debugging.

Using Nix

These are included in the dev shell:

nix develop

Traditional install

You can install these manually via your system package manager or pip.

Testing and coverage - gcovr - libcoverage - pytest
Static analysis and formatting - compiledb - clang-tools - black - mypy - isort - vulture
Logging & profiling - hl-log-viewer - valgrind - kcachegrind - graphviz

Recommended approach¶

We strongly recommend using Nix for development:

nix develop

This ensures:

Reproducible builds
All dependencies present
Correct versions matched to the project

You can build/run each package from their nix derivation, following the flake schema:

└───packages
└───x86_64-linux
    ├───ai: package 'python3.13-zappy-ai'
    ├───bleach: package 'bleach-0.0.1'
    ├───cpp-fmt: package 'cpp-fmt'
    ├───default: package 'zappy'
    ├───doc: package 'doc'
    ├───exhale: package 'python3.13-exhale-0.3.7'
    ├───gui: package 'zappy-gui-0.0.1'
    ├───ref: package 'ref'
    ├───ref-gui: package 'ref-gui-3.0.0'
    ├───ref-server: package 'ref-server-3.0.1'
    ├───runner: package 'python3.13-zappy'
    ├───server: package 'zappy-server-0.0.1'
    └───server-debug: package 'zappy-server-0.0.1'

Note: it is recommended to derectly build/run the final derivation (default), that contains our delivery and reference binaries, alongside the zappy-runner … see instructions on how to use the zappy-runner

If you prefer manual installs, make sure to match the versions in your package manager as closely as possible to avoid compatibility issues.