Help/command/try_compile.rst

   1 try_compile
   2 -----------
   3
   4 .. only:: html
   5
   6    .. contents::
   7
   8 Try building some code.
   9
  10 .. _`Try Compiling Whole Projects`:
  11
  12 Try Compiling Whole Projects
  13 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  14
  15 .. code-block:: cmake
  16
  17   try_compile(<resultVar> <bindir> <srcdir>
  18               <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
  19               [OUTPUT_VARIABLE <var>])
  20
  21 Try building a project.  The success or failure of the ``try_compile``,
  22 i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.
  23
  24 In this form, ``<srcdir>`` should contain a complete CMake project with a
  25 ``CMakeLists.txt`` file and all sources.  The ``<bindir>`` and ``<srcdir>``
  26 will not be deleted after this command is run.  Specify ``<targetName>`` to
  27 build a specific target instead of the ``all`` or ``ALL_BUILD`` target.  See
  28 below for the meaning of other options.
  29
  30 .. versionchanged:: 3.24
  31   CMake variables describing platform settings, and those listed by the
  32   :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable, are propagated
  33   into the project's build configuration.  See policy :policy:`CMP0137`.
  34   Previously this was only done by the
  35   :ref:`source file <Try Compiling Source Files>` signature.
  36
  37 .. _`Try Compiling Source Files`:
  38
  39 Try Compiling Source Files
  40 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  41
  42 .. code-block:: cmake
  43
  44   try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
  45               [CMAKE_FLAGS <flags>...]
  46               [COMPILE_DEFINITIONS <defs>...]
  47               [LINK_OPTIONS <options>...]
  48               [LINK_LIBRARIES <libs>...]
  49               [OUTPUT_VARIABLE <var>]
  50               [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
  51               [<LANG>_STANDARD <std>]
  52               [<LANG>_STANDARD_REQUIRED <bool>]
  53               [<LANG>_EXTENSIONS <bool>]
  54               )
  55
  56 Try building an executable or static library from one or more source files
  57 (which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE`
  58 variable).  The success or failure of the ``try_compile``, i.e. ``TRUE`` or
  59 ``FALSE`` respectively, is returned in ``<resultVar>``.
  60
  61 In this form, one or more source files must be provided.  If
  62 :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``,
  63 the sources must include a definition for ``main`` and CMake will create a
  64 ``CMakeLists.txt`` file to build the source(s) as an executable.
  65 If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``,
  66 a static library will be built instead and no definition for ``main`` is
  67 required.  For an executable, the generated ``CMakeLists.txt`` file would
  68 contain something like the following:
  69
  70 .. code-block:: cmake
  71
  72   add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
  73   include_directories(${INCLUDE_DIRECTORIES})
  74   link_directories(${LINK_DIRECTORIES})
  75   add_executable(cmTryCompileExec <srcfile>...)
  76   target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
  77   target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
  78
  79 The options are:
  80
  81 ``CMAKE_FLAGS <flags>...``
  82   Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to
  83   the ``cmake`` command-line used to drive the test build.
  84   The above example shows how values for variables
  85   ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
  86   are used.
  87
  88 ``COMPILE_DEFINITIONS <defs>...``
  89   Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions`
  90   in the generated test project.
  91
  92 ``COPY_FILE <fileName>``
  93   Copy the built executable or static library to the given ``<fileName>``.
  94
  95 ``COPY_FILE_ERROR <var>``
  96   Use after ``COPY_FILE`` to capture into variable ``<var>`` any error
  97   message encountered while trying to copy the file.
  98
  99 ``LINK_LIBRARIES <libs>...``
 100   Specify libraries to be linked in the generated project.
 101   The list of libraries may refer to system libraries and to
 102   :ref:`Imported Targets <Imported Targets>` from the calling project.
 103
 104   If this option is specified, any ``-DLINK_LIBRARIES=...`` value
 105   given to the ``CMAKE_FLAGS`` option will be ignored.
 106
 107 ``LINK_OPTIONS <options>...``
 108   .. versionadded:: 3.14
 109
 110   Specify link step options to pass to :command:`target_link_options` or to
 111   set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
 112   project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.
 113
 114 ``OUTPUT_VARIABLE <var>``
 115   Store the output from the build process in the given variable.
 116
 117 ``<LANG>_STANDARD <std>``
 118   .. versionadded:: 3.8
 119
 120   Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`,
 121   :prop_tgt:`OBJC_STANDARD`, :prop_tgt:`OBJCXX_STANDARD`,
 122   or :prop_tgt:`CUDA_STANDARD` target property of the generated project.
 123
 124 ``<LANG>_STANDARD_REQUIRED <bool>``
 125   .. versionadded:: 3.8
 126
 127   Specify the :prop_tgt:`C_STANDARD_REQUIRED`,
 128   :prop_tgt:`CXX_STANDARD_REQUIRED`, :prop_tgt:`OBJC_STANDARD_REQUIRED`,
 129   :prop_tgt:`OBJCXX_STANDARD_REQUIRED`,or :prop_tgt:`CUDA_STANDARD_REQUIRED`
 130   target property of the generated project.
 131
 132 ``<LANG>_EXTENSIONS <bool>``
 133   .. versionadded:: 3.8
 134
 135   Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_EXTENSIONS`,
 136   :prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`,
 137   or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project.
 138
 139 In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be
 140 cleaned automatically.  For debugging, ``--debug-trycompile`` can be
 141 passed to ``cmake`` to avoid this clean.  However, multiple sequential
 142 ``try_compile`` operations reuse this single output directory.  If you use
 143 ``--debug-trycompile``, you can only debug one ``try_compile`` call at a time.
 144 The recommended procedure is to protect all ``try_compile`` calls in your
 145 project by ``if(NOT DEFINED <resultVar>)`` logic, configure with cmake
 146 all the way through once, then delete the cache entry associated with
 147 the try_compile call of interest, and then re-run cmake again with
 148 ``--debug-trycompile``.
 149
 150 Other Behavior Settings
 151 ^^^^^^^^^^^^^^^^^^^^^^^
 152
 153 .. versionadded:: 3.4
 154   If set, the following variables are passed in to the generated
 155   try_compile CMakeLists.txt to initialize compile target properties with
 156   default values:
 157
 158   * :variable:`CMAKE_CUDA_RUNTIME_LIBRARY`
 159   * :variable:`CMAKE_ENABLE_EXPORTS`
 160   * :variable:`CMAKE_LINK_SEARCH_START_STATIC`
 161   * :variable:`CMAKE_LINK_SEARCH_END_STATIC`
 162   * :variable:`CMAKE_MSVC_RUNTIME_LIBRARY`
 163   * :variable:`CMAKE_POSITION_INDEPENDENT_CODE`
 164   * :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY`
 165
 166   If :policy:`CMP0056` is set to ``NEW``, then
 167   :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well.
 168
 169 .. versionchanged:: 3.14
 170   If :policy:`CMP0083` is set to ``NEW``, then in order to obtain correct
 171   behavior at link time, the ``check_pie_supported()`` command from the
 172   :module:`CheckPIESupported` module must be called before using the
 173   :command:`try_compile` command.
 174
 175 The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated
 176 through to the generated test project.
 177
 178 Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
 179 a build configuration.
 180
 181 .. versionadded:: 3.6
 182   Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify
 183   the type of target used for the source file signature.
 184
 185 .. versionadded:: 3.6
 186   Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify
 187   variables that must be propagated into the test project.  This variable is
 188   meant for use only in toolchain files and is only honored by the
 189   ``try_compile()`` command for the source files form, not when given a whole
 190   project.
 191
 192 .. versionchanged:: 3.8
 193   If :policy:`CMP0067` is set to ``NEW``, or any of the ``<LANG>_STANDARD``,
 194   ``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_EXTENSIONS`` options are used,
 195   then the language standard variables are honored:
 196
 197   * :variable:`CMAKE_C_STANDARD`
 198   * :variable:`CMAKE_C_STANDARD_REQUIRED`
 199   * :variable:`CMAKE_C_EXTENSIONS`
 200   * :variable:`CMAKE_CXX_STANDARD`
 201   * :variable:`CMAKE_CXX_STANDARD_REQUIRED`
 202   * :variable:`CMAKE_CXX_EXTENSIONS`
 203   * :variable:`CMAKE_OBJC_STANDARD`
 204   * :variable:`CMAKE_OBJC_STANDARD_REQUIRED`
 205   * :variable:`CMAKE_OBJC_EXTENSIONS`
 206   * :variable:`CMAKE_OBJCXX_STANDARD`
 207   * :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED`
 208   * :variable:`CMAKE_OBJCXX_EXTENSIONS`
 209   * :variable:`CMAKE_CUDA_STANDARD`
 210   * :variable:`CMAKE_CUDA_STANDARD_REQUIRED`
 211   * :variable:`CMAKE_CUDA_EXTENSIONS`
 212
 213   Their values are used to set the corresponding target properties in
 214   the generated project (unless overridden by an explicit option).
 215
 216 .. versionchanged:: 3.14
 217   For the :generator:`Green Hills MULTI` generator the GHS toolset and target
 218   system customization cache variables are also propagated into the test project.
 219
 220 .. versionadded:: 3.24
 221   The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be
 222   set to disable passing platform variables into the test project.