Spec-Zone.ru › CMake 3.16

cmake-compile-features(7)

  • Введение

  • Требования к функциям компиляции

    • Требование к стандартам языка
    • Доступность расширений компилятора
  • Необязательные функции компиляции
  • Условные параметры компиляции
  • Поддерживаемые компиляторы

Введение

Исходный код проекта может зависеть от наличия определенных функций компилятора или быть условным в зависимости от их наличия. Возникает три случая: Требования к функциям компиляции, Необязательные функции компиляции и Условные параметры компиляции.

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

Глобальные свойства CMAKE_C_KNOWN_FEATURES и CMAKE_CXX_KNOWN_FEATURES содержат все функции, известные CMake, независимо от поддержки компилятором данной функции. Переменные CMAKE_C_COMPILE_FEATURES и CMAKE_CXX_COMPILE_FEATURES содержат все функции, известные CMake как поддерживаемые компилятором, независимо от стандарта языка или флагов компиляции, необходимых для их использования.

Функции, известные CMake, обычно имеют ту же конвенцию именования, что и макросы тестирования функций Clang. Есть некоторые исключения, такие как CMake использует cxx_final и cxx_override вместо единственного cxx_override_control используемого Clang.

Обратите внимание, что нет отдельных свойств или переменных компиляции для языков OBJC или OBJCXX. Они основаны соответственно на C или C++, поэтому следует использовать свойства и переменные соответствующего базового языка.

Требования к функциям компиляции

Требования к функциям компиляции могут быть заданы с помощью команды target_compile_features(). Например, если целевой объект должен быть скомпилирован с поддержкой компилятором функции cxx_constexpr:

add_library(mylib requires_constexpr.cpp)
target_compile_features(mylib PRIVATE cxx_constexpr)

При обработке требования к функции cxx_constexpr, cmake(1) убедится, что используемый C++ компилятор поддерживает данную функцию и добавит необходимые флаги, такие как -std=gnu++11, к строкам компиляции файлов C++ в целевом объекте mylib. Будет выдано сообщение об ошибке, если компилятор не поддерживает функцию.

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

Эти флаги компиляции добавляются даже если компилятор поддерживает определённую функцию без флага. Например, GNU компилятор поддерживает вариативные шаблоны (с предупреждением), даже если используется -std=gnu++98. CMake добавит флаг -std=gnu++11, если cxx_variadic_templates указан как требование.

В приведенном выше примере mylib требует cxx_constexpr, когда он сам компилируется, но потребители mylib не обязаны использовать компилятор, поддерживающий cxx_constexpr. Если интерфейс mylib требует функции cxx_constexpr (или любой другой известной функции), это может быть указано с помощью подписей PUBLIC или INTERFACE команды target_compile_features():

add_library(mylib requires_constexpr.cpp)
# cxx_constexpr is a usage-requirement
target_compile_features(mylib PUBLIC cxx_constexpr)

# main.cpp will be compiled with -std=gnu++11 on GNU for cxx_constexpr.
add_executable(myexe main.cpp)
target_link_libraries(myexe mylib)

Требования к функциям оцениваются транзитивно, потребляя реализацию связи. См. cmake-buildsystem(7) для получения дополнительной информации о транзитивном поведении свойств сборки и требованиях к использованию.

Требование к стандартам языка

В проектах, использующих большое количество часто встречающихся функций из определенного стандарта языка (например, C++ 11), можно указать метафункцию (например, cxx_std_11), которая требует использование режима компилятора, по крайней мере, поддерживающего этот стандарт, но может быть и более новой версии. Это проще, чем указывать все функции по отдельности, но не гарантирует существование какой-либо конкретной функции. Диагностика использования неподдерживаемых функций будет отложена до времени компиляции.

Например, если функции C++ 11 широко используются в заголовочных файлах проекта, то клиенты должны использовать режим компилятора не ниже C++ 11. Это можно запросить с помощью кода:

target_compile_features(mylib PUBLIC cxx_std_11)

В этом примере CMake убедится, что компилятор будет вызван в режиме, по крайней мере, C++ 11 (или C++ 14, C++ 17, …), добавив необходимые флаги, такие как -std=gnu++11, при необходимости. Это относится к исходным кодам внутри mylib, а также к любым зависимостям (которые могут включать заголовочные файлы из mylib).

Доступность расширений компилятора

Поскольку свойство целевого объекта CXX_EXTENSIONS по умолчанию является ON, CMake по умолчанию использует расширенные варианты диалектов языка, такие как -std=gnu++11 вместо -std=c++11. Это свойство целевого объекта можно установить в OFF для использования нерасширенного варианта флага диалекта. Обратите внимание, что, поскольку большинство компиляторов по умолчанию включают расширения, это может привести к появлению проблем с кросс-платформенной совместимостью в пользовательском коде или в заголовочных файлах зависимостей сторонних разработчиков.

Необязательные функции компиляции

Функции компиляции могут быть предпочтительны, если доступны, без создания жестких требований. Например, библиотека может предоставить альтернативные реализации в зависимости от того, доступна ли функция cxx_variadic_templates:

#if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
template<int I, int... Is>
struct Interface;

template<int I>
struct Interface<I>
{
  static int accumulate()
  {
    return I;
  }
};

template<int I, int... Is>
struct Interface
{
  static int accumulate()
  {
    return I + Interface<Is...>::accumulate();
  }
};
#else
template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
struct Interface
{
  static int accumulate() { return I1 + I2 + I3 + I4; }
};
#endif

Такой интерфейс зависит от использования правильных определений препроцессора для функций компилятора. CMake может сгенерировать заголовочный файл, содержащий такие определения, используя модуль WriteCompilerDetectionHeader. Модуль содержит функцию write_compiler_detection_header, которая принимает параметры для управления содержимым сгенерированного заголовочного файла:

write_compiler_detection_header(
  FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
  PREFIX Foo
  COMPILERS GNU
  FEATURES
    cxx_variadic_templates
)

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

Для каждой функции, перечисленных в FEATURES, в заголовочный файл создается определение препроцессора и определяется как 1 или 0.

Кроме того, некоторые функции требуют дополнительных определений, например, функции cxx_final и cxx_override. Вместо использования в коде #ifdef, ключевое слово final абстрагируется символом, который определяется как final, эквивалентом, специфичным для компилятора, или пустой строкой. Таким образом, код C++ может быть написан для безусловного использования символа, а поддержка компилятора определяет, к чему он будет раскрыт:

struct Interface {
  virtual void Execute() = 0;
};

struct Concrete Foo_FINAL {
  void Execute() Foo_OVERRIDE;
};

В этом случае Foo_FINAL будет раскрываться как final, если компилятор поддерживает ключевое слово, или как пустая строка в противном случае.

В этом случае код CMake будет стремиться включить определенный стандарт языка, если он доступен от компилятора. Переменная свойства целевого объекта CXX_STANDARD может быть установлена на желаемый стандарт языка для определенного целевого объекта, а CMAKE_CXX_STANDARD может быть установлена для влияния на все последующие целевые объекты:

write_compiler_detection_header(
  FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
  PREFIX Foo
  COMPILERS GNU
  FEATURES
    cxx_final cxx_override
)

# Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
# which will expand to 'final' if the compiler supports the requested
# CXX_STANDARD.
add_library(foo foo.cpp)
set_property(TARGET foo PROPERTY CXX_STANDARD 11)

# Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
# which will expand to 'final' if the compiler supports the feature,
# even though CXX_STANDARD is not set explicitly.  The requirement of
# cxx_constexpr causes CMake to set CXX_STANDARD internally, which
# affects the compile flags.
add_library(foo_impl foo_impl.cpp)
target_compile_features(foo_impl PRIVATE cxx_constexpr)

Функция write_compiler_detection_header также создает совместимый код для других функций, у которых есть стандартные эквиваленты. Например, функция cxx_static_assert эмулируется шаблоном и абстрагируется функциями-макросами <PREFIX>_STATIC_ASSERT и <PREFIX>_STATIC_ASSERT_MSG.

Условные параметры компиляции

Библиотеки могут предоставлять совершенно разные заголовочные файлы в зависимости от запрошенных функций компилятора.

Например, заголовочный файл по адресу with_variadics/interface.h может содержать:

template<int I, int... Is>
struct Interface;

template<int I>
struct Interface<I>
{
  static int accumulate()
  {
    return I;
  }
};

template<int I, int... Is>
struct Interface
{
  static int accumulate()
  {
    return I + Interface<Is...>::accumulate();
  }
};

в то время как заголовочный файл по адресу no_variadics/interface.h может содержать:

template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
struct Interface
{
  static int accumulate() { return I1 + I2 + I3 + I4; }
};

Возможным было бы написать абстрактный заголовочный файл interface.h, содержащий что-то вроде:

#include "foo_compiler_detection.h"
#if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
#include "with_variadics/interface.h"
#else
#include "no_variadics/interface.h"
#endif

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

END_OF_DOCUMENT_MARKER

CMake предоставляет COMPILE_FEATURES generator expression для реализации таких условий. Это можно использовать с командами свойств сборки, такими как target_include_directories() и target_link_libraries() для установки соответствующих свойств buildsystem:

add_library(foo INTERFACE)
set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics)
set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics)
target_include_directories(foo
  INTERFACE
    "$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>"
    "$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>"
  )

Потребительский код затем просто подключается к целевому объекту foo как обычно и использует соответствующий включаемый каталог.

add_executable(consumer_with consumer_with.cpp)
target_link_libraries(consumer_with foo)
set_property(TARGET consumer_with CXX_STANDARD 11)

add_executable(consumer_no consumer_no.cpp)
target_link_libraries(consumer_no foo)

Поддерживаемые компиляторы

CMake в настоящее время осведомлён о C++ standards и compile features, доступных от следующих compiler ids по состоянию на указанные версии:

  • AppleClang: Apple Clang для Xcode версий 4.4+.
  • Clang: Компилятор Clang версий 2.9+.
  • GNU: GNU компилятор версий 4.4+.
  • MSVC: Microsoft Visual Studio версии 2010+.
  • SunPro: Oracle SolarisStudio версии 12.4+.
  • Intel: Intel компилятор версий 12.1+.

CMake в настоящее время осведомлён о C standards и compile features, доступных от следующих compiler ids по состоянию на указанные версии:

  • все компиляторы и версии, перечисленные выше для C++.
  • GNU: GNU компилятор версий 3.4+.

CMake в настоящее время осведомлён о C++ standards и их связанных мета-функциях (например, cxx_std_11) доступных от следующих compiler ids по состоянию на указанные версии:

  • Cray: Cray Compiler Environment версии 8.1+.
  • PGI: PGI версии 12.10+.
  • XL: IBM XL версии 10.1+.

CMake в настоящее время осведомлён о C standards и их связанных мета-функциях (например, c_std_99) доступных от следующих compiler ids по состоянию на указанные версии:

  • все компиляторы и версии, перечисленные выше, с мета-функциями только для C++.
  • TI: Компилятор Texas Instruments.

CMake в настоящее время осведомлён о CUDA standards от следующих compiler ids по состоянию на указанные версии:

  • NVIDIA: Компилятор NVIDIA nvcc 7.5+.

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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API