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
6 changes: 6 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,9 @@ jobs:
- name: Run independent public header compilation tests
run: cmake -P tests/setup/test_header_checks.cmake

- name: Run static and in-source unit testing checks
run: cmake -P tests/setup/test_source_testing.cmake

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

Expand Down Expand Up @@ -82,6 +85,9 @@ jobs:
- name: Run independent public header compilation tests
run: cmake -P tests/setup/test_header_checks.cmake

- name: Run static and in-source unit testing checks
run: cmake -P tests/setup/test_source_testing.cmake

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

Expand Down
1 change: 1 addition & 0 deletions .scout/memory/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
- [[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/static-and-in-source-tests-require-separate-implementation-compilations.md|Static and in-source tests require separate implementation compilations]] (decision, 0.99) `cmake` `testing` `doctest` `static-linkage` `private-components` `generated-headers`
- [[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`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,23 @@ 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
last_accessed: 2026-11-19T20:40:56Z
last_reinforced: 2026-11-19T20:40:56Z
access_count: 3
sources:
- "cpp-library.cmake:314-323"
- "tests/setup/test_header_checks.cmake:151-159"
- "cpp-library.cmake:326-335"
- "tests/setup/test_header_checks.cmake:152-162"
tags: ["cmake", "header-verification", "testing", "file-sets"]
tier: knowledge
votes_up: 1
votes_down: 0
last_voted: 2026-11-19T20:41:02Z
---

# 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.
# 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. Keep unit tests' private src/ include root and generated testing configuration out of the production target's public interface so these checks remain independent.
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
---
title: "Static and in-source tests require separate implementation compilations"
entity_type: decision
confidence: 0.99
created: 2026-11-19T20:41:11Z
last_accessed: 2026-11-19T20:55:02Z
last_reinforced: 2026-11-19T20:55:02Z
access_count: 2
sources:
- "cmake/cpp-library-testing.cmake:8-60"
- "cmake/cpp-library-testing.cmake:62-96"
- "cmake/cpp-library-testing.cmake:9"
- "cmake/cpp-library-testing.cmake:18"
- "README.md:792"
tags: ["cmake", "testing", "doctest", "static-linkage", "private-components", "generated-headers"]
tier: knowledge
---

# Static and in-source tests require separate implementation compilations

# Static and in-source tests require separate implementation compilations

Preserve existing TESTS executable names and per-file mains. Their compiled component uses a separate production-mode static target, while <project>_in_source_tests compiles every implementation source directly with one generated doctest main. Do not combine these modes: enabling registrations in the ordinary static test library repeats embedded tests in existing binaries, while relying on archive extraction can silently omit registration-only translation units.

The private generated cpp-library/testing.hpp defines the function-style CPP_LIBRARY_TESTING() macro as 0 for production and the ordinary static implementation, and 1 for per-file test translation units and the separate in-source runner. Guard both doctest includes and cases with #if CPP_LIBRARY_TESTING(); never expose this generated header through installed public headers.

Finalize variants after the owner directory declares its sources, links, and generated-header dependencies. CMake file-set headers are stored separately from SOURCES: preserve HEADER_SETS and INTERFACE_HEADER_SETS generation ordering through one shared header-generation target used by production and both test variants. Requiring callers to add explicit add_dependencies() masks missing file-set support; clean direct test-target builds must also work without that workaround.

Static unit tests consume implementation compile requirements, including private requirements, rather than the production target's consumer-only compile definitions: the documented Windows DLL pattern adds an INTERFACE import definition that is incorrect for a static implementation. Keep production BUILD_SHARED_LIBS and third-party dependency linkage unchanged. Test targets and their private include roots are not exported.
68 changes: 66 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ cpp_library_enable_dependency_tracking()
# Now declare project
project(your-library LANGUAGES CXX)

# Enable testing infrastructure (required for TESTS and EXAMPLES)
# Enable testing infrastructure (required for SOURCES, TESTS, and EXAMPLES)
include(CTest)

# Setup library
Expand Down Expand Up @@ -791,7 +791,71 @@ precedence over the legacy variable.

### Testing

Uses [doctest](https://github.com/doctest/doctest) with CTest integration. Compile-fail tests are automatically detected via `_fail` suffix in filenames.
Tests use [doctest](https://github.com/doctest/doctest) with CTest integration.
Call `include(CTest)` at directory scope before `cpp_library_setup()`.
Development tests are enabled for top-level projects with `BUILD_TESTING=ON`.
Filenames containing `_fail` register compile-fail tests.

Each `TESTS` file remains a separate executable with its own main.
Unit tests link a separate static implementation, even when the production
library uses `BUILD_SHARED_LIBS=ON`. They inherit the implementation's private
build requirements rather than consumer-only DLL-import definitions. Dependencies
retain the client's selected linkage, so a test can still require third-party
DLLs. Examples continue to link the production library.

The library implementation and unit tests have a private `src/` include root.
Place private headers in `src/private/` and include them as
`#include "private/header.hpp"`. This path isn't added to the production
library's public interface or to the independent public-header checks.

#### In-source tests

Put tests for unnamed-namespace components in the same `.cpp` file as the
implementation. Include the generated private configuration header and guard
both the doctest include and test cases:

```cpp
#include <cpp-library/testing.hpp>

namespace {
/// Reports whether value is even.
constexpr bool is_even(unsigned value) noexcept {
return value % 2 == 0;
}
}

#if CPP_LIBRARY_TESTING()
#include <doctest/doctest.h>

TEST_CASE("even values") {
CHECK(is_even(0));
CHECK(is_even(4));
CHECK_FALSE(is_even(3));
}
#endif
```

After you include the configuration header, `CPP_LIBRARY_TESTING()` is always
defined as `0` or `1`. Use `#if CPP_LIBRARY_TESTING()`, not `#ifdef`, and don't
define it yourself. Production compilation and the static implementation used
by existing per-file tests use `0`; the in-source runner and the per-file test
sources use `1`. Keep this header private; don't include it from installed
public headers. Production compilation doesn't need doctest headers or libraries.

For compiled libraries, cpp-library adds `<project>_in_source_tests` to the normal
build and CTest, even if you omit `TESTS`. This separate executable compiles the
implementation with testing enabled and includes every source directly, so
registration-only translation units aren't lost inside a static archive.
cpp-library supplies its doctest main: don't define
`DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN` in implementation sources. Keep the existing
mains in your `TESTS` files unchanged. Embedded tests run only in the separate
runner, not again in each per-file executable.

Test variants require additional implementation compilation. They use the
library's finalized build settings, including dependencies and generated-header
ordering declared after `cpp_library_setup()`, and its configured C++ standard.
No in-source runner is added for header-only libraries, subprojects, or
`BUILD_TESTING=OFF`.

#### Public-header compilation

Expand Down
2 changes: 2 additions & 0 deletions cmake/cpp-library-setup.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,8 @@ function(_cpp_library_setup_core)
if(ARG_SOURCES)
# Respect the consumer's BUILD_SHARED_LIBS setting.
add_library(${ARG_NAME} ${ARG_SOURCES})
_cpp_library_setup_testing_config(TARGET "${ARG_NAME}" ENABLED 0)
target_include_directories(${ARG_NAME} PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/src")
if(NOT DEFINED CMAKE_CXX_EXTENSIONS)
set_target_properties(${ARG_NAME} PROPERTIES CXX_EXTENSIONS OFF)
endif()
Expand Down
117 changes: 116 additions & 1 deletion cmake/cpp-library-testing.cmake
Original file line number Diff line number Diff line change
@@ -1,10 +1,125 @@
# SPDX-License-Identifier: BSL-1.0
#
# cpp-library-testing.cmake - Runtime DLL deployment and testing compatibility
# cpp-library-testing.cmake - Private test configuration and executable support
#
# Provides cpp_library_copy_runtime_dlls for custom and toolkit-created executables.
# _cpp_library_setup_testing delegates to _cpp_library_setup_executables for compatibility.

# Adds a private, always-defined function-style testing configuration.
function(_cpp_library_setup_testing_config)
cmake_parse_arguments(ARG "" "TARGET;ENABLED" "" ${ARGN})
set(directory "${CMAKE_CURRENT_BINARY_DIR}/cpp-library/testing-${ARG_ENABLED}")
file(CONFIGURE OUTPUT "${directory}/cpp-library/testing.hpp"
CONTENT "#pragma once\n#define CPP_LIBRARY_TESTING() @ARG_ENABLED@\n" @ONLY)
target_include_directories("${ARG_TARGET}" BEFORE PRIVATE "${directory}")
endfunction()

# Copies finalized build requirements without linking the production implementation.
function(_cpp_library_finish_test_target source destination)
get_target_property(sources "${source}" SOURCES)
target_sources("${destination}" PRIVATE ${sources})
# File-set headers aren't SOURCES; share their generation before any compilation.
set(header_target "${source}_test_headers")
if(NOT TARGET "${header_target}")
get_property(header_sets TARGET "${source}" PROPERTY HEADER_SETS)
get_property(interface_sets TARGET "${source}" PROPERTY INTERFACE_HEADER_SETS)
list(APPEND header_sets ${interface_sets})
list(REMOVE_DUPLICATES header_sets)
set(headers)
foreach(header_set IN LISTS header_sets)
if(header_set STREQUAL "HEADERS")
get_property(files TARGET "${source}" PROPERTY HEADER_SET)
else()
get_property(files TARGET "${source}" PROPERTY "HEADER_SET_${header_set}")
endif()
list(APPEND headers ${files})
endforeach()
if(headers)
list(REMOVE_DUPLICATES headers)
add_custom_target("${header_target}" DEPENDS ${headers})
add_dependencies("${source}" "${header_target}")
endif()
endif()
if(TARGET "${header_target}")
add_dependencies("${destination}" "${header_target}")
endif()
get_target_property(type "${destination}" TYPE)
set(compile_usage INCLUDE_DIRECTORIES COMPILE_DEFINITIONS COMPILE_OPTIONS COMPILE_FEATURES)
foreach(property INCLUDE_DIRECTORIES COMPILE_DEFINITIONS COMPILE_OPTIONS
COMPILE_FEATURES CXX_STANDARD CXX_STANDARD_REQUIRED CXX_EXTENSIONS
CXX_VISIBILITY_PRESET VISIBILITY_INLINES_HIDDEN POSITION_INDEPENDENT_CODE
CXX_CLANG_TIDY CXX_COMPILER_LAUNCHER LINK_OPTIONS LINK_DIRECTORIES
INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
INTERFACE_LINK_OPTIONS INTERFACE_LINK_DIRECTORIES
INTERFACE_LINK_LIBRARIES_DIRECT INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE)
get_property(is_set TARGET "${source}" PROPERTY "${property}" SET)
if(is_set)
get_target_property(value "${source}" "${property}")
set_property(TARGET "${destination}" PROPERTY "${property}" "${value}")
if(type STREQUAL "STATIC_LIBRARY" AND property IN_LIST compile_usage)
# Unit tests consume implementation settings, not DLL-import definitions.
set_property(TARGET "${destination}" PROPERTY "INTERFACE_${property}" "${value}")
endif()
endif()
endforeach()
get_target_property(links "${source}" LINK_LIBRARIES)
if(links)
if(type STREQUAL "STATIC_LIBRARY")
target_link_libraries("${destination}" PUBLIC ${links})
else()
target_link_libraries("${destination}" PRIVATE ${links})
endif()
endif()
get_target_property(standard "${source}" CXX_STANDARD)
if(type STREQUAL "STATIC_LIBRARY" AND standard)
target_compile_features("${destination}" INTERFACE "cxx_std_${standard}")
endif()
get_target_property(interface_links "${source}" INTERFACE_LINK_LIBRARIES)
if(interface_links)
target_link_libraries("${destination}" INTERFACE ${interface_links})
endif()
get_target_property(dependencies "${source}" MANUALLY_ADDED_DEPENDENCIES)
if(dependencies)
add_dependencies("${destination}" ${dependencies})
endif()
endfunction()

# Configures the separate runner after all implementation requirements are known.
function(_cpp_library_finish_in_source_tests source destination)
_cpp_library_finish_test_target("${source}" "${destination}")
_cpp_library_setup_testing_config(TARGET "${destination}" ENABLED 1)
target_link_libraries("${destination}" PRIVATE doctest::doctest)
endfunction()

# Creates static per-file test support and a separate in-source runner.
function(_cpp_library_setup_test_support)
cmake_parse_arguments(ARG "" "TARGET" "" ${ARGN})
get_target_property(type "${ARG_TARGET}" TYPE)
set(test_target "${ARG_TARGET}")
if(NOT type STREQUAL "INTERFACE_LIBRARY")
set(test_target "${ARG_TARGET}_static_tests")
add_library("${test_target}" STATIC EXCLUDE_FROM_ALL)
cmake_language(EVAL CODE
"cmake_language(DEFER CALL _cpp_library_finish_test_target
[[${ARG_TARGET}]] [[${test_target}]])")
endif()
set_property(TARGET "${ARG_TARGET}" PROPERTY _CPP_LIBRARY_UNIT_TEST_TARGET "${test_target}")
if(NOT type STREQUAL "INTERFACE_LIBRARY")
set(runner "${ARG_TARGET}_in_source_tests")
set(main "${CMAKE_CURRENT_BINARY_DIR}/cpp-library/${runner}.cpp")
file(CONFIGURE OUTPUT "${main}" CONTENT
"#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN\n#include <doctest/doctest.h>\n")
add_executable("${runner}" "${main}")
cmake_language(EVAL CODE
"cmake_language(DEFER CALL _cpp_library_finish_in_source_tests
[[${ARG_TARGET}]] [[${runner}]])")
cpp_library_copy_runtime_dlls("${runner}")
add_test(NAME "${runner}" COMMAND "${runner}")
set_tests_properties("${runner}" PROPERTIES LABELS doctest
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")
endif()
endfunction()

# Deploys runtime DLLs beside a custom target on Windows; empty lists need no copy.
# Call in the directory that created the target, as required by POST_BUILD commands.
function(cpp_library_copy_runtime_dlls target)
Expand Down
Loading
Loading