Developer FAQ

Why is cbindgen behind a feature flag?

cargo publish forbids build scripts that modify the source directory. Since cbindgen writes include/rgpot.h into the crate tree, it must be opt- in. The committed header is the canonical copy; regenerate it with pixi r gen- header when the public Rust API changes.

Why is the Cap’n Proto schema bundled?

The schema at rgpot-core/schema/Potentials.capnp is included in the crate so that the rpc feature works when installed from crates.io, where the monorepo’s CppCore/ directory is not available. The build.rs tries the bundled copy first, then falls back to CppCore/rgpot/ rpc/Potentials.capnp in the monorepo.

Why is the crate README in org-mode?

The source of truth is rgpot-core/README.org. It is exported to README.md via pixi r -e docs gen-readme (which uses Emacs ox-md). The rendered markdown is committed and referenced by Cargo.toml for display on crates.io. Edit the .org file, then regenerate.

How do I add a new pixi environment?

Edit pixi.toml: add a feature section with its dependencies, then register it in [environments]. See the existing rpctest and docs features as examples.

Where does the Rust API documentation come from?

The Sphinx extension sphinxcontrib-rust parses the Rust source directly (rgpot-core/src/) and generates RST during sphinx-build. The output goes to docs/source/crates/rgpot_core/ and is included in the main documentation site alongside the C++ API reference.

How do I run a single Rust test?

cargo nextest run --manifest-path rgpot-core/Cargo.toml -E 'test(test_name)'

Or with standard cargo test:

cargo test --manifest-path rgpot-core/Cargo.toml -- test_name