CheckIncludeFiles: Honor CMAKE_REQUIRED_LIBRARIES

Other check modules honor this variable, so include file checks should
too.  Add policy `CMP0075` to enable the behavior in a compatible way.

This change was originally made by commit v3.11.0-rc1~108^2
(CheckIncludeFiles: Honor CMAKE_REQUIRED_LIBRARIES, 2017-12-24) but it
was reverted by commit v3.11.1~9^2 (Revert "CheckIncludeFiles: Honor
CMAKE_REQUIRED_LIBRARIES", 2018-04-04) because the behavior change could
affect checks in existing projects in an incompatible way.

Fixes: #9514

Help/manual/cmake-policies.7.rst

@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.12
 .. toctree::
    :maxdepth: 1
 
+   CMP0075: Include file check macros honor CMAKE_REQUIRED_LIBRARIES. </policy/CMP0075>
    CMP0074: find_package uses PackageName_ROOT variables. </policy/CMP0074>
    CMP0073: Do not produce legacy _LIB_DEPENDS cache entries. </policy/CMP0073>
 

Help/policy/CMP0075.rst

@@ -0,0 +1,26 @@
+CMP0075
+-------
+
+Include file check macros honor ``CMAKE_REQUIRED_LIBRARIES``.
+
+In CMake 3.12 and above, the
+
+* ``check_include_file`` macro in the :module:`CheckIncludeFile` module, the
+* ``check_include_file_cxx`` macro in the
+  :module:`CheckIncludeFileCXX` module, and the
+* ``check_include_files`` macro in the :module:`CheckIncludeFiles` module
+
+now prefer to link the check executable to the libraries listed in the
+``CMAKE_REQUIRED_LIBRARIES`` variable.  This policy provides compatibility
+with projects that have not been updated to expect this behavior.
+
+The ``OLD`` behavior for this policy is to ignore ``CMAKE_REQUIRED_LIBRARIES``
+in the include file check macros.  The ``NEW`` behavior of this policy is to
+honor ``CMAKE_REQUIRED_LIBRARIES`` in the include file check macros.
+
+This policy was introduced in CMake version 3.12.  CMake version
+|release| warns when the policy is not set and uses ``OLD`` behavior.
+Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
+explicitly.
+
+.. include:: DEPRECATED.txt

Help/release/dev/CheckIncludeFile-required-libs.rst

@@ -0,0 +1,14 @@
+CheckIncludeFile-required-libs
+------------------------------
+
+* The :module:`CheckIncludeFile` module ``check_include_file`` macro
+  learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
+  See policy :policy:`CMP0075`.
+
+* The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro
+  learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
+  See policy :policy:`CMP0075`.
+
+* The :module:`CheckIncludeFiles` module ``check_include_files`` macro
+  learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
+  See policy :policy:`CMP0075`.

Modules/CheckIncludeFile.cmake

@@ -27,6 +27,8 @@
 #   list of macros to define (-DFOO=bar)
 # ``CMAKE_REQUIRED_INCLUDES``
 #   list of include directories
+# ``CMAKE_REQUIRED_LIBRARIES``
+#   A list of libraries to link.  See policy :policy:`CMP0075`.
 # ``CMAKE_REQUIRED_QUIET``
 #   execute quietly without messages
 #
@@ -55,14 +57,39 @@ macro(CHECK_INCLUDE_FILE INCLUDE VARIABLE)
       string(APPEND CMAKE_C_FLAGS " ${ARGV2}")
     endif()
 
+    set(_CIF_LINK_LIBRARIES "")
+    if(CMAKE_REQUIRED_LIBRARIES)
+      cmake_policy(GET CMP0075 _CIF_CMP0075
+        PARENT_SCOPE # undocumented, do not use outside of CMake
+        )
+      if("x${_CIF_CMP0075}x" STREQUAL "xNEWx")
+        set(_CIF_LINK_LIBRARIES LINK_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES})
+      elseif("x${_CIF_CMP0075}x" STREQUAL "xOLDx")
+      elseif(NOT _CIF_CMP0075_WARNED)
+        set(_CIF_CMP0075_WARNED 1)
+        message(AUTHOR_WARNING
+          "Policy CMP0075 is not set: Include file check macros honor CMAKE_REQUIRED_LIBRARIES.  "
+          "Run \"cmake --help-policy CMP0075\" for policy details.  "
+          "Use the cmake_policy command to set the policy and suppress this warning."
+          "\n"
+          "CMAKE_REQUIRED_LIBRARIES is set to:\n"
+          "  ${CMAKE_REQUIRED_LIBRARIES}\n"
+          "For compatibility with CMake 3.11 and below this check is ignoring it."
+          )
+      endif()
+      unset(_CIF_CMP0075)
+    endif()
+
     try_compile(${VARIABLE}
       ${CMAKE_BINARY_DIR}
       ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeTmp/CheckIncludeFile.c
       COMPILE_DEFINITIONS ${CMAKE_REQUIRED_DEFINITIONS}
+      ${_CIF_LINK_LIBRARIES}
       CMAKE_FLAGS
       -DCOMPILE_DEFINITIONS:STRING=${MACRO_CHECK_INCLUDE_FILE_FLAGS}
       "${CHECK_INCLUDE_FILE_C_INCLUDE_DIRS}"
       OUTPUT_VARIABLE OUTPUT)
+    unset(_CIF_LINK_LIBRARIES)
 
     if(${ARGC} EQUAL 3)
       set(CMAKE_C_FLAGS ${CMAKE_C_FLAGS_SAVE})

Modules/CheckIncludeFileCXX.cmake

@@ -27,6 +27,8 @@
 #   list of macros to define (-DFOO=bar)
 # ``CMAKE_REQUIRED_INCLUDES``
 #   list of include directories
+# ``CMAKE_REQUIRED_LIBRARIES``
+#   A list of libraries to link.  See policy :policy:`CMP0075`.
 # ``CMAKE_REQUIRED_QUIET``
 #   execute quietly without messages
 #
@@ -54,14 +56,39 @@ macro(CHECK_INCLUDE_FILE_CXX INCLUDE VARIABLE)
       string(APPEND CMAKE_CXX_FLAGS " ${ARGV2}")
     endif()
 
+    set(_CIF_LINK_LIBRARIES "")
+    if(CMAKE_REQUIRED_LIBRARIES)
+      cmake_policy(GET CMP0075 _CIF_CMP0075
+        PARENT_SCOPE # undocumented, do not use outside of CMake
+        )
+      if("x${_CIF_CMP0075}x" STREQUAL "xNEWx")
+        set(_CIF_LINK_LIBRARIES LINK_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES})
+      elseif("x${_CIF_CMP0075}x" STREQUAL "xOLDx")
+      elseif(NOT _CIF_CMP0075_WARNED)
+        set(_CIF_CMP0075_WARNED 1)
+        message(AUTHOR_WARNING
+          "Policy CMP0075 is not set: Include file check macros honor CMAKE_REQUIRED_LIBRARIES.  "
+          "Run \"cmake --help-policy CMP0075\" for policy details.  "
+          "Use the cmake_policy command to set the policy and suppress this warning."
+          "\n"
+          "CMAKE_REQUIRED_LIBRARIES is set to:\n"
+          "  ${CMAKE_REQUIRED_LIBRARIES}\n"
+          "For compatibility with CMake 3.11 and below this check is ignoring it."
+          )
+      endif()
+      unset(_CIF_CMP0075)
+    endif()
+
     try_compile(${VARIABLE}
       ${CMAKE_BINARY_DIR}
       ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeTmp/CheckIncludeFile.cxx
       COMPILE_DEFINITIONS ${CMAKE_REQUIRED_DEFINITIONS}
+      ${_CIF_LINK_LIBRARIES}
       CMAKE_FLAGS
       -DCOMPILE_DEFINITIONS:STRING=${MACRO_CHECK_INCLUDE_FILE_FLAGS}
       "${CHECK_INCLUDE_FILE_CXX_INCLUDE_DIRS}"
       OUTPUT_VARIABLE OUTPUT)
+    unset(_CIF_LINK_LIBRARIES)
 
     if(${ARGC} EQUAL 3)
       set(CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS_SAVE})

Modules/CheckIncludeFiles.cmake

@@ -33,6 +33,8 @@
 #   list of macros to define (-DFOO=bar)
 # ``CMAKE_REQUIRED_INCLUDES``
 #   list of include directories
+# ``CMAKE_REQUIRED_LIBRARIES``
+#   A list of libraries to link.  See policy :policy:`CMP0075`.
 # ``CMAKE_REQUIRED_QUIET``
 #   execute quietly without messages
 #
@@ -95,6 +97,29 @@ macro(CHECK_INCLUDE_FILES INCLUDE VARIABLE)
       set(_description "include file ${_INCLUDE}")
     endif()
 
+    set(_CIF_LINK_LIBRARIES "")
+    if(CMAKE_REQUIRED_LIBRARIES)
+      cmake_policy(GET CMP0075 _CIF_CMP0075
+        PARENT_SCOPE # undocumented, do not use outside of CMake
+        )
+      if("x${_CIF_CMP0075}x" STREQUAL "xNEWx")
+        set(_CIF_LINK_LIBRARIES LINK_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES})
+      elseif("x${_CIF_CMP0075}x" STREQUAL "xOLDx")
+      elseif(NOT _CIF_CMP0075_WARNED)
+        set(_CIF_CMP0075_WARNED 1)
+        message(AUTHOR_WARNING
+          "Policy CMP0075 is not set: Include file check macros honor CMAKE_REQUIRED_LIBRARIES.  "
+          "Run \"cmake --help-policy CMP0075\" for policy details.  "
+          "Use the cmake_policy command to set the policy and suppress this warning."
+          "\n"
+          "CMAKE_REQUIRED_LIBRARIES is set to:\n"
+          "  ${CMAKE_REQUIRED_LIBRARIES}\n"
+          "For compatibility with CMake 3.11 and below this check is ignoring it."
+          )
+      endif()
+      unset(_CIF_CMP0075)
+    endif()
+
     if(NOT CMAKE_REQUIRED_QUIET)
       message(STATUS "Looking for ${_description}")
     endif()
@@ -102,10 +127,12 @@ macro(CHECK_INCLUDE_FILES INCLUDE VARIABLE)
       ${CMAKE_BINARY_DIR}
       ${src}
       COMPILE_DEFINITIONS ${CMAKE_REQUIRED_DEFINITIONS}
+      ${_CIF_LINK_LIBRARIES}
       CMAKE_FLAGS
       -DCOMPILE_DEFINITIONS:STRING=${MACRO_CHECK_INCLUDE_FILES_FLAGS}
       "${CHECK_INCLUDE_FILES_INCLUDE_DIRS}"
       OUTPUT_VARIABLE OUTPUT)
+    unset(_CIF_LINK_LIBRARIES)
     if(${VARIABLE})
       if(NOT CMAKE_REQUIRED_QUIET)
         message(STATUS "Looking for ${_description} - found")

Source/cmPolicies.h

@@ -219,7 +219,10 @@ class cmMakefile;
          "Do not produce legacy _LIB_DEPENDS cache entries.", 3, 12, 0,       \
          cmPolicies::WARN)                                                    \
   SELECT(POLICY, CMP0074, "find_package uses PackageName_ROOT variables.", 3, \
-         12, 0, cmPolicies::WARN)
+         12, 0, cmPolicies::WARN)                                             \
+  SELECT(POLICY, CMP0075,                                                     \
+         "Include file check macros honor CMAKE_REQUIRED_LIBRARIES.", 3, 12,  \
+         0, cmPolicies::WARN)
 
 #define CM_SELECT_ID(F, A1, A2, A3, A4, A5, A6) F(A1)
 #define CM_FOR_EACH_POLICY_ID(POLICY)                                         \

Tests/RunCMake/CheckModules/CMP0075-stderr.txt

@@ -0,0 +1,50 @@
+^CMake Warning \(dev\) at [^
+]*/Modules/CheckIncludeFile.cmake:[0-9]+ \(message\):
+  Policy CMP0075 is not set: Include file check macros honor
+  CMAKE_REQUIRED_LIBRARIES.  Run "cmake --help-policy CMP0075" for policy
+  details.  Use the cmake_policy command to set the policy and suppress this
+  warning.
+
+  CMAKE_REQUIRED_LIBRARIES is set to:
+
+    does_not_exist
+
+  For compatibility with CMake 3.11 and below this check is ignoring it.
+Call Stack \(most recent call first\):
+  CMP0075.cmake:11 \(check_include_file\)
+  CMakeLists.txt:[0-9]+ \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.
++
+CMake Warning \(dev\) at [^
+]*/Modules/CheckIncludeFileCXX.cmake:[0-9]+ \(message\):
+  Policy CMP0075 is not set: Include file check macros honor
+  CMAKE_REQUIRED_LIBRARIES.  Run "cmake --help-policy CMP0075" for policy
+  details.  Use the cmake_policy command to set the policy and suppress this
+  warning.
+
+  CMAKE_REQUIRED_LIBRARIES is set to:
+
+    does_not_exist
+
+  For compatibility with CMake 3.11 and below this check is ignoring it.
+Call Stack \(most recent call first\):
+  CMP0075.cmake:26 \(check_include_file_cxx\)
+  CMakeLists.txt:[0-9]+ \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.
++
+CMake Warning \(dev\) at [^
+]*/Modules/CheckIncludeFiles.cmake:[0-9]+ \(message\):
+  Policy CMP0075 is not set: Include file check macros honor
+  CMAKE_REQUIRED_LIBRARIES.  Run "cmake --help-policy CMP0075" for policy
+  details.  Use the cmake_policy command to set the policy and suppress this
+  warning.
+
+  CMAKE_REQUIRED_LIBRARIES is set to:
+
+    does_not_exist
+
+  For compatibility with CMake 3.11 and below this check is ignoring it.
+Call Stack \(most recent call first\):
+  CMP0075.cmake:41 \(check_include_files\)
+  CMakeLists.txt:[0-9]+ \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.$

Tests/RunCMake/CheckModules/CMP0075.cmake

@@ -0,0 +1,124 @@
+enable_language(C)
+enable_language(CXX)
+include(CheckIncludeFile)
+include(CheckIncludeFileCXX)
+include(CheckIncludeFiles)
+
+set(CMAKE_REQUIRED_LIBRARIES does_not_exist)
+
+#============================================================================
+
+check_include_file("stddef.h" HAVE_STDDEF_H_1)
+if(NOT HAVE_STDDEF_H_1)
+  message(SEND_ERROR "HAVE_STDDEF_H_1 failed but should have passed.")
+endif()
+if(NOT _CIF_CMP0075_WARNED)
+  message(SEND_ERROR "HAVE_STDDEF_H_1 did not warn but should have")
+endif()
+check_include_file("stddef.h" HAVE_STDDEF_H_2) # second does not warn
+if(NOT HAVE_STDDEF_H_2)
+  message(SEND_ERROR "HAVE_STDDEF_H_2 failed but should have passed.")
+endif()
+unset(_CIF_CMP0075_WARNED)
+
+#----------------------------------------------------------------------------
+
+check_include_file_cxx("stddef.h" HAVE_STDDEF_H_CXX_1)
+if(NOT HAVE_STDDEF_H_CXX_1)
+  message(SEND_ERROR "HAVE_STDDEF_H_CXX_1 failed but should have passed.")
+endif()
+if(NOT _CIF_CMP0075_WARNED)
+  message(SEND_ERROR "HAVE_STDDEF_H_CXX_1 did not warn but should have")
+endif()
+check_include_file_cxx("stddef.h" HAVE_STDDEF_H_CXX_2) # second does not warn
+if(NOT HAVE_STDDEF_H_CXX_2)
+  message(SEND_ERROR "HAVE_STDDEF_H_CXX_2 failed but should have passed.")
+endif()
+unset(_CIF_CMP0075_WARNED)
+
+#----------------------------------------------------------------------------
+
+check_include_files("stddef.h;stdlib.h" HAVE_STDLIB_H_1)
+if(NOT HAVE_STDLIB_H_1)
+  message(SEND_ERROR "HAVE_STDLIB_H_1 failed but should have passed.")
+endif()
+if(NOT _CIF_CMP0075_WARNED)
+  message(SEND_ERROR "HAVE_STDLIB_H_1 did not warn but should have")
+endif()
+check_include_files("stddef.h;stdlib.h" HAVE_STDLIB_H_2) # second does not warn
+if(NOT HAVE_STDLIB_H_2)
+  message(SEND_ERROR "HAVE_STDLIB_H_2 failed but should have passed.")
+endif()
+unset(_CIF_CMP0075_WARNED)
+
+#============================================================================
+cmake_policy(SET CMP0075 OLD)
+# These should not warn.
+# These should pass the checks due to ignoring 'does_not_exist'.
+
+check_include_file("stddef.h" HAVE_STDDEF_H_3)
+if(NOT HAVE_STDDEF_H_3)
+  message(SEND_ERROR "HAVE_STDDEF_H_3 failed but should have passed.")
+endif()
+if(_CIF_CMP0075_WARNED)
+  message(SEND_ERROR "HAVE_STDDEF_H_3 warned but should not have")
+endif()
+unset(_CIF_CMP0075_WARNED)
+
+#----------------------------------------------------------------------------
+
+check_include_file_cxx("stddef.h" HAVE_STDDEF_H_CXX_3)
+if(NOT HAVE_STDDEF_H_CXX_3)
+  message(SEND_ERROR "HAVE_STDDEF_H_CXX_3 failed but should have passed.")
+endif()
+if(_CIF_CMP0075_WARNED)
+  message(SEND_ERROR "HAVE_STDDEF_H_CXX_3 warned but should not have")
+endif()
+unset(_CIF_CMP0075_WARNED)
+
+#----------------------------------------------------------------------------
+
+check_include_files("stddef.h;stdlib.h" HAVE_STDLIB_H_3)
+if(NOT HAVE_STDLIB_H_3)
+  message(SEND_ERROR "HAVE_STDLIB_H_3 failed but should have passed.")
+endif()
+if(_CIF_CMP0075_WARNED)
+  message(SEND_ERROR "HAVE_STDLIB_H_3 warned but should not have")
+endif()
+unset(_CIF_CMP0075_WARNED)
+
+#============================================================================
+cmake_policy(SET CMP0075 NEW)
+# These should not warn.
+# These should fail the checks due to requiring 'does_not_exist'.
+
+check_include_file("stddef.h" HAVE_STDDEF_H_4)
+if(HAVE_STDDEF_H_4)
+  message(SEND_ERROR "HAVE_STDDEF_H_4 passed but should have failed.")
+endif()
+if(_CIF_CMP0075_WARNED)
+  message(SEND_ERROR "HAVE_STDDEF_H_4 warned but should not have")
+endif()
+unset(_CIF_CMP0075_WARNED)
+
+#----------------------------------------------------------------------------
+
+check_include_file_cxx("stddef.h" HAVE_STDDEF_H_CXX_4)
+if(HAVE_STDDEF_H_CXX_4)
+  message(SEND_ERROR "HAVE_STDDEF_H_CXX_4 passed but should have failed.")
+endif()
+if(_CIF_CMP0075_WARNED)
+  message(SEND_ERROR "HAVE_STDDEF_H_CXX_4 warned but should not have")
+endif()
+unset(_CIF_CMP0075_WARNED)
+
+#----------------------------------------------------------------------------
+
+check_include_files("stddef.h;stdlib.h" HAVE_STDLIB_H_4)
+if(HAVE_STDLIB_H_4)
+  message(SEND_ERROR "HAVE_STDLIB_H_4 passed but should have failed.")
+endif()
+if(_CIF_CMP0075_WARNED)
+  message(SEND_ERROR "HAVE_STDLIB_H_4 warned but should not have")
+endif()
+unset(_CIF_CMP0075_WARNED)

Tests/RunCMake/CheckModules/RunCMakeTest.cmake

@@ -1,5 +1,7 @@
 include(RunCMake)
 
+run_cmake(CMP0075)
+
 run_cmake(CheckStructHasMemberOk)
 run_cmake(CheckStructHasMemberUnknownLanguage)
 run_cmake(CheckStructHasMemberMissingLanguage)