Superbuild philosophy
What "superbuild" means in this workflow, why multiple Git repositories are coordinated from a workspace root, and how first-party source differs from third-party or patched code.
Definition
A superbuild is a workspace root whose primary job is to orchestrate multiple software components into one coherent build tree — not to contain all source inline. The root CMake project (and associated Conan workspace recipe) defines:
- Which components participate
- Build order and dependencies between them
- Shared toolchain, options, and install layout
Individual components often live in separate Git repositories under src/ (first-party) or libs/ (vendored/patched third-party).
Why multiple repositories
| Factor | Benefit |
|---|---|
| Team ownership | Repos match team or component boundaries |
| Access control | Finer-grained permissions per component |
| Release cadence | Components version and tag independently |
| Reuse | Same library repo in multiple superbuilds |
| History clarity | Product meta-repo commits track integration, not every line of code |
A monorepo is valid but not assumed. This workflow targets organizations already using or preferring multi-repo + superbuild.
Physical vs logical workspace
- Logical workspace — one developer checkout that builds the full product
- Physical layout — superbuild root +
src/*repos + optionallibs/*+tools/ai-rules
The superbuild root is the integration anchor. Cloning "the product" means cloning the meta-repository and initializing submodules (including tools/ai-rules and src/ components).
First-party: src/
Code the organization maintains as product or platform:
- Feature development happens here
- CI often runs per-repo and at superbuild level
- APIs between components are contractual; breaking changes coordinated via superbuild bumps
Agents should default to editing repositories under src/ for product features, not the superbuild root — unless changing integration, options, or global dependencies.
Third-party and patched: libs/
Material that is not first-party but is built inside the workspace:
- Upstream snapshots with local patches
- Dependencies with no suitable Conan package
- Transition holding area before Conan adoption
libs/ is not a junk drawer. Each entry should have documented reason and owner in the consumer AGENTS.md.
Conan vs libs/
Prefer Conan for mainstream dependencies with acceptable packages. Use libs/ when:
- No reliable Conan recipe exists
- Required patches are not upstreamable quickly
- Legal or air-gap constraints require vendoring
The superbuild still integrates libs/ targets via CMake like any other subproject.
Shared workflow submodule
tools/ai-rules/ is another coordinated repository — not compiled into the product, but required for consistent developer and agent behavior across superbuilds. It follows the same submodule discipline as src/ components.
Integration changes vs component changes
| Change type | Typical location |
|---|---|
| New first-party module | New or existing repo under src/ + superbuild CMake registration |
| Add Conan dependency | Consumer conanfile.py / recipe + CMake find_package |
| Vendor library | libs/<name> + superbuild subdirectory |
| Shared agent/build policy | tools/ai-rules/ upstream repo |
Agents must not conflate superbuild integration edits with shared workflow policy edits.
Failure modes this model avoids
- Secret monorepo — everything copied into one tree without boundary discipline
- Orphan repos — components built only by hand, not in CI superbuild
- Undocumented vendoring — duplicate deps in Conan and
libs/ - Workflow drift — each superbuild invents its own agent instructions
Related documents
- repository-layout.md — directory map
- cmake-conan-policy.md — build and dependency rules
- architecture.md — policy vs product layers