Undocumented Behavior of `CHECK_INCLUDE_FILE_CXX` Depending on Policy or Version

This turned out to be a bit of head-scratcher. The CHECK_INCLUDE_FILE_CXX macro changes behavior depending on if the minimum CMake version is below version 3.8 or if policy CMP0067 is set to NEW.

In short, it seems like CHECK_INCLUDE_FILE_CXX uses try_compile internally and thus only uses the CMAKE_CXX_STANDARD when CMP0067 is set to NEW as stated here. In my opinion, this should be added to the documentation for the macro. Actually, this should probably be stated in all the CheckIncludeFile{,s,CXX} documentation pages.

A small example project is included below showing this behavior, and in case someone wants to test this, this is on an M1 Mac, with extra OpenCL headers installed in $ENV{HOME}/.local/include.

#cmake_minimum_required(VERSION 3.8)

cmake_minimum_required(VERSION 3.1)
# cmake_policy(SET CMP0067 NEW)

project(TEST C CXX)

set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Double-check that the OpenCL C++ bindings are present.
find_package(OpenCL 1.2)
if (OpenCL_FOUND)
  cmake_policy(SET CMP0075 NEW)
  include(CheckIncludeFileCXX)
  set(OpenCL_INCLUDE_DIRS "${OpenCL_INCLUDE_DIRS};$ENV{HOME}/.local/include")
  set(CMAKE_REQUIRED_INCLUDES ${OpenCL_INCLUDE_DIRS})
  set(CMAKE_REQUIRED_LIBRARIES ${OpenCL_LIBRARIES})
  CHECK_INCLUDE_FILE_CXX(CL/opencl.hpp OpenCLHPP_FOUND)
  if (NOT OpenCLHPP_FOUND)
    set(OpenCL_FOUND NO)
  endif()
endif()

Most of the Check* modules use try_compile, so perhaps we need a note in all check module’s documentation, possibly linking to a section somewhere with more details.