try_compile¶
Try building some code.
Try Compiling Whole Projects¶
try_compile(<compileResultVar> PROJECT <projectName>
SOURCE_DIR <srcdir>
[BINARY_DIR <bindir>]
[TARGET <targetName>]
[LOG_DESCRIPTION <text>]
[NO_CACHE]
[NO_LOG]
[CMAKE_FLAGS <flags>...]
[OUTPUT_VARIABLE <var>])
New in version 3.25.
Try building a project. Build success returns TRUE
and build failure
returns FALSE
in <compileResultVar>
.
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.
Changed in version 3.24: CMake variables describing platform settings, and those listed by the
CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
variable, are propagated
into the project's build configuration. See policy CMP0137
.
Previously this was only done by the
source file signature.
New in version 3.26: This command records a
configure-log try_compile event
if the NO_LOG
option is not specified.
New in version 3.30: If the PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE
global
property is set to true, CMAKE_PROJECT_TOP_LEVEL_INCLUDES
is
propagated into the project's build configuration.
This command supports an alternate signature for CMake older than 3.25. The signature above is recommended for clarity.
try_compile(<compileResultVar> <bindir> <srcdir>
<projectName> [<targetName>]
[CMAKE_FLAGS <flags>...]
[OUTPUT_VARIABLE <var>])
Try Compiling Source Files¶
try_compile(<compileResultVar>
[SOURCES_TYPE <type>]
<SOURCES <srcfile...> |
SOURCE_FROM_CONTENT <name> <content> |
SOURCE_FROM_VAR <name> <var> |
SOURCE_FROM_FILE <name> <path> >...
[LOG_DESCRIPTION <text>]
[NO_CACHE]
[NO_LOG]
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
[LINK_LIBRARIES <libs>...]
[LINKER_LANGUAGE <lang>]
[OUTPUT_VARIABLE <var>]
[COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
[<LANG>_STANDARD <std>]
[<LANG>_STANDARD_REQUIRED <bool>]
[<LANG>_EXTENSIONS <bool>]
)
New in version 3.25.
Try building an executable or static library from one or more source files
(which one is determined by the CMAKE_TRY_COMPILE_TARGET_TYPE
variable). Build success returns TRUE
and build failure returns FALSE
in <compileResultVar>
.
In this form, one or more source files must be provided. Additionally, one of
SOURCES
and/or SOURCE_FROM_*
must precede other keywords.
If 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 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:
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 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
--debug-trycompile
is passed to cmake.
Such directories from previous runs are also unconditionally cleaned at the
beginning of any cmake execution.
This command supports an alternate signature for CMake older than 3.25. The signature above is recommended for clarity.
try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...>
[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, --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.
Options¶
The options for the above signatures are:
CMAKE_FLAGS <flags>...
Specify flags of the form
-DVAR:TYPE=VALUE
to be passed to thecmake(1)
command-line used to drive the test build. The above example shows how values for variablesCOMPILE_DEFINITIONS
,INCLUDE_DIRECTORIES
,LINK_DIRECTORIES
,LINK_LIBRARIES
, andLINK_OPTIONS
are used. Compiler options can be passed in like CMAKE_FLAGS -DCOMPILE_DEFINITIONS=-Werror.COMPILE_DEFINITIONS <defs>...
Specify
-Ddefinition
arguments to pass toadd_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 Imported Targets from the calling project.
If this option is specified, any
-DLINK_LIBRARIES=...
value given to theCMAKE_FLAGS
option will be ignored.New in version 3.29: Alias targets to imported libraries are also supported.
LINK_OPTIONS <options>...
New in version 3.14.
Specify link step options to pass to
target_link_options()
or to set theSTATIC_LIBRARY_OPTIONS
target property in the generated project, depending on theCMAKE_TRY_COMPILE_TARGET_TYPE
variable.LINKER_LANGUAGE <lang>
New in version 3.29.
Specify the
LINKER_LANGUAGE
target property of the generated project. When using multiple source files with different languages, set this to the language of the source file containing the program entry point, e.g.,main
.LOG_DESCRIPTION <text>
New in version 3.26.
Specify a non-empty text description of the purpose of the check. This is recorded in the
cmake-configure-log(7)
entry.NO_CACHE
New in version 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:
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
New in version 3.26.
Do not record a
cmake-configure-log(7)
entry for this call.OUTPUT_VARIABLE <var>
Store the output from the build process in the given variable.
SOURCE_FROM_CONTENT <name> <content>
New in version 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>
New in version 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 bySOURCE_FROM_*
. (Otherwise,SOURCES
is usually more convenient.) The specified<name>
is not allowed to contain path components.SOURCE_FROM_VAR <name> <var>
New in version 3.25.
Write the contents of
<var>
to a file named<name>
in the operation directory. This is the same asSOURCE_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 wrapstry_compile
. The specified<name>
is not allowed to contain path components.SOURCE_FROM_VAR
may be specified multiple times.SOURCES_TYPE <type>
New in version 3.28.
Sources may be classified using the
SOURCES_TYPE
argument. Once specified, all subsequent sources specified will be treated as that type until anotherSOURCES_TYPE
is given. Available types are:NORMAL
Sources are not added to any
FILE_SET
in the generated project.CXX_MODULE
New in version 3.28.
Sources are added to a
FILE_SET
of typeCXX_MODULES
in the generated project.
The default type of sources is
NORMAL
.<LANG>_STANDARD <std>
New in version 3.8.
Specify the
C_STANDARD
,CXX_STANDARD
,OBJC_STANDARD
,OBJCXX_STANDARD
, orCUDA_STANDARD
target property of the generated project.<LANG>_STANDARD_REQUIRED <bool>
New in version 3.8.
Specify the
C_STANDARD_REQUIRED
,CXX_STANDARD_REQUIRED
,OBJC_STANDARD_REQUIRED
,OBJCXX_STANDARD_REQUIRED
,orCUDA_STANDARD_REQUIRED
target property of the generated project.<LANG>_EXTENSIONS <bool>
New in version 3.8.
Specify the
C_EXTENSIONS
,CXX_EXTENSIONS
,OBJC_EXTENSIONS
,OBJCXX_EXTENSIONS
, orCUDA_EXTENSIONS
target property of the generated project.
Other Behavior Settings¶
New in version 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:
If CMP0056
is set to NEW
, then
CMAKE_EXE_LINKER_FLAGS
is passed in as well.
Changed in version 3.14: If CMP0083
is set to NEW
, then in order to obtain correct
behavior at link time, the check_pie_supported()
command from the
CheckPIESupported
module must be called before using the
try_compile
command.
The current settings of CMP0065
and CMP0083
are propagated
through to the generated test project.
Set 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
CMAKE_BUILD_TYPE
in the test project.
New in version 3.6: Set the CMAKE_TRY_COMPILE_TARGET_TYPE
variable to specify
the type of target used for the source file signature.
New in version 3.6: Set the 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.
Changed in version 3.8: If 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:
Their values are used to set the corresponding target properties in the generated project (unless overridden by an explicit option).
Changed in version 3.14: For the Green Hills MULTI
generator, the GHS toolset and target
system customization cache variables are also propagated into the test
project.
New in version 3.24: The CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES
variable may be
set to disable passing platform variables into the test project.
New in version 3.25: If CMP0141
is set to NEW
, one can use
CMAKE_MSVC_DEBUG_INFORMATION_FORMAT
to specify the MSVC debug
information format.
New in version 3.30: If the PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE
global
property is set to true, CMAKE_PROJECT_TOP_LEVEL_INCLUDES
is
propagated into the test project's build configuration when using the
whole-project signature.