try_compile.rst 7.05 KB
Newer Older
1
2
3
try_compile
-----------

4
5
6
7
.. only:: html

   .. contents::

8
9
Try building some code.

10
11
12
Try Compiling Whole Projects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

13
.. code-block:: cmake
14

15
  try_compile(<resultVar> <bindir> <srcdir>
16
              <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
17
18
              [OUTPUT_VARIABLE <var>])

19
Try building a project.  The success or failure of the ``try_compile``,
20
i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.
21
22
23
24
25
26
27
28
29

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.

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

31
.. code-block:: cmake
32

33
  try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
34
35
              [CMAKE_FLAGS <flags>...]
              [COMPILE_DEFINITIONS <defs>...]
36
              [LINK_OPTIONS <options>...]
37
              [LINK_LIBRARIES <libs>...]
38
              [OUTPUT_VARIABLE <var>]
39
40
41
42
43
              [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
              [<LANG>_STANDARD <std>]
              [<LANG>_STANDARD_REQUIRED <bool>]
              [<LANG>_EXTENSIONS <bool>]
              )
44

45
46
47
48
49
50
51
52
53
54
55
56
57
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.  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:
58
59

.. code-block:: cmake
60

61
  add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
62
63
  include_directories(${INCLUDE_DIRECTORIES})
  link_directories(${LINK_DIRECTORIES})
64
  add_executable(cmTryCompileExec <srcfile>...)
65
  target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
66
67
  target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})

68
69
70
71
72
73
74
75
76
77
The options are:

``CMAKE_FLAGS <flags>...``
  Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to
  the ``cmake`` 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>...``
78
  Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions`
79
80
81
  in the generated test project.

``COPY_FILE <fileName>``
82
  Copy the built executable or static library to the given ``<fileName>``.
83
84
85
86
87
88
89
90
91
92
93
94
95

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

96
``LINK_OPTIONS <options>...``
97
98
99
  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.
100

101
``OUTPUT_VARIABLE <var>``
102
  Store the output from the build process in the given variable.
103

104
``<LANG>_STANDARD <std>``
105
106
  Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`,
  or :prop_tgt:`CUDA_STANDARD` target property of the generated project.
107
108

``<LANG>_STANDARD_REQUIRED <bool>``
109
110
111
  Specify the :prop_tgt:`C_STANDARD_REQUIRED`,
  :prop_tgt:`CXX_STANDARD_REQUIRED`, or :prop_tgt:`CUDA_STANDARD_REQUIRED`
  target property of the generated project.
112
113

``<LANG>_EXTENSIONS <bool>``
114
115
  Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_EXTENSIONS`,
  or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project.
116

117
118
119
120
121
122
In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be
cleaned automatically.  For debugging, ``--debug-trycompile`` can be
passed to ``cmake`` to avoid this clean.  However, multiple sequential
``try_compile`` operations reuse this single output directory.  If you use
``--debug-trycompile``, you can only debug one ``try_compile`` call at a time.
The recommended procedure is to protect all ``try_compile`` calls in your
123
project by ``if(NOT DEFINED <resultVar>)`` logic, configure with cmake
124
125
126
127
128
129
130
all the way through once, then delete the cache entry associated with
the try_compile call of interest, and then re-run cmake again with
``--debug-trycompile``.

Other Behavior Settings
^^^^^^^^^^^^^^^^^^^^^^^

131
132
133
134
If set, the following variables are passed in to the generated
try_compile CMakeLists.txt to initialize compile target properties with
default values:

135
* :variable:`CMAKE_ENABLE_EXPORTS`
136
137
* :variable:`CMAKE_LINK_SEARCH_START_STATIC`
* :variable:`CMAKE_LINK_SEARCH_END_STATIC`
138
139
140
141
* :variable:`CMAKE_POSITION_INDEPENDENT_CODE`

If :policy:`CMP0056` is set to ``NEW``, then
:variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well.
142

143
144
145
146
147
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.

148
149
The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated
through to the generated test project.
150

151
152
Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
a build configuration.
153
154
155

Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify
the type of target used for the source file signature.
156
157
158
159

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.
160
161
162
163
164
165
166
167
168
169
170

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`
171
172
173
* :variable:`CMAKE_CUDA_STANDARD`
* :variable:`CMAKE_CUDA_STANDARD_REQUIRED`
* :variable:`CMAKE_CUDA_EXTENSIONS`
174
175
176

Their values are used to set the corresponding target properties in
the generated project (unless overridden by an explicit option).
177
178
179

For the :generator:`Green Hills MULTI` generator the GHS toolset and target
system customization cache variables are also propagated into the test project.