Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,8 +120,9 @@ consumer templates.
prefix, the alias strips it. Matching namespace and clean project name collapse
to one package name rather than duplicating it.
- Consumer versions come from Git tags with a leading `v` removed.
`CPP_LIBRARY_VERSION` overrides Git discovery for source archives and package
managers; missing tags fall back to `0.0.0` with a warning.
`CPP_LIBRARY_VERSION_<PROJECT_NAME>` overrides Git discovery for the exact CMake
project name. Legacy `CPP_LIBRARY_VERSION` applies only to the top-level project;
missing tags fall back to `0.0.0` with a warning.
- Non-namespaced dependency targets need explicit mappings such as
`cpp_library_map_dependency(opencv_core "OpenCV 4.8")`. Keep dependency
declarations after `project()` in the top-level consumer scope; explicit
Expand Down
32 changes: 32 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,12 @@ jobs:
- name: Run target type tests
run: cmake -P tests/setup/test_target_type.cmake

- name: Run independent public header compilation tests
run: cmake -P tests/setup/test_header_checks.cmake

- name: Run project version override tests
run: cmake -P tests/setup/test_version_override.cmake

- name: Run install directory tests
run: cmake -P tests/setup/test_install_dirs.cmake

Expand All @@ -50,9 +56,35 @@ jobs:
# [DEPENDENCY] https://github.com/ilammy/msvc-dev-cmd/releases
- uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756

- name: Verify documented PowerShell scaffold commands
shell: pwsh
run: |
$work = Join-Path $env:RUNNER_TEMP "cpp-library-powershell-scaffold"
New-Item -ItemType Directory -Path $work | Out-Null
Set-Location $work
$setupUrl = "https://raw.githubusercontent.com/stlab/cpp-library/main/setup.cmake"
Invoke-WebRequest -UseBasicParsing -Uri $setupUrl -OutFile setup.cmake
cmake -P setup.cmake -- `
--name=my-library `
--namespace=mycompany `
--description="My awesome library" `
--header-only=yes `
--examples=yes `
--tests=yes
if ($LASTEXITCODE -ne 0) { throw "Scaffolding failed" }
if (!(Test-Path -LiteralPath "my-library/CMakeLists.txt")) {
throw "The scaffold did not create CMakeLists.txt"
}

- name: Run target type tests
run: cmake -P tests/setup/test_target_type.cmake

- name: Run independent public header compilation tests
run: cmake -P tests/setup/test_header_checks.cmake

- name: Run project version override tests
run: cmake -P tests/setup/test_version_override.cmake

- name: Run install directory tests
run: cmake -P tests/setup/test_install_dirs.cmake

Expand Down
4 changes: 4 additions & 0 deletions .scout/memory/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,15 @@
- [[knowledge/architecture-overview.md|Architecture Overview]] (concept, 0.80) `architecture-overview` `cpp-library-architecture` `cpp-library-overview` `toolkit-architecture` `cmake-infrastructure-overview`
- [[knowledge/consumer-lifecycle-and-template-overwrite-controls.md|Consumer Lifecycle and Template Overwrite Controls]] (decision, 0.75) `template-initialization` `cpp-library-force-init` `project-is-top-level` `lightweight-consumer-mode` `template-copying`
- [[knowledge/deferred-install-dependency-validation-and-config-generation.md|Deferred Install Dependency Validation and Config Generation]] (pattern, 0.75) `deferred-install` `install-validation` `untracked-dependencies` `cmake-language-defer` `find-dependency`
- [[knowledge/dependency-mappings-follow-the-exported-target-s-owning-project.md|Dependency mappings follow the exported target's owning project]] (discovery, 0.99) `cmake` `dependency-mappings` `project-scope` `deferred-install`
- [[knowledge/dependency-tracking-lifecycle-and-provider-ordering.md|Dependency Tracking Lifecycle and Provider Ordering]] (observation, 0.75) `dependency-tracking` `dependency-provider` `cpp-library-enable-dependency-tracking` `cmake-project-top-level-includes` `set-dependency-provider`
- [[knowledge/documentation-setup-and-theme-integration-with-build-docs.md|Documentation Setup and Theme Integration with BUILD_DOCS]] (pattern, 0.75) `build-docs` `doxygen` `doxygen-awesome-css` `documentation-generation` `docs-target`
- [[knowledge/generated-ci-package-artifact-check.md|Generated CI package artifact check]] (decision, 0.95) `ci` `packaging` `cmake`
- [[knowledge/installation-supports-separately-installed-dependencies-not-mixed-source-export-workarounds.md|Installation supports separately installed dependencies, not mixed source export workarounds]] (decision, 0.99) `cmake` `installation` `cpm` `supported-boundary`
- [[knowledge/public-header-verification-must-participate-in-the-default-build.md|Public-header verification must participate in the default build]] (pattern, 0.99) `cmake` `header-verification` `testing` `file-sets`
- [[knowledge/target-naming-and-alias-deduplication-convention.md|Target Naming and Alias Deduplication Convention]] (pattern, 0.75) `target-naming` `alias-deduplication` `package-name` `clean-name` `cmake-alias-convention`
- [[knowledge/testing-and-example-executable-target-generation-gated-by-build-testing.md|Testing and Example Executable Target Generation Gated by BUILD_TESTING]] (pattern, 0.75) `build-testing` `doctest` `testing-setup` `negative-compilation-tests` `runtime-dll-copy`
- [[knowledge/version-overrides-must-not-leak-into-independently-named-subprojects.md|Version overrides must not leak into independently named subprojects]] (decision, 0.99) `cmake` `versions` `project-scope` `package-managers`

## Procedures

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
title: "Dependency mappings follow the exported target's owning project"
entity_type: discovery
confidence: 0.99
created: 2026-11-18T23:22:31Z
last_accessed: 2026-11-18T23:22:31Z
last_reinforced: 2026-11-18T23:22:31Z
access_count: 1
sources:
- "cmake/cpp-library-install.cmake:34-40"
- "cmake/cpp-library-install.cmake:65-68"
tags: ["cmake", "dependency-mappings", "project-scope", "deferred-install"]
tier: knowledge
---

# Dependency mappings follow the exported target's owning project

Explicit dependency mappings are isolated per CMake project. Registration keys GLOBAL properties by SHA256(PROJECT_BINARY_DIR) plus dependency target. Generation must derive PROJECT_BINARY_DIR from the exported target's BINARY_DIR, not from the directory calling the generator. Helper directories and deferred package finalization can generate another project's target; using caller scope leaks or selects the wrong override. Non-project subdirectories share the owning project's mappings; nested and sibling projects do not. Retain the binary-directory identity so separate configurations of the same source project remain distinct. The GLOBAL storage also supports the script-mode mock harness; do not replace it with an unscoped target-only key.
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
title: "Installation supports separately installed dependencies, not mixed source export workarounds"
entity_type: decision
confidence: 0.99
created: 2026-11-18T23:22:41Z
last_accessed: 2026-11-18T23:22:41Z
last_reinforced: 2026-11-18T23:22:41Z
access_count: 1
sources:
- "README.md:215-226"
- "README.md:240-245"
- "cmake/cpp-library-install.cmake:70-72"
tags: ["cmake", "installation", "cpm", "supported-boundary"]
tier: knowledge
---

# Installation supports separately installed dependencies, not mixed source export workarounds

The supported installation workflow installs required dependencies separately before configuring the component, then has CPM resolve those installed packages. Installing a component against dependencies fetched from source in that same build is explicitly unsupported. Ordinary source consumption uses ordinary PUBLIC/INTERFACE target links, not BUILD_INTERFACE/INSTALL_INTERFACE wrappers to bypass export checks. CMake validates enabled installation exports during configuration/generation, before cmake --install; source-only builds without installed dependencies should disable component installation. Do not reintroduce the removed special extraction of BUILD_INTERFACE dependencies into installed find_dependency() requirements. CPM_USE_LOCAL_PACKAGES is only a preference and may fall back to source; it does not guarantee this installation precondition.
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
title: "Public-header verification must participate in the default build"
entity_type: pattern
confidence: 0.99
created: 2026-11-19T00:38:12Z
last_accessed: 2026-11-19T00:38:12Z
last_reinforced: 2026-11-19T00:38:12Z
access_count: 1
sources:
- "cpp-library.cmake:314-323"
- "tests/setup/test_header_checks.cmake:151-159"
tags: ["cmake", "header-verification", "testing", "file-sets"]
tier: knowledge
---

# Public-header verification must participate in the default build

cpp_library_setup() enables native CMake VERIFY_INTERFACE_HEADER_SETS only for top-level projects with BUILD_TESTING enabled. Preserve both the target property and the ALL custom target dependency on <target>_verify_interface_header_sets: native verification targets are excluded from the default build, so setting the property alone does not enforce the check. Keep verification based on PUBLIC/INTERFACE header file sets rather than a second header list; this includes generated headers and file sets added after setup. These build-time, per-header checks are separate from configure-time clangd indexing. C++17/20/23 fixtures check the configured standard, public usage requirements, generated-header ordering, and the testing-off/subproject scope boundaries. Platform-specific public headers must guard their contents and be no-ops when unsupported; do not introduce platform-exclusion lists.
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
title: "Version overrides must not leak into independently named subprojects"
entity_type: decision
confidence: 0.99
created: 2026-11-18T23:22:35Z
last_accessed: 2026-11-18T23:22:35Z
last_reinforced: 2026-11-18T23:22:35Z
access_count: 1
sources:
- "cmake/cpp-library-setup.cmake:5-23"
- "README.md:769-790"
tags: ["cmake", "versions", "project-scope", "package-managers"]
tier: knowledge
---

# Version overrides must not leak into independently named subprojects

Both cpp_library_setup() and cpp_library_set_version() share _cpp_library_get_git_version(). Override precedence is: nonempty CPP_LIBRARY_VERSION_<PROJECT_NAME> for the exact case-sensitive CMake project() name (hyphens included); nonempty legacy CPP_LIBRARY_VERSION only for PROJECT_IS_TOP_LEVEL; then the project's Git tag; then the existing warning and 0.0.0 fallback. A cache entry for the legacy variable otherwise leaks through nested directory scopes and incorrectly overwrites dependency ConfigVersion.cmake files. Package managers overriding nested projects must use the scoped variable; do not restore unconditional legacy-variable lookup. Independently named children and siblings must retain their own tags or explicit scoped overrides.
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ or pin to a specific commit: `CPMAddPackage("gh:stlab/cpp-library#<commit-sha>")
2. Consumer calls `project(name)`, then `include(CTest)` if using TESTS/EXAMPLES, then `cpp_library_setup(NAMESPACE ... HEADERS ... [SOURCES ...] [TESTS ...] [EXAMPLES ...])`.
3. `cpp_library_setup()`:
- Derives `PACKAGE_NAME` (namespace-prefixed, e.g. `stlab-enum-ops`) and `CLEAN_NAME` (namespace stripped from `PROJECT_NAME`).
- Sets project version from git tags (`_cpp_library_get_git_version`, overridable via `CPP_LIBRARY_VERSION` cache var for package managers without git history).
- Sets project version from git tags (`_cpp_library_get_git_version`, overridable via `CPP_LIBRARY_VERSION_<PROJECT_NAME>` for the exact CMake project name). Legacy `CPP_LIBRARY_VERSION` applies only to the top-level project.
- Creates the library target (`INTERFACE` if no `SOURCES`, else a compiled target respecting `BUILD_SHARED_LIBS`) with `FILE_SET headers`, aliased as `NAMESPACE::CLEAN_NAME`.
- Calls `_cpp_library_setup_install()`, which is gated by `${NAMESPACE}_INSTALL` (default `PROJECT_IS_TOP_LEVEL`) and uses `cmake_language(DEFER)` to generate `Config.cmake` and register install-time dependency validation *after* all `target_link_libraries()` calls in the consumer's `CMakeLists.txt` have executed (deferred calls run LIFO — validation is registered first so it executes last, right before config files are written).
- If `PROJECT_IS_TOP_LEVEL`: also copies static template files (`.clang-format`, `.gitignore`, `CMakePresets.json`, etc. — skipped if already present unless `CPP_LIBRARY_FORCE_INIT` is set), configures the CI workflow, downloads doctest, and wires up `TESTS`/`EXAMPLES`/`docs`. When consumed as a subproject (not top-level), it returns early after target creation — "lightweight consumer mode".
Expand Down
Loading
Loading