Do not exclude include directories made implicit by CPATH

Entries of the `CPATH` environment variable are implicitly searched as
include directories by some C/C++ compilers.  Since commit 5990ecb741
(Compute implicit include directories from compiler output, 2018-12-07,
v3.14.0-rc1~108^2) these entries are detected by CMake and included in
the `CMAKE_{C,CXX}_IMPLICIT_INCLUDE_DIRECTORIES` variables.

However, we should not exclude them from explicit specification via `-I`
or particularly `-isystem` because they are meant as user-specified
include directories that can be re-ordered without breaking compiler
builtin headers.  In particular, we need explicit requests via
`include_directories` with the `SYSTEM` option to result in `-isystem`
so that third-party headers do not produce warnings.

Co-Author: Ben Boeckel <ben.boeckel@kitware.com>
Fixes: #19291

4 files changed, 61 insertions, 0 deletions

diff --git a/Tests/CMakeLists.txt b/Tests/CMakeLists.txt
index 431a4921e2..588c8e0d22 100644
--- a/Tests/CMakeLists.txt
+++ b/Tests/CMakeLists.txt
@@ -3620,6 +3620,24 @@ ${CMake_BINARY_DIR}/bin/cmake -DDIR=dev -P ${CMake_SOURCE_DIR}/Utilities/Release
     --test-command IncludeDirectories)
   list(APPEND TEST_BUILD_DIRS "${CMake_BINARY_DIR}/Tests/IncludeDirectories")
 
+  if(CMAKE_GENERATOR MATCHES "^((Unix|MSYS) Makefiles|Ninja)$" AND
+     ((CMAKE_CXX_COMPILER_ID STREQUAL "GNU" AND CMAKE_CXX_COMPILER_VERSION VERSION_GREATER 4.4)
+      OR (CMAKE_CXX_COMPILER_ID STREQUAL "Clang" AND NOT "x${CMAKE_CXX_SIMULATE_ID}" STREQUAL "xMSVC")
+      OR (CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang")))
+    add_test(IncludeDirectoriesCPATH ${CMAKE_CTEST_COMMAND}
+      --build-and-test
+      "${CMake_SOURCE_DIR}/Tests/IncludeDirectoriesCPATH"
+      "${CMake_BINARY_DIR}/Tests/IncludeDirectoriesCPATH"
+      --build-two-config
+      ${build_generator_args}
+      --build-project IncludeDirectoriesCPATH
+      --build-options ${build_options})
+    list(APPEND TEST_BUILD_DIRS "${CMake_BINARY_DIR}/Tests/IncludeDirectoriesCPATH")
+    set_tests_properties(IncludeDirectoriesCPATH
+      PROPERTIES
+        ENVIRONMENT "CPATH=${CMAKE_CURRENT_SOURCE_DIR}/IncludeDirectoriesCPATH/viacpath")
+  endif()
+
   add_test(InterfaceLinkLibraries ${CMAKE_CTEST_COMMAND}
     --build-and-test
     "${CMake_SOURCE_DIR}/Tests/InterfaceLinkLibraries"
diff --git a/Tests/IncludeDirectoriesCPATH/CMakeLists.txt b/Tests/IncludeDirectoriesCPATH/CMakeLists.txt
new file mode 100644
index 0000000000..31cbc3680a
--- /dev/null
+++ b/Tests/IncludeDirectoriesCPATH/CMakeLists.txt
@@ -0,0 +1,22 @@
+cmake_minimum_required (VERSION 3.14)
+project(IncludeDirectoriesCPATH CXX)
+message(STATUS "ENV{CPATH}: '$ENV{CPATH}'")
+message(STATUS "CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES: '${CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES}'")
+
+include(CheckCXXCompilerFlag)
+check_cxx_compiler_flag(-Wunused-variable run_sys_includes_test)
+if(run_sys_includes_test)
+  # The Bullseye wrapper appears to break the -isystem effect.
+  execute_process(COMMAND ${CMAKE_CXX_COMPILER} --version OUTPUT_VARIABLE out ERROR_VARIABLE out)
+  if("x${out}" MATCHES "Bullseye")
+    set(run_sys_includes_test 0)
+  endif()
+endif()
+if (NOT run_sys_includes_test)
+  return()
+endif()
+
+add_library(consumer consumer.cpp)
+add_library(consumer_system consumer.cpp)
+target_compile_options(consumer_system PRIVATE -Werror=unused-variable)
+target_include_directories(consumer_system SYSTEM PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/viacpath")
diff --git a/Tests/IncludeDirectoriesCPATH/consumer.cpp b/Tests/IncludeDirectoriesCPATH/consumer.cpp
new file mode 100644
index 0000000000..59608dada2
--- /dev/null
+++ b/Tests/IncludeDirectoriesCPATH/consumer.cpp
@@ -0,0 +1,6 @@
+#include "systemlib.h"
+
+int consumer()
+{
+  return systemlib();
+}
diff --git a/Tests/IncludeDirectoriesCPATH/viacpath/systemlib.h b/Tests/IncludeDirectoriesCPATH/viacpath/systemlib.h
new file mode 100644
index 0000000000..1aaafa9f40
--- /dev/null
+++ b/Tests/IncludeDirectoriesCPATH/viacpath/systemlib.h
@@ -0,0 +1,15 @@
+#ifndef SYSTEMLIB_H
+#define SYSTEMLIB_H
+
+int systemlib()
+{
+  return 0;
+}
+
+int unusedFunc()
+{
+  int unused;
+  return systemlib();
+}
+
+#endif