target_precompile_headers: Fix documented example using genex

When the path to a header file is specified using a generator
expression, evaluation of the genex must produce an absolute path.
Update our documented example and add a test covering the case.

Fixes: #20617

5 files changed, 19 insertions, 16 deletions

diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst
index 569c7eb..0d4f45a 100644
--- a/Help/command/target_precompile_headers.rst
+++ b/Help/command/target_precompile_headers.rst
@@ -56,35 +56,34 @@ e.g. ``[["other_header.h"]]``) will be treated as is, and include directories
 must be available for the compiler to find them.  Other header file names
 (e.g. ``project_header.h``) are interpreted as being relative to the current
 source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be
-included by absolute path.
-
-Arguments to ``target_precompile_headers()`` may use "generator expressions"
-with the syntax ``$<...>``.
-See the :manual:`cmake-generator-expressions(7)` manual for available
-expressions.  See the :manual:`cmake-compile-features(7)` manual for
-information on compile features and a list of supported compilers.
-The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly
-useful for specifying a language-specific header to precompile for
-only one language (e.g. ``CXX`` and not ``C``).  For example:
+included by absolute path.  For example:
 
 .. code-block:: cmake
 
   target_precompile_headers(myTarget
     PUBLIC
       project_header.h
-      "$<$<COMPILE_LANGUAGE:CXX>:cxx_only.h>"
     PRIVATE
       [["other_header.h"]]
       <unordered_map>
   )
 
-When specifying angle brackets inside a :manual:`generator expression
-<cmake-generator-expressions(7)>`, be sure to encode the closing ``>``
-as ``$<ANGLE-R>``.  For example:
+Arguments to ``target_precompile_headers()`` may use "generator expressions"
+with the syntax ``$<...>``.
+See the :manual:`cmake-generator-expressions(7)` manual for available
+expressions.
+The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly
+useful for specifying a language-specific header to precompile for
+only one language (e.g. ``CXX`` and not ``C``).  In this case, header
+file names that are not explicitly in double quotes or angle brackets
+must be specified by absolute path.  Also, when specifying angle brackets
+inside a generator expression, be sure to encode the closing ``>`` as
+``$<ANGLE-R>``.  For example:
 
 .. code-block:: cmake
 
   target_precompile_headers(mylib PRIVATE
+    "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
     "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
     "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
   )
diff --git a/Tests/RunCMake/PrecompileHeaders/PchMultilanguage-check.cmake b/Tests/RunCMake/PrecompileHeaders/PchMultilanguage-check.cmake
index cc01ecb..9714bea 100644
--- a/Tests/RunCMake/PrecompileHeaders/PchMultilanguage-check.cmake
+++ b/Tests/RunCMake/PrecompileHeaders/PchMultilanguage-check.cmake
@@ -13,14 +13,14 @@ endif()
 
 file(STRINGS ${foobar_pch_h_header} foobar_pch_h_header_strings)
 
-if (NOT foobar_pch_h_header_strings MATCHES ";#include <stddef.h>(;|$)")
+if (NOT foobar_pch_h_header_strings MATCHES ";#include \"[^\"]*PrecompileHeaders/include/foo_C.h\";#include <stddef.h>(;|$)")
   set(RunCMake_TEST_FAILED "Generated foo pch header\n  ${foobar_pch_h_header}\nhas bad content:\n  ${foobar_pch_h_header_strings}")
   return()
 endif()
 
 file(STRINGS ${foobar_pch_hxx_header} foobar_pch_hxx_header_strings)
 
-if (NOT foobar_pch_hxx_header_strings MATCHES ";#include <cstddef>(;|$)")
+if (NOT foobar_pch_hxx_header_strings MATCHES ";#include \"[^\"]*PrecompileHeaders/include/foo_CXX.h\";#include <cstddef>(;|$)")
   set(RunCMake_TEST_FAILED "Generated foo pch header\n  ${foobar_pch_hxx_header}\nhas bad content:\n  ${foobar_pch_hxx_header_strings}")
   return()
 endif()
diff --git a/Tests/RunCMake/PrecompileHeaders/PchMultilanguage.cmake b/Tests/RunCMake/PrecompileHeaders/PchMultilanguage.cmake
index cdc42b2..bb18a64 100644
--- a/Tests/RunCMake/PrecompileHeaders/PchMultilanguage.cmake
+++ b/Tests/RunCMake/PrecompileHeaders/PchMultilanguage.cmake
@@ -7,6 +7,8 @@ add_executable(foobar
 )
 target_include_directories(foobar PUBLIC include)
 target_precompile_headers(foobar PRIVATE
+  "$<$<COMPILE_LANGUAGE:C>:${CMAKE_CURRENT_SOURCE_DIR}/include/foo_C.h>"
+  "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/include/foo_CXX.h>"
   "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
   "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
   )
diff --git a/Tests/RunCMake/PrecompileHeaders/include/foo_C.h b/Tests/RunCMake/PrecompileHeaders/include/foo_C.h
new file mode 100644
index 0000000..f4de601
--- /dev/null
+++ b/Tests/RunCMake/PrecompileHeaders/include/foo_C.h
@@ -0,0 +1 @@
+#include "foo.h"
diff --git a/Tests/RunCMake/PrecompileHeaders/include/foo_CXX.h b/Tests/RunCMake/PrecompileHeaders/include/foo_CXX.h
new file mode 100644
index 0000000..f4de601
--- /dev/null
+++ b/Tests/RunCMake/PrecompileHeaders/include/foo_CXX.h
@@ -0,0 +1 @@
+#include "foo.h"