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 re‐
69       quire  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   -DC‐
77       MAKE_TOOLCHAIN_FILE=path/to/file,  the file will be loaded early to set
78       values for the compilers.  The CMAKE_CROSSCOMPILING variable is set  to
79       true when CMake is cross-compiling.
80
81       Note  that using the CMAKE_SOURCE_DIR or CMAKE_BINARY_DIR variables in‐
82       side a toolchain file is typically undesirable.  The toolchain file  is
83       used  in contexts where these variables have different values when used
84       in different places (e.g. as part of a call to try_compile()).  In most
85       cases, where there is a need to evaluate paths inside a toolchain file,
86       the more appropriate variable to use would  be  CMAKE_CURRENT_LIST_DIR,
87       since it always has an unambiguous, predictable value.
88
89   Cross Compiling for Linux
90       A typical cross-compiling toolchain for Linux has content such as:
91
92          set(CMAKE_SYSTEM_NAME Linux)
93          set(CMAKE_SYSTEM_PROCESSOR arm)
94
95          set(CMAKE_SYSROOT /home/devel/rasp-pi-rootfs)
96          set(CMAKE_STAGING_PREFIX /home/devel/stage)
97
98          set(tools /home/devel/gcc-4.7-linaro-rpi-gnueabihf)
99          set(CMAKE_C_COMPILER ${tools}/bin/arm-linux-gnueabihf-gcc)
100          set(CMAKE_CXX_COMPILER ${tools}/bin/arm-linux-gnueabihf-g++)
101
102          set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
103          set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
104          set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
105          set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
106
107       The CMAKE_SYSTEM_NAME is the CMake-identifier of the target platform to
108       build for.
109
110       The CMAKE_SYSTEM_PROCESSOR is the CMake-identifier of the target archi‐
111       tecture to build for.
112
113       The  CMAKE_SYSROOT  is  optional,  and may be specified if a sysroot is
114       available.
115
116       The CMAKE_STAGING_PREFIX is also optional. It may be used to specify  a
117       path  on the host to install to. The CMAKE_INSTALL_PREFIX is always the
118       runtime installation location, even when cross-compiling.
119
120       The CMAKE_<LANG>_COMPILER variables may be set to  full  paths,  or  to
121       names   of  compilers  to  search  for  in  standard  locations.    For
122       toolchains that do not support linking binaries without custom flags or
123       scripts  one  may  set  the  CMAKE_TRY_COMPILE_TARGET_TYPE  variable to
124       STATIC_LIBRARY to tell CMake not to try to link executables during  its
125       checks.
126
127       CMake   find_*   commands   will   look   in   the   sysroot,  and  the
128       CMAKE_FIND_ROOT_PATH entries by default in all cases, as well as  look‐
129       ing in the host system root prefix.  Although this can be controlled on
130       a case-by-case basis, when cross-compiling, it can be useful to exclude
131       looking in either the host or the target for particular artifacts. Gen‐
132       erally, includes, libraries and packages should be found in the  target
133       system  prefixes,  whereas executables which must be run as part of the
134       build should be found only on the host and not on the target.  This  is
135       the purpose of the CMAKE_FIND_ROOT_PATH_MODE_* variables.
136
137   Cross Compiling for the Cray Linux Environment
138       Cross  compiling for compute nodes in the Cray Linux Environment can be
139       done without  needing  a  separate  toolchain  file.   Specifying  -DC‐
140       MAKE_SYSTEM_NAME=CrayLinuxEnvironment  on  the  CMake command line will
141       ensure that the appropriate build settings and search paths are config‐
142       ured.   The platform will pull its configuration from the current envi‐
143       ronment variables and will configure a  project  to  use  the  compiler
144       wrappers  from  the  Cray Programming Environment's PrgEnv-* modules if
145       present and loaded.
146
147       The default configuration of the Cray  Programming  Environment  is  to
148       only  support  static libraries.  This can be overridden and shared li‐
149       braries enabled by setting the CRAYPE_LINK_TYPE environment variable to
150       dynamic.
151
152       Running CMake without specifying CMAKE_SYSTEM_NAME will run the config‐
153       ure step in host mode assuming a standard Linux  environment.   If  not
154       overridden,  the  PrgEnv-*  compiler wrappers will end up getting used,
155       which if targeting the either the login node or compute node, is likely
156       not  the  desired  behavior.  The exception to this would be if you are
157       building directly on a NID instead  of  cross-compiling  from  a  login
158       node.  If  trying  to build software for a login node, you will need to
159       either first unload the currently loaded PrgEnv-* module or  explicitly
160       tell  CMake to use the system compilers in /usr/bin instead of the Cray
161       wrappers.  If instead targeting a compute node is desired, just specify
162       the CMAKE_SYSTEM_NAME as mentioned above.
163
164   Cross Compiling using Clang
165       Some  compilers  such  as  Clang  are  inherently cross compilers.  The
166       CMAKE_<LANG>_COMPILER_TARGET can be set to pass a value to  those  sup‐
167       ported compilers when compiling:
168
169          set(CMAKE_SYSTEM_NAME Linux)
170          set(CMAKE_SYSTEM_PROCESSOR arm)
171
172          set(triple arm-linux-gnueabihf)
173
174          set(CMAKE_C_COMPILER clang)
175          set(CMAKE_C_COMPILER_TARGET ${triple})
176          set(CMAKE_CXX_COMPILER clang++)
177          set(CMAKE_CXX_COMPILER_TARGET ${triple})
178
179       Similarly, some compilers do not ship their own supplementary utilities
180       such as linkers, but provide a way to specify the location of  the  ex‐
181       ternal  toolchain  which  will  be  used  by  the  compiler driver. The
182       CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN  variable  can  be  set  in  a
183       toolchain file to pass the path to the compiler driver.
184
185   Cross Compiling for QNX
186       As  the  Clang  compiler the QNX QCC compile is inherently a cross com‐
187       piler.  And the CMAKE_<LANG>_COMPILER_TARGET can be set to pass a value
188       to those supported compilers when compiling:
189
190          set(CMAKE_SYSTEM_NAME QNX)
191
192          set(arch gcc_ntoarmv7le)
193
194          set(CMAKE_C_COMPILER qcc)
195          set(CMAKE_C_COMPILER_TARGET ${arch})
196          set(CMAKE_CXX_COMPILER QCC)
197          set(CMAKE_CXX_COMPILER_TARGET ${arch})
198
199          set(CMAKE_SYSROOT $ENV{QNX_TARGET})
200
201   Cross Compiling for Windows CE
202       Cross compiling for Windows CE requires the corresponding SDK being in‐
203       stalled on your system.  These SDKs are usually installed under C:/Pro‐
204       gram Files (x86)/Windows CE Tools/SDKs.
205
206       A  toolchain file to configure a Visual Studio generator for Windows CE
207       may look like this:
208
209          set(CMAKE_SYSTEM_NAME WindowsCE)
210
211          set(CMAKE_SYSTEM_VERSION 8.0)
212          set(CMAKE_SYSTEM_PROCESSOR arm)
213
214          set(CMAKE_GENERATOR_TOOLSET CE800) # Can be omitted for 8.0
215          set(CMAKE_GENERATOR_PLATFORM SDK_AM335X_SK_WEC2013_V310)
216
217       The CMAKE_GENERATOR_PLATFORM tells the  generator  which  SDK  to  use.
218       Further  CMAKE_SYSTEM_VERSION  tells the generator what version of Win‐
219       dows CE to use.  Currently version 8.0 (Windows Embedded Compact  2013)
220       is  supported  out  of  the box.  Other versions may require one to set
221       CMAKE_GENERATOR_TOOLSET to the correct value.
222
223   Cross Compiling for Windows 10 Universal Applications
224       A toolchain file to configure a Visual Studio generator for  a  Windows
225       10 Universal Application may look like this:
226
227          set(CMAKE_SYSTEM_NAME WindowsStore)
228          set(CMAKE_SYSTEM_VERSION 10.0)
229
230       A  Windows 10 Universal Application targets both Windows Store and Win‐
231       dows Phone.  Specify the CMAKE_SYSTEM_VERSION variable to  be  10.0  to
232       build  with  the  latest available Windows 10 SDK.  Specify a more spe‐
233       cific version (e.g. 10.0.10240.0 for RTM) to build with the correspond‐
234       ing SDK.
235
236   Cross Compiling for Windows Phone
237       A  toolchain  file  to  configure a Visual Studio generator for Windows
238       Phone may look like this:
239
240          set(CMAKE_SYSTEM_NAME WindowsPhone)
241          set(CMAKE_SYSTEM_VERSION 8.1)
242
243   Cross Compiling for Windows Store
244       A toolchain file to configure a Visual  Studio  generator  for  Windows
245       Store may look like this:
246
247          set(CMAKE_SYSTEM_NAME WindowsStore)
248          set(CMAKE_SYSTEM_VERSION 8.1)
249
250   Cross Compiling for Android
251       A  toolchain  file may configure cross-compiling for Android by setting
252       the CMAKE_SYSTEM_NAME variable to Android.   Further  configuration  is
253       specific to the Android development environment to be used.
254
255       For  Visual Studio Generators, CMake expects NVIDIA Nsight Tegra Visual
256       Studio Edition or the Visual Studio tools for Android to be  installed.
257       See those sections for further configuration details.
258
259       For  Makefile  Generators and the Ninja generator, CMake expects one of
260       these environments:
261
262NDK
263
264Standalone Toolchain
265
266       CMake uses the following steps to select one of the environments:
267
268       • If the CMAKE_ANDROID_NDK variable is set, the NDK  at  the  specified
269         location will be used.
270
271       • Else,  if the CMAKE_ANDROID_STANDALONE_TOOLCHAIN variable is set, the
272         Standalone Toolchain at the specified location will be used.
273
274       • Else, if the CMAKE_SYSROOT variable is set to a directory of the form
275         <ndk>/platforms/android-<api>/arch-<arch>,  the  <ndk>  part  will be
276         used as the value of CMAKE_ANDROID_NDK and the NDK will be used.
277
278       • Else, if the CMAKE_SYSROOT variable is set to a directory of the form
279         <standalone-toolchain>/sysroot,  the <standalone-toolchain> part will
280         be used as the value of  CMAKE_ANDROID_STANDALONE_TOOLCHAIN  and  the
281         Standalone Toolchain will be used.
282
283       • Else,  if  a cmake variable ANDROID_NDK is set it will be used as the
284         value of CMAKE_ANDROID_NDK, and the NDK will be used.
285
286       • Else, if a cmake variable  ANDROID_STANDALONE_TOOLCHAIN  is  set,  it
287         will  be used as the value of CMAKE_ANDROID_STANDALONE_TOOLCHAIN, and
288         the Standalone Toolchain will be used.
289
290       • Else, if an environment variable ANDROID_NDK_ROOT or  ANDROID_NDK  is
291         set,  it  will be used as the value of CMAKE_ANDROID_NDK, and the NDK
292         will be used.
293
294       • Else, if an environment variable ANDROID_STANDALONE_TOOLCHAIN is  set
295         then   it   will   be  used  as  the  value  of  CMAKE_ANDROID_STAND‐
296         ALONE_TOOLCHAIN, and the Standalone Toolchain will be used.
297
298       • Else, an error diagnostic will be issued  that  neither  the  NDK  or
299         Standalone Toolchain can be found.
300
301       New  in version 3.20: If an Android NDK is selected, its version number
302       is reported in the CMAKE_ANDROID_NDK_VERSION variable.
303
304
305   Cross Compiling for Android with the NDK
306       A toolchain file may configure Makefile Generators,  Ninja  Generators,
307       or Visual Studio Generators to target Android for cross-compiling.
308
309       Configure use of an Android NDK with the following variables:
310
311       CMAKE_SYSTEM_NAME
312              Set to Android.  Must be specified to enable cross compiling for
313              Android.
314
315       CMAKE_SYSTEM_VERSION
316              Set to the Android API level.  If not specified,  the  value  is
317              determined as follows:
318
319              • If the CMAKE_ANDROID_API variable is set, its value is used as
320                the API level.
321
322              • If the CMAKE_SYSROOT variable is set, the  API  level  is  de‐
323                tected  from  the  NDK directory structure containing the sys‐
324                root.
325
326              • Otherwise, the latest API level available in the NDK is used.
327
328       CMAKE_ANDROID_ARCH_ABI
329              Set to the Android ABI (architecture).  If not  specified,  this
330              variable  will default to the first supported ABI in the list of
331              armeabi,  armeabi-v7a  and  arm64-v8a.   The  CMAKE_ANDROID_ARCH
332              variable  will be computed from CMAKE_ANDROID_ARCH_ABI automati‐
333              cally.   Also  see  the  CMAKE_ANDROID_ARM_MODE  and   CMAKE_AN‐
334              DROID_ARM_NEON variables.
335
336       CMAKE_ANDROID_NDK
337              Set  to the absolute path to the Android NDK root directory.  If
338              not specified, a default for this variable  will  be  chosen  as
339              specified above.
340
341       CMAKE_ANDROID_NDK_DEPRECATED_HEADERS
342              Set  to a true value to use the deprecated per-api-level headers
343              instead of the unified headers.  If not specified,  the  default
344              will  be  false unless using a NDK that does not provide unified
345              headers.
346
347       CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
348              On NDK r19 or above, this variable  must  be  unset  or  set  to
349              clang.   On NDK r18 or below, set this to the version of the NDK
350              toolchain to be selected as the compiler.  If not specified, the
351              default will be the latest available GCC toolchain.
352
353       CMAKE_ANDROID_STL_TYPE
354              Set to specify which C++ standard library to use.  If not speci‐
355              fied, a default will be selected as described  in  the  variable
356              documentation.
357
358       The following variables will be computed and provided automatically:
359
360       CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
361              The absolute path prefix to the binutils in the NDK toolchain.
362
363       CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
364              The host platform suffix of the binutils in the NDK toolchain.
365
366       For example, a toolchain file might contain:
367
368          set(CMAKE_SYSTEM_NAME Android)
369          set(CMAKE_SYSTEM_VERSION 21) # API level
370          set(CMAKE_ANDROID_ARCH_ABI arm64-v8a)
371          set(CMAKE_ANDROID_NDK /path/to/android-ndk)
372          set(CMAKE_ANDROID_STL_TYPE gnustl_static)
373
374       Alternatively one may specify the values without a toolchain file:
375
376          $ cmake ../src \
377            -DCMAKE_SYSTEM_NAME=Android \
378            -DCMAKE_SYSTEM_VERSION=21 \
379            -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
380            -DCMAKE_ANDROID_NDK=/path/to/android-ndk \
381            -DCMAKE_ANDROID_STL_TYPE=gnustl_static
382
383   Cross Compiling for Android with a Standalone Toolchain
384       A toolchain file may configure Makefile Generators or the Ninja genera‐
385       tor to target Android for cross-compiling using a standalone toolchain.
386
387       Configure use of an Android standalone  toolchain  with  the  following
388       variables:
389
390       CMAKE_SYSTEM_NAME
391              Set to Android.  Must be specified to enable cross compiling for
392              Android.
393
394       CMAKE_ANDROID_STANDALONE_TOOLCHAIN
395              Set to the absolute path to the standalone toolchain root direc‐
396              tory.  A ${CMAKE_ANDROID_STANDALONE_TOOLCHAIN}/sysroot directory
397              must exist.  If not specified, a default for this variable  will
398              be chosen as specified above.
399
400       CMAKE_ANDROID_ARM_MODE
401              When  the  standalone toolchain targets ARM, optionally set this
402              to ON to target 32-bit ARM instead of 16-bit Thumb.   See  vari‐
403              able documentation for details.
404
405       CMAKE_ANDROID_ARM_NEON
406              When  the  standalone  toolchain  targets ARM v7, optionally set
407              thisto ON to target ARM NEON devices.  See  variable  documenta‐
408              tion for details.
409
410       The following variables will be computed and provided automatically:
411
412       CMAKE_SYSTEM_VERSION
413              The Android API level detected from the standalone toolchain.
414
415       CMAKE_ANDROID_ARCH_ABI
416              The Android ABI detected from the standalone toolchain.
417
418       CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
419              The  absolute  path  prefix  to  the  binutils in the standalone
420              toolchain.
421
422       CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
423              The host platform suffix  of  the  binutils  in  the  standalone
424              toolchain.
425
426       For example, a toolchain file might contain:
427
428          set(CMAKE_SYSTEM_NAME Android)
429          set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android-toolchain)
430
431       Alternatively one may specify the values without a toolchain file:
432
433          $ cmake ../src \
434            -DCMAKE_SYSTEM_NAME=Android \
435            -DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android-toolchain
436
437   Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition
438       A  toolchain  file  to configure one of the Visual Studio Generators to
439       build using NVIDIA Nsight Tegra targeting Android may look like this:
440
441          set(CMAKE_SYSTEM_NAME Android)
442
443       The CMAKE_GENERATOR_TOOLSET may be  set  to  select  the  Nsight  Tegra
444       "Toolchain Version" value.
445
446       See also target properties:
447
448ANDROID_ANT_ADDITIONAL_OPTIONS
449
450ANDROID_API_MIN
451
452ANDROID_API
453
454ANDROID_ARCH
455
456ANDROID_ASSETS_DIRECTORIES
457
458ANDROID_GUI
459
460ANDROID_JAR_DEPENDENCIES
461
462ANDROID_JAR_DIRECTORIES
463
464ANDROID_JAVA_SOURCE_DIR
465
466ANDROID_NATIVE_LIB_DEPENDENCIES
467
468ANDROID_NATIVE_LIB_DIRECTORIES
469
470ANDROID_PROCESS_MAX
471
472ANDROID_PROGUARD_CONFIG_PATH
473
474ANDROID_PROGUARD
475
476ANDROID_SECURE_PROPS_PATH
477
478ANDROID_SKIP_ANT_STEP
479
480ANDROID_STL_TYPE
481
482   Cross Compiling for iOS, tvOS, or watchOS
483       For  cross-compiling  to  iOS, tvOS, or watchOS, the Xcode generator is
484       recommended.  The Unix Makefiles or Ninja generators can also be  used,
485       but  they  require the project to handle more areas like target CPU se‐
486       lection and code signing.
487
488       Any of the three systems can be  targeted  by  setting  the  CMAKE_SYS‐
489       TEM_NAME  variable  to  a  value from the table below.  By default, the
490       latest Device SDK is chosen.  As for all Apple platforms,  a  different
491       SDK (e.g. a simulator) can be selected by setting the CMAKE_OSX_SYSROOT
492       variable, although this should rarely be necessary (see  Switching  Be‐
493       tween Device and Simulator below).  A list of available SDKs can be ob‐
494       tained by running xcodebuild -showsdks.
495
496            ┌────────┬────────────┬──────────────────┬──────────────────┐
497            │OS      │ CMAKE_SYS‐ │ Device  SDK (de‐ │ Simulator SDK    │
498            │        │ TEM_NAME   │ fault)           │                  │
499            ├────────┼────────────┼──────────────────┼──────────────────┤
500            │iOS     │ iOS        │ iphoneos         │ iphonesimulator  │
501            ├────────┼────────────┼──────────────────┼──────────────────┤
502            │tvOS    │ tvOS       │ appletvos        │ appletvsimulator │
503            ├────────┼────────────┼──────────────────┼──────────────────┤
504            │watchOS │ watchOS    │ watchos          │ watchsimulator   │
505            └────────┴────────────┴──────────────────┴──────────────────┘
506
507       For example, to create a CMake configuration  for  iOS,  the  following
508       command is sufficient:
509
510          cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS
511
512       Variable  CMAKE_OSX_ARCHITECTURES  can be used to set architectures for
513       both device and simulator. Variable CMAKE_OSX_DEPLOYMENT_TARGET can  be
514       used to set an iOS/tvOS/watchOS deployment target.
515
516       Next configuration will install fat 5 architectures iOS library and add
517       the -miphoneos-version-min=9.3/-mios-simulator-version-min=9.3 flags to
518       the compiler:
519
520          $ cmake -S. -B_builds -GXcode \
521              -DCMAKE_SYSTEM_NAME=iOS \
522              "-DCMAKE_OSX_ARCHITECTURES=armv7;armv7s;arm64;i386;x86_64" \
523              -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \
524              -DCMAKE_INSTALL_PREFIX=`pwd`/_install \
525              -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO \
526              -DCMAKE_IOS_INSTALL_COMBINED=YES
527
528       Example:
529
530          # CMakeLists.txt
531          cmake_minimum_required(VERSION 3.14)
532          project(foo)
533          add_library(foo foo.cpp)
534          install(TARGETS foo DESTINATION lib)
535
536       Install:
537
538          $ cmake --build _builds --config Release --target install
539
540       Check library:
541
542          $ lipo -info _install/lib/libfoo.a
543          Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64
544
545          $ otool -l _install/lib/libfoo.a | grep -A2 LC_VERSION_MIN_IPHONEOS
546                cmd LC_VERSION_MIN_IPHONEOS
547            cmdsize 16
548            version 9.3
549
550   Code Signing
551       Some build artifacts for the embedded Apple platforms require mandatory
552       code signing.  If the Xcode generator is being used and code signing is
553       required  or  desired, the development team ID can be specified via the
554       CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM CMake variable.   This  team  ID
555       will  then  be  included  in  the generated Xcode project.  By default,
556       CMake avoids the need for code signing during the  internal  configura‐
557       tion phase (i.e compiler ID and feature detection).
558
559   Switching Between Device and Simulator
560       When  configuring for any of the embedded platforms, one can target ei‐
561       ther real devices or the simulator.  Both have their own separate  SDK,
562       but  CMake  only supports specifying a single SDK for the configuration
563       phase.  This means the developer must select one or the other  at  con‐
564       figuration  time.   When  using  the Xcode generator, this is less of a
565       limitation because Xcode still allows you to build for either a  device
566       or a simulator, even though configuration was only performed for one of
567       the two.  From within the Xcode IDE, builds are performed for  the  se‐
568       lected  "destination"  platform.   When building from the command line,
569       the desired sdk can be specified directly by passing a -sdk  option  to
570       the underlying build tool (xcodebuild).  For example:
571
572          $ cmake --build ... -- -sdk iphonesimulator
573
574       Please  note  that  checks  made  during  configuration  were performed
575       against the configure-time SDK and might not hold true for other  SDKs.
576       Commands  like  find_package(),  find_library(), etc. store and use de‐
577       tails only for the configured SDK/platform, so they can be  problematic
578       if  wanting to switch between device and simulator builds. You can fol‐
579       low the next rules to make device + simulator configuration work:
580
581       • Use explicit -l linker flag,  e.g.  target_link_libraries(foo  PUBLIC
582         "-lz")
583
584       • Use  explicit  -framework linker flag, e.g. target_link_libraries(foo
585         PUBLIC "-framework CoreFoundation")
586
587       • Use find_package() only for libraries  installed  with  CMAKE_IOS_IN‐
588         STALL_COMBINED feature
589
591       2000-2021 Kitware, Inc. and Contributors
592
593
594
595
5963.20.3                           May 30, 2021              CMAKE-TOOLCHAINS(7)
Impressum