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_uma_engine (potctl ci metatomic-test --rpc) / potentials_tight_binding / potentials_plugins (potctl ci plugin-test); see One job and one ccache key per pixi environment

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)

One job and one ccache key per pixi environment

Each pixi environment that builds the project runs in its own CI job with its own compiler-cache key (ccache-pot-mta-, ccache-pot-engine-, …). Two environments in one job share the step environment and the cache directory. potctl ci ensure-torch-metatomic exports the torch and cmake paths of its environment through GITHUB_ENV, so a later step in another environment inherits them, and a cache entry written against one environment’s headers can satisfy a build against another’s. A metatomicbld build followed by an umaenginebld build in one job linked objects compiled against Catch2 3.13 headers with the Catch2 3.16 library of the second environment, and failed at the link of plugin_test. Add a new environment leg as a new job, not as another step of an existing one.

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).