.\" Man page generated from reStructuredText.

.

.TH "CMAKE-TOOLCHAINS" "7" "October 14, 2015" "3.3.2" "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 C and CXX:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

project(C_Only C)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

A special value of NONE 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\-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.

.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. In cases where CMake does

not have enough information to extract information from the compiler, the

\fBCMakeForceCompiler\fP module can be used to bypass some of the 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 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})

.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 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 using NVIDIA Nsight Tegra

.sp

A toolchain file to configure a Visual Studio generator 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 the \fBANDROID_API_MIN\fP, \fBANDROID_API\fP

and \fBANDROID_GUI\fP target properties to configure

targets within the project.

.SH COPYRIGHT

2000-2015 Kitware, Inc.

.\" Generated by docutils manpage writer.

.