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> PROJECT <projectName>
  18               SOURCE_DIR <srcdir>
  19               [BINARY_DIR <bindir>]
  20               [TARGET <targetName>]
  21               [NO_CACHE]
  22               [CMAKE_FLAGS <flags>...]
  23               [OUTPUT_VARIABLE <var>])
  24
  25 .. versionadded:: 3.25
  26
  27 Try building a project.  The success or failure of the ``try_compile``,
  28 i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.
  29
  30 In this form, ``<srcdir>`` should contain a complete CMake project with a
  31 ``CMakeLists.txt`` file and all sources.  The ``<bindir>`` and ``<srcdir>``
  32 will not be deleted after this command is run.  Specify ``<targetName>`` to
  33 build a specific target instead of the ``all`` or ``ALL_BUILD`` target.  See
  34 below for the meaning of other options.
  35
  36 .. versionchanged:: 3.24
  37   CMake variables describing platform settings, and those listed by the
  38   :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable, are propagated
  39   into the project's build configuration.  See policy :policy:`CMP0137`.
  40   Previously this was only done by the
  41   :ref:`source file <Try Compiling Source Files>` signature.
  42
  43 This command also supports an alternate signature
  44 which was present in older versions of CMake:
  45
  46 .. code-block:: cmake
  47
  48   try_compile(<resultVar> <bindir> <srcdir>
  49               <projectName> [<targetName>]
  50               [NO_CACHE]
  51               [CMAKE_FLAGS <flags>...]
  52               [OUTPUT_VARIABLE <var>])
  53
  54 .. _`Try Compiling Source Files`:
  55
  56 Try Compiling Source Files
  57 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  58
  59 .. code-block:: cmake
  60
  61   try_compile(<resultVar>
  62               <SOURCES <srcfile...>                 |
  63                SOURCE_FROM_CONTENT <name> <content> |
  64                SOURCE_FROM_VAR <name> <var>         |
  65                SOURCE_FROM_FILE <name> <path>       >...
  66               [NO_CACHE]
  67               [CMAKE_FLAGS <flags>...]
  68               [COMPILE_DEFINITIONS <defs>...]
  69               [LINK_OPTIONS <options>...]
  70               [LINK_LIBRARIES <libs>...]
  71               [OUTPUT_VARIABLE <var>]
  72               [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
  73               [<LANG>_STANDARD <std>]
  74               [<LANG>_STANDARD_REQUIRED <bool>]
  75               [<LANG>_EXTENSIONS <bool>]
  76               )
  77
  78 .. versionadded:: 3.25
  79
  80 Try building an executable or static library from one or more source files
  81 (which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE`
  82 variable).  The success or failure of the ``try_compile``, i.e. ``TRUE`` or
  83 ``FALSE`` respectively, is returned in ``<resultVar>``.
  84
  85 In this form, one or more source files must be provided. Additionally, one of
  86 ``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords.
  87
  88 If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to
  89 ``EXECUTABLE``, the sources must include a definition for ``main`` and CMake
  90 will create a ``CMakeLists.txt`` file to build the source(s) as an executable.
  91 If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``,
  92 a static library will be built instead and no definition for ``main`` is
  93 required.  For an executable, the generated ``CMakeLists.txt`` file would
  94 contain something like the following:
  95
  96 .. code-block:: cmake
  97
  98   add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
  99   include_directories(${INCLUDE_DIRECTORIES})
 100   link_directories(${LINK_DIRECTORIES})
 101   add_executable(cmTryCompileExec <srcfile>...)
 102   target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
 103   target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
 104
 105 CMake automatically generates, for each ``try_compile`` operation, a
 106 unique directory under ``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch``
 107 with an unspecified name.  These directories are cleaned automatically unless
 108 :option:`--debug-trycompile <cmake --debug-trycompile>` is passed to ``cmake``.
 109 Such directories from previous runs are also unconditionally cleaned at the
 110 beginning of any ``cmake`` execution.
 111
 112 This command also supports an alternate signature
 113 which was present in older versions of CMake:
 114
 115 .. code-block:: cmake
 116
 117   try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
 118               [NO_CACHE]
 119               [CMAKE_FLAGS <flags>...]
 120               [COMPILE_DEFINITIONS <defs>...]
 121               [LINK_OPTIONS <options>...]
 122               [LINK_LIBRARIES <libs>...]
 123               [OUTPUT_VARIABLE <var>]
 124               [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
 125               [<LANG>_STANDARD <std>]
 126               [<LANG>_STANDARD_REQUIRED <bool>]
 127               [<LANG>_EXTENSIONS <bool>]
 128               )
 129
 130 In this version, ``try_compile`` will use ``<bindir>/CMakeFiles/CMakeTmp`` for
 131 its operation, and all such files will be cleaned automatically.
 132 For debugging, :option:`--debug-trycompile <cmake --debug-trycompile>` can be
 133 passed to ``cmake`` to avoid this clean.  However, multiple sequential
 134 ``try_compile`` operations, if given the same ``<bindir>``, will reuse this
 135 single output directory, such that you can only debug one such ``try_compile``
 136 call at a time.  Use of the newer signature is recommended to simplify
 137 debugging of multiple ``try_compile`` operations.
 138
 139 The options are:
 140
 141 ``CMAKE_FLAGS <flags>...``
 142   Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed
 143   to the :manual:`cmake(1)` command-line used to drive the test build.
 144   The above example shows how values for variables
 145   ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
 146   are used.
 147
 148 ``COMPILE_DEFINITIONS <defs>...``
 149   Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions`
 150   in the generated test project.
 151
 152 ``COPY_FILE <fileName>``
 153   Copy the built executable or static library to the given ``<fileName>``.
 154
 155 ``COPY_FILE_ERROR <var>``
 156   Use after ``COPY_FILE`` to capture into variable ``<var>`` any error
 157   message encountered while trying to copy the file.
 158
 159 ``LINK_LIBRARIES <libs>...``
 160   Specify libraries to be linked in the generated project.
 161   The list of libraries may refer to system libraries and to
 162   :ref:`Imported Targets <Imported Targets>` from the calling project.
 163
 164   If this option is specified, any ``-DLINK_LIBRARIES=...`` value
 165   given to the ``CMAKE_FLAGS`` option will be ignored.
 166
 167 ``LINK_OPTIONS <options>...``
 168   .. versionadded:: 3.14
 169
 170   Specify link step options to pass to :command:`target_link_options` or to
 171   set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
 172   project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.
 173
 174 ``NO_CACHE``
 175   .. versionadded:: 3.25
 176
 177   The result will be stored in a normal variable rather than a cache entry.
 178
 179   The result variable is normally cached so that a simple pattern can be used
 180   to avoid repeating the test on subsequent executions of CMake:
 181
 182   .. code-block:: cmake
 183
 184     if(NOT DEFINED RESULTVAR)
 185       # ...(check-specific setup code)...
 186       try_compile(RESULTVAR ...)
 187       # ...(check-specific logging and cleanup code)...
 188     endif()
 189
 190   If the guard variable and result variable are not the same (for example, if
 191   the test is part of a larger inspection), ``NO_CACHE`` may be useful to avoid
 192   leaking the intermediate result variable into the cache.
 193
 194 ``OUTPUT_VARIABLE <var>``
 195   Store the output from the build process in the given variable.
 196
 197 ``SOURCE_FROM_CONTENT <name> <content>``
 198   .. versionadded:: 3.25
 199
 200   Write ``<content>`` to a file named ``<name>`` in the operation directory.
 201   This can be used to bypass the need to separately write a source file when
 202   the contents of the file are dynamically specified. The specified ``<name>``
 203   is not allowed to contain path components.
 204
 205   ``SOURCE_FROM_CONTENT`` may be specified multiple times.
 206
 207 ``SOURCE_FROM_FILE <name> <path>``
 208   .. versionadded:: 3.25
 209
 210   Copy ``<path>`` to a file named ``<name>`` in the operation directory. This
 211   can be used to consolidate files into the operation directory, which may be
 212   useful if a source which already exists (i.e. as a stand-alone file in a
 213   project's source repository) needs to refer to other file(s) created by
 214   ``SOURCE_FROM_*``. (Otherwise, ``SOURCES`` is usually more convenient.) The
 215   specified ``<name>`` is not allowed to contain path components.
 216
 217 ``SOURCE_FROM_VAR <name> <var>``
 218   .. versionadded:: 3.25
 219
 220   Write the contents of ``<var>`` to a file named ``<name>`` in the operation
 221   directory. This is the same as ``SOURCE_FROM_CONTENT``, but takes the
 222   contents from the specified CMake variable, rather than directly, which may
 223   be useful when passing arguments through a function which wraps
 224   ``try_compile``. The specified ``<name>`` is not allowed to contain path
 225   components.
 226
 227   ``SOURCE_FROM_VAR`` may be specified multiple times.
 228
 229 ``<LANG>_STANDARD <std>``
 230   .. versionadded:: 3.8
 231
 232   Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`,
 233   :prop_tgt:`OBJC_STANDARD`, :prop_tgt:`OBJCXX_STANDARD`,
 234   or :prop_tgt:`CUDA_STANDARD` target property of the generated project.
 235
 236 ``<LANG>_STANDARD_REQUIRED <bool>``
 237   .. versionadded:: 3.8
 238
 239   Specify the :prop_tgt:`C_STANDARD_REQUIRED`,
 240   :prop_tgt:`CXX_STANDARD_REQUIRED`, :prop_tgt:`OBJC_STANDARD_REQUIRED`,
 241   :prop_tgt:`OBJCXX_STANDARD_REQUIRED`,or :prop_tgt:`CUDA_STANDARD_REQUIRED`
 242   target property of the generated project.
 243
 244 ``<LANG>_EXTENSIONS <bool>``
 245   .. versionadded:: 3.8
 246
 247   Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_EXTENSIONS`,
 248   :prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`,
 249   or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project.
 250
 251 Other Behavior Settings
 252 ^^^^^^^^^^^^^^^^^^^^^^^
 253
 254 .. versionadded:: 3.4
 255   If set, the following variables are passed in to the generated
 256   try_compile CMakeLists.txt to initialize compile target properties with
 257   default values:
 258
 259   * :variable:`CMAKE_CUDA_RUNTIME_LIBRARY`
 260   * :variable:`CMAKE_ENABLE_EXPORTS`
 261   * :variable:`CMAKE_LINK_SEARCH_START_STATIC`
 262   * :variable:`CMAKE_LINK_SEARCH_END_STATIC`
 263   * :variable:`CMAKE_MSVC_RUNTIME_LIBRARY`
 264   * :variable:`CMAKE_POSITION_INDEPENDENT_CODE`
 265   * :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY`
 266
 267   If :policy:`CMP0056` is set to ``NEW``, then
 268   :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well.
 269
 270 .. versionchanged:: 3.14
 271   If :policy:`CMP0083` is set to ``NEW``, then in order to obtain correct
 272   behavior at link time, the ``check_pie_supported()`` command from the
 273   :module:`CheckPIESupported` module must be called before using the
 274   :command:`try_compile` command.
 275
 276 The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated
 277 through to the generated test project.
 278
 279 Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
 280 a build configuration.
 281
 282 .. versionadded:: 3.6
 283   Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify
 284   the type of target used for the source file signature.
 285
 286 .. versionadded:: 3.6
 287   Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify
 288   variables that must be propagated into the test project.  This variable is
 289   meant for use only in toolchain files and is only honored by the
 290   ``try_compile()`` command for the source files form, not when given a whole
 291   project.
 292
 293 .. versionchanged:: 3.8
 294   If :policy:`CMP0067` is set to ``NEW``, or any of the ``<LANG>_STANDARD``,
 295   ``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_EXTENSIONS`` options are used,
 296   then the language standard variables are honored:
 297
 298   * :variable:`CMAKE_C_STANDARD`
 299   * :variable:`CMAKE_C_STANDARD_REQUIRED`
 300   * :variable:`CMAKE_C_EXTENSIONS`
 301   * :variable:`CMAKE_CXX_STANDARD`
 302   * :variable:`CMAKE_CXX_STANDARD_REQUIRED`
 303   * :variable:`CMAKE_CXX_EXTENSIONS`
 304   * :variable:`CMAKE_OBJC_STANDARD`
 305   * :variable:`CMAKE_OBJC_STANDARD_REQUIRED`
 306   * :variable:`CMAKE_OBJC_EXTENSIONS`
 307   * :variable:`CMAKE_OBJCXX_STANDARD`
 308   * :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED`
 309   * :variable:`CMAKE_OBJCXX_EXTENSIONS`
 310   * :variable:`CMAKE_CUDA_STANDARD`
 311   * :variable:`CMAKE_CUDA_STANDARD_REQUIRED`
 312   * :variable:`CMAKE_CUDA_EXTENSIONS`
 313
 314   Their values are used to set the corresponding target properties in
 315   the generated project (unless overridden by an explicit option).
 316
 317 .. versionchanged:: 3.14
 318   For the :generator:`Green Hills MULTI` generator, the GHS toolset and target
 319   system customization cache variables are also propagated into the test
 320   project.
 321
 322 .. versionadded:: 3.24
 323   The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be
 324   set to disable passing platform variables into the test project.
 325
 326 .. versionadded:: 3.25
 327   If :policy:`CMP0141` is set to ``NEW``, one can use
 328   :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify the MSVC debug
 329   information format.