try_compile ----------- .. only:: html .. contents:: Try building some code. .. _`Try Compiling Whole Projects`: Try Compiling Whole Projects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: cmake try_compile( PROJECT SOURCE_DIR [BINARY_DIR ] [TARGET ] [NO_CACHE] [CMAKE_FLAGS ...] [OUTPUT_VARIABLE ]) .. versionadded:: 3.25 Try building a project. The success or failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ````. In this form, ```` should contain a complete CMake project with a ``CMakeLists.txt`` file and all sources. The ```` and ```` will not be deleted after this command is run. Specify ```` to build a specific target instead of the ``all`` or ``ALL_BUILD`` target. See below for the meaning of other options. .. versionchanged:: 3.24 CMake variables describing platform settings, and those listed by the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable, are propagated into the project's build configuration. See policy :policy:`CMP0137`. Previously this was only done by the :ref:`source file ` signature. This command also supports an alternate signature which was present in older versions of CMake: .. code-block:: cmake try_compile( [] [NO_CACHE] [CMAKE_FLAGS ...] [OUTPUT_VARIABLE ]) .. _`Try Compiling Source Files`: Try Compiling Source Files ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: cmake try_compile( | SOURCE_FROM_CONTENT | SOURCE_FROM_VAR | SOURCE_FROM_FILE >... [NO_CACHE] [CMAKE_FLAGS ...] [COMPILE_DEFINITIONS ...] [LINK_OPTIONS ...] [LINK_LIBRARIES ...] [OUTPUT_VARIABLE ] [COPY_FILE [COPY_FILE_ERROR ]] [_STANDARD ] [_STANDARD_REQUIRED ] [_EXTENSIONS ] ) .. versionadded:: 3.25 Try building an executable or static library from one or more source files (which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable). The success or failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ````. In this form, one or more source files must be provided. Additionally, one of ``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords. If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``, the sources must include a definition for ``main`` and CMake will create a ``CMakeLists.txt`` file to build the source(s) as an executable. If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``, a static library will be built instead and no definition for ``main`` is required. For an executable, the generated ``CMakeLists.txt`` file would contain something like the following: .. code-block:: cmake add_definitions() include_directories(${INCLUDE_DIRECTORIES}) link_directories(${LINK_DIRECTORIES}) add_executable(cmTryCompileExec ...) target_link_options(cmTryCompileExec PRIVATE ) target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES}) CMake automatically generates, for each ``try_compile`` operation, a unique directory under ``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch`` with an unspecified name. These directories are cleaned automatically unless :option:`--debug-trycompile ` is passed to ``cmake``. Such directories from previous runs are also unconditionally cleaned at the beginning of any ``cmake`` execution. This command also supports an alternate signature which was present in older versions of CMake: .. code-block:: cmake try_compile( [NO_CACHE] [CMAKE_FLAGS ...] [COMPILE_DEFINITIONS ...] [LINK_OPTIONS ...] [LINK_LIBRARIES ...] [OUTPUT_VARIABLE ] [COPY_FILE [COPY_FILE_ERROR ]] [_STANDARD ] [_STANDARD_REQUIRED ] [_EXTENSIONS ] ) In this version, ``try_compile`` will use ``/CMakeFiles/CMakeTmp`` for its operation, and all such files will be cleaned automatically. For debugging, :option:`--debug-trycompile ` can be passed to ``cmake`` to avoid this clean. However, multiple sequential ``try_compile`` operations, if given the same ````, will reuse this single output directory, such that you can only debug one such ``try_compile`` call at a time. Use of the newer signature is recommended to simplify debugging of multiple ``try_compile`` operations. The options are: ``CMAKE_FLAGS ...`` Specify flags of the form :option:`-DVAR:TYPE=VALUE ` to be passed to the :manual:`cmake(1)` command-line used to drive the test build. The above example shows how values for variables ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES`` are used. ``COMPILE_DEFINITIONS ...`` Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions` in the generated test project. ``COPY_FILE `` Copy the built executable or static library to the given ````. ``COPY_FILE_ERROR `` Use after ``COPY_FILE`` to capture into variable ```` any error message encountered while trying to copy the file. ``LINK_LIBRARIES ...`` Specify libraries to be linked in the generated project. The list of libraries may refer to system libraries and to :ref:`Imported Targets ` from the calling project. If this option is specified, any ``-DLINK_LIBRARIES=...`` value given to the ``CMAKE_FLAGS`` option will be ignored. ``LINK_OPTIONS ...`` .. versionadded:: 3.14 Specify link step options to pass to :command:`target_link_options` or to set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. ``NO_CACHE`` .. versionadded:: 3.25 The result will be stored in a normal variable rather than a cache entry. The result variable is normally cached so that a simple pattern can be used to avoid repeating the test on subsequent executions of CMake: .. code-block:: cmake if(NOT DEFINED RESULTVAR) # ...(check-specific setup code)... try_compile(RESULTVAR ...) # ...(check-specific logging and cleanup code)... endif() If the guard variable and result variable are not the same (for example, if the test is part of a larger inspection), ``NO_CACHE`` may be useful to avoid leaking the intermediate result variable into the cache. ``OUTPUT_VARIABLE `` Store the output from the build process in the given variable. ``SOURCE_FROM_CONTENT `` .. versionadded:: 3.25 Write ```` to a file named ```` in the operation directory. This can be used to bypass the need to separately write a source file when the contents of the file are dynamically specified. The specified ```` is not allowed to contain path components. ``SOURCE_FROM_CONTENT`` may be specified multiple times. ``SOURCE_FROM_FILE `` .. versionadded:: 3.25 Copy ```` to a file named ```` in the operation directory. This can be used to consolidate files into the operation directory, which may be useful if a source which already exists (i.e. as a stand-alone file in a project's source repository) needs to refer to other file(s) created by ``SOURCE_FROM_*``. (Otherwise, ``SOURCES`` is usually more convenient.) The specified ```` is not allowed to contain path components. ``SOURCE_FROM_VAR `` .. versionadded:: 3.25 Write the contents of ```` to a file named ```` in the operation directory. This is the same as ``SOURCE_FROM_CONTENT``, but takes the contents from the specified CMake variable, rather than directly, which may be useful when passing arguments through a function which wraps ``try_compile``. The specified ```` is not allowed to contain path components. ``SOURCE_FROM_VAR`` may be specified multiple times. ``_STANDARD `` .. versionadded:: 3.8 Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`, :prop_tgt:`OBJC_STANDARD`, :prop_tgt:`OBJCXX_STANDARD`, or :prop_tgt:`CUDA_STANDARD` target property of the generated project. ``_STANDARD_REQUIRED `` .. versionadded:: 3.8 Specify the :prop_tgt:`C_STANDARD_REQUIRED`, :prop_tgt:`CXX_STANDARD_REQUIRED`, :prop_tgt:`OBJC_STANDARD_REQUIRED`, :prop_tgt:`OBJCXX_STANDARD_REQUIRED`,or :prop_tgt:`CUDA_STANDARD_REQUIRED` target property of the generated project. ``_EXTENSIONS `` .. versionadded:: 3.8 Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_EXTENSIONS`, :prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`, or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project. Other Behavior Settings ^^^^^^^^^^^^^^^^^^^^^^^ .. versionadded:: 3.4 If set, the following variables are passed in to the generated try_compile CMakeLists.txt to initialize compile target properties with default values: * :variable:`CMAKE_CUDA_RUNTIME_LIBRARY` * :variable:`CMAKE_ENABLE_EXPORTS` * :variable:`CMAKE_LINK_SEARCH_START_STATIC` * :variable:`CMAKE_LINK_SEARCH_END_STATIC` * :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` * :variable:`CMAKE_POSITION_INDEPENDENT_CODE` * :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` If :policy:`CMP0056` is set to ``NEW``, then :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well. .. versionchanged:: 3.14 If :policy:`CMP0083` is set to ``NEW``, then in order to obtain correct behavior at link time, the ``check_pie_supported()`` command from the :module:`CheckPIESupported` module must be called before using the :command:`try_compile` command. The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated through to the generated test project. Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose a build configuration. .. versionadded:: 3.6 Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify the type of target used for the source file signature. .. versionadded:: 3.6 Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify variables that must be propagated into the test project. This variable is meant for use only in toolchain files and is only honored by the ``try_compile()`` command for the source files form, not when given a whole project. .. versionchanged:: 3.8 If :policy:`CMP0067` is set to ``NEW``, or any of the ``_STANDARD``, ``_STANDARD_REQUIRED``, or ``_EXTENSIONS`` options are used, then the language standard variables are honored: * :variable:`CMAKE_C_STANDARD` * :variable:`CMAKE_C_STANDARD_REQUIRED` * :variable:`CMAKE_C_EXTENSIONS` * :variable:`CMAKE_CXX_STANDARD` * :variable:`CMAKE_CXX_STANDARD_REQUIRED` * :variable:`CMAKE_CXX_EXTENSIONS` * :variable:`CMAKE_OBJC_STANDARD` * :variable:`CMAKE_OBJC_STANDARD_REQUIRED` * :variable:`CMAKE_OBJC_EXTENSIONS` * :variable:`CMAKE_OBJCXX_STANDARD` * :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` * :variable:`CMAKE_OBJCXX_EXTENSIONS` * :variable:`CMAKE_CUDA_STANDARD` * :variable:`CMAKE_CUDA_STANDARD_REQUIRED` * :variable:`CMAKE_CUDA_EXTENSIONS` Their values are used to set the corresponding target properties in the generated project (unless overridden by an explicit option). .. versionchanged:: 3.14 For the :generator:`Green Hills MULTI` generator, the GHS toolset and target system customization cache variables are also propagated into the test project. .. versionadded:: 3.24 The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be set to disable passing platform variables into the test project. .. versionadded:: 3.25 If :policy:`CMP0141` is set to ``NEW``, one can use :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify the MSVC debug information format.