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})

Аналогично, некоторые компиляторы не поставляют собственных вспомогательных утилит, таких как компоновщики, но предоставляют способ указать расположение внешнего toolchain, который будет использоваться драйвером компилятора. Переменная 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, будет использоваться 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, и будет использован Standalone Toolchain.
В противном случае, если установлена переменная cmake ANDROID_NDK, она будет использоваться в качестве значения CMAKE_ANDROID_NDK, и будет использован NDK.
В противном случае, если установлена переменная cmake ANDROID_STANDALONE_TOOLCHAIN, она будет использоваться в качестве значения CMAKE_ANDROID_STANDALONE_TOOLCHAIN, и будет использован Standalone Toolchain.
В противном случае, если установлена переменная окружения ANDROID_NDK_ROOT или ANDROID_NDK, она будет использоваться в качестве значения CMAKE_ANDROID_NDK, и будет использован NDK.
В противном случае, если установлена переменная окружения ANDROID_STANDALONE_TOOLCHAIN, она будет использоваться в качестве значения CMAKE_ANDROID_STANDALONE_TOOLCHAIN, и будет использован Standalone Toolchain.
В противном случае будет выдано сообщение об ошибке, что ни NDK, ни Standalone Toolchain не найдены.

Кросс-компиляция для 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

Установлено в 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_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.

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

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.7/manual/cmake-toolchains.7.html