1CMAKE-TOOLCHAINS(7)                  CMake                 CMAKE-TOOLCHAINS(7)
2
3
4

NAME

6       cmake-toolchains - CMake Toolchains Reference
7

INTRODUCTION

9       CMake uses a toolchain of utilities to compile, link libraries and cre‐
10       ate archives, and other tasks to drive the build. The toolchain  utili‐
11       ties  available  are  determined  by  the  languages enabled. In normal
12       builds, CMake automatically determines the toolchain  for  host  builds
13       based  on system introspection and defaults. In cross-compiling scenar‐
14       ios, a toolchain file may be specified with information about  compiler
15       and utility paths.
16

LANGUAGES

18       Languages  are  enabled  by  the  project() command.  Language-specific
19       built-in variables, such as  CMAKE_CXX_COMPILER,  CMAKE_CXX_COMPILER_ID
20       etc  are  set by invoking the project() command.  If no project command
21       is in the top-level CMakeLists file, one will be implicitly  generated.
22       By default the enabled languages are C and CXX:
23
24          project(C_Only C)
25
26       A  special value of NONE can also be used with the project() command to
27       enable no languages:
28
29          project(MyProject NONE)
30
31       The enable_language() command can be used to enable languages after the
32       project() command:
33
34          enable_language(CXX)
35
36       When  a  language is enabled, CMake finds a compiler for that language,
37       and determines some information, such as the vendor and version of  the
38       compiler,  the target architecture and bitwidth, the location of corre‐
39       sponding utilities etc.
40
41       The ENABLED_LANGUAGES global property contains the languages which  are
42       currently enabled.
43

VARIABLES AND PROPERTIES

45       Several  variables  relate  to  the  language components of a toolchain
46       which are enabled. CMAKE_<LANG>_COMPILER is the full path to  the  com‐
47       piler  used for <LANG>. CMAKE_<LANG>_COMPILER_ID is the identifier used
48       by CMake for the compiler and CMAKE_<LANG>_COMPILER_VERSION is the ver‐
49       sion of the compiler.
50
51       The CMAKE_<LANG>_FLAGS variables and the configuration-specific equiva‐
52       lents contain flags that will be added to the compile command when com‐
53       piling a file of a particular language.
54
55       As  the  linker is invoked by the compiler driver, CMake needs a way to
56       determine which compiler to use to invoke the linker.  This  is  calcu‐
57       lated by the LANGUAGE of source files in the target, and in the case of
58       static libraries, the language of the dependent libraries.  The  choice
59       CMake makes may be overridden with the LINKER_LANGUAGE target property.
60

TOOLCHAIN FEATURES

62       CMake  provides  the  try_compile()  command and wrapper macros such as
63       CheckCXXSourceCompiles, CheckCXXSymbolExists  and  CheckIncludeFile  to
64       test  capability  and availability of various toolchain features. These
65       APIs test the toolchain in some way and cache the result  so  that  the
66       test does not have to be performed again the next time CMake runs.
67
68       Some  toolchain  features  have  built-in handling in CMake, and do not
69       require compile-tests. For  example,  POSITION_INDEPENDENT_CODE  allows
70       specifying  that a target should be built as position-independent code,
71       if the compiler supports that feature. The <LANG>_VISIBILITY_PRESET and
72       VISIBILITY_INLINES_HIDDEN  target properties add flags for hidden visi‐
73       bility, if supported by the compiler.
74

CROSS COMPILING

76       If   cmake(1)   is   invoked   with   the   command   line    parameter
77       -DCMAKE_TOOLCHAIN_FILE=path/to/file,  the  file will be loaded early to
78       set values for the compilers.  The CMAKE_CROSSCOMPILING variable is set
79       to true when CMake is cross-compiling.
80
81   Cross Compiling for Linux
82       A typical cross-compiling toolchain for Linux has content such as:
83
84          set(CMAKE_SYSTEM_NAME Linux)
85          set(CMAKE_SYSTEM_PROCESSOR arm)
86
87          set(CMAKE_SYSROOT /home/devel/rasp-pi-rootfs)
88          set(CMAKE_STAGING_PREFIX /home/devel/stage)
89
90          set(tools /home/devel/gcc-4.7-linaro-rpi-gnueabihf)
91          set(CMAKE_C_COMPILER ${tools}/bin/arm-linux-gnueabihf-gcc)
92          set(CMAKE_CXX_COMPILER ${tools}/bin/arm-linux-gnueabihf-g++)
93
94          set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
95          set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
96          set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
97          set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
98
99       The CMAKE_SYSTEM_NAME is the CMake-identifier of the target platform to
100       build for.
101
102       The CMAKE_SYSTEM_PROCESSOR is the CMake-identifier of the target archi‐
103       tecture to build for.
104
105       The  CMAKE_SYSROOT  is  optional,  and may be specified if a sysroot is
106       available.
107
108       The CMAKE_STAGING_PREFIX is also optional. It may be used to specify  a
109       path  on the host to install to. The CMAKE_INSTALL_PREFIX is always the
110       runtime installation location, even when cross-compiling.
111
112       The CMAKE_<LANG>_COMPILER variables may be set to  full  paths,  or  to
113       names   of  compilers  to  search  for  in  standard  locations.    For
114       toolchains that do not support linking binaries without custom flags or
115       scripts  one  may  set  the  CMAKE_TRY_COMPILE_TARGET_TYPE  variable to
116       STATIC_LIBRARY to tell CMake not to try to link executables during  its
117       checks.
118
119       CMake   find_*   commands   will   look   in   the   sysroot,  and  the
120       CMAKE_FIND_ROOT_PATH entries by default in all cases, as well as  look‐
121       ing in the host system root prefix.  Although this can be controlled on
122       a case-by-case basis, when cross-compiling, it can be useful to exclude
123       looking in either the host or the target for particular artifacts. Gen‐
124       erally, includes, libraries and packages should be found in the  target
125       system  prefixes,  whereas executables which must be run as part of the
126       build should be found only on the host and not on the target.  This  is
127       the purpose of the CMAKE_FIND_ROOT_PATH_MODE_* variables.
128
129   Cross Compiling for the Cray Linux Environment
130       Cross  compiling for compute nodes in the Cray Linux Environment can be
131       done  without  needing   a   separate   toolchain   file.    Specifying
132       -DCMAKE_SYSTEM_NAME=CrayLinuxEnvironment on the CMake command line will
133       ensure that the appropriate build settings and search paths are config‐
134       ured.   The platform will pull its configuration from the current envi‐
135       ronment variables and will configure a  project  to  use  the  compiler
136       wrappers  from  the  Cray Programming Environment’s PrgEnv-* modules if
137       present and loaded.
138
139       The default configuration of the Cray  Programming  Environment  is  to
140       only  support  static  libraries.   This  can  be overridden and shared
141       libraries enabled by setting the CRAYPE_LINK_TYPE environment  variable
142       to dynamic.
143
144       Running CMake without specifying CMAKE_SYSTEM_NAME will run the config‐
145       ure step in host mode assuming a standard Linux  environment.   If  not
146       overridden,  the  PrgEnv-*  compiler wrappers will end up getting used,
147       which if targeting the either the login node or compute node, is likely
148       not  the  desired  behavior.  The exception to this would be if you are
149       building directly on a NID instead  of  cross-compiling  from  a  login
150       node.  If  trying  to build software for a login node, you will need to
151       either first unload the currently loaded PrgEnv-* module or  explicitly
152       tell  CMake to use the system compilers in /usr/bin instead of the Cray
153       wrappers.  If instead targeting a compute node is desired, just specify
154       the CMAKE_SYSTEM_NAME as mentioned above.
155
156   Cross Compiling using Clang
157       Some  compilers  such  as  Clang  are  inherently cross compilers.  The
158       CMAKE_<LANG>_COMPILER_TARGET can be set to pass a value to  those  sup‐
159       ported compilers when compiling:
160
161          set(CMAKE_SYSTEM_NAME Linux)
162          set(CMAKE_SYSTEM_PROCESSOR arm)
163
164          set(triple arm-linux-gnueabihf)
165
166          set(CMAKE_C_COMPILER clang)
167          set(CMAKE_C_COMPILER_TARGET ${triple})
168          set(CMAKE_CXX_COMPILER clang++)
169          set(CMAKE_CXX_COMPILER_TARGET ${triple})
170
171       Similarly, some compilers do not ship their own supplementary utilities
172       such as linkers, but provide a way  to  specify  the  location  of  the
173       external  toolchain  which  will  be  used  by the compiler driver. The
174       CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN  variable  can  be  set  in  a
175       toolchain file to pass the path to the compiler driver.
176
177   Cross Compiling for QNX
178       As  the  Clang  compiler the QNX QCC compile is inherently a cross com‐
179       piler.  And the CMAKE_<LANG>_COMPILER_TARGET can be set to pass a value
180       to those supported compilers when compiling:
181
182          set(CMAKE_SYSTEM_NAME QNX)
183
184          set(arch gcc_ntoarmv7le)
185
186          set(CMAKE_C_COMPILER qcc)
187          set(CMAKE_C_COMPILER_TARGET ${arch})
188          set(CMAKE_CXX_COMPILER QCC)
189          set(CMAKE_CXX_COMPILER_TARGET ${arch})
190
191   Cross Compiling for Windows CE
192       Cross  compiling  for  Windows  CE requires the corresponding SDK being
193       installed on your system.   These  SDKs  are  usually  installed  under
194       C:/Program Files (x86)/Windows CE Tools/SDKs.
195
196       A  toolchain file to configure a Visual Studio generator for Windows CE
197       may look like this:
198
199          set(CMAKE_SYSTEM_NAME WindowsCE)
200
201          set(CMAKE_SYSTEM_VERSION 8.0)
202          set(CMAKE_SYSTEM_PROCESSOR arm)
203
204          set(CMAKE_GENERATOR_TOOLSET CE800) # Can be omitted for 8.0
205          set(CMAKE_GENERATOR_PLATFORM SDK_AM335X_SK_WEC2013_V310)
206
207       The CMAKE_GENERATOR_PLATFORM tells the  generator  which  SDK  to  use.
208       Further  CMAKE_SYSTEM_VERSION  tells the generator what version of Win‐
209       dows CE to use.  Currently version 8.0 (Windows Embedded Compact  2013)
210       is  supported  out  of  the box.  Other versions may require one to set
211       CMAKE_GENERATOR_TOOLSET to the correct value.
212
213   Cross Compiling for Windows 10 Universal Applications
214       A toolchain file to configure a Visual Studio generator for  a  Windows
215       10 Universal Application may look like this:
216
217          set(CMAKE_SYSTEM_NAME WindowsStore)
218          set(CMAKE_SYSTEM_VERSION 10.0)
219
220       A  Windows 10 Universal Application targets both Windows Store and Win‐
221       dows Phone.  Specify the CMAKE_SYSTEM_VERSION variable to  be  10.0  to
222       build  with  the  latest available Windows 10 SDK.  Specify a more spe‐
223       cific version (e.g. 10.0.10240.0 for RTM) to build with the correspond‐
224       ing SDK.
225
226   Cross Compiling for Windows Phone
227       A  toolchain  file  to  configure a Visual Studio generator for Windows
228       Phone may look like this:
229
230          set(CMAKE_SYSTEM_NAME WindowsPhone)
231          set(CMAKE_SYSTEM_VERSION 8.1)
232
233   Cross Compiling for Windows Store
234       A toolchain file to configure a Visual  Studio  generator  for  Windows
235       Store may look like this:
236
237          set(CMAKE_SYSTEM_NAME WindowsStore)
238          set(CMAKE_SYSTEM_VERSION 8.1)
239
240   Cross Compiling for Android
241       A  toolchain  file may configure cross-compiling for Android by setting
242       the CMAKE_SYSTEM_NAME variable to Android.   Further  configuration  is
243       specific to the Android development environment to be used.
244
245       For  Visual Studio Generators, CMake expects NVIDIA Nsight Tegra Visual
246       Studio Edition to be installed.  See that section for further  configu‐
247       ration details.
248
249       For  Makefile  Generators and the Ninja generator, CMake expects one of
250       these environments:
251
252       · NDK
253
254       · Standalone Toolchain
255
256       CMake uses the following steps to select one of the environments:
257
258       · If the CMAKE_ANDROID_NDK variable is set, the NDK  at  the  specified
259         location will be used.
260
261       · Else,  if the CMAKE_ANDROID_STANDALONE_TOOLCHAIN variable is set, the
262         Standalone Toolchain at the specified location will be used.
263
264       · Else, if the CMAKE_SYSROOT variable is set to a directory of the form
265         <ndk>/platforms/android-<api>/arch-<arch>,  the  <ndk>  part  will be
266         used as the value of CMAKE_ANDROID_NDK and the NDK will be used.
267
268       · Else, if the CMAKE_SYSROOT variable is set to a directory of the form
269         <standalone-toolchain>/sysroot,  the <standalone-toolchain> part will
270         be used as the value of  CMAKE_ANDROID_STANDALONE_TOOLCHAIN  and  the
271         Standalone Toolchain will be used.
272
273       · Else,  if  a cmake variable ANDROID_NDK is set it will be used as the
274         value of CMAKE_ANDROID_NDK, and the NDK will be used.
275
276       · Else, if a cmake variable  ANDROID_STANDALONE_TOOLCHAIN  is  set,  it
277         will  be used as the value of CMAKE_ANDROID_STANDALONE_TOOLCHAIN, and
278         the Standalone Toolchain will be used.
279
280       · Else, if an environment variable ANDROID_NDK_ROOT or  ANDROID_NDK  is
281         set,  it  will be used as the value of CMAKE_ANDROID_NDK, and the NDK
282         will be used.
283
284       · Else, if an environment variable ANDROID_STANDALONE_TOOLCHAIN is  set
285         then   it   will   be  used  as  the  value  of  CMAKE_ANDROID_STAND‐
286         ALONE_TOOLCHAIN, and the Standalone Toolchain will be used.
287
288       · Else, an error diagnostic will be issued  that  neither  the  NDK  or
289         Standalone Toolchain can be found.
290
291   Cross Compiling for Android with the NDK
292       A toolchain file may configure Makefile Generators or the Ninja genera‐
293       tor to target Android for cross-compiling.
294
295       Configure use of an Android NDK with the following variables:
296
297       CMAKE_SYSTEM_NAME
298              Set to Android.  Must be specified to enable cross compiling for
299              Android.
300
301       CMAKE_SYSTEM_VERSION
302              Set  to  the  Android API level.  If not specified, the value is
303              determined as follows:
304
305              · If the CMAKE_ANDROID_API variable is set, its value is used as
306                the API level.
307
308              · If  the  CMAKE_SYSROOT  variable  is  set,  the  API  level is
309                detected from the NDK directory structure containing the  sys‐
310                root.
311
312              · Otherwise, the latest API level available in the NDK is used.
313
314       CMAKE_ANDROID_ARCH_ABI
315              Set  to  the Android ABI (architecture).  If not specified, this
316              variable will default to armeabi.  The CMAKE_ANDROID_ARCH  vari‐
317              able will be computed from CMAKE_ANDROID_ARCH_ABI automatically.
318              Also see the CMAKE_ANDROID_ARM_MODE  and  CMAKE_ANDROID_ARM_NEON
319              variables.
320
321       CMAKE_ANDROID_NDK
322              Set  to  the absolute path to the Android NDK root directory.  A
323              ${CMAKE_ANDROID_NDK}/platforms directory  must  exist.   If  not
324              specified,  a default for this variable will be chosen as speci‐
325              fied above.
326
327       CMAKE_ANDROID_NDK_DEPRECATED_HEADERS
328              Set to a true value to use the deprecated per-api-level  headers
329              instead  of  the unified headers.  If not specified, the default
330              will be false unless using a NDK that does not  provide  unified
331              headers.
332
333       CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
334              Set  to  the  version of the NDK toolchain to be selected as the
335              compiler.  If not specified, the  default  will  be  the  latest
336              available GCC toolchain.
337
338       CMAKE_ANDROID_STL_TYPE
339              Set to specify which C++ standard library to use.  If not speci‐
340              fied, a default will be selected as described  in  the  variable
341              documentation.
342
343       The following variables will be computed and provided automatically:
344
345       CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
346              The absolute path prefix to the binutils in the NDK toolchain.
347
348       CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
349              The host platform suffix of the binutils in the NDK toolchain.
350
351       For example, a toolchain file might contain:
352
353          set(CMAKE_SYSTEM_NAME Android)
354          set(CMAKE_SYSTEM_VERSION 21) # API level
355          set(CMAKE_ANDROID_ARCH_ABI arm64-v8a)
356          set(CMAKE_ANDROID_NDK /path/to/android-ndk)
357          set(CMAKE_ANDROID_STL_TYPE gnustl_static)
358
359       Alternatively one may specify the values without a toolchain file:
360
361          $ cmake ../src \
362            -DCMAKE_SYSTEM_NAME=Android \
363            -DCMAKE_SYSTEM_VERSION=21 \
364            -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
365            -DCMAKE_ANDROID_NDK=/path/to/android-ndk \
366            -DCMAKE_ANDROID_STL_TYPE=gnustl_static
367
368   Cross Compiling for Android with a Standalone Toolchain
369       A toolchain file may configure Makefile Generators or the Ninja genera‐
370       tor to target Android for cross-compiling using a standalone toolchain.
371
372       Configure use of an Android standalone  toolchain  with  the  following
373       variables:
374
375       CMAKE_SYSTEM_NAME
376              Set to Android.  Must be specified to enable cross compiling for
377              Android.
378
379       CMAKE_ANDROID_STANDALONE_TOOLCHAIN
380              Set to the absolute path to the standalone toolchain root direc‐
381              tory.  A ${CMAKE_ANDROID_STANDALONE_TOOLCHAIN}/sysroot directory
382              must exist.  If not specified, a default for this variable  will
383              be chosen as specified above.
384
385       CMAKE_ANDROID_ARM_MODE
386              When  the  standalone toolchain targets ARM, optionally set this
387              to ON to target 32-bit ARM instead of 16-bit Thumb.   See  vari‐
388              able documentation for details.
389
390       CMAKE_ANDROID_ARM_NEON
391              When  the  standalone  toolchain  targets ARM v7, optionally set
392              thisto ON to target ARM NEON devices.  See  variable  documenta‐
393              tion for details.
394
395       The following variables will be computed and provided automatically:
396
397       CMAKE_SYSTEM_VERSION
398              The Android API level detected from the standalone toolchain.
399
400       CMAKE_ANDROID_ARCH_ABI
401              The Android ABI detected from the standalone toolchain.
402
403       CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
404              The  absolute  path  prefix  to  the  binutils in the standalone
405              toolchain.
406
407       CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
408              The host platform suffix  of  the  binutils  in  the  standalone
409              toolchain.
410
411       For example, a toolchain file might contain:
412
413          set(CMAKE_SYSTEM_NAME Android)
414          set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android-toolchain)
415
416       Alternatively one may specify the values without a toolchain file:
417
418          $ cmake ../src \
419            -DCMAKE_SYSTEM_NAME=Android \
420            -DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android-toolchain
421
422   Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition
423       A  toolchain  file  to configure one of the Visual Studio Generators to
424       build using NVIDIA Nsight Tegra targeting Android may look like this:
425
426          set(CMAKE_SYSTEM_NAME Android)
427
428       The CMAKE_GENERATOR_TOOLSET may be  set  to  select  the  Nsight  Tegra
429       “Toolchain Version” value.
430
431       See also target properties:
432
433       · ANDROID_ANT_ADDITIONAL_OPTIONS
434
435       · ANDROID_API_MIN
436
437       · ANDROID_API
438
439       · ANDROID_ARCH
440
441       · ANDROID_ASSETS_DIRECTORIES
442
443       · ANDROID_GUI
444
445       · ANDROID_JAR_DEPENDENCIES
446
447       · ANDROID_JAR_DIRECTORIES
448
449       · ANDROID_JAVA_SOURCE_DIR
450
451       · ANDROID_NATIVE_LIB_DEPENDENCIES
452
453       · ANDROID_NATIVE_LIB_DIRECTORIES
454
455       · ANDROID_PROCESS_MAX
456
457       · ANDROID_PROGUARD_CONFIG_PATH
458
459       · ANDROID_PROGUARD
460
461       · ANDROID_SECURE_PROPS_PATH
462
463       · ANDROID_SKIP_ANT_STEP
464
465       · ANDROID_STL_TYPE
466
468       2000-2018 Kitware, Inc. and Contributors
469
470
471
472
4733.11.4                           May 13, 2019              CMAKE-TOOLCHAINS(7)
Impressum