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:
- 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 underprojects/ores.COMPONENT/{api,core,service}/modeling/; a group-level overview atprojects/ores.COMPONENT/modeling/is optional (used for navigation + group-level scalars). - Scaffold the C++ + CMake. Use Component Creator to run codegen
against each overview:
codegen.sh generate --model <overview> --profile component(-api|-core|-service). - Wire CMake. Add the component to the top-level
projects/CMakeLists.txtand configure dependencies per CMake setup. - Add stub tests. Follow Unit test conventions to add a Catch2 test skeleton (codegen already produces the test-main stub).
- Build and verify. Run
cmake --build --preset <preset>andctestto confirm the scaffold compiles and passes stub tests. Verify the codegen-side flow withpython3 projects/ores.codegen/tests/component_scaffold/verify.pywhich exercises the loader + scaffold-path resolution against fixtures and prior art. - 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
- Component architecture — api/core/service split.
- Runbooks catalogue — all runbooks.