cmake工具鏈

命令
project()
enable_language()
try_compile()

變量
CMAKE_<LANG>_COMPILER
CMAKE_<LANG>_COMPILER_ID
CMAKE_<LANG>_COMPILER_VERSION
CMAKE_<LANG>_FLAGS
CMAKE_TOOLCHAIN_FILE
CMAKE_CROSSCOMPILING
CMAKE_SYSTEM_NAME
CMAKE_SYSTEM_PROCESSOR
CMAKE_SYSROOT
CMAKE_STAGING_PREFIX
CMAKE_FIND_ROOT_PATH
find_*
CMAKE_FIND_ROOT_PATH_MODE_*
CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN
CMAKE_<LANG>_COMPILER_TARGET
CMAKE_GENERATOR_PLATFORM
CMAKE_SYSTEM_VERSION
CMAKE_GENERATOR_TOOLSET

屬性
ENABLED_LANGUAGES
LINKER_LANGUAGE
POSITION_INDEPENDENT_CODE
<LANG>_VISIBILITY_PRESET
VISIBILITY_INLINES_HIDDEN

宏
CheckCXXSourceCompiles
CheckCXXSymbolExists
CheckIncludeFile

一些參考
CMAKE_CXX_COMPILER
CMAKE_CXX_COMPILER_ID
CMAKE_CXX_COMPILER_TARGET
CMAKE_C_COMPILER
CMAKE_CXX_COMPILER_ID
CMAKE_CXX_COMPILER_TARGET
CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
CMAKE_FIND_ROOT_PATH_MODE_PACKAGE

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.

CMake使用(實用工具)工具鏈編譯、連接庫和建立歸檔，和其它任務去驅動構建。啓用的(編程)語言決定工具鏈工具。在常規構建中，CMake基於系統自檢和缺省自動爲宿主構建決定工具鏈。在交叉編譯的狀況下，能夠經過相關的編譯器和工具路徑來指定工具鏈文件。

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()命令啓用的。指定語言的內置變量(如CMAKE_CXX_COMPILER\CMAKE_CXX_COMPILER_ID等)在調用project()命令時被設置。若是在頂層的CMakeLists文件中沒有project()命令，將生成一個隱式的。缺省啓用的語言是C和CXX：

project(C_Only C)

A special value of NONE can also be used with the project() command to enable no languages:
在 project() 命令中指定 NONE 將不啓用任何語言：

project(MyProject NONE)

The enable_language() command can be used to enable languages after the project() command:
在 project() 命令以後，可使用 enable_language() 命令來啓用語言:

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.

當一個語言被啓用，CMake爲該語言查找編譯器，決定一些信息，如編譯器的供應商和版本，目標架構和位寬，相應工具的位置等。

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

全局屬性ENABLED_LANGUAGES包含當前啓用的語言。

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.

幾個關於工具鏈條的語言組件的變量被啓用。CMAKE_<LANG>_COMPILER 是用於 <LANG> 編譯器的全路徑。CMake使用 CMAKE_<LANG>_COMPILER_ID 做爲編譯器識別，CMAKE_<LANG>_COMPILER_VERSION 是編譯器的版本。

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.

CMAKE_<LANG>_FLAGS 變量和對應的具體配置包含將被添加到編譯命令的標誌，在特定語言編譯文件時。

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.

鏈接器被編譯驅動器調用。CMake須要一個方法去決定使用哪一個編譯器去調用連接器。這個經過目標中的源文件的語言來計算，在靜態庫的狀況下，也經過依賴庫的語言來計算。CMake作出的選擇可能被目標屬性 LINKER_LANGUAGE 重寫。

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.

CMake提供 try_compile() 命令和宏測試各類工具鏈功能的性能和有效性，好比 CheckCXXSourceCompiles, CheckCXXSymbolExists 和 CheckIncludeFile。這些 API 測試工具鏈使用一些方法和緩存結果，使測試不必定在下一次CMake運行時再次被執行。

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.

一些工具鏈功能在CMake中有內置處理，不請求編譯測試。例如，POSITION_INDEPENDENT_CODE 容許指定目標被構建做爲位置無關代碼，若是編譯器支持此項特性。目標屬性 <LANG>_VISIBILITY_PRESET 和 VISIBILITY_INLINES_HIDDEN 添加標誌以隱藏可見性，若是編譯器支持此功能。

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.

若是cmake被調用攜帶命令行參數 -DCMAKE_TOOLCHAIN_FILE=path/to/file，文件將被提早加載覺得編譯器設置值。在交叉編譯時CMAKE_CROSSCOMPILING變量將被設置爲真值。

Cross Compiling for Linux

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

一個典型的linux下的交叉編譯工具鏈內容以下：

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.

CMAKE_SYSTEM_NAME 是將要構建的目標平臺的CMake識別。

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

CMAKE_SYSTEM_PROCESSOR 是將要構建的目標架構的CMake識別。

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

CMAKE_SYSROOT 是一個選項，在sysroot有效時被指定。

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.

CMAKE_STAGING_PREFIX 也是一個選項。能夠指定宿主機的安裝路徑。CMAKE_INSTALL_PREFIX指定運行時安裝位置，即時在交叉編譯環境下。

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_<LANG>_COMPILER 變量能夠是全路徑，或者是編譯器將要查找的標準位置。一旦CMake不能從編譯器提取到足夠的信息，CMakeForceCompiler 模塊能夠作一些旁路檢查。

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.

find_*命令將在sysroot中查找，CMAKE_FIND_ROOT_PATH 在全部狀況下是缺省的條目，包括查找宿主系統的根前綴。雖然基於不一樣的狀況這能夠被控制，當交叉編譯時，它在排除查找主機或者特定工件的目標時是有用的。一般，包含文件，庫文件和包在目標系統預處理時被發現，而那些做爲構建的一部分的必須運行的可執行程序僅僅在宿主和非目標上被發現。這是 CMAKE_FIND_ROOT_PATH_MODE_* 變量的目的。

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:

一些編譯器是交叉編譯固有的，如 Clang。當編譯時，能夠設置 CMAKE_<LANG>_COMPILER_TARGET 去傳遞值到支持的編譯器：

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.
一樣，有些編譯器不傳送他們本身的輔助工具，像鏈接器啊，可是提供方法來指定外部工具鏈的位置供編譯驅動器使用。能夠在工具鏈文件設置 CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN 變量去傳遞路徑給編譯驅動。

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:

像Clang編譯器同樣，QNX QCC 編譯器也是一個跨平臺編譯器。當編譯時，能夠設置 CMAKE_<LANG>_COMPILER_TARGET 去傳遞值到支持的編譯器：

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.

Windows CE的跨平臺編譯須要系統上裝有對應的SDK。這些SDK一般安裝在 C:/Program Files (x86)/Windows CE Tools/SDKs 。

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

爲 Windows CE 配置 Visual Studio 生成器的工具鏈文件，以下：

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.

CMAKE_GENERATOR_PLATFORM 告訴生成器使用哪個SDK。此外CMAKE_SYSTEM_VERSION告訴生成器Windows CE的版本。目前版本8.0(Windows Embedded Compact 2013)支持即開即用。其它版本可能須要給 CMAKE_GENERATOR_TOOLSET 設置正確的值。

Cross Compiling for Windows Phone

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

爲 Windows Phone 配置 Visual Studio 生成器的工具鏈文件，以下：

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:

爲 Windows Store 配置 Visual Studio 生成器的工具鏈文件，以下：

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:

使用 NVIDIA Nsight Tegra 的 Android，配置 Visual Studio 生成器的工具鏈文件以下：

set(CMAKE_SYSTEM_NAME Android)

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

能夠設置 CMAKE_GENERATOR_TOOLSET 爲 Nsight Tegra 「Toolchain Version」 值。

See the ANDROID_API_MIN, ANDROID_API and ANDROID_GUI target properties to configure targets within the project.

參考 ANDROID_API_MIN，ANDROID_API 和 ANDROID_GUI 目標屬性配置項目內的目標。