# 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”](https://dev.azure.com/LindeEngineering/LiPPS/_git/EPyC/pullrequest/17351), 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](https://dev.azure.com/LindeEngineering/LiPPS/_git/physical-properties-simulation-interface). Consumers including [M-SMILE](https://dev.azure.com/LindeEngineering/ITP-Smile/_git/M-SMILE), its [optisim_unit_interface](https://dev.azure.com/LindeEngineering/ITP-Smile/_git/optisim_unit_interface?path=%2F&version=GBmaster&_a=contents), [PHASE2_SPYDER_SMILE_models](https://dev.azure.com/LindeEngineering/SPYDER/_git/PHASE2_SPYDER_SMILE_models), and [EPyC](https://dev.azure.com/LindeEngineering/LiPPS/_git/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. ```mermaid 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](https://dev.azure.com/LindeEngineering/LiPPS/_git/physical-properties-simulation-interface/pullrequest/16573) 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: ```text 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: ```text 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`](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: - Downstream (this repo): `sympy_modeling` - Upstream (library): `physical-properties-simulation-interface` (already present here as a submodule at [external/physical-properties-simulation-interface](external/physical-properties-simulation-interface)) 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: ```bash 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.1 Recommended extensions for multi-repo work - **GitLens** (already required above) — per-repo Source Control sections, independent Commit Graphs, and File History/Blame that correctly attribute lines to the repo that actually owns the file. - **Built-in Source Control Graph** — VS Code includes a per-repository commit graph in the Source Control view. It is a lightweight alternative to GitLens' Commit Graph and does not require another extension. (The previously popular *Git Graph* extension is no longer actively maintained.) - **CMake Tools** — needed to configure/build/debug the combined `add_subdirectory` tree from inside VS Code (CMake kit/preset selection, build/test buttons, IntelliSense across both repos' sources). - **Peacock** — color-codes a window's title bar/status bar per workspace/folder. Handy once you routinely have an upstream-only window and a combined multi-root window open side by side, so you can tell at a glance which one you're editing in. - **Pull request tooling** — for GitHub, the *GitHub Pull Requests* extension lets you review and create PRs in VS Code. For Azure DevOps, there is currently no official Microsoft PR extension for VS Code (the old *Azure Repos* Team extension is deprecated). Use the Azure DevOps web UI or the `az repos pr` commands from the Azure CLI `azure-devops` extension. This matters once "land upstream first, then downstream" (Exercise 3, step 6) becomes routine. - **Project Manager** — quickly switch between saved multi-root workspace layouts (e.g. "Core + one model repo" vs. "Core + all model repos") without hunting for `.code-workspace` files manually. ### 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](CMakeLists.txt): ```cmake 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 )`. - 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/` 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: ```bash cd external/physical-properties-simulation-interface git checkout feature/ 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 ```bash # Add an upstream repo as a submodule git submodule add external/ # Clone a repo that has submodules git clone --recurse-submodules # 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/ fetch --tags git -C external/ checkout vX.Y.Z git add external/ # Update a submodule to the tip of its tracking branch (default: remote HEAD) git submodule update --remote external/ # Point a submodule at a specific local/remote branch for in-progress work cd external/ && git checkout && cd - git add external/ # stage the new pin in the downstream repo ``` ```cmake # Downstream CMakeLists.txt if(NOT TARGET ) # avoid duplicate targets in diamond graphs add_subdirectory(external/) endif() target_link_libraries(my_target PRIVATE ) ``` ```cmake # Alternative: FetchContent pinned to a commit; the first declaration wins include(FetchContent) FetchContent_Declare( GIT_REPOSITORY GIT_TAG ) FetchContent_MakeAvailable() ```