Development Checks

Run the default parser, socket, and stub checks before changing the ABI, schema, renderer, or session runtime:

meson setup build -Dwith_tests=true
meson compile -C build
meson test -C build --print-errorlogs

Use focused suites while iterating, then run the default suite before pushing a public change:

Contract	Command
Full default ABI and parser suite	meson test -C build --print-errorlogs
Cap’n Proto decode and deck rendering	meson test -C build --suite cmocka --print-errorlogs
Session, topology, result sizing, and unit conversion	meson test -C build --suite e2e --print-errorlogs
Generated feature inventory	meson test -C build feature-inventory --print-errorlogs
Base &CPMD keyword inventory	meson test -C build cpmd-base-keyword-inventory --print-errorlogs
Top-level CPMDParams feature rows and duplicate inventory lists	meson test -C build cpmd-params-field-inventory --print-errorlogs
Public C ABI inventory	meson test -C build cpmd-public-abi-inventory --print-errorlogs
Stub ABI feature rows	meson test -C build stub-abi-symbol-coverage stub-abi --print-errorlogs
Shared library ABI exports	meson test -C build shared-dlopen-symbol-coverage shared-dlopen-abi --print-errorlogs
CPMDCpmdSection render mappings	meson test -C build cpmd-schema-render-coverage --print-errorlogs
Inline option token coverage	meson test -C build cpmd-option-token-coverage --print-errorlogs
Typed render field coverage	meson test -C build cpmd-typed-render-field-coverage --print-errorlogs
Long-tail directive section coverage	meson test -C build cpmd-long-tail-section-coverage --print-errorlogs
Escape-hatch carrier coverage	meson test -C build cpmd-escape-hatch-coverage --print-errorlogs
Embedding docs coverage	meson test -C build cpmd-embedding-docs-coverage --print-errorlogs
Public header docs coverage	meson test -C build cpmd-public-header-docs-coverage --print-errorlogs
Public host example docs	meson test -C build examples-documented --print-errorlogs
README and quickstart navigation	meson test -C build readme-navigation --print-errorlogs
OpenCPMD archive build	CPMDC_PSEUDO_DIR=/path/to/PP_LIBRARY meson test -C build-cpmd --print-errorlogs

Params render coverage lives under tests/cmocka/ and uses cmocka assertions on generated Cap’n Proto types (read_CPMDParams, deck substrings) only. Session tests use encoded CPMDParams and ForceInput fixtures from tests/*.capnp.txt. feature-inventory ties the generated JSON inventory to the schema, public feature table, docs, public headers, ABI symbol list, and optional CPMD_ROOT parser section probe. cpmd-base-keyword-inventory requires every base &CPMD keyword in schema/inventory/cpmd_cp_keywords.txt to resolve to a catalog.cpmd.* row. cpmd-params-field-inventory requires every top-level CPMDParams schema field to resolve to a params.* feature row and rejects duplicate inventory IDs/lists and C feature table duplicates before set comparisons can hide them. cpmd-public-abi-inventory requires every public cpmdc_* header function to resolve through abi_symbols and the feature table, then verifies the native src/cpmdc.c, stub src/cpmdc_stub.c, or shared src/cpmdc_features.c implementation that exports it. stub-abi-symbol-coverage requires the standalone stub test to assert every abi_symbols feature row is present and stub-applicable. shared-dlopen-symbol-coverage requires the shared-library dlopen test to load every abi_symbols entry from libcpmdc.so. cpmd-schema-render-coverage and cpmd-option-token-coverage keep typed CPMDCpmdSection fields and fixture inline tokens tied to render coverage. cpmd-typed-render-field-coverage requires typed cpmd, system, dft, and atoms fields to appear in render fixtures or render assertions. cpmd-long-tail-section-coverage requires every CPMDDirectiveSection union arm to appear in the long-tail fixture, render assertions, and option reference. cpmd-escape-hatch-coverage requires inputBlocks, generic, set, and raw carriers to stay covered by schema, fixtures, render tests, and option docs. cpmd-embedding-docs-coverage requires the embedding how-to to name the public ABI feature IDs plus the typed, long-tail, and escape-hatch CPMDParams carrier IDs used by host authors. cpmd-public-header-docs-coverage requires the public header and generated C API docs to describe the serialized CPMDParams input surface. examples-documented requires public docs to point at the runnable examples/host_step.c host program. readme-navigation keeps the README and quickstart docs focused on entry paths, work-loop labels, and current wording.

Add a typed CPMD keyword

Use a typed field when a CPMD control has stable structure, affects ordinary host inputs, or should be discoverable through cpmdc_feature_find(). Use directives, set, generic, raw, or inputBlocks for rare literal deck fragments that should stay text.

Start from the test surface:

File	Required change
tests/test_params_cp_dft_render.c	Add catalog coverage and rendered-token checks
tests/test_features_cmocka.c	Add catalog.cpmd.* and params.inputSections.cpmd.* expectations
tests/params_*.capnp.txt	Add a fixture value that exercises the new field

Run the focused failure before adding production code:

CPMD_ROOT=/tmp/OpenCPMD-cpmdc meson test -C build \
  params-cp-dft-render features-cmocka feature-inventory \
  cpmd-base-keyword-inventory cpmd-params-field-inventory \
  cpmd-public-abi-inventory cpmd-schema-render-coverage \
  stub-abi-symbol-coverage \
  shared-dlopen-symbol-coverage \
  cpmd-option-token-coverage cpmd-typed-render-field-coverage \
  cpmd-long-tail-section-coverage \
  cpmd-escape-hatch-coverage \
  --print-errorlogs

Then update the production and docs surface in one change:

File	Required change
schema/Potentials.capnp	Add the CPMDCpmdSection field with the next field number
src/cpmdc_params.c	Render the exact &CPMD deck spelling accepted by OpenCPMD
src/cpmdc_features.c	Add catalog and parameter feature table rows
schema/inventory/cpmd_features.json	Add matching inventory metadata
schema/inventory/cpmd_cp_keywords.txt	Add a base &CPMD keyword when the parser accepts it as a top-level control
docs/orgmode/reference/cpmd-options.org	Document every writable field ID

Re-run the focused command, then run:

meson test -C build --print-errorlogs
pixi run -e docs sphinxbld

For parser coverage audits, compare OpenCPMD control_utils.mod.F90 keyword_contains(line, ...) branches against catalog.cpmd.* rows. Treat context-specific branch tokens as covered by their structured parent when the schema field renders the accepted deck form, such as LBFGS_NTRUST for LBFGS NTRUST or NOSE_IONS_LOCAL for NOSE IONS LOCAL.

Source Layout

Path	Ownership
schema/Potentials.capnp	shared RPC and direct-call wire contract
include/cpmdc.h	public C ABI and session result entry points
include/cpmdc_features.h	runtime feature discovery ABI
src/cpmdc_params.c	Cap’n Proto decode, effective config, CPMD deck rendering
src/cpmdc.c	session lifecycle, topology guard, unit conversion, result writing
src/cpmd_embed_c_api.F90	Fortran iso_c_binding bridge and OpenCPMD archive path
tests/	encoded fixtures and C/cmocka contract tests

Documentation

Documentation source lives under docs/orgmode (authoritative prose), with light/dark logos in docs/source/_static/ and branding/logo/. Build docs (exports Org to RST, Doxygen XML, Sphinx HTML with Antics analytics):

pixi run -e docs docbld

Link between pages with Org file links, [[file:../howto/mpi.org][text]]. The export runs docs/org-links.lua through pandoc, which turns each relative .org link into a Sphinx :doc: reference, so the same link works on the forge and in the built site.

Regenerate RST after editing Org sources:

pixi run -e docs mkrst

The Sphinx theme injects antics-api.turtletech.us/antics.js via docs/source/_templates/partials/extra-head.html (same pattern as nwchemc / rgpot).

Release Process

• Versioning
• Checklist