Modules/CheckFunctionExists.cmake

   1 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   2 # file Copyright.txt or https://cmake.org/licensing for details.
   3
   4 #[=======================================================================[.rst:
   5 CheckFunctionExists
   6 -------------------
   7
   8 Check if a C function can be linked
   9
  10 .. command:: check_function_exists
  11
  12   .. code-block:: cmake
  13
  14     check_function_exists(<function> <variable>)
  15
  16   Checks that the ``<function>`` is provided by libraries on the system and store
  17   the result in a ``<variable>``, which will be created as an internal
  18   cache variable.
  19
  20 The following variables may be set before calling this macro to modify the
  21 way the check is run:
  22
  23 ``CMAKE_REQUIRED_FLAGS``
  24   string of compile command line flags.
  25 ``CMAKE_REQUIRED_DEFINITIONS``
  26   a :ref:`;-list <CMake Language Lists>` of macros to define (-DFOO=bar).
  27 ``CMAKE_REQUIRED_INCLUDES``
  28   a :ref:`;-list <CMake Language Lists>` of header search paths to pass to
  29   the compiler.
  30 ``CMAKE_REQUIRED_LINK_OPTIONS``
  31   .. versionadded:: 3.14
  32     a :ref:`;-list <CMake Language Lists>` of options to add to the link command.
  33 ``CMAKE_REQUIRED_LIBRARIES``
  34   a :ref:`;-list <CMake Language Lists>` of libraries to add to the link
  35   command. See policy :policy:`CMP0075`.
  36 ``CMAKE_REQUIRED_QUIET``
  37   .. versionadded:: 3.1
  38     execute quietly without messages.
  39
  40 .. note::
  41
  42   Prefer using :Module:`CheckSymbolExists` instead of this module,
  43   for the following reasons:
  44
  45   * ``check_function_exists()`` can't detect functions that are inlined
  46     in headers or specified as a macro.
  47
  48   * ``check_function_exists()`` can't detect anything in the 32-bit
  49     versions of the Win32 API, because of a mismatch in calling conventions.
  50
  51   * ``check_function_exists()`` only verifies linking, it does not verify
  52     that the function is declared in system headers.
  53 #]=======================================================================]
  54
  55 include_guard(GLOBAL)
  56
  57 macro(CHECK_FUNCTION_EXISTS FUNCTION VARIABLE)
  58   if(NOT DEFINED "${VARIABLE}" OR "x${${VARIABLE}}" STREQUAL "x${VARIABLE}")
  59     set(MACRO_CHECK_FUNCTION_DEFINITIONS
  60       "-DCHECK_FUNCTION_EXISTS=${FUNCTION} ${CMAKE_REQUIRED_FLAGS}")
  61     if(NOT CMAKE_REQUIRED_QUIET)
  62       message(CHECK_START "Looking for ${FUNCTION}")
  63     endif()
  64     if(CMAKE_REQUIRED_LINK_OPTIONS)
  65       set(CHECK_FUNCTION_EXISTS_ADD_LINK_OPTIONS
  66         LINK_OPTIONS ${CMAKE_REQUIRED_LINK_OPTIONS})
  67     else()
  68       set(CHECK_FUNCTION_EXISTS_ADD_LINK_OPTIONS)
  69     endif()
  70     if(CMAKE_REQUIRED_LIBRARIES)
  71       set(CHECK_FUNCTION_EXISTS_ADD_LIBRARIES
  72         LINK_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES})
  73     else()
  74       set(CHECK_FUNCTION_EXISTS_ADD_LIBRARIES)
  75     endif()
  76     if(CMAKE_REQUIRED_INCLUDES)
  77       set(CHECK_FUNCTION_EXISTS_ADD_INCLUDES
  78         "-DINCLUDE_DIRECTORIES:STRING=${CMAKE_REQUIRED_INCLUDES}")
  79     else()
  80       set(CHECK_FUNCTION_EXISTS_ADD_INCLUDES)
  81     endif()
  82
  83     if(CMAKE_C_COMPILER_LOADED)
  84       set(_cfe_source ${CMAKE_ROOT}/Modules/CheckFunctionExists.c)
  85     elseif(CMAKE_CXX_COMPILER_LOADED)
  86       set(_cfe_source ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CheckFunctionExists/CheckFunctionExists.cxx)
  87       configure_file(${CMAKE_ROOT}/Modules/CheckFunctionExists.c "${_cfe_source}" COPYONLY)
  88     else()
  89       message(FATAL_ERROR "CHECK_FUNCTION_EXISTS needs either C or CXX language enabled")
  90     endif()
  91
  92     try_compile(${VARIABLE}
  93       ${CMAKE_BINARY_DIR}
  94       ${_cfe_source}
  95       COMPILE_DEFINITIONS ${CMAKE_REQUIRED_DEFINITIONS}
  96       ${CHECK_FUNCTION_EXISTS_ADD_LINK_OPTIONS}
  97       ${CHECK_FUNCTION_EXISTS_ADD_LIBRARIES}
  98       CMAKE_FLAGS -DCOMPILE_DEFINITIONS:STRING=${MACRO_CHECK_FUNCTION_DEFINITIONS}
  99       "${CHECK_FUNCTION_EXISTS_ADD_INCLUDES}"
 100       OUTPUT_VARIABLE OUTPUT)
 101     unset(_cfe_source)
 102
 103     if(${VARIABLE})
 104       set(${VARIABLE} 1 CACHE INTERNAL "Have function ${FUNCTION}")
 105       if(NOT CMAKE_REQUIRED_QUIET)
 106         message(CHECK_PASS "found")
 107       endif()
 108       file(APPEND ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeOutput.log
 109         "Determining if the function ${FUNCTION} exists passed with the following output:\n"
 110         "${OUTPUT}\n\n")
 111     else()
 112       if(NOT CMAKE_REQUIRED_QUIET)
 113         message(CHECK_FAIL "not found")
 114       endif()
 115       set(${VARIABLE} "" CACHE INTERNAL "Have function ${FUNCTION}")
 116       file(APPEND ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeError.log
 117         "Determining if the function ${FUNCTION} exists failed with the following output:\n"
 118         "${OUTPUT}\n\n")
 119     endif()
 120   endif()
 121 endmacro()