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:

  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, once per address: --address ores.cmake.component writes the CMakeLists.txt files and --address ores.cpp writes the C++ presence (the overview's #+component_kind: frontmatter picks the flat/api/core/service variant). The overview scaffold writes :ores.cpp.scaffold.enabled: true into 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.
  3. Wire CMake. Add the component to the top-level projects/CMakeLists.txt and configure dependencies per CMake setup.
  4. Add tests. Follow Unit test conventions to add a Catch2 test as the first real model lands. The test_main comes from codegen; a placeholder test comes from the opt-in scaffold in step 2 and goes with it.
  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.

4. Postconditions

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

5. See also

Emacs 29.3 (Org mode 9.6.15)