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 ]
[LOG_DESCRIPTION ]
[NO_CACHE]
[NO_LOG]
[CMAKE_FLAGS ...]
[OUTPUT_VARIABLE ])
.. versionadded:: 3.25
Try building a project. Build success returns ``TRUE`` and build failure
returns ``FALSE`` 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.
.. versionadded:: 3.26
This command records a
:ref:`configure-log try_compile event `
if the ``NO_LOG`` option is not specified.
This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.
.. code-block:: cmake
try_compile(
[]
[CMAKE_FLAGS ...]
[OUTPUT_VARIABLE ])
.. _`Try Compiling Source Files`:
Try Compiling Source Files
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
try_compile(
[SOURCES_TYPE ]
|
SOURCE_FROM_CONTENT |
SOURCE_FROM_VAR |
SOURCE_FROM_FILE >...
[LOG_DESCRIPTION ]
[NO_CACHE]
[NO_LOG]
[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). Build success returns ``TRUE`` and build failure returns ``FALSE``
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 :program:`cmake`.
Such directories from previous runs are also unconditionally cleaned at the
beginning of any :program:`cmake` execution.
This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.
.. code-block:: cmake
try_compile(
[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 :program:`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.
.. _`try_compile Options`:
Options
^^^^^^^
The options for the above signatures 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.
``LOG_DESCRIPTION ``
.. versionadded:: 3.26
Specify a non-empty text description of the purpose of the check.
This is recorded in the :manual:`cmake-configure-log(7)` entry.
``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.
``NO_LOG``
.. versionadded:: 3.26
Do not record a :manual:`cmake-configure-log(7)` entry for this call.
``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.
``SOURCES_TYPE ``
.. versionadded:: 3.28
Sources may be classified using the ``SOURCES_TYPE`` argument. Once
specified, all subsequent sources specified will be treated as that type
until another ``SOURCES_TYPE`` is given. Available types are:
``NORMAL``
Sources are not added to any ``FILE_SET`` in the generated project.
``CXX_MODULE``
.. versionadded:: 3.28
Sources are added to a ``FILE_SET`` of type ``CXX_MODULES`` in the
generated project.
The default type of sources is ``NORMAL``.
``_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
``try_compile`` command.
The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated
through to the generated test project.
Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build
configuration:
* For multi-config generators, this selects which configuration to build.
* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in
the test project.
.. 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.
See Also
^^^^^^^^
* :command:`try_run`