diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index c8721437ae..29c583963f 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -83,7 +83,7 @@ with the :prop_tgt:`LINKER_LANGUAGE` target property. Toolchain Features ================== -CMake provides the :command:`try_compile` command and wrapper macros such as +CMake provides the :command:`try_compile` command and modules such as :module:`CheckSourceCompiles`, :module:`CheckCXXSymbolExists` and :module:`CheckIncludeFile` to test capability and availability of various toolchain features. These APIs test the toolchain in some way and cache the diff --git a/Modules/CheckCXXSymbolExists.cmake b/Modules/CheckCXXSymbolExists.cmake index 490d97c8de..a53413e5ff 100644 --- a/Modules/CheckCXXSymbolExists.cmake +++ b/Modules/CheckCXXSymbolExists.cmake @@ -5,41 +5,61 @@ CheckCXXSymbolExists -------------------- -Check if a symbol exists as a function, variable, or macro in ``C++``. +This module provides a command to check whether a C++ symbol exists. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CheckCXXSymbolExists) + +Commands +^^^^^^^^ + +This module provides the following command: .. command:: check_cxx_symbol_exists + Checks once whether a symbol exists as a function, variable, or preprocessor + macro in C++: + .. code-block:: cmake - check_cxx_symbol_exists( ) + check_cxx_symbol_exists( ) - Check that the ```` is available after including given header - ```` and store the result in a ````. Specify the list of - files in one argument as a semicolon-separated list. - ``check_cxx_symbol_exists()`` can be used to check for symbols as seen by - the C++ compiler, as opposed to :command:`check_symbol_exists`, which always - uses the ``C`` compiler. + This command checks whether the ```` is available after including + the specified header file(s) ````, and stores the result in the + internal cache variable ````. Multiple header files can be + specified in one argument as a string using a + :ref:`semicolon-separated list `. - If the header files define the symbol as a macro it is considered - available and assumed to work. If the header files declare the symbol - as a function or variable then the symbol must also be available for - linking. If the symbol is a type, enum value, or C++ template it will - not be recognized: consider using the :module:`CheckTypeSize` - or :module:`CheckSourceCompiles` module instead. + If the header files define the symbol as a macro, it is considered + available and assumed to work. If the symbol is declared as a function + or variable, the check also ensures that it links successfully + (i.e., the symbol must exist in a linked library or object file). -.. note:: + Symbols that are types, enum values, or C++ templates are not + recognized. For those, consider using the :module:`CheckTypeSize` or + :module:`CheckSourceCompiles` module instead. - This command is unreliable when ```` is (potentially) an overloaded - function. Since there is no reliable way to predict whether a given function - in the system environment may be defined as an overloaded function or may be - an overloaded function on other systems or will become so in the future, it - is generally advised to use the :module:`CheckSourceCompiles` module for - checking any function symbol (unless somehow you surely know the checked - function is not overloaded on other systems or will not be so in the - future). + This command is intended to check symbols as they appear in C++. For C + symbols, use the :module:`CheckSymbolExists` module instead. -The following variables may be set before calling this macro to modify -the way the check is run: + .. note:: + + This command is unreliable for symbols that are (potentially) overloaded + functions. Since there is no reliable way to predict whether + a given function in the system environment may be defined as an + overloaded function or may be an overloaded function on other systems + or will become so in the future, it is generally advised to use the + :module:`CheckSourceCompiles` module for checking any function symbol + (unless it is certain the checked function is not overloaded on other + systems or will not be so in the future). + + .. rubric:: Variables Affecting the Check + + The following variables may be set before calling this command to modify + the way the check is run: .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst @@ -55,7 +75,12 @@ the way the check is run: .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst -For example: +Examples +^^^^^^^^ + +The following example demonstrates how to check for the presence of a +preprocessor macro ``SEEK_SET`` and the C++ function ``std::fopen()`` from +the ```` header using this module: .. code-block:: cmake @@ -63,8 +88,14 @@ For example: # Check for macro SEEK_SET check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET) + # Check for function std::fopen check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN) + +See Also +^^^^^^^^ + +* The :module:`CheckSymbolExists` module to check whether a C symbol exists. #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckSymbolExists.cmake b/Modules/CheckSymbolExists.cmake index ddf1700f83..46d1ab33f7 100644 --- a/Modules/CheckSymbolExists.cmake +++ b/Modules/CheckSymbolExists.cmake @@ -5,31 +5,52 @@ CheckSymbolExists ----------------- -Provides a macro to check if a symbol exists as a function, variable, -or macro in ``C``. +This module provides a command to check whether a C symbol exists. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CheckSymbolExists) + +Commands +^^^^^^^^ + +This module provides the following command: .. command:: check_symbol_exists + Checks once whether a symbol exists as a function, variable, or preprocessor + macro in C: + .. code-block:: cmake - check_symbol_exists( ) + check_symbol_exists( ) - Check that the ```` is available after including given header - ```` and store the result in a ````. Specify the list - of files in one argument as a semicolon-separated list. - ```` will be created as an internal cache variable. + This command checks whether the ```` is available after including + the specified header file(s) ````, and stores the result in the + internal cache variable ````. Multiple header files can be + specified in one argument as a string using a + :ref:`semicolon-separated list `. -If the header files define the symbol as a macro it is considered -available and assumed to work. If the header files declare the symbol -as a function or variable then the symbol must also be available for -linking (so intrinsics may not be detected). -If the symbol is a type, enum value, or intrinsic it will not be recognized -(consider using :module:`CheckTypeSize` or :module:`CheckSourceCompiles`). -If the check needs to be done in C++, consider using -:module:`CheckCXXSymbolExists` instead. + If the header files define the symbol as a macro, it is considered + available and assumed to work. If the symbol is declared as a function + or variable, the check also ensures that it links successfully + (i.e., the symbol must exist in a linked library or object file). + Compiler intrinsics may not be detected, as they are not always linkable + or explicitly declared in headers. -The following variables may be set before calling this macro to modify -the way the check is run: + Symbols that are types, enum values, or compiler intrinsics are not + recognized. For those, consider using the :module:`CheckTypeSize` or + :module:`CheckSourceCompiles` module instead. + + This command is intended to check symbols as they appear in C. For C++ + symbols, use the :module:`CheckCXXSymbolExists` module instead. + + .. rubric:: Variables Affecting the Check + + The following variables may be set before calling this command to modify + the way the check is run: .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst @@ -45,7 +66,12 @@ the way the check is run: .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst -For example: +Examples +^^^^^^^^ + +The following example demonstrates how to check for the presence of a +preprocessor macro ``SEEK_SET`` and the C function ``fopen()`` from +the ```` header using this module: .. code-block:: cmake @@ -53,8 +79,15 @@ For example: # Check for macro SEEK_SET check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET) + # Check for function fopen check_symbol_exists(fopen "stdio.h" HAVE_FOPEN) + +See Also +^^^^^^^^ + +* The :module:`CheckCXXSymbolExists` module to check whether a C++ symbol + exists. #]=======================================================================] include_guard(GLOBAL)