cmake-toolchains(7)

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

Введение

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

Языки

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

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

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

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

По умолчанию среда программирования Cray поддерживает только статические библиотеки. Это можно изменить и включить динамические библиотеки, установив переменную среды 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 компилятор 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.

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

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

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

Файл toolchain может настроить генераторы 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

Устанавливается до Android ABI (архитектура). Если не указано, по умолчанию эта переменная будет установлена в 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.9/manual/cmake-toolchains.7.html