| .\" Man page generated from reStructuredText. |
| . |
| .TH "CMAKE-TOOLCHAINS" "7" "Apr 12, 2022" "3.23.1" "CMake" |
| .SH NAME |
| cmake-toolchains \- CMake Toolchains Reference |
| . |
| .nr rst2man-indent-level 0 |
| . |
| .de1 rstReportMargin |
| \\$1 \\n[an-margin] |
| level \\n[rst2man-indent-level] |
| level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| - |
| \\n[rst2man-indent0] |
| \\n[rst2man-indent1] |
| \\n[rst2man-indent2] |
| .. |
| .de1 INDENT |
| .\" .rstReportMargin pre: |
| . RS \\$1 |
| . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] |
| . nr rst2man-indent-level +1 |
| .\" .rstReportMargin post: |
| .. |
| .de UNINDENT |
| . RE |
| .\" indent \\n[an-margin] |
| .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| .nr rst2man-indent-level -1 |
| .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| .in \\n[rst2man-indent\\n[rst2man-indent-level]]u |
| .. |
| .SH INTRODUCTION |
| .sp |
| CMake uses a toolchain of utilities to compile, link libraries and create |
| archives, and other tasks to drive the build. The toolchain utilities available |
| are determined by the languages enabled. In normal builds, CMake automatically |
| determines the toolchain for host builds based on system introspection and |
| defaults. In cross\-compiling scenarios, a toolchain file may be specified |
| with information about compiler and utility paths. |
| .SH LANGUAGES |
| .sp |
| Languages are enabled by the \fBproject()\fP command. Language\-specific |
| built\-in variables, such as |
| \fBCMAKE_CXX_COMPILER\fP, |
| \fBCMAKE_CXX_COMPILER_ID\fP etc are set by |
| invoking the \fBproject()\fP command. If no project command |
| is in the top\-level CMakeLists file, one will be implicitly generated. By default |
| the enabled languages are \fBC\fP and \fBCXX\fP: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| project(C_Only C) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| A special value of \fBNONE\fP can also be used with the \fBproject()\fP command |
| to enable no languages: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| project(MyProject NONE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBenable_language()\fP command can be used to enable languages after the |
| \fBproject()\fP command: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| enable_language(CXX) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| When a language is enabled, CMake finds a compiler for that language, and |
| determines some information, such as the vendor and version of the compiler, |
| the target architecture and bitwidth, the location of corresponding utilities |
| etc. |
| .sp |
| The \fBENABLED_LANGUAGES\fP global property contains the languages which |
| are currently enabled. |
| .SH VARIABLES AND PROPERTIES |
| .sp |
| Several variables relate to the language components of a toolchain which are |
| enabled. \fBCMAKE_<LANG>_COMPILER\fP is the full path to the compiler used |
| for \fB<LANG>\fP\&. \fBCMAKE_<LANG>_COMPILER_ID\fP is the identifier used |
| by CMake for the compiler and \fBCMAKE_<LANG>_COMPILER_VERSION\fP is the |
| version of the compiler. |
| .sp |
| The \fBCMAKE_<LANG>_FLAGS\fP variables and the configuration\-specific |
| equivalents contain flags that will be added to the compile command when |
| compiling a file of a particular language. |
| .sp |
| As the linker is invoked by the compiler driver, CMake needs a way to determine |
| which compiler to use to invoke the linker. This is calculated by the |
| \fBLANGUAGE\fP of source files in the target, and in the case of static |
| libraries, the language of the dependent libraries. The choice CMake makes may |
| be overridden with the \fBLINKER_LANGUAGE\fP target property. |
| .SH TOOLCHAIN FEATURES |
| .sp |
| CMake provides the \fBtry_compile()\fP command and wrapper macros such as |
| \fBCheckCXXSourceCompiles\fP, \fBCheckCXXSymbolExists\fP and |
| \fBCheckIncludeFile\fP to test capability and availability of various |
| toolchain features. These APIs test the toolchain in some way and cache the |
| result so that the test does not have to be performed again the next time |
| CMake runs. |
| .sp |
| Some toolchain features have built\-in handling in CMake, and do not require |
| compile\-tests. For example, \fBPOSITION_INDEPENDENT_CODE\fP allows |
| specifying that a target should be built as position\-independent code, if |
| the compiler supports that feature. The \fB<LANG>_VISIBILITY_PRESET\fP |
| and \fBVISIBILITY_INLINES_HIDDEN\fP target properties add flags for |
| hidden visibility, if supported by the compiler. |
| .SH CROSS COMPILING |
| .sp |
| If \fBcmake(1)\fP is invoked with the command line parameter |
| \fB\-\-toolchain path/to/file\fP or \fB\-DCMAKE_TOOLCHAIN_FILE=path/to/file\fP, the |
| file will be loaded early to set values for the compilers. |
| The \fBCMAKE_CROSSCOMPILING\fP variable is set to true when CMake is |
| cross\-compiling. |
| .sp |
| Note that using the \fBCMAKE_SOURCE_DIR\fP or \fBCMAKE_BINARY_DIR\fP |
| variables inside a toolchain file is typically undesirable. The toolchain |
| file is used in contexts where these variables have different values when used |
| in different places (e.g. as part of a call to \fBtry_compile()\fP). In most |
| cases, where there is a need to evaluate paths inside a toolchain file, the more |
| appropriate variable to use would be \fBCMAKE_CURRENT_LIST_DIR\fP, since |
| it always has an unambiguous, predictable value. |
| .SS Cross Compiling for Linux |
| .sp |
| A typical cross\-compiling toolchain for Linux has content such |
| as: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_SYSTEM_NAME Linux) |
| set(CMAKE_SYSTEM_PROCESSOR arm) |
| |
| set(CMAKE_SYSROOT /home/devel/rasp\-pi\-rootfs) |
| set(CMAKE_STAGING_PREFIX /home/devel/stage) |
| |
| set(tools /home/devel/gcc\-4.7\-linaro\-rpi\-gnueabihf) |
| set(CMAKE_C_COMPILER ${tools}/bin/arm\-linux\-gnueabihf\-gcc) |
| set(CMAKE_CXX_COMPILER ${tools}/bin/arm\-linux\-gnueabihf\-g++) |
| |
| set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) |
| set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) |
| set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) |
| set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBCMAKE_SYSTEM_NAME\fP is the CMake\-identifier of the target platform |
| to build for. |
| .sp |
| The \fBCMAKE_SYSTEM_PROCESSOR\fP is the CMake\-identifier of the target architecture |
| to build for. |
| .sp |
| The \fBCMAKE_SYSROOT\fP is optional, and may be specified if a sysroot |
| is available. |
| .sp |
| The \fBCMAKE_STAGING_PREFIX\fP is also optional. It may be used to specify |
| a path on the host to install to. The \fBCMAKE_INSTALL_PREFIX\fP is always |
| the runtime installation location, even when cross\-compiling. |
| .sp |
| The \fBCMAKE_<LANG>_COMPILER\fP variables may be set to full paths, or to |
| names of compilers to search for in standard locations. For toolchains that |
| do not support linking binaries without custom flags or scripts one may set |
| the \fBCMAKE_TRY_COMPILE_TARGET_TYPE\fP variable to \fBSTATIC_LIBRARY\fP |
| to tell CMake not to try to link executables during its checks. |
| .sp |
| CMake \fBfind_*\fP commands will look in the sysroot, and the \fBCMAKE_FIND_ROOT_PATH\fP |
| entries by default in all cases, as well as looking in the host system root prefix. |
| Although this can be controlled on a case\-by\-case basis, when cross\-compiling, it |
| can be useful to exclude looking in either the host or the target for particular |
| artifacts. Generally, includes, libraries and packages should be found in the |
| target system prefixes, whereas executables which must be run as part of the build |
| should be found only on the host and not on the target. This is the purpose of |
| the \fBCMAKE_FIND_ROOT_PATH_MODE_*\fP variables. |
| .SS Cross Compiling for the Cray Linux Environment |
| .sp |
| Cross compiling for compute nodes in the Cray Linux Environment can be done |
| without needing a separate toolchain file. Specifying |
| \fB\-DCMAKE_SYSTEM_NAME=CrayLinuxEnvironment\fP on the CMake command line will |
| ensure that the appropriate build settings and search paths are configured. |
| The platform will pull its configuration from the current environment |
| variables and will configure a project to use the compiler wrappers from the |
| Cray Programming Environment\(aqs \fBPrgEnv\-*\fP modules if present and loaded. |
| .sp |
| The default configuration of the Cray Programming Environment is to only |
| support static libraries. This can be overridden and shared libraries |
| enabled by setting the \fBCRAYPE_LINK_TYPE\fP environment variable to |
| \fBdynamic\fP\&. |
| .sp |
| Running CMake without specifying \fBCMAKE_SYSTEM_NAME\fP will |
| run the configure step in host mode assuming a standard Linux environment. |
| If not overridden, the \fBPrgEnv\-*\fP compiler wrappers will end up getting used, |
| which if targeting the either the login node or compute node, is likely not the |
| desired behavior. The exception to this would be if you are building directly |
| on a NID instead of cross\-compiling from a login node. If trying to build |
| software for a login node, you will need to either first unload the |
| currently loaded \fBPrgEnv\-*\fP module or explicitly tell CMake to use the |
| system compilers in \fB/usr/bin\fP instead of the Cray wrappers. If instead |
| targeting a compute node is desired, just specify the |
| \fBCMAKE_SYSTEM_NAME\fP as mentioned above. |
| .SS Cross Compiling using Clang |
| .sp |
| Some compilers such as Clang are inherently cross compilers. |
| The \fBCMAKE_<LANG>_COMPILER_TARGET\fP can be set to pass a |
| value to those supported compilers when compiling: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_SYSTEM_NAME Linux) |
| set(CMAKE_SYSTEM_PROCESSOR arm) |
| |
| set(triple arm\-linux\-gnueabihf) |
| |
| set(CMAKE_C_COMPILER clang) |
| set(CMAKE_C_COMPILER_TARGET ${triple}) |
| set(CMAKE_CXX_COMPILER clang++) |
| set(CMAKE_CXX_COMPILER_TARGET ${triple}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Similarly, some compilers do not ship their own supplementary utilities |
| such as linkers, but provide a way to specify the location of the external |
| toolchain which will be used by the compiler driver. The |
| \fBCMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN\fP variable can be set in a |
| toolchain file to pass the path to the compiler driver. |
| .SS Cross Compiling for QNX |
| .sp |
| As the Clang compiler the QNX QCC compile is inherently a cross compiler. |
| And the \fBCMAKE_<LANG>_COMPILER_TARGET\fP can be set to pass a |
| value to those supported compilers when compiling: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_SYSTEM_NAME QNX) |
| |
| set(arch gcc_ntoarmv7le) |
| |
| set(CMAKE_C_COMPILER qcc) |
| set(CMAKE_C_COMPILER_TARGET ${arch}) |
| set(CMAKE_CXX_COMPILER QCC) |
| set(CMAKE_CXX_COMPILER_TARGET ${arch}) |
| |
| set(CMAKE_SYSROOT $ENV{QNX_TARGET}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Cross Compiling for Windows CE |
| .sp |
| Cross compiling for Windows CE requires the corresponding SDK being |
| installed on your system. These SDKs are usually installed under |
| \fBC:/Program Files (x86)/Windows CE Tools/SDKs\fP\&. |
| .sp |
| A toolchain file to configure a Visual Studio generator for |
| Windows CE may look like this: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_SYSTEM_NAME WindowsCE) |
| |
| set(CMAKE_SYSTEM_VERSION 8.0) |
| set(CMAKE_SYSTEM_PROCESSOR arm) |
| |
| set(CMAKE_GENERATOR_TOOLSET CE800) # Can be omitted for 8.0 |
| set(CMAKE_GENERATOR_PLATFORM SDK_AM335X_SK_WEC2013_V310) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBCMAKE_GENERATOR_PLATFORM\fP tells the generator which SDK to use. |
| Further \fBCMAKE_SYSTEM_VERSION\fP tells the generator what version of |
| Windows CE to use. Currently version 8.0 (Windows Embedded Compact 2013) is |
| supported out of the box. Other versions may require one to set |
| \fBCMAKE_GENERATOR_TOOLSET\fP to the correct value. |
| .SS Cross Compiling for Windows 10 Universal Applications |
| .sp |
| A toolchain file to configure a Visual Studio generator for a |
| Windows 10 Universal Application may look like this: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_SYSTEM_NAME WindowsStore) |
| set(CMAKE_SYSTEM_VERSION 10.0) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| A Windows 10 Universal Application targets both Windows Store and |
| Windows Phone. Specify the \fBCMAKE_SYSTEM_VERSION\fP variable |
| to be \fB10.0\fP to build with the latest available Windows 10 SDK. |
| Specify a more specific version (e.g. \fB10.0.10240.0\fP for RTM) |
| to build with the corresponding SDK. |
| .SS Cross Compiling for Windows Phone |
| .sp |
| A toolchain file to configure a Visual Studio generator for |
| Windows Phone may look like this: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_SYSTEM_NAME WindowsPhone) |
| set(CMAKE_SYSTEM_VERSION 8.1) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Cross Compiling for Windows Store |
| .sp |
| A toolchain file to configure a Visual Studio generator for |
| Windows Store may look like this: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_SYSTEM_NAME WindowsStore) |
| set(CMAKE_SYSTEM_VERSION 8.1) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Cross Compiling for Android |
| .sp |
| A toolchain file may configure cross\-compiling for Android by setting the |
| \fBCMAKE_SYSTEM_NAME\fP variable to \fBAndroid\fP\&. Further configuration |
| is specific to the Android development environment to be used. |
| .sp |
| For Visual Studio Generators, CMake expects \fI\%NVIDIA Nsight Tegra |
| Visual Studio Edition\fP or the \fI\%Visual Studio tools for Android\fP to be installed. See those sections |
| for further configuration details. |
| .sp |
| For Makefile Generators and the \fBNinja\fP generator, |
| CMake expects one of these environments: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fI\%NDK\fP |
| .IP \(bu 2 |
| \fI\%Standalone Toolchain\fP |
| .UNINDENT |
| .sp |
| CMake uses the following steps to select one of the environments: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| If the \fBCMAKE_ANDROID_NDK\fP variable is set, the NDK at the |
| specified location will be used. |
| .IP \(bu 2 |
| Else, if the \fBCMAKE_ANDROID_STANDALONE_TOOLCHAIN\fP variable |
| is set, the Standalone Toolchain at the specified location will be used. |
| .IP \(bu 2 |
| Else, if the \fBCMAKE_SYSROOT\fP variable is set to a directory |
| of the form \fB<ndk>/platforms/android\-<api>/arch\-<arch>\fP, the \fB<ndk>\fP |
| part will be used as the value of \fBCMAKE_ANDROID_NDK\fP and the |
| NDK will be used. |
| .IP \(bu 2 |
| Else, if the \fBCMAKE_SYSROOT\fP variable is set to a directory of the |
| form \fB<standalone\-toolchain>/sysroot\fP, the \fB<standalone\-toolchain>\fP part |
| will be used as the value of \fBCMAKE_ANDROID_STANDALONE_TOOLCHAIN\fP |
| and the Standalone Toolchain will be used. |
| .IP \(bu 2 |
| Else, if a cmake variable \fBANDROID_NDK\fP is set it will be used |
| as the value of \fBCMAKE_ANDROID_NDK\fP, and the NDK will be used. |
| .IP \(bu 2 |
| Else, if a cmake variable \fBANDROID_STANDALONE_TOOLCHAIN\fP is set, it will be |
| used as the value of \fBCMAKE_ANDROID_STANDALONE_TOOLCHAIN\fP, and the |
| Standalone Toolchain will be used. |
| .IP \(bu 2 |
| Else, if an environment variable \fBANDROID_NDK_ROOT\fP or |
| \fBANDROID_NDK\fP is set, it will be used as the value of |
| \fBCMAKE_ANDROID_NDK\fP, and the NDK will be used. |
| .IP \(bu 2 |
| Else, if an environment variable \fBANDROID_STANDALONE_TOOLCHAIN\fP is |
| set then it will be used as the value of |
| \fBCMAKE_ANDROID_STANDALONE_TOOLCHAIN\fP, and the Standalone |
| Toolchain will be used. |
| .IP \(bu 2 |
| Else, an error diagnostic will be issued that neither the NDK or |
| Standalone Toolchain can be found. |
| .UNINDENT |
| .sp |
| New in version 3.20: If an Android NDK is selected, its version number is reported |
| in the \fBCMAKE_ANDROID_NDK_VERSION\fP variable. |
| |
| .SS Cross Compiling for Android with the NDK |
| .sp |
| A toolchain file may configure Makefile Generators, |
| Ninja Generators, or Visual Studio Generators to target |
| Android for cross\-compiling. |
| .sp |
| Configure use of an Android NDK with the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_SYSTEM_NAME\fP |
| Set to \fBAndroid\fP\&. Must be specified to enable cross compiling |
| for Android. |
| .TP |
| .B \fBCMAKE_SYSTEM_VERSION\fP |
| Set to the Android API level. If not specified, the value is |
| determined as follows: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| If the \fBCMAKE_ANDROID_API\fP variable is set, its value |
| is used as the API level. |
| .IP \(bu 2 |
| If the \fBCMAKE_SYSROOT\fP variable is set, the API level is |
| detected from the NDK directory structure containing the sysroot. |
| .IP \(bu 2 |
| Otherwise, the latest API level available in the NDK is used. |
| .UNINDENT |
| .TP |
| .B \fBCMAKE_ANDROID_ARCH_ABI\fP |
| Set to the Android ABI (architecture). If not specified, this |
| variable will default to the first supported ABI in the list of |
| \fBarmeabi\fP, \fBarmeabi\-v7a\fP and \fBarm64\-v8a\fP\&. |
| The \fBCMAKE_ANDROID_ARCH\fP variable will be computed |
| from \fBCMAKE_ANDROID_ARCH_ABI\fP automatically. |
| Also see the \fBCMAKE_ANDROID_ARM_MODE\fP and |
| \fBCMAKE_ANDROID_ARM_NEON\fP variables. |
| .TP |
| .B \fBCMAKE_ANDROID_NDK\fP |
| Set to the absolute path to the Android NDK root directory. |
| If not specified, a default for this variable will be chosen |
| as specified \fI\%above\fP\&. |
| .TP |
| .B \fBCMAKE_ANDROID_NDK_DEPRECATED_HEADERS\fP |
| Set to a true value to use the deprecated per\-api\-level headers |
| instead of the unified headers. If not specified, the default will |
| be false unless using a NDK that does not provide unified headers. |
| .TP |
| .B \fBCMAKE_ANDROID_NDK_TOOLCHAIN_VERSION\fP |
| On NDK r19 or above, this variable must be unset or set to \fBclang\fP\&. |
| On NDK r18 or below, set this to the version of the NDK toolchain to |
| be selected as the compiler. If not specified, the default will be |
| the latest available GCC toolchain. |
| .TP |
| .B \fBCMAKE_ANDROID_STL_TYPE\fP |
| Set to specify which C++ standard library to use. If not specified, |
| a default will be selected as described in the variable documentation. |
| .UNINDENT |
| .sp |
| The following variables will be computed and provided automatically: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX\fP |
| The absolute path prefix to the binutils in the NDK toolchain. |
| .TP |
| .B \fBCMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX\fP |
| The host platform suffix of the binutils in the NDK toolchain. |
| .UNINDENT |
| .sp |
| For example, a toolchain file might contain: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_SYSTEM_NAME Android) |
| set(CMAKE_SYSTEM_VERSION 21) # API level |
| set(CMAKE_ANDROID_ARCH_ABI arm64\-v8a) |
| set(CMAKE_ANDROID_NDK /path/to/android\-ndk) |
| set(CMAKE_ANDROID_STL_TYPE gnustl_static) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Alternatively one may specify the values without a toolchain file: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| $ cmake ../src \e |
| \-DCMAKE_SYSTEM_NAME=Android \e |
| \-DCMAKE_SYSTEM_VERSION=21 \e |
| \-DCMAKE_ANDROID_ARCH_ABI=arm64\-v8a \e |
| \-DCMAKE_ANDROID_NDK=/path/to/android\-ndk \e |
| \-DCMAKE_ANDROID_STL_TYPE=gnustl_static |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Cross Compiling for Android with a Standalone Toolchain |
| .sp |
| A toolchain file may configure Makefile Generators or the |
| \fBNinja\fP generator to target Android for cross\-compiling |
| using a standalone toolchain. |
| .sp |
| Configure use of an Android standalone toolchain with the following variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_SYSTEM_NAME\fP |
| Set to \fBAndroid\fP\&. Must be specified to enable cross compiling |
| for Android. |
| .TP |
| .B \fBCMAKE_ANDROID_STANDALONE_TOOLCHAIN\fP |
| Set to the absolute path to the standalone toolchain root directory. |
| A \fB${CMAKE_ANDROID_STANDALONE_TOOLCHAIN}/sysroot\fP directory |
| must exist. |
| If not specified, a default for this variable will be chosen |
| as specified \fI\%above\fP\&. |
| .TP |
| .B \fBCMAKE_ANDROID_ARM_MODE\fP |
| When the standalone toolchain targets ARM, optionally set this to \fBON\fP |
| to target 32\-bit ARM instead of 16\-bit Thumb. |
| See variable documentation for details. |
| .TP |
| .B \fBCMAKE_ANDROID_ARM_NEON\fP |
| When the standalone toolchain targets ARM v7, optionally set thisto \fBON\fP |
| to target ARM NEON devices. See variable documentation for details. |
| .UNINDENT |
| .sp |
| The following variables will be computed and provided automatically: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_SYSTEM_VERSION\fP |
| The Android API level detected from the standalone toolchain. |
| .TP |
| .B \fBCMAKE_ANDROID_ARCH_ABI\fP |
| The Android ABI detected from the standalone toolchain. |
| .TP |
| .B \fBCMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX\fP |
| The absolute path prefix to the \fBbinutils\fP in the standalone toolchain. |
| .TP |
| .B \fBCMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX\fP |
| The host platform suffix of the \fBbinutils\fP in the standalone toolchain. |
| .UNINDENT |
| .sp |
| For example, a toolchain file might contain: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_SYSTEM_NAME Android) |
| set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android\-toolchain) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Alternatively one may specify the values without a toolchain file: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| $ cmake ../src \e |
| \-DCMAKE_SYSTEM_NAME=Android \e |
| \-DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android\-toolchain |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition |
| .sp |
| A toolchain file to configure one of the Visual Studio Generators |
| to build using NVIDIA Nsight Tegra targeting Android may look like this: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(CMAKE_SYSTEM_NAME Android) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBCMAKE_GENERATOR_TOOLSET\fP may be set to select |
| the Nsight Tegra "Toolchain Version" value. |
| .sp |
| See also target properties: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBANDROID_ANT_ADDITIONAL_OPTIONS\fP |
| .IP \(bu 2 |
| \fBANDROID_API_MIN\fP |
| .IP \(bu 2 |
| \fBANDROID_API\fP |
| .IP \(bu 2 |
| \fBANDROID_ARCH\fP |
| .IP \(bu 2 |
| \fBANDROID_ASSETS_DIRECTORIES\fP |
| .IP \(bu 2 |
| \fBANDROID_GUI\fP |
| .IP \(bu 2 |
| \fBANDROID_JAR_DEPENDENCIES\fP |
| .IP \(bu 2 |
| \fBANDROID_JAR_DIRECTORIES\fP |
| .IP \(bu 2 |
| \fBANDROID_JAVA_SOURCE_DIR\fP |
| .IP \(bu 2 |
| \fBANDROID_NATIVE_LIB_DEPENDENCIES\fP |
| .IP \(bu 2 |
| \fBANDROID_NATIVE_LIB_DIRECTORIES\fP |
| .IP \(bu 2 |
| \fBANDROID_PROCESS_MAX\fP |
| .IP \(bu 2 |
| \fBANDROID_PROGUARD_CONFIG_PATH\fP |
| .IP \(bu 2 |
| \fBANDROID_PROGUARD\fP |
| .IP \(bu 2 |
| \fBANDROID_SECURE_PROPS_PATH\fP |
| .IP \(bu 2 |
| \fBANDROID_SKIP_ANT_STEP\fP |
| .IP \(bu 2 |
| \fBANDROID_STL_TYPE\fP |
| .UNINDENT |
| .SS Cross Compiling for iOS, tvOS, or watchOS |
| .sp |
| For cross\-compiling to iOS, tvOS, or watchOS, the \fBXcode\fP |
| generator is recommended. The \fBUnix Makefiles\fP or |
| \fBNinja\fP generators can also be used, but they require the |
| project to handle more areas like target CPU selection and code signing. |
| .sp |
| Any of the three systems can be targeted by setting the |
| \fBCMAKE_SYSTEM_NAME\fP variable to a value from the table below. |
| By default, the latest Device SDK is chosen. As for all Apple platforms, |
| a different SDK (e.g. a simulator) can be selected by setting the |
| \fBCMAKE_OSX_SYSROOT\fP variable, although this should rarely be |
| necessary (see \fI\%Switching Between Device and Simulator\fP below). |
| A list of available SDKs can be obtained by running \fBxcodebuild \-showsdks\fP\&. |
| .TS |
| center; |
| |l|l|l|l|. |
| _ |
| T{ |
| OS |
| T} T{ |
| CMAKE_SYSTEM_NAME |
| T} T{ |
| Device SDK (default) |
| T} T{ |
| Simulator SDK |
| T} |
| _ |
| T{ |
| iOS |
| T} T{ |
| iOS |
| T} T{ |
| iphoneos |
| T} T{ |
| iphonesimulator |
| T} |
| _ |
| T{ |
| tvOS |
| T} T{ |
| tvOS |
| T} T{ |
| appletvos |
| T} T{ |
| appletvsimulator |
| T} |
| _ |
| T{ |
| watchOS |
| T} T{ |
| watchOS |
| T} T{ |
| watchos |
| T} T{ |
| watchsimulator |
| T} |
| _ |
| .TE |
| .sp |
| For example, to create a CMake configuration for iOS, the following |
| command is sufficient: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake .. \-GXcode \-DCMAKE_SYSTEM_NAME=iOS |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Variable \fBCMAKE_OSX_ARCHITECTURES\fP can be used to set architectures |
| for both device and simulator. Variable \fBCMAKE_OSX_DEPLOYMENT_TARGET\fP |
| can be used to set an iOS/tvOS/watchOS deployment target. |
| .sp |
| Next configuration will install fat 5 architectures iOS library |
| and add the \fB\-miphoneos\-version\-min=9.3\fP/\fB\-mios\-simulator\-version\-min=9.3\fP |
| flags to the compiler: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| $ cmake \-S. \-B_builds \-GXcode \e |
| \-DCMAKE_SYSTEM_NAME=iOS \e |
| "\-DCMAKE_OSX_ARCHITECTURES=armv7;armv7s;arm64;i386;x86_64" \e |
| \-DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \e |
| \-DCMAKE_INSTALL_PREFIX=\(gapwd\(ga/_install \e |
| \-DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO \e |
| \-DCMAKE_IOS_INSTALL_COMBINED=YES |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # CMakeLists.txt |
| cmake_minimum_required(VERSION 3.14) |
| project(foo) |
| add_library(foo foo.cpp) |
| install(TARGETS foo DESTINATION lib) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Install: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| $ cmake \-\-build _builds \-\-config Release \-\-target install |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check library: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| $ lipo \-info _install/lib/libfoo.a |
| Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| $ otool \-l _install/lib/libfoo.a | grep \-A2 LC_VERSION_MIN_IPHONEOS |
| cmd LC_VERSION_MIN_IPHONEOS |
| cmdsize 16 |
| version 9.3 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Code Signing |
| .sp |
| Some build artifacts for the embedded Apple platforms require mandatory |
| code signing. If the \fBXcode\fP generator is being used and |
| code signing is required or desired, the development team ID can be |
| specified via the \fBCMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM\fP CMake variable. |
| This team ID will then be included in the generated Xcode project. |
| By default, CMake avoids the need for code signing during the internal |
| configuration phase (i.e compiler ID and feature detection). |
| .SS Switching Between Device and Simulator |
| .sp |
| When configuring for any of the embedded platforms, one can target either |
| real devices or the simulator. Both have their own separate SDK, but CMake |
| only supports specifying a single SDK for the configuration phase. This |
| means the developer must select one or the other at configuration time. |
| When using the \fBXcode\fP generator, this is less of a limitation |
| because Xcode still allows you to build for either a device or a simulator, |
| even though configuration was only performed for one of the two. From |
| within the Xcode IDE, builds are performed for the selected "destination" |
| platform. When building from the command line, the desired sdk can be |
| specified directly by passing a \fB\-sdk\fP option to the underlying build |
| tool (\fBxcodebuild\fP). For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| $ cmake \-\-build ... \-\- \-sdk iphonesimulator |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Please note that checks made during configuration were performed against |
| the configure\-time SDK and might not hold true for other SDKs. Commands |
| like \fBfind_package()\fP, \fBfind_library()\fP, etc. store and use |
| details only for the configured SDK/platform, so they can be problematic |
| if wanting to switch between device and simulator builds. You can follow |
| the next rules to make device + simulator configuration work: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Use explicit \fB\-l\fP linker flag, |
| e.g. \fBtarget_link_libraries(foo PUBLIC "\-lz")\fP |
| .IP \(bu 2 |
| Use explicit \fB\-framework\fP linker flag, |
| e.g. \fBtarget_link_libraries(foo PUBLIC "\-framework CoreFoundation")\fP |
| .IP \(bu 2 |
| Use \fBfind_package()\fP only for libraries installed with |
| \fBCMAKE_IOS_INSTALL_COMBINED\fP feature |
| .UNINDENT |
| .SH COPYRIGHT |
| 2000-2022 Kitware, Inc. and Contributors |
| .\" Generated by docutils manpage writer. |
| . |