Commit 63fc3bff authored by Craig Scott's avatar Craig Scott

Check*Source{Compiles,Runs}: Rewrite docs for these modules

parent 4c7caf15
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CheckCSourceCompiles
# --------------------
#
# Check if given C source compiles and links into an executable
#
# CHECK_C_SOURCE_COMPILES(<code> <var> [FAIL_REGEX <fail-regex>])
#
# ::
#
# <code> - source code to try to compile, must define 'main'
# <var> - variable to store whether the source code compiled
# Will be created as an internal cache variable.
# <fail-regex> - fail if test output matches this regex
#
# 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_LIBRARIES = list of libraries to link
# CMAKE_REQUIRED_QUIET = execute quietly without messages
#[=======================================================================[.rst:
CheckCSourceCompiles
--------------------
Check if given C source compiles and links into an executable.
.. command:: check_c_source_compiles
::
check_c_source_compiles(code resultVar [FAIL_REGEX regex1 [regex2...]])
Check that the source supplied in ``code`` can be compiled as a C source
file and linked as an executable (so it must contain at least a ``main()``
function). The result will be stored in the internal cache variable specified
by ``resultVar``, with a boolean true value for success and boolean false for
failure. If ``FAIL_REGEX`` is provided, then failure is determined by
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_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.
#]=======================================================================]
macro(CHECK_C_SOURCE_COMPILES SOURCE VAR)
if(NOT DEFINED "${VAR}")
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CheckCSourceRuns
# ----------------
#
# Check if the given C source code compiles and runs.
#
# CHECK_C_SOURCE_RUNS(<code> <var>)
#
# ::
#
# <code> - source code to try to compile
# <var> - variable to store the result
# (1 for success, empty for failure)
# 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:
#
# ::
#
# 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_LIBRARIES = list of libraries to link
# CMAKE_REQUIRED_QUIET = execute quietly without messages
#[=======================================================================[.rst:
CheckCSourceRuns
----------------
Check if given C source compiles and links into an executable and can
subsequently be run.
.. command:: check_c_source_runs
::
check_c_source_runs(code resultVar)
Check that the source supplied in ``code`` can be compiled as a C source
file, linked as an executable and then run. The ``code`` must contain at
least a ``main()`` function. If the code could be built and run successfully,
the internal cache variable specified by ``resultVar`` will 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_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
``resultVar`` must be manually removed from the cache.
#]=======================================================================]
macro(CHECK_C_SOURCE_RUNS SOURCE VAR)
if(NOT DEFINED "${VAR}")
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CheckCXXSourceCompiles
# ----------------------
#
# Check if given C++ source compiles and links into an executable
#
# CHECK_CXX_SOURCE_COMPILES(<code> <var> [FAIL_REGEX <fail-regex>])
#
# ::
#
# <code> - source code to try to compile, must define 'main'
# <var> - variable to store whether the source code compiled
# Will be created as an internal cache variable.
# <fail-regex> - fail if test output matches this regex
#
# 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_LIBRARIES = list of libraries to link
# CMAKE_REQUIRED_QUIET = execute quietly without messages
#[=======================================================================[.rst:
CheckCXXSourceCompiles
----------------------
Check if given C++ source compiles and links into an executable.
.. command:: check_cxx_source_compiles
::
check_cxx_source_compiles(code resultVar [FAIL_REGEX regex1 [regex2...]])
Check that the source supplied in ``code`` can be compiled as a C++ source
file and linked as an executable (so it must contain at least a ``main()``
function). The result will be stored in the internal cache variable specified
by ``resultVar``, with a boolean true value for success and boolean false for
failure. If ``FAIL_REGEX`` is provided, then failure is determined by
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_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.
#]=======================================================================]
macro(CHECK_CXX_SOURCE_COMPILES SOURCE VAR)
if(NOT DEFINED "${VAR}")
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CheckCXXSourceRuns
# ------------------
#
# Check if the given C++ source code compiles and runs.
#
# CHECK_CXX_SOURCE_RUNS(<code> <var>)
#
# ::
#
# <code> - source code to try to compile
# <var> - variable to store the result
# (1 for success, empty for failure)
# 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:
#
# ::
#
# 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_LIBRARIES = list of libraries to link
# CMAKE_REQUIRED_QUIET = execute quietly without messages
#[=======================================================================[.rst:
CheckCXXSourceRuns
------------------
Check if given C++ source compiles and links into an executable and can
subsequently be run.
.. command:: check_cxx_source_runs
::
check_cxx_source_runs(code resultVar)
Check that the source supplied in ``code`` can be compiled as a C++ source
file, linked as an executable and then run. The ``code`` must contain at
least a ``main()`` function. If the code could be built and run successfully,
the internal cache variable specified by ``resultVar`` will 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_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
``resultVar`` must be manually removed from the cache.
#]=======================================================================]
macro(CHECK_CXX_SOURCE_RUNS SOURCE VAR)
if(NOT DEFINED "${VAR}")
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CheckFortranSourceCompiles
# --------------------------
#
# Check if given Fortran source compiles and links into an executable::
#
# CHECK_Fortran_SOURCE_COMPILES(<code> <var> [FAIL_REGEX <fail-regex>]
# [SRC_EXT <ext>])
#
# The arguments are:
#
# ``<code>``
# Source code to try to compile. It must define a PROGRAM entry point.
# ``<var>``
# Variable to store whether the source code compiled.
# Will be created as an internal cache variable.
# ``FAIL_REGEX <fail-regex>``
# Fail if test output matches this regex.
# ``SRC_EXT <ext>``
# Use source extension ``.<ext>`` instead of the default ``.F``.
#
# 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_LIBRARIES = list of libraries to link
# CMAKE_REQUIRED_QUIET = execute quietly without messages
#[=======================================================================[.rst:
CheckFortranSourceCompiles
--------------------------
Check if given Fortran source compiles and links into an executable.
.. command:: check_fortran_source_compiles
::
check_fortran_source_compiles(code resultVar
[FAIL_REGEX regex1 [regex2...]]
[SRC_EXT ext]
)
Check that the source supplied in ``code`` can be compiled as a Fortran
source file and linked as an executable (so it must contain at least a
``PROGRAM`` entry point). The result will be stored in the internal cache
variable specified by ``resultVar``, with a boolean true value for success
and boolean false for failure. If ``FAIL_REGEX`` is provided, then failure is
determined by checking if anything in the output matches any of the specified
regular expressions.
By default, the test source file will be given a ``.F`` file extension. The
``SRC_EXT`` option can be used to override this with ``.ext`` instead.
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_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.
#]=======================================================================]
macro(CHECK_Fortran_SOURCE_COMPILES SOURCE VAR)
if(NOT DEFINED "${VAR}")
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment