Create a new component

Table of Contents

This page documents a runbook — a named, repeatable composition of recipes and skills for a complete multi-step procedure. Each step references a recipe or skill by id-link.

Goal

Scaffold a new ORE Studio component following the component architecture: api/core/service layers, CMake wiring, component overview doc, and stub tests.

Preconditions

  • Component name, purpose, and dependencies are defined.
  • Build environment is configured.

Steps

In execution order. Since PR #1014 the overview is the single source of truth for codegen — it must come before the C++ scaffold:

  1. Write the component overview(s). Follow How do I create a component overview? to scaffold and fill in each part. The scaffold template includes the codegen-readable keywords (#+name:, #+full_name:, #+brief:) so codegen can read identity straight off the overview. For a split component, create one overview per part under projects/ores.COMPONENT/{api,core,service}/modeling/; a group-level overview at projects/ores.COMPONENT/modeling/ is optional (used for navigation + group-level scalars).
  2. Scaffold the C++ + CMake. Use Component Creator to run codegen against each overview: codegen.sh generate --model <overview> --profile component(-api|-core|-service).
  3. Wire CMake. Add the component to the top-level projects/CMakeLists.txt and configure dependencies per CMake setup.
  4. Add stub tests. Follow Unit test conventions to add a Catch2 test skeleton (codegen already produces the test-main stub).
  5. Build and verify. Run cmake --build --preset <preset> and ctest to confirm the scaffold compiles and passes stub tests. Verify the codegen-side flow with python3 projects/ores.codegen/tests/component_scaffold/verify.py which exercises the loader + scaffold-path resolution against fixtures and prior art.
  6. Commit and PR. Use commit conventions and create a PR.

Postconditions

  • Component compiles and links.
  • Stub tests pass.
  • Component overview doc exists.
  • PR is open.

See also

Emacs 29.1 (Org mode 9.6.6)