1CMAKE-TOOLCHAINS(7) CMake CMAKE-TOOLCHAINS(7)
2
6 cmake-toolchains - CMake Toolchains Reference
7
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 New in version 3.19: One may use cmake-presets(7) to specify toolchain
18 files.
19
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 project(C_Only C)
29 A special value of NONE can also be used with the project() command to
31 enable no languages:
32 project(MyProject NONE)
34 The enable_language() command can be used to enable languages after the
36 project() command:
37 enable_language(CXX)
39 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 The ENABLED_LANGUAGES global property contains the languages which are
46 currently enabled.
47
49 Several variables relate to the language components of a toolchain
50 which are enabled:
51 CMAKE_<LANG>_COMPILER
53 The full path to the compiler used for <LANG>
54 CMAKE_<LANG>_COMPILER_ID
56 The compiler identifier used by CMake
57 CMAKE_<LANG>_COMPILER_VERSION
59 The version of the compiler.
60 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 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
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 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
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 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 Cross Compiling for Linux
101 A typical cross-compiling toolchain for Linux has content such as:
102 set(CMAKE_SYSTEM_NAME Linux)
104 set(CMAKE_SYSTEM_PROCESSOR arm)
105 set(CMAKE_SYSROOT /home/devel/rasp-pi-rootfs)
107 set(CMAKE_STAGING_PREFIX /home/devel/stage)
108 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 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 Where:
119 CMAKE_SYSTEM_NAME
121 is the CMake-identifier of the target platform to build for.
122 CMAKE_SYSTEM_PROCESSOR
124 is the CMake-identifier of the target architecture.
125 CMAKE_SYSROOT
127 is optional, and may be specified if a sysroot is available.
128 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 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 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 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 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 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 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 set(CMAKE_SYSTEM_NAME Linux)
184 set(CMAKE_SYSTEM_PROCESSOR arm)
185 set(triple arm-linux-gnueabihf)
187 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 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 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 set(CMAKE_SYSTEM_NAME QNX)
205 set(arch gcc_ntoarmv7le)
207 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 set(CMAKE_SYSROOT $ENV{QNX_TARGET})
214 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 A toolchain file to configure a Visual Studio generator for Windows CE
221 may look like this:
222 set(CMAKE_SYSTEM_NAME WindowsCE)
224 set(CMAKE_SYSTEM_VERSION 8.0)
226 set(CMAKE_SYSTEM_PROCESSOR arm)
227 set(CMAKE_GENERATOR_TOOLSET CE800) # Can be omitted for 8.0
229 set(CMAKE_GENERATOR_PLATFORM SDK_AM335X_SK_WEC2013_V310)
230 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 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 set(CMAKE_SYSTEM_NAME WindowsStore)
242 set(CMAKE_SYSTEM_VERSION 10.0)
243 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 Cross Compiling for Windows Phone
251 A toolchain file to configure a Visual Studio generator for Windows
252 Phone may look like this:
253 set(CMAKE_SYSTEM_NAME WindowsPhone)
255 set(CMAKE_SYSTEM_VERSION 8.1)
256 Cross Compiling for Windows Store
258 A toolchain file to configure a Visual Studio generator for Windows
259 Store may look like this:
260 set(CMAKE_SYSTEM_NAME WindowsStore)
262 set(CMAKE_SYSTEM_VERSION 8.1)
263 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 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 The compiler (cc21k vs. ccblkfn) is selected automatically based on the
277 CMAKE_SYSTEM_PROCESSOR value provided.
278 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 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 For Makefile Generators and the Ninja generator, CMake expects one of
289 these environments:
290 • NDK
292 • Standalone Toolchain
294 CMake uses the following steps to select one of the environments:
296 • If the CMAKE_ANDROID_NDK variable is set, the NDK at the specified
298 location will be used.
299 • Else, if the CMAKE_ANDROID_STANDALONE_TOOLCHAIN variable is set, the
301 Standalone Toolchain at the specified location will be used.
302 • 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 • 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 • 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 • 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 • 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 • 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 • Else, an error diagnostic will be issued that neither the NDK or
329 Standalone Toolchain can be found.
330 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 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 Configure use of an Android NDK with the following variables:
340 CMAKE_SYSTEM_NAME
342 Set to Android. Must be specified to enable cross compiling for
343 Android.
344 CMAKE_SYSTEM_VERSION
346 Set to the Android API level. If not specified, the value is
347 determined as follows:
348 • If the CMAKE_ANDROID_API variable is set, its value is used as
350 the API level.
351 • 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 • Otherwise, the latest API level available in the NDK is used.
357 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 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 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 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 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 The following variables will be computed and provided automatically:
389 CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
391 The absolute path prefix to the binutils in the NDK toolchain.
392 CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
394 The host platform suffix of the binutils in the NDK toolchain.
395 For example, a toolchain file might contain:
397 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 Alternatively one may specify the values without a toolchain file:
405 $ 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 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 Configure use of an Android standalone toolchain with the following
418 variables:
419 CMAKE_SYSTEM_NAME
421 Set to Android. Must be specified to enable cross compiling for
422 Android.
423 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 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 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 The following variables will be computed and provided automatically:
441 CMAKE_SYSTEM_VERSION
443 The Android API level detected from the standalone toolchain.
444 CMAKE_ANDROID_ARCH_ABI
446 The Android ABI detected from the standalone toolchain.
447 CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
449 The absolute path prefix to the binutils in the standalone
450 toolchain.
451 CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
453 The host platform suffix of the binutils in the standalone
454 toolchain.
455 For example, a toolchain file might contain:
457 set(CMAKE_SYSTEM_NAME Android)
459 set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android-toolchain)
460 Alternatively one may specify the values without a toolchain file:
462 $ cmake ../src \
464 -DCMAKE_SYSTEM_NAME=Android \
465 -DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android-toolchain
466 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 set(CMAKE_SYSTEM_NAME Android)
472 The CMAKE_GENERATOR_TOOLSET may be set to select the Nsight Tegra
474 "Toolchain Version" value.
475 See also target properties:
477 • ANDROID_ANT_ADDITIONAL_OPTIONS
479 • ANDROID_API_MIN
481 • ANDROID_API
483 • ANDROID_ARCH
485 • ANDROID_ASSETS_DIRECTORIES
487 • ANDROID_GUI
489 • ANDROID_JAR_DEPENDENCIES
491 • ANDROID_JAR_DIRECTORIES
493 • ANDROID_JAVA_SOURCE_DIR
495 • ANDROID_NATIVE_LIB_DEPENDENCIES
497 • ANDROID_NATIVE_LIB_DIRECTORIES
499 • ANDROID_PROCESS_MAX
501 • ANDROID_PROGUARD_CONFIG_PATH
503 • ANDROID_PROGUARD
505 • ANDROID_SECURE_PROPS_PATH
507 • ANDROID_SKIP_ANT_STEP
509 • ANDROID_STL_TYPE
511 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 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 ┌────────┬────────────┬──────────────────┬──────────────────┐
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 For example, to create a CMake configuration for iOS, the following
538 command is sufficient:
539 cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS
541 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 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 $ 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 Example:
559 # 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 Install:
567 $ cmake --build _builds --config Release --target install
569 Check library:
571 $ lipo -info _install/lib/libfoo.a
573 Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64
574 $ 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 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 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 $ cmake --build ... -- -sdk iphonesimulator
603 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 • Use explicit -l linker flag, e.g. target_link_libraries(foo PUBLIC
612 "-lz")
613 • Use explicit -framework linker flag, e.g. target_link_libraries(foo
615 PUBLIC "-framework CoreFoundation")
616 • Use find_package() only for libraries installed with
618 CMAKE_IOS_INSTALL_COMBINED feature
619
621 2000-2023 Kitware, Inc. and Contributors
6223.25.2 Jan 19, 2023 CMAKE-TOOLCHAINS(7)