From 4ae2dcb1b965efac7c088cbf97fa66c4d3c41858 Mon Sep 17 00:00:00 2001 From: Stephen Sorley Date: Thu, 12 Jan 2017 13:10:25 -0500 Subject: CheckFunctionExists: Document suggestion to use CheckSymbolExists instead. CheckFunctionExists has some severe limitations that are overcome by CheckSymbolExists. Document them and suggest the alternative. --- Modules/CheckFunctionExists.cmake | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/Modules/CheckFunctionExists.cmake b/Modules/CheckFunctionExists.cmake index 5f049e7..ef08062 100644 --- a/Modules/CheckFunctionExists.cmake +++ b/Modules/CheckFunctionExists.cmake @@ -5,18 +5,16 @@ # CheckFunctionExists # ------------------- # -# Check if a C function can be linked +# Check if a C function can be linked:: # -# CHECK_FUNCTION_EXISTS( ) +# check_function_exists( ) # -# Check that the is provided by libraries on the system and -# store the result in a . This does not verify that any -# system header file declares the function, only that it can be found at -# link time (consider using CheckSymbolExists). -# will be created as an internal cache variable. +# Check that the ```` is provided by libraries on the system and store +# the result in a ````. ```` will be created as an internal +# cache variable. # -# The following variables may be set before calling this macro to modify -# the way the check is run: +# The following variables may be set before calling this macro to modify the +# way the check is run: # # :: # @@ -25,6 +23,20 @@ # CMAKE_REQUIRED_INCLUDES = list of include directories # CMAKE_REQUIRED_LIBRARIES = list of libraries to link # CMAKE_REQUIRED_QUIET = execute quietly without messages +# +# .. note:: +# +# Prefer using :Module:`CheckSymbolExists` instead of this module, +# for the following reasons: +# +# * ``check_function_exists()`` can't detect functions that are inlined +# in headers or specified as a macro. +# +# * ``check_function_exists()`` can't detect anything in the 32-bit +# versions of the Win32 API, because of a mismatch in calling conventions. +# +# * ``check_function_exists()`` only verifies linking, it does not verify +# that the function is declared in system headers. macro(CHECK_FUNCTION_EXISTS FUNCTION VARIABLE) if(NOT DEFINED "${VARIABLE}" OR "x${${VARIABLE}}" STREQUAL "x${VARIABLE}") -- cgit v0.12