Docs advise projects shouldn't set CMAKE_VERIFY_INTERFACE_HEADER_SETS, but that is questionable
At the moment, the docs for CMAKE_VERIFY_INTERFACE_HEADER_SETS
state the following:
Projects should not set this variable, it is intended as a developer control to be set on the cmake(1) command line or other equivalent methods. The developer must have the ability to enable or disable header set verification according to the capabilities of their own machine and compiler.
However, thinking about how more complex project hierarchies are structured and the way dependencies may be brought into the build, I don't think this is appropriate advice. Consider projects that use FetchContent to build their dependencies from source, or that add them directly from git submodules. Users typically wouldn't want verification targets for the dependencies, but they might for the main project's headers. Without help from the project, they can't easily do that. Setting CMAKE_VERIFY_INTERFACE_HEADER_SETS
as a cache variable would enable verification for the whole build, including the dependencies. In large monorepo projects, there could be many dependencies in the build. Even if the user elects to build just some of the main project, there could be many verification targets created due to all the dependencies, and this may be an annoyance for the user.
My instinct when starting to use this feature was to treat it like all the other target properties that support initialization from a CMAKE_<propertyName>
variable. These are routinely set by the project as a more convenient way of setting default behavior across a whole project. My feeling is that this is actually more of a project control than a user control. The project knows whether it expects its headers to be properly formed and not rely on including any other header ahead of it. Therefore, the project should be able to enable this feature. The user would still explicitly have to ask for the verification targets to be built. This would allow the project to set things up appropriately for the user, who can then make a build time decision whether they want verification or not.
I'd recommend modifying the docs and adding an example that does something like the following, which also highlights how to be a good citizen for hierarchical projects:
cmake_minimum_required(VERSION 3.24)
project(SomeExample)
# Include the project's dependencies first, which can use a variety of methods
find_package(...) # Could redirect to building from source via FetchContent
FetchContent_MakeAvailable(...) # Assuming you FetchContent_Declare() them first
add_subdirectory(...) # Vendored sources, e.g. as git submodules
# Add the project's own sources
if(PROJECT_IS_TOP_LEVEL)
set(CMAKE_VERIFY_INTERFACE_HEADER_SETS TRUE)
endif()
add_subdirectory(src)