cmake-toolchains(7)

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

Введение

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

Языки

Языки включаются командой project(). Языковые встроенные переменные, такие как CMAKE_CXX_COMPILER, CMAKE_CXX_COMPILER_ID и т. д., устанавливаются при вызове команды project(). Если команда project отсутствует в файле CMakeLists верхнего уровня, она будет неявно сгенерирована. По умолчанию включены языки 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 может быть выполнена без необходимости отдельного файла toolchain. Указание -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 может быть установлена в файле 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.

Файл toolchain для настройки генератора 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

Файл toolchain для настройки генератора 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

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

set(CMAKE_SYSTEM_NAME WindowsPhone)
set(CMAKE_SYSTEM_VERSION 8.1)

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

Файл toolchain для настройки генератора Visual Studio для Магазина Windows может выглядеть следующим образом:

set(CMAKE_SYSTEM_NAME WindowsStore)
set(CMAKE_SYSTEM_VERSION 8.1)

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

Файл toolchain может настроить кросс-компиляцию для 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, которая будет выбрана в качестве компилятора. Если не указано, по умолчанию будет использована последняя доступная инструментальная цепочка GCC.

CMAKE_ANDROID_STL_TYPE

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

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

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

Например, файл конфигурации инструментальной цепочки может содержать:

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)

В качестве альтернативы, значения можно указать без файла конфигурации инструментальной цепочки:

$ 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 с автономной инструментальной цепочкой

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

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

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

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

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

Например, файл конфигурации инструментальной цепочки может содержать:

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

В качестве альтернативы, значения можно указать без файла конфигурации инструментальной цепочки:

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

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

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

set(CMAKE_SYSTEM_NAME Android)

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

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

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