FILE_SET: Add VERIFY_HEADER_SETS target property

Fixes: #23338

5 files changed, 50 insertions, 0 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 65f9248..968a3b1 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -380,6 +380,7 @@ Properties on Targets
    /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE
    /prop_tgt/UNITY_BUILD_MODE
    /prop_tgt/UNITY_BUILD_UNIQUE_ID
+   /prop_tgt/VERIFY_HEADER_SETS
    /prop_tgt/VERSION
    /prop_tgt/VISIBILITY_INLINES_HIDDEN
    /prop_tgt/VS_CONFIGURATION_TYPE
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 8d20ae2..0b81677 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -503,6 +503,7 @@ Variables that Control the Build
    /variable/CMAKE_UNITY_BUILD_BATCH_SIZE
    /variable/CMAKE_UNITY_BUILD_UNIQUE_ID
    /variable/CMAKE_USE_RELATIVE_PATHS
+   /variable/CMAKE_VERIFY_HEADER_SETS
    /variable/CMAKE_VISIBILITY_INLINES_HIDDEN
    /variable/CMAKE_VS_GLOBALS
    /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
diff --git a/Help/prop_tgt/VERIFY_HEADER_SETS.rst b/Help/prop_tgt/VERIFY_HEADER_SETS.rst
new file mode 100644
index 0000000..cbfd51b
--- /dev/null
+++ b/Help/prop_tgt/VERIFY_HEADER_SETS.rst
@@ -0,0 +1,24 @@
+VERIFY_HEADER_SETS
+------------------
+
+.. versionadded:: 3.24
+
+Used to verify that all headers in a target's header sets can be included on
+their own.
+
+When this property is set to true, and the target is an object library, static
+library, shared library, or executable with exports enabled, and the target
+has one or more header sets, an object library target named
+``<target_name>_verify_header_sets`` is created. This verification target has
+one source file per header in the header sets. Each source file only includes
+its associated header file. The verification target links against the original
+target to get all of its usage requirements. The verification target has its
+:prop_tgt:`EXCLUDE_FROM_ALL` and :prop_tgt:`DISABLE_PRECOMPILE_HEADERS`
+properties set to true, and its :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC`,
+:prop_tgt:`AUTOUIC`, and :prop_tgt:`UNITY_BUILD` properties set to false.
+
+If the header's :prop_sf:`LANGUAGE` property is set, the value of that property
+is used to determine the language with which to compile the header file.
+Otherwise, if the target has any C++ sources, the header is compiled as C++.
+Otherwise, if the target has any C sources, the header is compiled as C.
+Otherwise, the header file is not compiled.
diff --git a/Help/release/dev/verify-header-sets.rst b/Help/release/dev/verify-header-sets.rst
new file mode 100644
index 0000000..7676382
--- /dev/null
+++ b/Help/release/dev/verify-header-sets.rst
@@ -0,0 +1,7 @@
+verify-header-sets
+------------------
+
+* A new :prop_tgt:`VERIFY_HEADER_SETS` target property was added, which can be
+  used to verify that all headers in header sets can be used on their own.
+* A new :variable:`CMAKE_VERIFY_HEADER_SETS` variable was added, which is used
+  to initialize the :prop_tgt:`VERIFY_HEADER_SETS` target property.
diff --git a/Help/variable/CMAKE_VERIFY_HEADER_SETS.rst b/Help/variable/CMAKE_VERIFY_HEADER_SETS.rst
new file mode 100644
index 0000000..8bd618a
--- /dev/null
+++ b/Help/variable/CMAKE_VERIFY_HEADER_SETS.rst
@@ -0,0 +1,17 @@
+CMAKE_VERIFY_HEADER_SETS
+------------------------
+
+.. versionadded:: 3.24
+
+This variable is used to initialize the :prop_tgt:`VERIFY_HEADER_SETS`
+property of targets when they are created.  Setting it to true
+enables header set verification.
+
+Projects should not set this variable, it is intended as a developer
+control to be set on the :manual:`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.
+
+By default, this variable is not set, which will result in header set
+verification being disabled.