Multi-Repo Development with VS Code (GitLens) and CMake add_subdirectory

Audience: software developers currently working in monorepos (OPTISIM, GMPS) Duration: 60 minutes (20 min motivation/intro, 40 min hands-on) Goal: understand why and how to split a codebase into independently versioned, reusable repositories, and be able to make a coordinated change that spans an “upstream” (library) repo and a “downstream” (consumer) repo inside a single VS Code window.


Part 1 — Motivation (20 min)

1.1 The problem with monorepos like OPTISIM and GMPS - and EPyC

Monorepos feel convenient at first: one clone, one build, one history. In practice, as these codebases grow, that convenience inverts:

  • Everything is coupled to everything. A change to a low-level numerical routine can’t be reviewed, tested, or released independently of the application code that happens to live next to it in the same repo.

  • No enforced boundaries. Nothing stops a “core” module from reaching into “application” internals, because there is no repository boundary — only folder convention, which is easy to violate under deadline pressure.

  • One version to rule them all. Every consumer is forced onto the same revision of every component. You cannot let one product move faster/slower than another, or pin a stable dependency while actively developing on top of it.

  • Reusability is theoretical. Code described as “reusable” that has never been extracted into its own repo usually isn’t — it has undocumented dependencies on the rest of the monorepo that only become visible when someone actually tries to reuse it elsewhere.

  • CI and review scale badly. Large, unrelated changes land in the same history; blame/bisect and code review both get harder as the repo grows.

This is not just a theoretical concern: EPyC PR 17351, “Use foreign model interface submodule”, makes the model contract an explicit, pinned repository dependency. That gives EPyC and model-producing repositories a deliberate boundary: they can coordinate through a shared interface without making the contract an implicit dependency on another repository’s internals.

None of this is a tooling problem — it’s an architecture problem. Splitting a monorepo into multiple repositories is a forcing function that makes the architecture honest: if two components can’t be separated into their own repos with a clean API between them, they were never properly decoupled in the first place.

1.2 Software engineering principles — they apply at the repo level too

We already apply these principles at the class/module level. The point of today’s session is that they apply one level up, at the repository boundary:

Principle

Module level

Repo level

SoC (Separation of Concerns)

Split classes/files by responsibility

Split repos by responsibility/domain (numerics vs. product logic vs. UI)

DIP (Dependency Inversion)

Depend on abstractions, not concretions

Downstream repos depend on a published, versioned interface/API of the upstream repo, not on its internal source layout

ISP (Interface Segregation)

Small, focused interfaces per consumer

A repo should expose a minimal, stable public surface — not “everything that happens to be public in the header”

A repo boundary is a much stronger enforcement of these principles than a folder boundary: you cannot #include "../../../other_teams_internal.hpp" across a repo boundary by accident, because it simply isn’t there until you deliberately add it as a dependency.

1.3 A proven DIP example and its application to model interfaces

An established example of the Dependency Inversion Principle (DIP) in this ecosystem is the physical-properties-simulation-interface. Consumers including M-SMILE, its optisim_unit_interface, PHASE2_SPYDER_SMILE_models, and EPyC rely on this contract rather than depending directly on physical-property backend implementations. Conceptually, GMPS can also be viewed as a consumer of the same contract, making it possible to use EPyC as a replay-testable alternative backend to GMPS.

The dependency graph below shows those consumers and this workspace’s concrete integration. Solid arrows indicate dependencies on the interface contract; the dashed GMPS arrow reflects the conceptual relationship described above.

flowchart LR
    subgraph Consumers
        M_SMILE["M-SMILE"]
        optisim["optisim_unit_interface"]
        phase2["PHASE2_SPYDER_SMILE_models"]
        EPyC
        sympy_modeling["sympy_modeling (this repo)"]
        GMPS
    end
    interface["physical-properties-simulation-interface"]

    M_SMILE --> interface
    optisim --> interface
    phase2 --> interface
    EPyC --> interface
    sympy_modeling -->|"git submodule + add_subdirectory"| interface
    GMPS -.-> interface

That contract boundary has enabled observability and replay-testability of physical-property interactions. The mprops_replay PR adds a PowerLog recording, replay, and validation tool. It also provides a proven integration-testing approach for an upcoming Spyder requirement: dispatching between physical-property backends at runtime. The dispatch can live in the composition layer, physical-properties-simulation-interface, without changes to Spyder or to the backends, and the existing replay framework can test the integrations.

This existing success is a practical starting point for the upcoming foreign_model_interface split: define a contract that lets reusable core code work with different model implementations. In this design:

  • EPyC Core provides generic simulation and numerical infrastructure. It depends on the model interface, not on any particular model implementation.

  • EPyC models contains concrete models, including models generated with this sympy_modeling project. The repositories are composed from submodules like this:

    EPyC-models
    └── sympy_modeling (git submodule)
        └── foreign_model_interface (git submodule)
    
    EPyC-core
    └── foreign_model_interface (git submodule)
    

    Each indented repository is a git submodule of the repository directly above it. foreign_model_interface is the shared contract: sympy_modeling produces models that follow it, and EPyC Core uses it without depending on sympy_modeling itself.

The same contract lets EPyC Core serve other applications with different models. For example:

Spyder-core
├── EPyC-core (git submodule)
│   └── foreign_model_interface (git submodule)
└── Spyder-models (git submodule)
    └── sympy_modeling (git submodule)
        └── foreign_model_interface (git submodule)

Here, Spyder-core combines the reusable EPyC Core with a separate Spyder-models repository. The model implementation can vary by application while EPyC Core continues to depend only on the shared interface.

Note the diamond dependency: foreign_model_interface is reachable through both EPyC-core and sympy_modeling. If each nested copy is added with add_subdirectory, CMake fails because the same target is defined twice. If the copies are pinned to different commits, the build may also mix two versions of the contract, which can violate C++’s one-definition rule (ODR). The top-level repository must therefore own the single shared copy:

  • Nested repositories guard their own inclusion, for example if(NOT TARGET foreign_model_interface) add_subdirectory(...) endif(). The top-level repository adds its pinned copy first.

  • Alternatively, declare shared dependencies with CMake FetchContent pinned to a commit hash. The first declaration wins, so the top-level project decides which version is used.

Either way, the top-level repository decides which contract version is used for the entire build.

This workspace also uses the existing external/physical-properties-simulation-interface repository as a git submodule, wired into the build with add_subdirectory. The hands-on exercises use that real dependency to explore the multi-repo workflow behind this proven pattern.

1.4 What “multi-repo” does not mean

  • It does not mean “copy-paste the code into every consumer.” The whole point is a single source of truth per component, consumed by reference (submodule pin / package version), not by duplication.

  • It does not mean upstream changes silently flow downstream and break consumers. A git submodule pins an exact upstream commit, so downstreams take an upstream change only when they deliberately update that pin. An explicit submodule-update PR makes the revision visible and reviewable, and gives the team a chance to test compatibility before merging. This mitigates accidental breakage; it does not replace testing the update.

  • It does not require consuming upstream as a separately built NuGet or Azure Artifacts package. With this workflow, add_subdirectory builds the pinned upstream source as part of the downstream CMake build, keeping headers and binaries together under the same compiler and build configuration instead of relying on ABI compatibility between independently built packages. It also makes stepping across upstream and downstream source in one debugging session straightforward. On Windows, deploying and loading matching PDB files for separately built packages can be fragile.

    • Binary packages remain valid when you need prebuilt distribution. In that case, use Source Link with a symbol server (Azure Artifacts provides one), or embed debug info with /Z7. These approaches reduce, but do not remove, the debugging and ABI friction.

    • Source-building package managers, such as vcpkg in manifest mode with a custom registry or overlay ports, or Conan, also avoid ABI mismatches by building from source with consistent settings. They are a reasonable alternative once the dependency graph grows beyond a few submodules.

  • It does not mean giving up a good developer experience. VS Code multi-root workspaces + GitLens give you a single window with full visibility and navigation across repos — you don’t lose the “monorepo feel” by splitting repos.

  • It does not mean every change becomes a cross-repo change. Most day-to-day work stays within one repo. Cross-repo changes are the exception, and today’s hands-on is specifically about handling that exception well.


Part 2 — Hands-on (40 min)

2.0 Setup (do this before the session if possible)

  1. Clone both repos locally:

  2. Open a multi-root VS Code workspace containing both as top-level folders (File > Add Folder to Workspace…). VS Code also detects submodules when you open only the outer repository (git.detectSubmodules), but a multi-root workspace makes each repository an explicit top-level entry in the Explorer, Source Control, and GitLens views.

  3. Install/verify the GitLens extension is active in both folders.

  4. Optionally save the multi-root layout as a .code-workspace file so everyone on the team opens the exact same folder set instead of reconstructing it by hand each time.

  5. Configure Git to handle submodules safely:

    git config --global submodule.recurse true          # checkout/pull also update submodules
    git config --global push.recurseSubmodules check    # refuse to push a pin to an unpushed submodule commit
    

2.2 Exercise 1: Navigate two repos in one window

  1. In the Source Control view, confirm you see two independent repos listed, each with its own branch, staged changes, and history.

  2. Open GitLens’ Commit Graph for the upstream repo (physical-properties-simulation-interface) and separately for the downstream repo (sympy_modeling). Note that commit history, branches, and tags are completely independent per repo.

  3. Use GitLens File History on a header in external/physical-properties-simulation-interface/include/ to see that it’s tracked by the upstream repo’s own history, not the downstream repo’s.

2.3 Exercise 2: Understand the add_subdirectory wiring

Look at the top-level CMakeLists.txt:

add_subdirectory(external/physical-properties-simulation-interface)
add_subdirectory(cpp_tests)
  • add_subdirectory pulls the upstream repo’s own CMakeLists.txt into the downstream build as a first-class subproject: its targets, include directories, and exported interface become available to cpp_tests (and anything else in this build) by name — e.g. target_link_libraries(my_target PRIVATE <upstream_target>).

  • Crucially, the downstream repo only depends on whatever the upstream repo chooses to export from its own CMakeLists.txt (its public targets) — this is ISP at the repo level: the upstream decides its public surface and can keep the rest private.

  • The dependency is pinned by the submodule commit, recorded as a gitlink in the parent repo’s tree; .gitmodules records only the URL and path (and optionally a tracking branch). The pin is not “whatever is newest”. Upgrading upstream is an explicit, reviewable action: check out the new release tag or commit in the submodule, review the diff, and commit the new pin.

2.4 Exercise 3: Make a coordinated upstream + downstream change

This is the core exercise. In pairs:

  1. Pick (or invent) a small API change to a function in the upstream repo (physical-properties-simulation-interface), e.g. add a new optional parameter, or rename a function.

  2. Create a feature branch in the upstream repo for that change (git checkout -b feature/<name> inside the upstream folder). Implement + build the change there.

  3. Create a matching feature branch in the downstream repo (sympy_modeling) to update the submodule pointer and adapt any call sites to the new API.

  4. Point the submodule at your local upstream branch so you can iterate without pushing yet:

    cd external/physical-properties-simulation-interface
    git checkout feature/<name>
    cd ../..
    git add external/physical-properties-simulation-interface   # records new pin
    

    Do not push this downstream commit until the upstream commit is pushed. push.recurseSubmodules=check from setup step 5 enforces this.

  5. Build the whole workspace from the top-level CMakeLists.txt and confirm the downstream code compiles/links/tests against your in-progress upstream change — this is the “simultaneous edit” workflow: you are editing both repos at once and validating the combination locally, before either branch is merged.

  6. Land them in the right order: merge/PR the upstream feature branch first, then update the downstream branch’s submodule pin to the merged upstream commit (not your local branch tip), and merge the downstream PR. This ordering is the key discipline of multi-repo work — downstream never depends on an unmerged/unpushed upstream commit once it’s ready to land. With squash or rebase merges, the commit on the upstream default branch has a different hash from your feature-branch commit, so you must re-pin to the new commit. Otherwise, the pinned commit can disappear when the feature branch is deleted.

2.5 Discussion / wrap-up

  • What felt harder than monorepo editing? (Usually: remembering to commit the submodule pin; the two-PR merge order.)

  • What felt better? (Usually: clear API boundary, smaller reviewable diffs, confidence that upstream wasn’t accidentally broken for other consumers.)

  • Where else in OPTISIM/GMPS do we already have an informal “this part is actually reusable” boundary that could become a real repo boundary?


Part 3 — Best practices worth adopting from day one

  • Only land pins to commits on the upstream default or release branch. Feature-branch commits move, and they can disappear after a squash or rebase merge followed by branch deletion. Add a CI check (or PR template checklist item) on the downstream repo that fails if the recorded submodule commit isn’t reachable from the upstream repo’s default or release branch. This automatically enforces the “local branch for iteration, merged commit for landing” rule from Exercise 3.

  • Check out submodules in CI. In Azure Pipelines, use checkout: self with submodules: recursive. If a submodule lives in another Azure DevOps project, grant the pipeline’s build identity read access to that repository; otherwise, the checkout fails.

  • Let the top-level repository own shared dependencies. In diamond-shaped graphs (see section 1.3), the top-level repository decides which commit of a shared dependency is built. Nested copies must not add a second instance of the same target.

  • Version the upstream repo’s public surface, not just its commits. Tag releases (semantic versioning: breaking API change -> major) so downstream repos can reason about “did this bump introduce a breaking change” from the tag alone, without reading the diff. A floating main pin tells you nothing about compatibility.

  • Keep the dependency graph acyclic. EPyC Models and EPyC Core both depend on foreign_model_interface; neither depends directly on the other. If either needs something from a specific implementation, that’s a signal the interface boundary may be in the wrong place, not a reason to introduce a cyclic dependency.

  • Make the exported surface explicit in CMake, not implicit. Use PUBLIC/INTERFACE on target_include_directories/target_link_libraries, and an actual install()/export set if the library is meant to be consumed outside the build tree. Anything not explicitly exported is private, even if the header happens to be physically reachable.

  • Write contract/integration tests at the boundary. A handful of tests in the downstream repo that exercise only the upstream repo’s public API (not its internals) catch breaking changes immediately in CI, independent of whichever internal refactor upstream did to get there.

  • Automate routine dependency bumps, review breaking ones manually. Renovate supports Azure DevOps and git submodules, and can open a PR automatically when upstream publishes a new release. Dependabot does not support Azure DevOps natively. Routine or patch bumps need light review, but major or breaking version bumps should get the same scrutiny as the Exercise 3 workflow.

  • Publish a changelog per upstream repo. Even a short one. “What changed and why” at the point of a tagged release is far cheaper for a downstream consumer to read than re-deriving it from a commit diff before deciding whether to bump.

  • Don’t over-fragment. A repo boundary should track a genuinely independent, reusable, separately-versioned unit (like EPyC Core) — not just “this folder got a bit big.” Splitting purely for file-count or team-ownership reasons without a real reuse/versioning need just adds submodule-management overhead for no benefit.

  • Define a deprecation policy for upstream public API removal, even an informal one (e.g. “deprecated functions stay for one minor version with a warning before removal”), so downstream repos aren’t broken without notice by an upstream repo they don’t control the release cadence of.


Appendix: Quick reference

# Add an upstream repo as a submodule
git submodule add <url> external/<name>

# Clone a repo that has submodules
git clone --recurse-submodules <url>

# Recommended Git settings for submodules
git config --global submodule.recurse true
git config --global push.recurseSubmodules check

# Bump a submodule to a release tag
git -C external/<name> fetch --tags
git -C external/<name> checkout vX.Y.Z
git add external/<name>

# Update a submodule to the tip of its tracking branch (default: remote HEAD)
git submodule update --remote external/<name>

# Point a submodule at a specific local/remote branch for in-progress work
cd external/<name> && git checkout <branch> && cd - 
git add external/<name>   # stage the new pin in the downstream repo
# Downstream CMakeLists.txt
if(NOT TARGET <upstream_exported_target>)   # avoid duplicate targets in diamond graphs
  add_subdirectory(external/<name>)
endif()
target_link_libraries(my_target PRIVATE <upstream_exported_target>)
# Alternative: FetchContent pinned to a commit; the first declaration wins
include(FetchContent)
FetchContent_Declare(<name>
  GIT_REPOSITORY <url>
  GIT_TAG        <full-commit-hash>)
FetchContent_MakeAvailable(<name>)