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

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

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

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

CMAKE_SYSTEM_NAME

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

CMAKE_SYSTEM_VERSION

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

Если установлена переменная CMAKE_ANDROID_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 может быть установлена для выбора значения “Toolchain Version” Nsight Tegra.

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

Компиляция для iOS, tvOS или watchOS

Для кросс-компиляции для iOS, tvOS или watchOS рекомендуется генератор Xcode. Генераторы Unix Makefiles или Ninja также могут быть использованы, но они требуют от проекта обработки таких областей, как выбор целевого процессора и подпись кода.

Любая из трёх систем может быть целевой, установив переменную CMAKE_SYSTEM_NAME на значение из таблицы ниже. По умолчанию выбирается последняя версия Device SDK. Как и для всех платформ Apple, другой SDK (например, симулятор) может быть выбран установкой переменной CMAKE_OSX_SYSROOT, хотя это вряд ли потребуется (см. Переключение между устройством и симулятором ниже). Список доступных SDK можно получить, выполнив xcodebuild -showsdks.

ОС	CMAKE_SYSTEM_NAME	SDK устройства (по умолчанию)	SDK симулятора
iOS	iOS	iphoneos	iphonesimulator
tvOS	tvOS	appletvos	appletvsimulator
watchOS	watchOS	watchos	watchsimulator

Например, для создания конфигурации CMake для iOS достаточно следующей команды:

cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS

Переменная CMAKE_OSX_ARCHITECTURES может быть использована для установки архитектур как для устройства, так и для симулятора. Переменная CMAKE_OSX_DEPLOYMENT_TARGET может быть использована для установки целевой версии iOS/tvOS/watchOS.

Следующая конфигурация установит библиотеку iOS с 5 архитектурами и добавит флаги -miphoneos-version-min=9.3/-mios-simulator-version-min=9.3 в компилятор:

$ cmake -S. -B_builds -GXcode \
    -DCMAKE_SYSTEM_NAME=iOS \
    "-DCMAKE_OSX_ARCHITECTURES=armv7;armv7s;arm64;i386;x86_64" \
    -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \
    -DCMAKE_INSTALL_PREFIX=`pwd`/_install \
    -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO \
    -DCMAKE_IOS_INSTALL_COMBINED=YES

Пример:

# CMakeLists.txt
cmake_minimum_required(VERSION 3.14)
project(foo)
add_library(foo foo.cpp)
install(TARGETS foo DESTINATION lib)

Установка:

$ cmake --build _builds --config Release --target install

Проверка библиотеки:

$ lipo -info _install/lib/libfoo.a
Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64

$ otool -l _install/lib/libfoo.a | grep -A2 LC_VERSION_MIN_IPHONEOS
      cmd LC_VERSION_MIN_IPHONEOS
  cmdsize 16
  version 9.3

Подпись кода

Некоторые сборки артефактов для встроенных платформ Apple требуют обязательной подписи кода. Если используется генератор Xcode и требуется или желательно подписание кода, идентификатор разработчика может быть указан через переменную CMake CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM. Этот идентификатор разработчика будет включен в сгенерированный Xcode-проект. По умолчанию CMake избегает необходимости подписи кода во время внутренней фазы конфигурации (т. е. идентификатор компилятора и обнаружение функций).

Переключение между устройством и симулятором

При конфигурации для любой из встроенных платформ можно нацеливаться как на реальные устройства, так и на симулятор. Оба имеют свои отдельные SDK, но CMake поддерживает указание только одного SDK на фазе конфигурации. Это означает, что разработчик должен выбрать один из них во время конфигурации. При использовании генератора Xcode это ограничение менее существенно, поскольку Xcode по-прежнему позволяет создавать сборки для устройства или симулятора, даже если конфигурация была выполнена только для одного из них. Внутри Xcode IDE сборки выполняются для выбранной платформы «назначения». При создании сборки из командной строки желаемый SDK можно указать непосредственно, передав опцию -sdk подлежащему инструменту сборки (xcodebuild). Например:

$ cmake --build ... -- -sdk iphonesimulator

Обратите внимание, что проверки, выполненные во время конфигурации, выполнялись с SDK времени конфигурации и могут не соответствовать другим SDK. Команды, такие как find_package(), find_library() и т. д. хранят и используют детали только для настроенного SDK/платформы, поэтому они могут быть проблематичны, если требуется переключение между сборками устройства и симулятора. Следуйте следующим правилам, чтобы сделать работу с конфигурацией устройства + симулятора:

Используйте явный флаг компоновщика -l, например, target_link_libraries(foo PUBLIC "-lz")
Используйте явный флаг компоновщика -framework, например, target_link_libraries(foo PUBLIC "-framework CoreFoundation")
Используйте find_package() только для библиотек, установленных с функцией CMAKE_IOS_INSTALL_COMBINED

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