cmake-toolchains(7)

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

Введение

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

Языки

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

project(C_Only C)

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

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 не пытаться компоновать исполняемые файлы во время проверок.

END_OF_DOCUMENT_MARKER

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

Кросс-компиляция для 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 Store, так и на Windows Phone. Установите переменную CMAKE_SYSTEM_VERSION в 10.0, чтобы скомпилировать с использованием последней доступной версии SDK Windows 10. Установите более конкретную версию (например, 10.0.10240.0 для RTM), чтобы скомпилировать с соответствующим SDK.

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

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

set(CMAKE_SYSTEM_NAME WindowsPhone)
set(CMAKE_SYSTEM_VERSION 8.1)

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

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

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

Устанавливается в истинное значение, чтобы использовать устаревшие заголовки на уровне API вместо объединённых заголовков. Если не указано, значение по умолчанию будет ложным, если не используется 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.11/manual/cmake-toolchains.7.html