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
17       New  in version 3.19: One may use cmake-presets(7) to specify toolchain
18       files.
19
20

LANGUAGES

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

VARIABLES AND PROPERTIES

49       Several variables relate to the  language  components  of  a  toolchain
50       which are enabled:
51
52       CMAKE_<LANG>_COMPILER
53              The full path to the compiler used for <LANG>
54
55       CMAKE_<LANG>_COMPILER_ID
56              The compiler identifier used by CMake
57
58       CMAKE_<LANG>_COMPILER_VERSION
59              The version of the compiler.
60
61       CMAKE_<LANG>_FLAGS
62              The variables and the configuration-specific equivalents contain
63              flags that will be added to the compile command when compiling a
64              file of a particular language.
65
66       CMake  needs  a  way  to  determine which compiler to use to invoke the
67       linker.  This is determined by the LANGUAGE property of source files of
68       the  target,  and  in the case of static libraries, the LANGUAGE of the
69       dependent libraries. The choice CMake makes may be overridden with  the
70       LINKER_LANGUAGE target property.
71

TOOLCHAIN FEATURES

73       CMake  provides  the  try_compile()  command and wrapper macros such as
74       CheckCXXSourceCompiles, CheckCXXSymbolExists  and  CheckIncludeFile  to
75       test  capability  and availability of various toolchain features. These
76       APIs test the toolchain in some way and cache the result  so  that  the
77       test does not have to be performed again the next time CMake runs.
78
79       Some toolchain features have built-in handling in CMake, and do not re‐
80       quire  compile-tests.  For  example,  POSITION_INDEPENDENT_CODE  allows
81       specifying  that a target should be built as position-independent code,
82       if the compiler supports that feature. The <LANG>_VISIBILITY_PRESET and
83       VISIBILITY_INLINES_HIDDEN  target properties add flags for hidden visi‐
84       bility, if supported by the compiler.
85

CROSS COMPILING

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