Cross Compiling for Linux¶

A typical cross-compiling toolchain for Linux has content such as:

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)

Where:

CMake find_* commands will look in the sysroot, and the CMAKE_FIND_ROOT_PATH 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 CMAKE_FIND_ROOT_PATH_MODE_* variables.

Cross Compiling for the Cray Linux Environment¶

Cross compiling for compute nodes in the Cray Linux Environment can be done without needing a separate toolchain file. Specifying -DCMAKE_SYSTEM_NAME=CrayLinuxEnvironment 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's PrgEnv-* modules if present and loaded.

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 CRAYPE_LINK_TYPE environment variable to dynamic.

Running CMake without specifying CMAKE_SYSTEM_NAME will run the configure step in host mode assuming a standard Linux environment. If not overridden, the PrgEnv-* 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 PrgEnv-* module or explicitly tell CMake to use the system compilers in /usr/bin instead of the Cray wrappers. If instead targeting a compute node is desired, just specify the CMAKE_SYSTEM_NAME as mentioned above.

Cross Compiling using Clang¶

Some compilers such as Clang are inherently cross compilers. The CMAKE_<LANG>_COMPILER_TARGET can be set to pass a value to those supported compilers when compiling:

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})

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 CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN variable can be set in a toolchain file to pass the path to the compiler driver.

Cross Compiling for QNX¶

As the Clang compiler the QNX QCC compile is inherently a cross compiler. And the CMAKE_<LANG>_COMPILER_TARGET can be set to pass a value to those supported compilers when compiling:

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})

Cross Compiling for Windows CE¶

Cross compiling for Windows CE requires the corresponding SDK being installed on your system. These SDKs are usually installed under C:/Program Files (x86)/Windows CE Tools/SDKs.

A toolchain file to configure a Visual Studio generator for Windows CE may look like this:

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)

The CMAKE_GENERATOR_PLATFORM tells the generator which SDK to use. Further CMAKE_SYSTEM_VERSION 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 CMAKE_GENERATOR_TOOLSET to the correct value.

Cross Compiling for Windows 10 Universal Applications¶

A toolchain file to configure Visual Studio Generators for a Windows 10 Universal Application may look like this:

set(CMAKE_SYSTEM_NAME WindowsStore)
set(CMAKE_SYSTEM_VERSION 10.0)

A Windows 10 Universal Application targets both Windows Store and Windows Phone. Specify the CMAKE_SYSTEM_VERSION variable to be 10.0 or higher.

CMake selects a Windows SDK as described by documentation of the CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION variable.

Cross Compiling for Windows Phone¶

A toolchain file to configure a Visual Studio generator for Windows Phone may look like this:

set(CMAKE_SYSTEM_NAME WindowsPhone)
set(CMAKE_SYSTEM_VERSION 8.1)

Cross Compiling for Windows Store¶

A toolchain file to configure a Visual Studio generator for Windows Store may look like this:

set(CMAKE_SYSTEM_NAME WindowsStore)
set(CMAKE_SYSTEM_VERSION 8.1)

Cross Compiling for ADSP SHARC/Blackfin¶

Cross-compiling for ADSP SHARC or Blackfin can be configured by setting the CMAKE_SYSTEM_NAME variable to ADSP and the CMAKE_SYSTEM_PROCESSOR variable to the "part number", excluding the ADSP- prefix, for example, 21594, SC589, etc. This value is case insensitive.

CMake will automatically search for CCES or VDSP++ installs in their default install locations and select the most recent version found. CCES will be selected over VDSP++ if both are installed. Custom install paths can be set via the CMAKE_ADSP_ROOT variable or the ADSP_ROOT environment variable.

The compiler (cc21k vs. ccblkfn) is selected automatically based on the CMAKE_SYSTEM_PROCESSOR value provided.

Cross Compiling for Android¶

A toolchain file may configure cross-compiling for Android by setting the CMAKE_SYSTEM_NAME variable to Android. Further configuration is specific to the Android development environment to be used.

For Visual Studio Generators, CMake expects NVIDIA Nsight Tegra Visual Studio Edition or the Visual Studio tools for Android to be installed. See those sections for further configuration details.

For Makefile Generators and the Ninja generator, CMake expects one of these environments:

CMake uses the following steps to select one of the environments:

Added in version 3.20: If an Android NDK is selected, its version number is reported in the CMAKE_ANDROID_NDK_VERSION variable.

Cross Compiling for Android with the NDK¶

A toolchain file may configure Makefile Generators, Ninja Generators, or Visual Studio Generators to target Android for cross-compiling.

Configure use of an Android NDK with the following variables:

The following variables will be computed and provided automatically:

For example, a toolchain file might contain:

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)

Alternatively one may specify the values without a toolchain file:

$ cmake ../src \


  -DCMAKE_SYSTEM_NAME=Android \


  -DCMAKE_SYSTEM_VERSION=21 \


  -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \


  -DCMAKE_ANDROID_NDK=/path/to/android-ndk \


  -DCMAKE_ANDROID_STL_TYPE=gnustl_static

Cross Compiling for Android with a Standalone Toolchain¶

A toolchain file may configure Makefile Generators or the Ninja generator to target Android for cross-compiling using a standalone toolchain.

Configure use of an Android standalone toolchain with the following variables:

The following variables will be computed and provided automatically:

For example, a toolchain file might contain:

set(CMAKE_SYSTEM_NAME Android)
set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android-toolchain)

Alternatively one may specify the values without a toolchain file:

$ cmake ../src \


  -DCMAKE_SYSTEM_NAME=Android \


  -DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android-toolchain

Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition¶

A toolchain file to configure one of the Visual Studio Generators to build using NVIDIA Nsight Tegra targeting Android may look like this:

set(CMAKE_SYSTEM_NAME Android)

The CMAKE_GENERATOR_TOOLSET may be set to select the Nsight Tegra "Toolchain Version" value.

See also target properties:

Cross Compiling for iOS, tvOS, visionOS, or watchOS¶

For cross-compiling to iOS, tvOS, visionOS, or watchOS, the Xcode generator is recommended. The Unix Makefiles or Ninja generators can also be used, but they require the project to handle more areas like target CPU selection and code signing.

Any of the Apple device platforms can be targeted by setting the CMAKE_SYSTEM_NAME 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 CMAKE_OSX_SYSROOT variable, although this should rarely be necessary (see Switching Between Device and Simulator below). A list of available SDKs can be obtained by running xcodebuild -showsdks.

For example, to create a CMake configuration for iOS, the following command is sufficient:

cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS

Variable CMAKE_OSX_ARCHITECTURES can be used to set architectures for both device and simulator. Variable CMAKE_OSX_DEPLOYMENT_TARGET can be used to set an iOS/tvOS/visionOS/watchOS deployment target.

The next example installs five architectures in a universal binary for an iOS library. It adds the relevant -miphoneos-version-min=9.3 or -mios-simulator-version-min=9.3 compiler flag where appropriate. Note that the CMAKE_IOS_INSTALL_COMBINED variable used in the example is now deprecated, so this approach is no longer recommended.

$ cmake -S. -B_builds -GXcode \


    -DCMAKE_SYSTEM_NAME=iOS \


    "-DCMAKE_OSX_ARCHITECTURES=armv7;armv7s;arm64;i386;x86_64" \


    -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \


    -DCMAKE_INSTALL_PREFIX=`pwd`/_install \


    -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO \


    -DCMAKE_IOS_INSTALL_COMBINED=YES

Example:

# CMakeLists.txt
cmake_minimum_required(VERSION 3.14)
project(foo)
add_library(foo foo.cpp)
install(TARGETS foo DESTINATION lib)

Install:

$ cmake --build _builds --config Release --target install

Check library:

$ lipo -info _install/lib/libfoo.a
Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64

$ otool -l _install/lib/libfoo.a | grep -A2 LC_VERSION_MIN_IPHONEOS


      cmd LC_VERSION_MIN_IPHONEOS


  cmdsize 16


  version 9.3

Code Signing¶

Some build artifacts for the embedded Apple platforms require mandatory code signing. If the Xcode generator is being used and code signing is required or desired, the development team ID can be specified via the CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM 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).

Switching Between Device and Simulator¶

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 Xcode 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 -sdk option to the underlying build tool (xcodebuild). For example:

$ cmake --build ... -- -sdk iphonesimulator

Please note that checks made during configuration were performed against the configure-time SDK and might not hold true for other SDKs. Commands like find_package(), find_library(), 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: