Developer Guide

This section covers the day-to-day development workflow for rgpot.

Environment Setup

All development is managed through pixi. Install it first, then:

pixi install          # default environment (build + test)
pixi shell            # activate the environment

Available environments:

Environment

Purpose

(default)

C/C++ build tools, Rust toolchain, linting

rpctest

RPC integration tests (pycapnp, numpy)

devbld

Full dev build (RPC + cache features)

docs

Documentation build (Sphinx, Doxygen, doxyrest)

cigen

CI workflow generation (Nickel)

Common Tasks

All tasks are invoked via pixi r <task>:

Task

Description

rust-test

Run Rust unit tests with nextest

rust-test-all

Run Rust tests with all features enabled

gen-header

Regenerate include/rgpot.h from Rust source via cbindgen

gen-gha

Regenerate nickel-exported workflows (release/docs/cosmo; not orchestrator)

towncrier-draft

Preview release notes (dry run)

towncrier-build

Write release notes into CHANGELOG.md

release-potctl / potctl

Project CLI (cargo run -p potctl -- …; pixi r release-potctl -- release assert)

release-sync-versions

Lockstep write (potctl release sync; pixi r release-sync-versions -- 1.2.3)

release-assert-lockstep

Assert meson/cmake/cargo/towncrier/pixi/pyproject agree (potctl release assert)

release-extract-changelog

One CHANGELOG.md section (potctl release notes; optional -o)

release-towncrier-check

towncrier check vs base (CI: orchestrator towncrier job on PRs)

Cut release

On main: cog bump --auto (cog 7+) then git push --follow-tags; see release.org

Potentials CI

ci-orchestrator.yml jobs potentials_metatomic / potentials_tight_binding

docbld

Build full documentation (org export + Doxygen + Sphinx)

docdel

Clean all generated documentation artifacts

gen-readme

Export rgpot-core/README.org to README.md (docs env)

snapper-check / snapper-fix

Semantic line breaks (TurtleTech snapper; GHA orchestrator docs_snapper)

lychee-check

Link audit with lychee (.lychee.toml; GHA orchestrator docs_lychee)

prek / prek-install / prek-validate

Run / install / validate prek.toml hooks (GHA orchestrator prek job)

Regenerating the C Header

The C header rgpot-core/include/rgpot.h is auto-generated by cbindgen from the Rust source. It is committed to the repository so C/C++ consumers always have a working copy. After changing the public Rust API:

pixi r gen-header
git diff rgpot-core/include/rgpot.h  # review changes

The gen-header feature is excluded from default builds and from cargo publish to avoid modifying the source tree during packaging.

Building Documentation

Documentation is built with Sphinx and served at [[https://rgpot.rgoswami.me] [rgpot.rgoswami.me]]. It combines:

  • Org-mode pages (this guide, architecture, changelog) exported to RST

  • C++ API reference generated by Doxygen + doxyrest

  • Rust API reference generated by sphinxcontrib-rust

To build locally:

pixi r -e docs docbld
# Open docs/build/index.html

To clean generated artifacts:

pixi r -e docs docdel

Git hooks (prek)

Hooks are configured in prek.toml and run with prek (Rust drop-in for pre-commit). Prefer prek over pre-commit / uvx pre-commit.

# one-time: install shims into .git/hooks
pixi r prek-install   # or: prek install

# run all hooks on the whole tree (CI parity)
pixi r prek           # or: prek run -a --config prek.toml

# validate config only
pixi r prek-validate

CI runs prek run -a on every PR via CI (orchestrator) (prek job). Org docs also go through snapper (semantic line breaks); links are audited separately by orchestrator docs_lychee (and weekly schedule).