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

.. code:: bash

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

Or with standard ``cargo test``:

.. code:: bash

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