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 GitHub Actions workflow from Nickel template

towncrier-draft

Preview release notes (dry run)

towncrier-build

Write release notes into CHANGELOG.md

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)

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

Pre-commit Hooks

uvx pre-commit run --all-files

CI runs these automatically on every PR via pipx run prek.