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.
1. Goal
Scaffold a new ORE Studio component following the component architecture: api/core/service layers, CMake wiring, component overview doc, and stub tests.
2. Preconditions
- Component name, purpose, and dependencies are defined.
- Build environment is configured.
3. 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, once per address:
--address ores.cmake.componentwrites theCMakeLists.txtfiles and--address ores.cppwrites the C++ presence (the overview's#+component_kind:frontmatter picks the flat/api/core/service variant). The overview scaffold writes:ores.cpp.scaffold.enabled: trueinto the drawer, because a component that has no models yet needs the first-generation scaffold: an umbrella header, a placeholder domain type with its implementation and a placeholder test. The line and the four files go together, once the first real model lands. The scaffold facet is#+default: disabled, so a component that does not carry the line never has them recreated, however often it is regenerated. - Wire CMake. Add the component to the top-level
projects/CMakeLists.txtand configure dependencies per CMake setup. - Add tests. Follow Unit test conventions to add a Catch2
test as the first real model lands. The
test_maincomes from codegen; a placeholder test comes from the opt-in scaffold in step 2 and goes with it. - 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.
4. Postconditions
- Component compiles and links.
- Stub tests pass.
- Component overview doc exists.
- PR is open.
5. See also
- Component architecture — api/core/service split.
- Runbooks catalogue — all runbooks.