Merge topic 'patch-CheckSymbolExists'
58e8999c28 CheckSymbolExists, CheckCXXSymbolExists: Update documentation
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !10804
diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst
index c872143..29c5839 100644
--- a/Help/manual/cmake-toolchains.7.rst
+++ b/Help/manual/cmake-toolchains.7.rst
@@ -83,7 +83,7 @@
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 490d97c..a53413e 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(<symbol> <files> <variable>)
+ check_cxx_symbol_exists(<symbol> <headers> <variable>)
- Check that the ``<symbol>`` is available after including given header
- ``<files>`` and store the result in a ``<variable>``. 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 ``<symbol>`` is available after including
+ the specified header file(s) ``<headers>``, and stores the result in the
+ internal cache variable ``<variable>``. Multiple header files can be
+ specified in one argument as a string using a
+ :ref:`semicolon-separated list <CMake Language Lists>`.
- 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 ``<symbol>`` 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 @@
.. 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 ``<cstdio>`` header using this module:
.. code-block:: cmake
@@ -63,8 +88,14 @@
# 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 ddf1700..46d1ab3 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(<symbol> <files> <variable>)
+ check_symbol_exists(<symbol> <headers> <variable>)
- Check that the ``<symbol>`` is available after including given header
- ``<files>`` and store the result in a ``<variable>``. Specify the list
- of files in one argument as a semicolon-separated list.
- ``<variable>`` will be created as an internal cache variable.
+ This command checks whether the ``<symbol>`` is available after including
+ the specified header file(s) ``<headers>``, and stores the result in the
+ internal cache variable ``<variable>``. Multiple header files can be
+ specified in one argument as a string using a
+ :ref:`semicolon-separated list <CMake Language Lists>`.
-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 @@
.. 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 ``<stdio.h>`` header using this module:
.. code-block:: cmake
@@ -53,8 +79,15 @@
# 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)
