diff options
35 files changed, 489 insertions, 704 deletions
diff --git a/Help/module/CMAKE_REQUIRED_DEFINITIONS.txt b/Help/module/CMAKE_REQUIRED_DEFINITIONS.txt new file mode 100644 index 0000000000..17289c378a --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_DEFINITIONS.txt @@ -0,0 +1,4 @@ + ``CMAKE_REQUIRED_DEFINITIONS`` + A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form + ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by + ``<resultVar>`` will also be added automatically. diff --git a/Help/module/CMAKE_REQUIRED_FLAGS.txt b/Help/module/CMAKE_REQUIRED_FLAGS.txt new file mode 100644 index 0000000000..80ae23999b --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_FLAGS.txt @@ -0,0 +1,6 @@ + ``CMAKE_REQUIRED_FLAGS`` + String of additional flags to pass to the compiler. The string must be + space-delimited--a :ref:`;-list <CMake Language Lists>` will not work. + The contents of :variable:`CMAKE_<LANG>_FLAGS <CMAKE_<LANG>_FLAGS>` and + its associated configuration-specific variable are automatically added + to the compiler command before the contents of ``CMAKE_REQUIRED_FLAGS``. diff --git a/Help/module/CMAKE_REQUIRED_INCLUDES.txt b/Help/module/CMAKE_REQUIRED_INCLUDES.txt new file mode 100644 index 0000000000..c8993bbfce --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_INCLUDES.txt @@ -0,0 +1,4 @@ + ``CMAKE_REQUIRED_INCLUDES`` + A :ref:`;-list <CMake Language Lists>` of header search paths to pass to + the compiler. These will be the only header search paths used--the contents + of the :prop_dir:`INCLUDE_DIRECTORIES` directory property will be ignored. diff --git a/Help/module/CMAKE_REQUIRED_LIBRARIES.txt b/Help/module/CMAKE_REQUIRED_LIBRARIES.txt new file mode 100644 index 0000000000..8611b9edf6 --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_LIBRARIES.txt @@ -0,0 +1,5 @@ + ``CMAKE_REQUIRED_LIBRARIES`` + A :ref:`;-list <CMake Language Lists>` of libraries to add to the link + command. These can be the name of system libraries or they can be + :ref:`Imported Targets <Imported Targets>` (see :command:`try_compile` for + further details). diff --git a/Help/module/CMAKE_REQUIRED_LINK_OPTIONS.txt b/Help/module/CMAKE_REQUIRED_LINK_OPTIONS.txt new file mode 100644 index 0000000000..f2a2474374 --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_LINK_OPTIONS.txt @@ -0,0 +1,5 @@ + ``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + + A :ref:`;-list <CMake Language Lists>` of options to add to the link + command (see :command:`try_compile` for further details). diff --git a/Help/module/CMAKE_REQUIRED_QUIET.txt b/Help/module/CMAKE_REQUIRED_QUIET.txt new file mode 100644 index 0000000000..aae8059f6d --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_QUIET.txt @@ -0,0 +1,5 @@ + ``CMAKE_REQUIRED_QUIET`` + .. versionadded:: 3.1 + + If this variable evaluates to a boolean true value, all status messages + associated with the check will be suppressed. diff --git a/Modules/CheckCCompilerFlag.cmake b/Modules/CheckCCompilerFlag.cmake index 335b437133..065b90ac2a 100644 --- a/Modules/CheckCCompilerFlag.cmake +++ b/Modules/CheckCCompilerFlag.cmake @@ -11,25 +11,37 @@ Check whether the C compiler supports a given flag. .. code-block:: cmake - check_c_compiler_flag(<flag> <var>) + check_c_compiler_flag(<flag> <resultVar>) Check that the ``<flag>`` is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry - named ``<var>``. - -This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable -and calls the ``check_c_source_compiles`` macro from the -:module:`CheckCSourceCompiles` module. See documentation of that -module for a listing of variables that can otherwise modify the build. + named ``<resultVar>``. A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. -.. note:: - Since the :command:`try_compile` command forwards flags from variables - like :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`, unknown flags - in such variables may cause a false negative for this check. +The check is only performed once, with the result cached in the variable named +by ``<resultVar>``. Every subsequent CMake run will re-use this cached value +rather than performing the check again, even if the ``<code>`` changes. In +order to force the check to be re-evaluated, the variable named by +``<resultVar>`` must be manually removed from the cache. + +The compile and link commands can be influenced by setting any of the +following variables prior to calling ``check_c_compiler_flag()`` + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckCSourceCompiles.cmake b/Modules/CheckCSourceCompiles.cmake index b24da49bc0..ce4719a30a 100644 --- a/Modules/CheckCSourceCompiles.cmake +++ b/Modules/CheckCSourceCompiles.cmake @@ -22,51 +22,27 @@ Check if given C source compiles and links into an executable. checking if anything in the output matches any of the specified regular expressions. - The underlying check is performed by the :command:`try_compile` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_c_source_compiles()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_compile()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_compile` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_compile` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - - The check is only performed once, with the result cached in the variable - named by ``<resultVar>``. Every subsequent CMake run will re-use this cached - value rather than performing the check again, even if the ``<code>`` changes. - In order to force the check to be re-evaluated, the variable named by + The check is only performed once, with the result cached in the variable named + by ``<resultVar>``. Every subsequent CMake run will re-use this cached value + rather than performing the check again, even if the ``<code>`` changes. In + order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_c_source_compiles()``: + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckCSourceRuns.cmake b/Modules/CheckCSourceRuns.cmake index a6081ff46e..d5a8fda423 100644 --- a/Modules/CheckCSourceRuns.cmake +++ b/Modules/CheckCSourceRuns.cmake @@ -21,51 +21,27 @@ subsequently be run. be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message). - The underlying check is performed by the :command:`try_run` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_c_source_runs()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_run()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_run` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_run` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - - The check is only performed once, with the result cached in the variable - named by ``<resultVar>``. Every subsequent CMake run will re-use this cached - value rather than performing the check again, even if the ``<code>`` changes. - In order to force the check to be re-evaluated, the variable named by + The check is only performed once, with the result cached in the variable named + by ``<resultVar>``. Every subsequent CMake run will re-use this cached value + rather than performing the check again, even if the ``<code>`` changes. In + order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_c_source_runs()``: + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckCXXCompilerFlag.cmake b/Modules/CheckCXXCompilerFlag.cmake index 3bc346362d..b319d90bb3 100644 --- a/Modules/CheckCXXCompilerFlag.cmake +++ b/Modules/CheckCXXCompilerFlag.cmake @@ -17,11 +17,6 @@ Check whether the CXX compiler supports a given flag. a diagnostic. Stores the result in an internal cache entry named ``<var>``. -This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable -and calls the ``check_cxx_source_compiles`` macro from the -:module:`CheckCXXSourceCompiles` module. See documentation of that -module for a listing of variables that can otherwise modify the build. - A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. diff --git a/Modules/CheckCXXSourceCompiles.cmake b/Modules/CheckCXXSourceCompiles.cmake index 502bfa76e6..4b33aa8ae4 100644 --- a/Modules/CheckCXXSourceCompiles.cmake +++ b/Modules/CheckCXXSourceCompiles.cmake @@ -22,51 +22,27 @@ Check if given C++ source compiles and links into an executable. checking if anything in the output matches any of the specified regular expressions. - The underlying check is performed by the :command:`try_compile` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_cxx_source_compiles()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_compile()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_compile` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_compile` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - - The check is only performed once, with the result cached in the variable - named by ``<resultVar>``. Every subsequent CMake run will re-use this cached - value rather than performing the check again, even if the ``<code>`` changes. - In order to force the check to be re-evaluated, the variable named by + The check is only performed once, with the result cached in the variable named + by ``<resultVar>``. Every subsequent CMake run will re-use this cached value + rather than performing the check again, even if the ``<code>`` changes. In + order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_cxx_source_compiles()``: + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckCXXSourceRuns.cmake b/Modules/CheckCXXSourceRuns.cmake index af03453d98..34027150e9 100644 --- a/Modules/CheckCXXSourceRuns.cmake +++ b/Modules/CheckCXXSourceRuns.cmake @@ -21,51 +21,27 @@ subsequently be run. be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message). - The underlying check is performed by the :command:`try_run` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_cxx_source_runs()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_run()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_run` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_run` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - - The check is only performed once, with the result cached in the variable - named by ``<resultVar>``. Every subsequent CMake run will re-use this cached - value rather than performing the check again, even if the ``<code>`` changes. - In order to force the check to be re-evaluated, the variable named by + The check is only performed once, with the result cached in the variable named + by ``<resultVar>``. Every subsequent CMake run will re-use this cached value + rather than performing the check again, even if the ``<code>`` changes. In + order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_cxx_source_runs()``: + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckCXXSymbolExists.cmake b/Modules/CheckCXXSymbolExists.cmake index 1fa0898286..569dafdc44 100644 --- a/Modules/CheckCXXSymbolExists.cmake +++ b/Modules/CheckCXXSymbolExists.cmake @@ -41,22 +41,17 @@ Check if a symbol exists as a function, variable, or macro in ``C++``. The following variables may be set before calling this macro to modify the way the check is run: -``CMAKE_REQUIRED_FLAGS`` - string of compile command line flags. -``CMAKE_REQUIRED_DEFINITIONS`` - a :ref:`;-list <CMake Language Lists>` of macros to define (-DFOO=bar). -``CMAKE_REQUIRED_INCLUDES`` - a :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. -``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. -``CMAKE_REQUIRED_LIBRARIES`` - a :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. See policy :policy:`CMP0075`. -``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - execute quietly without messages. +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt For example: diff --git a/Modules/CheckCompilerFlag.cmake b/Modules/CheckCompilerFlag.cmake index 77c07b95da..a18435b3b1 100644 --- a/Modules/CheckCompilerFlag.cmake +++ b/Modules/CheckCompilerFlag.cmake @@ -13,24 +13,36 @@ Check whether the compiler supports a given flag. .. code-block:: cmake - check_compiler_flag(<lang> <flag> <var>) + check_compiler_flag(<lang> <flag> <resultVar>) Check that the ``<flag>`` is accepted by the compiler without a diagnostic. -Stores the result in an internal cache entry named ``<var>``. - -This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable -and calls the ``check_source_compiles(<LANG>)`` function from the -:module:`CheckSourceCompiles` module. See documentation of that -module for a listing of variables that can otherwise modify the build. +Stores the result in an internal cache entry named ``<resultVar>``. A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. -.. note:: - Since the :command:`try_compile` command forwards flags from variables - like :variable:`CMAKE_<LANG>_FLAGS <CMAKE_<LANG>_FLAGS>`, unknown flags - in such variables may cause a false negative for this check. +The check is only performed once, with the result cached in the variable named +by ``<resultVar>``. Every subsequent CMake run will re-use this cached value +rather than performing the check again, even if the ``<code>`` changes. In +order to force the check to be re-evaluated, the variable named by +``<resultVar>`` must be manually removed from the cache. + +The compile and link commands can be influenced by setting any of the +following variables prior to calling ``check_compiler_flag()`` + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckFortranCompilerFlag.cmake b/Modules/CheckFortranCompilerFlag.cmake index 5b1cd02779..a7e544ded7 100644 --- a/Modules/CheckFortranCompilerFlag.cmake +++ b/Modules/CheckFortranCompilerFlag.cmake @@ -13,25 +13,37 @@ Check whether the Fortran compiler supports a given flag. .. code-block:: cmake - check_fortran_compiler_flag(<flag> <var>) + check_fortran_compiler_flag(<flag> <resultVar>) Check that the ``<flag>`` is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry - named ``<var>``. - -This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable -and calls the ``check_fortran_source_compiles`` macro from the -:module:`CheckFortranSourceCompiles` module. See documentation of that -module for a listing of variables that can otherwise modify the build. + named ``<resultVar>``. A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. -.. note:: - Since the :command:`try_compile` command forwards flags from variables - like :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`, unknown flags - in such variables may cause a false negative for this check. +The check is only performed once, with the result cached in the variable named +by ``<resultVar>``. Every subsequent CMake run will re-use this cached value +rather than performing the check again, even if the ``<code>`` changes. In +order to force the check to be re-evaluated, the variable named by +``<resultVar>`` must be manually removed from the cache. + +The compile and link commands can be influenced by setting any of the +following variables prior to calling ``check_fortran_compiler_flag()`` + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckFortranSourceCompiles.cmake b/Modules/CheckFortranSourceCompiles.cmake index 8dcc1d54a5..5158b7eed4 100644 --- a/Modules/CheckFortranSourceCompiles.cmake +++ b/Modules/CheckFortranSourceCompiles.cmake @@ -47,49 +47,27 @@ Check if given Fortran source compiles and links into an executable. ``SRC_EXT`` option can be used to override this with ``.<extension>`` instead-- ``.F90`` is a typical choice. - The underlying check is performed by the :command:`try_compile` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_fortran_source_compiles()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_compile()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_compile` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_compile` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - - The check is only performed once, with the result cached in the variable - named by ``<resultVar>``. Every subsequent CMake run will re-use this cached - value rather than performing the check again, even if the ``<code>`` changes. - In order to force the check to be re-evaluated, the variable named by + The check is only performed once, with the result cached in the variable named + by ``<resultVar>``. Every subsequent CMake run will re-use this cached value + rather than performing the check again, even if the ``<code>`` changes. In + order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_fortran_source_compiles()``: + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckFortranSourceRuns.cmake b/Modules/CheckFortranSourceRuns.cmake index 985c765599..f9967498c4 100644 --- a/Modules/CheckFortranSourceRuns.cmake +++ b/Modules/CheckFortranSourceRuns.cmake @@ -43,47 +43,27 @@ subsequently be run. By default, the test source file will be given a ``.F90`` file extension. The ``SRC_EXT`` option can be used to override this with ``.<extension>`` instead. - The underlying check is performed by the :command:`try_run` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_fortran_source_runs()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_run()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_run` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_run` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - - The check is only performed once, with the result cached in the variable - named by ``<resultVar>``. Every subsequent CMake run will re-use this cached - value rather than performing the check again, even if the ``<code>`` changes. - In order to force the check to be re-evaluated, the variable named by + The check is only performed once, with the result cached in the variable named + by ``<resultVar>``. Every subsequent CMake run will re-use this cached value + rather than performing the check again, even if the ``<code>`` changes. In + order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_fortran_source_runs()``: + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckFunctionExists.cmake b/Modules/CheckFunctionExists.cmake index e2939ed97d..e7c47a4e7a 100644 --- a/Modules/CheckFunctionExists.cmake +++ b/Modules/CheckFunctionExists.cmake @@ -20,22 +20,17 @@ Check if a C function can be linked The following variables may be set before calling this macro to modify the way the check is run: -``CMAKE_REQUIRED_FLAGS`` - string of compile command line flags. -``CMAKE_REQUIRED_DEFINITIONS`` - a :ref:`;-list <CMake Language Lists>` of macros to define (-DFOO=bar). -``CMAKE_REQUIRED_INCLUDES`` - a :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. -``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. -``CMAKE_REQUIRED_LIBRARIES`` - a :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. See policy :policy:`CMP0075`. -``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - execute quietly without messages. +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt .. note:: diff --git a/Modules/CheckIncludeFile.cmake b/Modules/CheckIncludeFile.cmake index 577130725d..1d8c9f766d 100644 --- a/Modules/CheckIncludeFile.cmake +++ b/Modules/CheckIncludeFile.cmake @@ -21,22 +21,17 @@ Provides a macro to check if a header file can be included in ``C``. The following variables may be set before calling this macro to modify the way the check is run: -``CMAKE_REQUIRED_FLAGS`` - string of compile command line flags. -``CMAKE_REQUIRED_DEFINITIONS`` - a :ref:`;-list <CMake Language Lists>` of macros to define (-DFOO=bar). -``CMAKE_REQUIRED_INCLUDES`` - a :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. -``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. -``CMAKE_REQUIRED_LIBRARIES`` - a :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. See policy :policy:`CMP0075`. -``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - execute quietly without messages. +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt See the :module:`CheckIncludeFiles` module to check for multiple headers at once. See the :module:`CheckIncludeFileCXX` module to check for headers diff --git a/Modules/CheckIncludeFileCXX.cmake b/Modules/CheckIncludeFileCXX.cmake index d27b485e57..53d9a456e0 100644 --- a/Modules/CheckIncludeFileCXX.cmake +++ b/Modules/CheckIncludeFileCXX.cmake @@ -21,22 +21,17 @@ Provides a macro to check if a header file can be included in ``CXX``. The following variables may be set before calling this macro to modify the way the check is run: -``CMAKE_REQUIRED_FLAGS`` - string of compile command line flags. -``CMAKE_REQUIRED_DEFINITIONS`` - a :ref:`;-list <CMake Language Lists>` of macros to define (-DFOO=bar). -``CMAKE_REQUIRED_INCLUDES`` - a :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. -``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. -``CMAKE_REQUIRED_LIBRARIES`` - a :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. See policy :policy:`CMP0075`. -``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - execute quietly without messages. +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt See modules :module:`CheckIncludeFile` and :module:`CheckIncludeFiles` to check for one or more ``C`` headers. diff --git a/Modules/CheckIncludeFiles.cmake b/Modules/CheckIncludeFiles.cmake index 2f50c61d47..071df0c601 100644 --- a/Modules/CheckIncludeFiles.cmake +++ b/Modules/CheckIncludeFiles.cmake @@ -27,22 +27,17 @@ be included together. The following variables may be set before calling this macro to modify the way the check is run: -``CMAKE_REQUIRED_FLAGS`` - string of compile command line flags. -``CMAKE_REQUIRED_DEFINITIONS`` - a :ref:`;-list <CMake Language Lists>` of macros to define (-DFOO=bar). -``CMAKE_REQUIRED_INCLUDES`` - a :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. -``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. -``CMAKE_REQUIRED_LIBRARIES`` - a :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. See policy :policy:`CMP0075`. -``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - execute quietly without messages. +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt See modules :module:`CheckIncludeFile` and :module:`CheckIncludeFileCXX` to check for a single header file in ``C`` or ``CXX`` languages. diff --git a/Modules/CheckLibraryExists.cmake b/Modules/CheckLibraryExists.cmake index 5f1a914b3c..8340500803 100644 --- a/Modules/CheckLibraryExists.cmake +++ b/Modules/CheckLibraryExists.cmake @@ -26,18 +26,16 @@ Check if the function exists. The following variables may be set before calling this macro to modify the way the check is run: -``CMAKE_REQUIRED_FLAGS`` - string of compile command line flags. -``CMAKE_REQUIRED_DEFINITIONS`` - list of macros to define (-DFOO=bar). -``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - list of options to pass to link command. -``CMAKE_REQUIRED_LIBRARIES`` - list of libraries to link. -``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - execute quietly without messages. +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckOBJCCompilerFlag.cmake b/Modules/CheckOBJCCompilerFlag.cmake index d8d874175f..b0b7a43481 100644 --- a/Modules/CheckOBJCCompilerFlag.cmake +++ b/Modules/CheckOBJCCompilerFlag.cmake @@ -13,25 +13,37 @@ Check whether the Objective-C compiler supports a given flag. .. code-block:: cmake - check_objc_compiler_flag(<flag> <var>) + check_objc_compiler_flag(<flag> <resultVar>) Check that the ``<flag>`` is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry - named ``<var>``. - -This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable -and calls the ``check_objc_source_compiles`` macro from the -:module:`CheckOBJCSourceCompiles` module. See documentation of that -module for a listing of variables that can otherwise modify the build. + named ``<resultVar>``. A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. -.. note:: - Since the :command:`try_compile` command forwards flags from variables - like :variable:`CMAKE_OBJC_FLAGS <CMAKE_<LANG>_FLAGS>`, unknown flags - in such variables may cause a false negative for this check. +The check is only performed once, with the result cached in the variable named +by ``<resultVar>``. Every subsequent CMake run will re-use this cached value +rather than performing the check again, even if the ``<code>`` changes. In +order to force the check to be re-evaluated, the variable named by +``<resultVar>`` must be manually removed from the cache. + +The compile and link commands can be influenced by setting any of the +following variables prior to calling ``check_objc_compiler_flag()`` + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckOBJCSourceCompiles.cmake b/Modules/CheckOBJCSourceCompiles.cmake index c268ef9050..7663054b62 100644 --- a/Modules/CheckOBJCSourceCompiles.cmake +++ b/Modules/CheckOBJCSourceCompiles.cmake @@ -24,47 +24,27 @@ Check if given Objective-C source compiles and links into an executable. checking if anything in the output matches any of the specified regular expressions. - The underlying check is performed by the :command:`try_compile` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_objc_source_compiles()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_OBJC_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_compile()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_compile` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_compile` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - - The check is only performed once, with the result cached in the variable - named by ``<resultVar>``. Every subsequent CMake run will re-use this cached - value rather than performing the check again, even if the ``<code>`` changes. - In order to force the check to be re-evaluated, the variable named by + The check is only performed once, with the result cached in the variable named + by ``<resultVar>``. Every subsequent CMake run will re-use this cached value + rather than performing the check again, even if the ``<code>`` changes. In + order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_objc_source_compiles()`` + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckOBJCSourceRuns.cmake b/Modules/CheckOBJCSourceRuns.cmake index dd03309936..a23a0c724e 100644 --- a/Modules/CheckOBJCSourceRuns.cmake +++ b/Modules/CheckOBJCSourceRuns.cmake @@ -23,47 +23,27 @@ subsequently be run. be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message). - The underlying check is performed by the :command:`try_run` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_objc_source_runs()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_OBJC_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_run()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_run` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_run` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - - The check is only performed once, with the result cached in the variable - named by ``<resultVar>``. Every subsequent CMake run will re-use this cached - value rather than performing the check again, even if the ``<code>`` changes. - In order to force the check to be re-evaluated, the variable named by + The check is only performed once, with the result cached in the variable named + by ``<resultVar>``. Every subsequent CMake run will re-use this cached value + rather than performing the check again, even if the ``<code>`` changes. In + order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_objc_source_runs()`` + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckOBJCXXCompilerFlag.cmake b/Modules/CheckOBJCXXCompilerFlag.cmake index 3f3f8fe38b..cead15be8f 100644 --- a/Modules/CheckOBJCXXCompilerFlag.cmake +++ b/Modules/CheckOBJCXXCompilerFlag.cmake @@ -13,25 +13,37 @@ Check whether the Objective-C++ compiler supports a given flag. .. code-block:: cmake - check_objcxx_compiler_flag(<flag> <var>) + check_objcxx_compiler_flag(<flag> <resultVar>) Check that the ``<flag>`` is accepted by the compiler without a diagnostic. Stores the result in an internal cache entry - named ``<var>``. - -This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable -and calls the ``check_objcxx_source_compiles`` macro from the -:module:`CheckOBJCXXSourceCompiles` module. See documentation of that -module for a listing of variables that can otherwise modify the build. + named ``<resultVar>``. A positive result from this check indicates only that the compiler did not issue a diagnostic message when given the flag. Whether the flag has any effect or even a specific one is beyond the scope of this module. -.. note:: - Since the :command:`try_compile` command forwards flags from variables - like :variable:`CMAKE_OBJCXX_FLAGS <CMAKE_<LANG>_FLAGS>`, unknown flags - in such variables may cause a false negative for this check. +The check is only performed once, with the result cached in the variable named +by ``<resultVar>``. Every subsequent CMake run will re-use this cached value +rather than performing the check again, even if the ``<code>`` changes. In +order to force the check to be re-evaluated, the variable named by +``<resultVar>`` must be manually removed from the cache. + +The compile and link commands can be influenced by setting any of the +following variables prior to calling ``check_objcxx_compiler_flag()`` + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckOBJCXXSourceCompiles.cmake b/Modules/CheckOBJCXXSourceCompiles.cmake index 11869343a4..cfbda3a3c3 100644 --- a/Modules/CheckOBJCXXSourceCompiles.cmake +++ b/Modules/CheckOBJCXXSourceCompiles.cmake @@ -24,47 +24,27 @@ Check if given Objective-C++ source compiles and links into an executable. checking if anything in the output matches any of the specified regular expressions. - The underlying check is performed by the :command:`try_compile` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_objcxx_source_compiles()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_OBJCXX_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_compile()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_compile` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_compile` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - - The check is only performed once, with the result cached in the variable - named by ``<resultVar>``. Every subsequent CMake run will re-use this cached - value rather than performing the check again, even if the ``<code>`` changes. - In order to force the check to be re-evaluated, the variable named by + The check is only performed once, with the result cached in the variable named + by ``<resultVar>``. Every subsequent CMake run will re-use this cached value + rather than performing the check again, even if the ``<code>`` changes. In + order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_objcxx_source_compiles()`` + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckOBJCXXSourceRuns.cmake b/Modules/CheckOBJCXXSourceRuns.cmake index 05a5e4cf59..b2831b6ed3 100644 --- a/Modules/CheckOBJCXXSourceRuns.cmake +++ b/Modules/CheckOBJCXXSourceRuns.cmake @@ -23,47 +23,27 @@ subsequently be run. be set to 1, otherwise it will be set to an value that evaluates to boolean false (e.g. an empty string or an error message). - The underlying check is performed by the :command:`try_run` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_objcxx_source_runs()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_OBJCXX_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_run()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_run` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_run` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - - The check is only performed once, with the result cached in the variable - named by ``<resultVar>``. Every subsequent CMake run will re-use this cached - value rather than performing the check again, even if the ``<code>`` changes. - In order to force the check to be re-evaluated, the variable named by + The check is only performed once, with the result cached in the variable named + by ``<resultVar>``. Every subsequent CMake run will re-use this cached value + rather than performing the check again, even if the ``<code>`` changes. In + order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_objcxx_source_runs()`` + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckPrototypeDefinition.cmake b/Modules/CheckPrototypeDefinition.cmake index 3d53b930a7..c1a7a1c579 100644 --- a/Modules/CheckPrototypeDefinition.cmake +++ b/Modules/CheckPrototypeDefinition.cmake @@ -35,20 +35,18 @@ Check if the prototype we expect is correct. The following variables may be set before calling this function to modify the way the check is run: -``CMAKE_REQUIRED_FLAGS`` - string of compile command line flags. -``CMAKE_REQUIRED_DEFINITIONS`` - list of macros to define (-DFOO=bar). -``CMAKE_REQUIRED_INCLUDES`` - list of include directories. -``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - list of options to pass to link command. -``CMAKE_REQUIRED_LIBRARIES`` - list of libraries to link. -``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - execute quietly without messages. +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] # diff --git a/Modules/CheckSourceCompiles.cmake b/Modules/CheckSourceCompiles.cmake index 978879815d..041b59c457 100644 --- a/Modules/CheckSourceCompiles.cmake +++ b/Modules/CheckSourceCompiles.cmake @@ -47,47 +47,27 @@ Check if given source compiles and links into an executable. end program" HAVE_ERROR_STOP) - The underlying check is performed by the :command:`try_compile` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_source_compiles()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_<LANG>_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_compile()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_compile` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_compile` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - The check is only performed once, with the result cached in the variable named by ``<resultVar>``. Every subsequent CMake run will re-use this cached value rather than performing the check again, even if the ``<code>`` changes. In order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_source_compiles()``: + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckSourceRuns.cmake b/Modules/CheckSourceRuns.cmake index e2fa579253..822ee07a82 100644 --- a/Modules/CheckSourceRuns.cmake +++ b/Modules/CheckSourceRuns.cmake @@ -47,47 +47,27 @@ subsequently be run. end program" HAVE_COARRAY) - The underlying check is performed by the :command:`try_run` command. The - compile and link commands can be influenced by setting any of the following - variables prior to calling ``check_source_runs()``: - - ``CMAKE_REQUIRED_FLAGS`` - Additional flags to pass to the compiler. Note that the contents of - :variable:`CMAKE_<LANG>_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated - configuration-specific variable are automatically added to the compiler - command before the contents of ``CMAKE_REQUIRED_FLAGS``. - - ``CMAKE_REQUIRED_DEFINITIONS`` - A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form - ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by - ``<resultVar>`` will also be added automatically. - - ``CMAKE_REQUIRED_INCLUDES`` - A :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. These will be the only header search paths used by - ``try_run()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES` - directory property will be ignored. - - ``CMAKE_REQUIRED_LINK_OPTIONS`` - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_run` for further details). - - ``CMAKE_REQUIRED_LIBRARIES`` - A :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. These can be the name of system libraries or they can be - :ref:`Imported Targets <Imported Targets>` (see :command:`try_run` for - further details). - - ``CMAKE_REQUIRED_QUIET`` - If this variable evaluates to a boolean true value, all status messages - associated with the check will be suppressed. - - The check is only performed once, with the result cached in the variable - named by ``<resultVar>``. Every subsequent CMake run will re-use this cached - value rather than performing the check again, even if the ``<code>`` changes. - In order to force the check to be re-evaluated, the variable named by + The check is only performed once, with the result cached in the variable named + by ``<resultVar>``. Every subsequent CMake run will re-use this cached value + rather than performing the check again, even if the ``<code>`` changes. In + order to force the check to be re-evaluated, the variable named by ``<resultVar>`` must be manually removed from the cache. + The compile and link commands can be influenced by setting any of the + following variables prior to calling ``check_source_runs()`` + +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckStructHasMember.cmake b/Modules/CheckStructHasMember.cmake index 8217c84c2a..55c7cf4447 100644 --- a/Modules/CheckStructHasMember.cmake +++ b/Modules/CheckStructHasMember.cmake @@ -26,20 +26,17 @@ Check if the given struct or class has the specified member variable The following variables may be set before calling this macro to modify the way the check is run: -``CMAKE_REQUIRED_FLAGS`` - string of compile command line flags. -``CMAKE_REQUIRED_DEFINITIONS`` - list of macros to define (-DFOO=bar). -``CMAKE_REQUIRED_INCLUDES`` - list of include directories. -``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - list of options to pass to link command. -``CMAKE_REQUIRED_LIBRARIES`` - list of libraries to link. -``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - execute quietly without messages. +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt Example: diff --git a/Modules/CheckSymbolExists.cmake b/Modules/CheckSymbolExists.cmake index 21d2ff5e17..931ed4a05c 100644 --- a/Modules/CheckSymbolExists.cmake +++ b/Modules/CheckSymbolExists.cmake @@ -31,22 +31,17 @@ If the check needs to be done in C++, consider using The following variables may be set before calling this macro to modify the way the check is run: -``CMAKE_REQUIRED_FLAGS`` - string of compile command line flags. -``CMAKE_REQUIRED_DEFINITIONS`` - a :ref:`;-list <CMake Language Lists>` of macros to define (-DFOO=bar). -``CMAKE_REQUIRED_INCLUDES`` - a :ref:`;-list <CMake Language Lists>` of header search paths to pass to - the compiler. -``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. -``CMAKE_REQUIRED_LIBRARIES`` - a :ref:`;-list <CMake Language Lists>` of libraries to add to the link - command. See policy :policy:`CMP0075`. -``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - execute quietly without messages. +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt For example: diff --git a/Modules/CheckTypeSize.cmake b/Modules/CheckTypeSize.cmake index a2a5b72f4e..01ce1d202a 100644 --- a/Modules/CheckTypeSize.cmake +++ b/Modules/CheckTypeSize.cmake @@ -67,20 +67,18 @@ member you can do something like this: The following variables may be set before calling this macro to modify the way the check is run: -``CMAKE_REQUIRED_FLAGS`` - string of compile command line flags. -``CMAKE_REQUIRED_DEFINITIONS`` - list of macros to define (-DFOO=bar). -``CMAKE_REQUIRED_INCLUDES`` - list of include directories. -``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - list of options to pass to link command. -``CMAKE_REQUIRED_LIBRARIES`` - list of libraries to link. -``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - execute quietly without messages. +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_INCLUDES.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + ``CMAKE_EXTRA_INCLUDE_FILES`` list of extra headers to include. #]=======================================================================] diff --git a/Modules/CheckVariableExists.cmake b/Modules/CheckVariableExists.cmake index 3a7a431fdf..9e5d710f33 100644 --- a/Modules/CheckVariableExists.cmake +++ b/Modules/CheckVariableExists.cmake @@ -26,18 +26,16 @@ Check if the variable exists. The following variables may be set before calling this macro to modify the way the check is run: -``CMAKE_REQUIRED_FLAGS`` - string of compile command line flags. -``CMAKE_REQUIRED_DEFINITIONS`` - list of macros to define (-DFOO=bar). -``CMAKE_REQUIRED_LINK_OPTIONS`` - .. versionadded:: 3.14 - list of options to pass to link command. -``CMAKE_REQUIRED_LIBRARIES`` - list of libraries to link. -``CMAKE_REQUIRED_QUIET`` - .. versionadded:: 3.1 - execute quietly without messages. +.. include:: /module/CMAKE_REQUIRED_FLAGS.txt + +.. include:: /module/CMAKE_REQUIRED_DEFINITIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LINK_OPTIONS.txt + +.. include:: /module/CMAKE_REQUIRED_LIBRARIES.txt + +.. include:: /module/CMAKE_REQUIRED_QUIET.txt + #]=======================================================================] include_guard(GLOBAL) |