Superbuild workflow

This section publishes documentation for the superbuild workflow — the authoritative shared policy repository for superbuild-style software workspaces using CMake, Conan, and multi-repository coordination.

Source of truth

Item	Location
GitLab path	ai-workflows/superbuild-workflow
Canonical docs	docs/*.md in that repository
Agent entry point	AGENTS.md in that repository
Local clone (example)	../superbuild-workflow relative to this portal

This page is portal-owned framing. The substantive workflow documentation in this section is mirrored from superbuild-workflow for publication. Edit policy and procedures in the workflow repository first, then sync into this portal.

pip install -r requirements-sync.txt
python scripts/sync_workflow.py superbuild --source ../superbuild-workflow

On develop, GitLab CI in superbuild-workflow triggers an automated downstream sync in this portal.

What the superbuild workflow covers

The upstream repository defines:

• Physical workspace model: multiple Git repositories coordinated by a CMake/Conan superbuild
• Build policy: CMake as authoritative build description, Conan for dependencies and toolchains
• Governance: what belongs in shared policy vs consuming repositories
• AI tool integration: Cursor adapters and portable AGENTS.md guidance
• Legacy migration methodology for workspaces moving from split Linux/Windows build systems

Consuming product repositories mount superbuild-workflow at tools/ai-rules/ (or equivalent). This portal does not replace that consumption model — it publishes the same documentation for centralized reading and search.

Reading order

After syncing upstream content, a typical reading path is:

1. Architecture and rationale — why the superbuild workflow exists
2. Repository layout and governance — what lives where
3. CMake/Conan policy and philosophy — build system rules
4. Workflow and development process — how changes land
5. Cursor and alternative tool integration — AI-assisted development
6. Legacy migration docs — when migrating existing superbuilds

Mirrored pages are listed in the sidebar after sync. Re-run sync when upstream docs change on develop.

Editing guidance

Change type	Where to edit
Superbuild policy, migration spec, governance	superbuild-workflow → sync here
Section intro, portal navigation, cross-links	This file and portal config
Site-wide portal documentation	docs-common/ in docs-portal

Do not treat mirrored pages in docs-superbuild/ as the primary editing location.