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