path: root/Help/command/try_compile.rst

try_compile
-----------

.. only:: html

   .. contents::

Try building some code.

.. _`Try Compiling Whole Projects`:

Try Compiling Whole Projects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  try_compile(<resultVar> PROJECT <projectName>
              SOURCE_DIR <srcdir>
              [BINARY_DIR <bindir>]
              [TARGET <targetName>]
              [NO_CACHE]
              [CMAKE_FLAGS <flags>...]
              [OUTPUT_VARIABLE <var>])

.. versionadded:: 3.25

Try building a project.  The success or failure of the ``try_compile``,
i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.

In this form, ``<srcdir>`` should contain a complete CMake project with a
``CMakeLists.txt`` file and all sources.  The ``<bindir>`` and ``<srcdir>``
will not be deleted after this command is run.  Specify ``<targetName>`` 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 <Try Compiling Source Files>` signature.

This command also supports an alternate signature
which was present in older versions of CMake:

.. code-block:: cmake

  try_compile(<resultVar> <bindir> <srcdir>
              <projectName> [<targetName>]
              [NO_CACHE]
              [CMAKE_FLAGS <flags>...]
              [OUTPUT_VARIABLE <var>])

.. _`Try Compiling Source Files`:

Try Compiling Source Files
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  try_compile(<resultVar>
              <SOURCES <srcfile...>]                 |
               SOURCE_FROM_CONTENT <name> <content>] |
               SOURCE_FROM_VAR <name> <var>]         |
               SOURCE_FROM_FILE <name> <path>        >...
              [NO_CACHE]
              [CMAKE_FLAGS <flags>...]
              [COMPILE_DEFINITIONS <defs>...]
              [LINK_OPTIONS <options>...]
              [LINK_LIBRARIES <libs>...]
              [OUTPUT_VARIABLE <var>]
              [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
              [<LANG>_STANDARD <std>]
              [<LANG>_STANDARD_REQUIRED <bool>]
              [<LANG>_EXTENSIONS <bool>]
              )

.. 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 ``<resultVar>``.

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(<expanded COMPILE_DEFINITIONS from caller>)
  include_directories(${INCLUDE_DIRECTORIES})
  link_directories(${LINK_DIRECTORIES})
  add_executable(cmTryCompileExec <srcfile>...)
  target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
  target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})

CMake will automatically generate a unique directory for each ``try_compile``
operation in an unspecified location within the project's binary directory.
These directories will be cleaned automatically unless
:option:`--debug-trycompile <cmake --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(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
              [NO_CACHE]
              [CMAKE_FLAGS <flags>...]
              [COMPILE_DEFINITIONS <defs>...]
              [LINK_OPTIONS <options>...]
              [LINK_LIBRARIES <libs>...]
              [OUTPUT_VARIABLE <var>]
              [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
              [<LANG>_STANDARD <std>]
              [<LANG>_STANDARD_REQUIRED <bool>]
              [<LANG>_EXTENSIONS <bool>]
              )

In this version, ``try_compile`` will use ``<bindir>/CMakeFiles/CMakeTmp`` for
its operation, and all such files will be cleaned automatically.
For debugging, :option:`--debug-trycompile <cmake --debug-trycompile>` can be
passed to ``cmake`` to avoid this clean.  However, multiple sequential
``try_compile`` operations, if given the same ``<bindir>``, 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 <flags>...``
  Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` 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 <defs>...``
  Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions`
  in the generated test project.

``COPY_FILE <fileName>``
  Copy the built executable or static library to the given ``<fileName>``.

``COPY_FILE_ERROR <var>``
  Use after ``COPY_FILE`` to capture into variable ``<var>`` any error
  message encountered while trying to copy the file.

``LINK_LIBRARIES <libs>...``
  Specify libraries to be linked in the generated project.
  The list of libraries may refer to system libraries and to
  :ref:`Imported Targets <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 <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 <var>``
  Store the output from the build process in the given variable.

``SOURCE_FROM_CONTENT <name> <content>``
  .. versionadded:: 3.25

  Write ``<content>`` to a file named ``<name>`` 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 ``<name>``
  is not allowed to contain path components.

  ``SOURCE_FROM_CONTENT`` may be specified multiple times.

``SOURCE_FROM_FILE <name> <path>``
  .. versionadded:: 3.25

  Copy ``<path>`` to a file named ``<name>`` 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 ``<name>`` is not allowed to contain path components.

``SOURCE_FROM_VAR <name> <var>``
  .. versionadded:: 3.25

  Write the contents of ``<var>`` to a file named ``<name>`` 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 ``<name>`` is not allowed to contain path
  components.

  ``SOURCE_FROM_VAR`` may be specified multiple times.

``<LANG>_STANDARD <std>``
  .. 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.

``<LANG>_STANDARD_REQUIRED <bool>``
  .. 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.

``<LANG>_EXTENSIONS <bool>``
  .. 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 ``<LANG>_STANDARD``,
  ``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_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 MSVC debug
  information format.