1# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
2# file Copyright.txt or https://cmake.org/licensing for details.
3
4
5#[=======================================================================[.rst:
6CheckSourceRuns
7-------------------
8
9.. versionadded:: 3.19
10
11Check if given source compiles and links into an executable and can
12subsequently be run.
13
14.. command:: check_source_runs
15
16  .. code-block:: cmake
17
18    check_source_runs(<lang> <code> <resultVar>
19                      [SRC_EXT <extension>])
20
21  Check that the source supplied in ``<code>`` can be compiled as a source
22  file for the requested language, linked as an executable and then run.
23  The ``<code>`` must contain at least a ``main()`` function. If the ``<code>``
24  could be built and run successfully, the internal cache variable specified by
25  ``<resultVar>`` will be set to 1, otherwise it will be set to an value that
26  evaluates to boolean false (e.g. an empty string or an error message).
27
28  By default, the test source file will be given a file extension that matches
29  the requested language. The ``SRC_EXT`` option can be used to override this
30  with ``.<extension>`` instead.
31
32  The underlying check is performed by the :command:`try_run` command. The
33  compile and link commands can be influenced by setting any of the following
34  variables prior to calling ``check_objc_source_runs()``:
35
36  ``CMAKE_REQUIRED_FLAGS``
37    Additional flags to pass to the compiler. Note that the contents of
38    :variable:`CMAKE_OBJC_FLAGS <CMAKE_<LANG>_FLAGS>` and its associated
39    configuration-specific variable are automatically added to the compiler
40    command before the contents of ``CMAKE_REQUIRED_FLAGS``.
41
42  ``CMAKE_REQUIRED_DEFINITIONS``
43    A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
44    ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
45    ``<resultVar>`` will also be added automatically.
46
47  ``CMAKE_REQUIRED_INCLUDES``
48    A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
49    the compiler. These will be the only header search paths used by
50    ``try_run()``, i.e. the contents of the :prop_dir:`INCLUDE_DIRECTORIES`
51    directory property will be ignored.
52
53  ``CMAKE_REQUIRED_LINK_OPTIONS``
54    A :ref:`;-list <CMake Language Lists>` of options to add to the link
55    command (see :command:`try_run` for further details).
56
57  ``CMAKE_REQUIRED_LIBRARIES``
58    A :ref:`;-list <CMake Language Lists>` of libraries to add to the link
59    command. These can be the name of system libraries or they can be
60    :ref:`Imported Targets <Imported Targets>` (see :command:`try_run` for
61    further details).
62
63  ``CMAKE_REQUIRED_QUIET``
64    If this variable evaluates to a boolean true value, all status messages
65    associated with the check will be suppressed.
66
67  The check is only performed once, with the result cached in the variable
68  named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
69  value rather than performing the check again, even if the ``<code>`` changes.
70  In order to force the check to be re-evaluated, the variable named by
71  ``<resultVar>`` must be manually removed from the cache.
72
73#]=======================================================================]
74
75include_guard(GLOBAL)
76include(Internal/CheckSourceRuns)
77
78function(CHECK_SOURCE_RUNS _lang _source _var)
79  cmake_check_source_runs(${_lang} "${_source}" ${_var} ${ARGN})
80endfunction()
81