cmake-toolchains(7)

Введение
Языки
Переменные и свойства
Возможности цепочки инструментов
Перекрёстная компиляция

Введение

CMake использует цепочку инструментов для компиляции, компоновки библиотек, создания архивов и выполнения других задач для управления сборкой. Доступные инструменты цепочки инструментов определяются включёнными языками. В обычных сборках CMake автоматически определяет цепочку инструментов для хостовых сборок на основе интроспекции системы и значений по умолчанию. В сценариях перекрёстной компиляции может быть указан файл цепочки инструментов с информацией о путях компиляторов и утилит.

Языки

Языки включаются командой project(). Языковые встроенные переменные, такие как CMAKE_CXX_COMPILER, CMAKE_CXX_COMPILER_ID и т. д. устанавливаются путём вызова команды project(). Если в файле CMakeLists верхнего уровня нет команды project, она будет сгенерирована неявно. По умолчанию включены языки C и CXX:

project(C_Only C)

Также можно использовать специальное значение NONE с командой project(), чтобы не включать языки:

project(MyProject NONE)

Команда enable_language() может быть использована для включения языков после команды project():

enable_language(CXX)

При включении языка CMake находит компилятор для этого языка и определяет некоторую информацию, такую как поставщик и версия компилятора, целевая архитектура и разрядность, расположение соответствующих утилит и т. д.

Глобальное свойство ENABLED_LANGUAGES содержит языки, которые в настоящее время включены.

Переменные и свойства

Несколько переменных относятся к языковым компонентам цепочки инструментов, которые включены. CMAKE_<LANG>_COMPILER — это полный путь к компилятору, используемому для <LANG>. CMAKE_<LANG>_COMPILER_ID — это идентификатор, используемый CMake для компилятора, а CMAKE_<LANG>_COMPILER_VERSION — версия компилятора.

Переменные CMAKE_<LANG>_FLAGS и соответствующие им переменные, зависящие от конфигурации, содержат флаги, которые будут добавлены к команде компиляции при компиляции файла определённого языка.

Так как компоновщик вызывается драйвером компилятора, CMake должен каким-то образом определить, какой компилятор использовать для вызова компоновщика. Это вычисляется по свойству LANGUAGE файлов исходного кода в целевом объекте, а в случае статических библиотек — по языку зависимых библиотек. Выбор, сделанный CMake, можно переопределить с помощью свойства целевого объекта LINKER_LANGUAGE.

Возможности цепочки инструментов

CMake предоставляет команду try_compile() и макросы-обёртки, такие как CheckCXXSourceCompiles, CheckCXXSymbolExists и CheckIncludeFile, для тестирования возможностей и доступности различных функций цепочки инструментов. Эти API тестируют цепочку инструментов каким-либо образом и кэшируют результат, чтобы тест не нужно было проводить повторно при следующем запуске CMake.

Некоторые возможности цепочки инструментов имеют встроенную обработку в CMake и не требуют проверочной компиляции. Например, POSITION_INDEPENDENT_CODE позволяет указать, что целевой объект должен быть скомпилирован как позиционно-независимый код, если компилятор поддерживает эту функцию. Свойства целевого объекта <LANG>_VISIBILITY_PRESET и VISIBILITY_INLINES_HIDDEN добавляют флаги для скрытой видимости, если это поддерживается компилятором.

Перекрёстная компиляция

Если cmake(1) вызывается с параметром командной строки -DCMAKE_TOOLCHAIN_FILE=path/to/file, файл будет загружен на ранней стадии, чтобы установить значения для компиляторов. Переменная CMAKE_CROSSCOMPILING устанавливается в true, когда CMake выполняет перекрёстную компиляцию.

Перекрёстная компиляция для Linux

Типичная цепочка инструментов для перекрёстной компиляции для 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)

Переменная CMAKE_SYSTEM_NAME — идентификатор CMake целевой платформы, для которой ведётся сборка.

Переменная CMAKE_SYSTEM_PROCESSOR — идентификатор CMake целевой архитектуры, для которой ведётся сборка.

Переменная CMAKE_SYSROOT необязательна и может быть указана, если доступен sysroot.

Переменная CMAKE_STAGING_PREFIX также необязательна. Она может использоваться для указания пути на хост-системе для установки. Переменная CMAKE_INSTALL_PREFIX всегда указывает на место установки времени выполнения, даже при перекрёстной компиляции.

Переменные CMAKE_<LANG>_COMPILER могут быть установлены в полные пути или имена компиляторов для поиска в стандартных расположениях. Для цепочек инструментов, которые не поддерживают компоновку бинарных файлов без пользовательских флагов или скриптов, можно установить переменную CMAKE_TRY_COMPILE_TARGET_TYPE в значение STATIC_LIBRARY, чтобы сообщить CMake о том, что не нужно пытаться компоновать исполняемые файлы во время проверок.

Команды CMake find_* будут искать в sysroot и в CMAKE_FIND_ROOT_PATH по умолчанию во всех случаях, а также в префиксе корневой системы хоста. Хотя это можно контролировать в каждом конкретном случае, при кросс-компиляции может быть полезно исключить поиск в хост- или целевой системе для определенных артефактов. Как правило, заголовочные файлы, библиотеки и пакеты должны находиться в префиксах целевой системы, а исполняемые файлы, которые должны запускаться в рамках сборки, должны находиться только в префиксе хост-системы, а не целевой. Для этого предназначены переменные CMAKE_FIND_ROOT_PATH_MODE_*.

Кросс-компиляция для среды Cray Linux

Кросс-компиляция для вычислительных узлов в среде Cray Linux может быть выполнена без необходимости отдельного файла с инструментом. Указание -DCMAKE_SYSTEM_NAME=CrayLinuxEnvironment в командной строке CMake обеспечит конфигурацию соответствующих настроек сборки и путей поиска. Платформа будет получать конфигурацию из текущих переменных среды и настраивать проект для использования оболочек компилятора из модулей PrgEnv-* среды Cray Programming Environment, если они присутствуют и загружены.

По умолчанию среда Cray Programming Environment поддерживает только статические библиотеки. Это можно изменить и включить динамические библиотеки, установив переменную среды CRAYPE_LINK_TYPE в значение dynamic.

Запуск CMake без указания CMAKE_SYSTEM_NAME выполнит этап конфигурации в режиме хоста, предполагая стандартную среду Linux. Если не переопределено, будут использованы оболочки компилятора PrgEnv-*, что, если целью является узел входа или вычислительный узел, скорее всего, не является желаемым поведением. Исключением является случай, если вы собираете непосредственно на узле NID, а не кросс-компилируете с узла входа. Если вы пытаетесь собрать программное обеспечение для узла входа, вам необходимо либо сначала разгрузить загруженный модуль PrgEnv-*, либо явно указать CMake использовать системные компиляторы в /usr/bin вместо оболочек Cray. Если вместо этого требуется целевой вычислительный узел, просто укажите CMAKE_SYSTEM_NAME, как указано выше.

Кросс-компиляция с использованием Clang

Некоторые компиляторы, такие как 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})

Аналогично, некоторые компиляторы не поставляют собственных дополнительных утилит, таких как компоновщики, но предоставляют способ указать расположение внешней цепочки инструментов, которая будет использоваться драйвером компилятора. Переменная CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN может быть установлена в файле цепочки инструментов для передачи пути к драйверу компилятора.

Кросс-компиляция для QNX

Как и компилятор Clang, компилятор QCC QNX является встроенным кросс-компилятором. И переменную 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})

Кросс-компиляция для Windows CE

Кросс-компиляция для Windows CE требует, чтобы соответствующий SDK был установлен на вашей системе. Обычно эти SDK устанавливаются в C:/Program Files (x86)/Windows CE Tools/SDKs.

Файл цепочки инструментов для настройки генератора Visual Studio для Windows CE может выглядеть так:

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)

Переменная CMAKE_GENERATOR_PLATFORM сообщает генератору, какой SDK использовать. Дальнейшая переменная CMAKE_SYSTEM_VERSION сообщает генератору, какую версию Windows CE использовать. В настоящее время поддерживается версия 8.0 (Windows Embedded Compact 2013). Для других версий может потребоваться установить CMAKE_GENERATOR_TOOLSET в нужное значение.

Кросс-компиляция для универсальных приложений Windows 10

Файл цепочки инструментов для настройки генератора Visual Studio для универсального приложения Windows 10 может выглядеть так:

set(CMAKE_SYSTEM_NAME WindowsStore)
set(CMAKE_SYSTEM_VERSION 10.0)

Универсальное приложение Windows 10 предназначено как для Магазина Windows, так и для Windows Phone. Установите переменную CMAKE_SYSTEM_VERSION в значение 10.0, чтобы собрать с последней доступной версией Windows 10 SDK. Укажите более конкретную версию (например, 10.0.10240.0 для RTM), чтобы собрать с соответствующим SDK.

Кросс-компиляция для Windows Phone

Файл цепочки инструментов для настройки генератора Visual Studio для Windows Phone может выглядеть так:

set(CMAKE_SYSTEM_NAME WindowsPhone)
set(CMAKE_SYSTEM_VERSION 8.1)

Кросс-компиляция для Магазина Windows

Файл цепочки инструментов для настройки генератора Visual Studio для Магазина Windows может выглядеть так:

set(CMAKE_SYSTEM_NAME WindowsStore)
set(CMAKE_SYSTEM_VERSION 8.1)

Кросс-компиляция для Android

Файл цепочки инструментов может настроить кросс-компиляцию для Android, установив переменную CMAKE_SYSTEM_NAME в значение Android. Дальнейшая настройка зависит от используемой среды разработки Android.

Для генераторов Visual Studio CMake ожидает установки NVIDIA Nsight Tegra Visual Studio Edition. Подробные сведения о настройке см. в этом разделе.

Для генераторов Makefile и генератора Ninja CMake ожидает одну из этих сред:

NDK
Отдельная цепочка инструментов

CMake выполняет следующие шаги для выбора одной из сред:

Если переменная CMAKE_ANDROID_NDK установлена, используется NDK по указанному расположению.
В противном случае, если переменная CMAKE_ANDROID_STANDALONE_TOOLCHAIN установлена, используется отдельная цепочка инструментов по указанному расположению.
В противном случае, если переменная CMAKE_SYSROOT установлена на каталог вида <ndk>/platforms/android-<api>/arch-<arch>, часть <ndk> будет использована как значение CMAKE_ANDROID_NDK, и будет использоваться NDK.
В противном случае, если переменная CMAKE_SYSROOT установлена на каталог вида <standalone-toolchain>/sysroot, часть <standalone-toolchain> будет использована как значение CMAKE_ANDROID_STANDALONE_TOOLCHAIN, и будет использоваться отдельная цепочка инструментов.
В противном случае, если переменная cmake ANDROID_NDK установлена, она будет использована как значение CMAKE_ANDROID_NDK, и будет использоваться NDK.
В противном случае, если переменная cmake ANDROID_STANDALONE_TOOLCHAIN установлена, она будет использована как значение CMAKE_ANDROID_STANDALONE_TOOLCHAIN, и будет использоваться отдельная цепочка инструментов.
В противном случае, если переменная среды ANDROID_NDK_ROOT или ANDROID_NDK установлена, она будет использована как значение CMAKE_ANDROID_NDK, и будет использоваться NDK.
В противном случае, если переменная среды ANDROID_STANDALONE_TOOLCHAIN установлена, она будет использована как значение CMAKE_ANDROID_STANDALONE_TOOLCHAIN, и будет использоваться отдельная цепочка инструментов.
В противном случае, будет выдано сообщение об ошибке, что ни NDK, ни отдельная цепочка инструментов не найдены.

Кросс-компиляция для Android с использованием NDK

Файл цепочки инструментов может настроить генераторы Makefile или генератор Ninja на целевую компиляцию для Android.

Настройка использования Android NDK с помощью следующих переменных:

CMAKE_SYSTEM_NAME

Установлено в Android. Необходимо указать для включения кросс-компиляции для Android.

CMAKE_SYSTEM_VERSION

Установлено на уровень API Android. Если не указано, значение определяется следующим образом:

Если переменная CMAKE_ANDROID_API установлена, её значение используется в качестве уровня API.
Если переменная CMAKE_SYSROOT установлена, уровень API определяется из структуры каталога NDK, содержащей sysroot.
В противном случае используется последний доступный уровень API в NDK.

CMAKE_ANDROID_ARCH_ABI

Установлено на ABI Android (архитектура). Если не указано, эта переменная по умолчанию будет armeabi. Переменная CMAKE_ANDROID_ARCH будет вычислена из CMAKE_ANDROID_ARCH_ABI автоматически. Также см. переменные CMAKE_ANDROID_ARM_MODE и CMAKE_ANDROID_ARM_NEON.

CMAKE_ANDROID_NDK

Установлено на абсолютный путь к корневому каталогу Android NDK. Должен существовать каталог ${CMAKE_ANDROID_NDK}/platforms. Если не указано, значение по умолчанию для этой переменной будет выбрано, как указано выше.

CMAKE_ANDROID_NDK_DEPRECATED_HEADERS

Установите в значение true, чтобы использовать устаревшие заголовки по уровню API вместо объединённых заголовков. Если не указано, значение по умолчанию будет false, за исключением случаев использования NDK, который не предоставляет объединённые заголовки.

CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION

Установите версию NDK toolchain, которая должна быть выбрана в качестве компилятора. Если не указано, значение по умолчанию — самая последняя доступная GCC toolchain.

CMAKE_ANDROID_STL_TYPE

Указывает, какую C++ стандартную библиотеку использовать. Если не указано, будет выбран параметр по умолчанию, как описано в документации к переменной.

Следующие переменные будут вычислены и предоставлены автоматически:

CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX: Абсолютный префикс пути к binutils в NDK toolchain.
CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX: Суффикс хост-платформы binutils в NDK toolchain.

Например, файл toolchain может содержать:

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)

Альтернативно, можно указать значения без файла toolchain:

$ 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

Кросс-компиляция для Android с автономной toolchain

Файл toolchain может настроить Генераторы Makefile или генератор Ninja для нацеливания на Android для кросс-компиляции с помощью автономной toolchain.

Настройка использования автономной toolchain Android с помощью следующих переменных:

CMAKE_SYSTEM_NAME: Установлено в Android. Необходимо указать для включения кросс-компиляции для Android.
CMAKE_ANDROID_STANDALONE_TOOLCHAIN: Установлено на абсолютный путь к корневому каталогу автономной toolchain. Должен существовать каталог ${CMAKE_ANDROID_STANDALONE_TOOLCHAIN}/sysroot. Если не указано, значение по умолчанию для этой переменной будет выбрано, как указано выше.
CMAKE_ANDROID_ARM_MODE: Когда автономная toolchain нацелена на ARM, можно установить это значение в ON для нацеливания на 32-битный ARM вместо 16-битного Thumb. Подробности см. в документации к переменной.
CMAKE_ANDROID_ARM_NEON: Когда автономная toolchain нацелена на ARM v7, можно установить это значение в ON для нацеливания на устройства с ARM NEON. Подробности см. в документации к переменной.

Следующие переменные будут вычислены и предоставлены автоматически:

CMAKE_SYSTEM_VERSION: Уровень API Android, определенный из автономной toolchain.
CMAKE_ANDROID_ARCH_ABI: ABI Android, определённый из автономной toolchain.
CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX: Абсолютный префикс пути к binutils в автономной toolchain.
CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX: Суффикс хост-платформы binutils в автономной toolchain.

Например, файл toolchain может содержать:

set(CMAKE_SYSTEM_NAME Android)
set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android-toolchain)

Альтернативно, можно указать значения без файла toolchain:

$ cmake ../src \
  -DCMAKE_SYSTEM_NAME=Android \
  -DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android-toolchain

Кросс-компиляция для Android с NVIDIA Nsight Tegra Visual Studio Edition

Файл toolchain для настройки одного из Генераторов Visual Studio для построения с помощью NVIDIA Nsight Tegra, нацеленного на Android, может выглядеть так:

set(CMAKE_SYSTEM_NAME Android)

Переменная CMAKE_GENERATOR_TOOLSET может быть установлена для выбора значения «Версии toolchain» Nsight Tegra.

См. также свойства целевых объектов:

© 2000–2019 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.13/manual/cmake-toolchains.7.html