Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CMAKE-TOOLCHAINS(7)		     CMake		   CMAKE-TOOLCHAINS(7)

NAME
       cmake-toolchains	- CMake	Toolchains Reference

INTRODUCTION
       CMake uses a toolchain of utilities to compile, link libraries and cre-
       ate archives, and other tasks to	drive the build. The toolchain	utili-
       ties  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 scenar-
       ios, 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	corre-
       sponding	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  com-
       piler  used for <LANG>. CMAKE_<LANG>_COMPILER_ID	is the identifier used
       by CMake	for the	compiler and CMAKE_<LANG>_COMPILER_VERSION is the ver-
       sion of the compiler.

       The CMAKE_<LANG>_FLAGS variables	and the	configuration-specific equiva-
       lents contain flags that	will be	added to the compile command when com-
       piling 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	calcu-
       lated 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 re-
       quire  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 visi-
       bility, if supported by the compiler.

CROSS COMPILING
       If  cmake(1)  is	 invoked  with	the  command   line   parameter	  -DC-
       MAKE_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	archi-
       tecture 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.	   For
       toolchains that do not support linking binaries without custom flags or
       scripts	one  may  set  the  CMAKE_TRY_COMPILE_TARGET_TYPE  variable to
       STATIC_LIBRARY to tell CMake not	to try to link executables during  its
       checks.

       CMake   find_*	commands   will	  look	 in   the   sysroot,  and  the
       CMAKE_FIND_ROOT_PATH entries by default in all cases, as	well as	 look-
       ing 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. Gen-
       erally, 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  -DC-
       MAKE_SYSTEM_NAME=CrayLinuxEnvironment  on  the  CMake command line will
       ensure that the appropriate build settings and search paths are config-
       ured.   The platform will pull its configuration	from the current envi-
       ronment 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 li-
       braries enabled by setting the CRAYPE_LINK_TYPE environment variable to
       dynamic.

       Running CMake without specifying	CMAKE_SYSTEM_NAME will run the config-
       ure 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  sup-
       ported 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  ex-
       ternal  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 com-
       piler.  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 in-
       stalled on your system.	These SDKs are usually installed under C:/Pro-
       gram 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 Win-
       dows 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 Win-
       dows Phone.  Specify the	CMAKE_SYSTEM_VERSION variable to  be  10.0  to
       build  with  the	 latest	available Windows 10 SDK.  Specify a more spe-
       cific version (e.g. 10.0.10240.0	for RTM) to build with the correspond-
       ing 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 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 to be installed.	See that section for further  configu-
       ration details.

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

       o NDK

       o Standalone Toolchain

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

       o If the	CMAKE_ANDROID_NDK variable is set, the NDK  at	the  specified
	 location will be used.

       o Else,	if the CMAKE_ANDROID_STANDALONE_TOOLCHAIN variable is set, the
	 Standalone Toolchain at the specified location	will be	used.

       o Else, if the CMAKE_SYSROOT variable is	set to a directory of the form
	 <ndk>/platforms/android-<api>/arch-<arch>,  the  <ndk>	 part  will be
	 used as the value of CMAKE_ANDROID_NDK	and the	NDK will be used.

       o Else, if the CMAKE_SYSROOT variable is	set to a directory of the form
	 <standalone-toolchain>/sysroot,  the <standalone-toolchain> part will
	 be used as the	value of  CMAKE_ANDROID_STANDALONE_TOOLCHAIN  and  the
	 Standalone Toolchain will be used.

       o Else,	if  a cmake variable ANDROID_NDK is set	it will	be used	as the
	 value of CMAKE_ANDROID_NDK, and the NDK will be used.

       o Else, if a cmake variable  ANDROID_STANDALONE_TOOLCHAIN  is  set,  it
	 will  be used as the value of CMAKE_ANDROID_STANDALONE_TOOLCHAIN, and
	 the Standalone	Toolchain will be used.

       o Else, if an environment variable ANDROID_NDK_ROOT or  ANDROID_NDK  is
	 set,  it  will	be used	as the value of	CMAKE_ANDROID_NDK, and the NDK
	 will be used.

       o Else, if an environment variable ANDROID_STANDALONE_TOOLCHAIN is  set
	 then	it   will   be	used  as  the  value  of  CMAKE_ANDROID_STAND-
	 ALONE_TOOLCHAIN, and the Standalone Toolchain will be used.

       o Else, an error	diagnostic will	be issued  that	 neither  the  NDK  or
	 Standalone Toolchain can be found.

   Cross Compiling for Android with the	NDK
       A toolchain file	may configure Makefile Generators or the Ninja genera-
       tor to target Android for cross-compiling.

       Configure use of	an Android NDK with the	following variables:

       CMAKE_SYSTEM_NAME
	      Set to Android.  Must be specified to enable cross compiling for
	      Android.

       CMAKE_SYSTEM_VERSION
	      Set  to  the  Android API	level.	If not specified, the value is
	      determined as follows:

	      o	If the CMAKE_ANDROID_API variable is set, its value is used as
		the API	level.

	      o	If  the	 CMAKE_SYSROOT	variable  is set, the API level	is de-
		tected from the	NDK directory structure	 containing  the  sys-
		root.

	      o	Otherwise, the latest API level	available in the NDK is	used.

       CMAKE_ANDROID_ARCH_ABI
	      Set  to  the Android ABI (architecture).	If not specified, this
	      variable will default to armeabi.	 The CMAKE_ANDROID_ARCH	 vari-
	      able will	be computed from CMAKE_ANDROID_ARCH_ABI	automatically.
	      Also see the CMAKE_ANDROID_ARM_MODE  and	CMAKE_ANDROID_ARM_NEON
	      variables.

       CMAKE_ANDROID_NDK
	      Set  to  the absolute path to the	Android	NDK root directory.  A
	      ${CMAKE_ANDROID_NDK}/platforms directory	must  exist.   If  not
	      specified,  a default for	this variable will be chosen as	speci-
	      fied above.

       CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
	      Set 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.

       CMAKE_ANDROID_STL_TYPE
	      Set to specify which C++ standard	library	to use.	 If not	speci-
	      fied,  a	default	 will be selected as described in the variable
	      documentation.

       The following variables will be computed	and provided automatically:

       CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
	      The absolute path	prefix to the binutils in the NDK toolchain.

       CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
	      The host platform	suffix of the binutils in the NDK toolchain.

       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 genera-
       tor to target Android for cross-compiling using a standalone toolchain.

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

       CMAKE_SYSTEM_NAME
	      Set to Android.  Must be specified to enable cross compiling for
	      Android.

       CMAKE_ANDROID_STANDALONE_TOOLCHAIN
	      Set to the absolute path to the standalone toolchain root	direc-
	      tory.  A ${CMAKE_ANDROID_STANDALONE_TOOLCHAIN}/sysroot directory
	      must  exist.  If not specified, a	default	for this variable will
	      be chosen	as specified above.

       CMAKE_ANDROID_ARM_MODE
	      When the standalone toolchain targets ARM, optionally  set  this
	      to  ON  to target	32-bit ARM instead of 16-bit Thumb.  See vari-
	      able documentation for details.

       CMAKE_ANDROID_ARM_NEON
	      When the standalone toolchain targets  ARM  v7,  optionally  set
	      thisto  ON  to target ARM	NEON devices.  See variable documenta-
	      tion for details.

       The following variables will be computed	and provided automatically:

       CMAKE_SYSTEM_VERSION
	      The Android API level detected from the standalone toolchain.

       CMAKE_ANDROID_ARCH_ABI
	      The Android ABI detected from the	standalone toolchain.

       CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
	      The absolute path	prefix	to  the	 binutils  in  the  standalone
	      toolchain.

       CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
	      The  host	 platform  suffix  of  the  binutils in	the standalone
	      toolchain.

       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:

       o ANDROID_ANT_ADDITIONAL_OPTIONS

       o ANDROID_API_MIN

       o ANDROID_API

       o ANDROID_ARCH

       o ANDROID_ASSETS_DIRECTORIES

       o ANDROID_GUI

       o ANDROID_JAR_DEPENDENCIES

       o ANDROID_JAR_DIRECTORIES

       o ANDROID_JAVA_SOURCE_DIR

       o ANDROID_NATIVE_LIB_DEPENDENCIES

       o ANDROID_NATIVE_LIB_DIRECTORIES

       o ANDROID_PROCESS_MAX

       o ANDROID_PROGUARD_CONFIG_PATH

       o ANDROID_PROGUARD

       o ANDROID_SECURE_PROPS_PATH

       o ANDROID_SKIP_ANT_STEP

       o ANDROID_STL_TYPE

COPYRIGHT
       2000-2017 Kitware, Inc. and Contributors

3.8.2				 Jul 02, 2017		   CMAKE-TOOLCHAINS(7)

NAME | INTRODUCTION | LANGUAGES | VARIABLES AND PROPERTIES | TOOLCHAIN FEATURES | CROSS COMPILING | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cmake-toolchains&sektion=7&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help