Provided by: cmake-data_3.5.1-1ubuntu1_all bug

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.