NAME

       cmake-toolchains - CMake Toolchains Reference

INTRODUCTION

       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.

LANGUAGES

       Languages  are  enabled  by  the  project()  command.   Language-specific  built-in  variables,  such  as
       CMAKE_CXX_COMPILER,  CMAKE_CXX_COMPILER_ID  etc are set by invoking the project() command.  If no project
       command is in the top-level CMakeLists file, one will be implicitly generated.  By  default  the  enabled
       languages are C and CXX:

          project(C_Only C)

       A special value of NONE can also be used with the project() command to enable no languages:

          project(MyProject NONE)

       The enable_language() command can be used to enable languages after the project() command:

          enable_language(CXX)

       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.

       The ENABLED_LANGUAGES global property contains the languages which are currently enabled.

VARIABLES AND PROPERTIES

       Several   variables   relate   to   the   language   components   of   a  toolchain  which  are  enabled.
       CMAKE_<LANG>_COMPILER is the full path to the compiler used for <LANG>. CMAKE_<LANG>_COMPILER_ID  is  the
       identifier  used  by  CMake  for  the  compiler  and  CMAKE_<LANG>_COMPILER_VERSION is the version of the
       compiler.

       The CMAKE_<LANG>_FLAGS variables and the configuration-specific equivalents contain flags  that  will  be
       added to the compile command when compiling a file of a particular language.

       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 LANGUAGE 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 LINKER_LANGUAGE target property.

TOOLCHAIN FEATURES

       CMake  provides  the  try_compile()  command  and  wrapper   macros   such   as   CheckCXXSourceCompiles,
       CheckCXXSymbolExists  and  CheckIncludeFile  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.

       Some  toolchain  features have built-in handling in CMake, and do not require compile-tests. For example,
       POSITION_INDEPENDENT_CODE allows specifying that a target should be built as  position-independent  code,
       if  the compiler supports that feature. The <LANG>_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN target
       properties add flags for hidden visibility, if supported by the compiler.

CROSS COMPILING

       If cmake(1) is invoked with the command line parameter -DCMAKE_TOOLCHAIN_FILE=path/to/file, the file will
       be loaded early to set values for the compilers.  The CMAKE_CROSSCOMPILING variable is set to  true  when
       CMake is cross-compiling.

   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)

       The CMAKE_SYSTEM_NAME is the CMake-identifier of the target platform to build for.

       The CMAKE_SYSTEM_PROCESSOR is the CMake-identifier of the target architecture to build for.

       The CMAKE_SYSROOT is optional, and may be specified if a sysroot is available.

       The  CMAKE_STAGING_PREFIX  is  also optional. It may be used to specify a path on the host to install to.
       The CMAKE_INSTALL_PREFIX is always the runtime installation location, even when cross-compiling.

       The CMAKE_<LANG>_COMPILER variables may be set to full paths, or to names of compilers to search  for  in
       standard locations. In cases where CMake does not have enough information to extract information from the
       compiler, the CMakeForceCompiler module can be used to bypass some of the checks.

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

   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 a Visual Studio generator 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 to build with the latest available Windows 10  SDK.   Specify  a
       more specific version (e.g. 10.0.10240.0 for RTM) to build with the corresponding SDK.

   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 using NVIDIA Nsight Tegra
       A  toolchain  file  to  configure  a Visual Studio generator 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:

       • ANDROID_ANT_ADDITIONAL_OPTIONS

       • ANDROID_API_MIN

       • ANDROID_API

       • ANDROID_ARCH

       • ANDROID_ASSETS_DIRECTORIES

       • ANDROID_GUI

       • ANDROID_JAR_DEPENDENCIES

       • ANDROID_JAR_DIRECTORIES

       • ANDROID_JAVA_SOURCE_DIR

       • ANDROID_NATIVE_LIB_DEPENDENCIES

       • ANDROID_NATIVE_LIB_DIRECTORIES

       • ANDROID_PROCESS_MAX

       • ANDROID_PROGUARD_CONFIG_PATH

       • ANDROID_PROGUARD

       • ANDROID_SECURE_PROPS_PATH

       • ANDROID_SKIP_ANT_STEP

       • ANDROID_STL_TYPE

COPYRIGHT

       2000-2016 Kitware, Inc.

3.5.1                                          September 26, 2016                            CMAKE-TOOLCHAINS(7)