WriteCompilerDetectionHeader

Этот модуль предоставляет функцию write_compiler_detection_header().

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

write_compiler_detection_header(
          FILE <file>
          PREFIX <prefix>
          [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
          COMPILERS <compiler> [...]
          FEATURES <feature> [...]
          [BARE_FEATURES <feature> [...]]
          [VERSION <version>]
          [PROLOG <prolog>]
          [EPILOG <epilog>]
          [ALLOW_UNKNOWN_COMPILERS]
          [ALLOW_UNKNOWN_COMPILER_VERSIONS]
)

Это генерирует файл <file> с макросами, у которых все имеют префикс <prefix>.

По умолчанию, всё содержимое записывается непосредственно в <file>. OUTPUT_FILES_VAR может быть указано, чтобы заставить содержимое, специфичное для компилятора, записываться в отдельные файлы. Эти отдельные файлы затем доступны в <output_files_var> и могут быть использованы вызывающей стороной для установки, например. OUTPUT_DIR указывает относительный путь от основного <file> к файлам, специфичным для компилятора. Например:

write_compiler_detection_header(
  FILE climbingstats_compiler_detection.h
  PREFIX ClimbingStats
  OUTPUT_FILES_VAR support_files
  OUTPUT_DIR compilers
  COMPILERS GNU Clang MSVC Intel
  FEATURES cxx_variadic_templates
)
install(FILES
  ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
  DESTINATION include
)
install(FILES
  ${support_files}
  DESTINATION include/compilers
)

VERSION может быть использовано для указания версии API, которая должна быть сгенерирована. Будущие версии CMake могут внедрить альтернативные API. Определённый API выбирается любым значением <version>, большим или равным версии CMake, которая представила данный API, и меньшим, чем версия CMake, представившая последующий API. Используется значение переменной CMAKE_MINIMUM_REQUIRED_VERSION, если явная версия не указана. (Начиная с версии CMake 3.14.7 существует только одна версия API.)

PROLOG может быть указано как текстовое содержимое, которое нужно записать в начале заголовка. EPILOG может быть указано как текстовое содержимое, которое нужно записать в конце заголовка.

Должны быть перечислены как минимум один <compiler> и один <feature>. Компиляторы, известные CMake, но не указанные, обнаруживаются, и для них генерируется препроцессор #error. Для каждого компилятора, известного CMake, генерируется макрос препроцессора, соответствующий <PREFIX>_COMPILER_IS_<compiler>, содержащий значение 0 или 1.

Возможные идентификаторы компиляторов документированы с переменной CMAKE_<LANG>_COMPILER_ID. Доступные возможности в этой версии CMake перечислены в глобальных свойствах CMAKE_C_KNOWN_FEATURES и CMAKE_CXX_KNOWN_FEATURES. Мета-возможности {c,cxx}_std_* игнорируются, если запрошены.

См. руководство cmake-compile-features(7) для информации о возможностях компиляции.

BARE_FEATURES определит макросы совместимости с именем, используемым в более новых версиях стандарта языка, поэтому код может использовать новое имя функции безусловно.

ALLOW_UNKNOWN_COMPILERS и ALLOW_UNKNOWN_COMPILER_VERSIONS заставляют модуль генерировать условия, которые рассматривают неизвестные компиляторы как просто лишенные всех возможностей. Без этих опций по умолчанию генерируется #error для неизвестных компиляторов и версий.

Макросы проверки возможностей

Для каждого компилятора генерируется макрос препроцессора, соответствующий <PREFIX>_COMPILER_IS_<compiler>, содержащий либо 0, либо 1, в зависимости от используемого компилятора. Макросы препроцессора для компонентов версии компилятора генерируются, соответствующие <PREFIX>_COMPILER_VERSION_MAJOR <PREFIX>_COMPILER_VERSION_MINOR и <PREFIX>_COMPILER_VERSION_PATCH, содержащие десятичные значения соответствующих компонентов версии компилятора, если они определены.

Генерируется проверка препроцессора на основе версии компилятора, обозначающая, включена ли каждая функция. Генерируется макрос препроцессора, соответствующий <PREFIX>_COMPILER_<FEATURE>, где <FEATURE> - это имя <feature> в верхнем регистре, который будет содержать значение 0 или 1, в зависимости от того, поддерживает ли используемый компилятор данную функцию:

write_compiler_detection_header(
  FILE climbingstats_compiler_detection.h
  PREFIX ClimbingStats
  COMPILERS GNU Clang AppleClang MSVC Intel
  FEATURES cxx_variadic_templates
)

#if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
template<typename... T>
void someInterface(T t...) { /* ... */ }
#else
// Compatibility versions
template<typename T1>
void someInterface(T1 t1) { /* ... */ }
template<typename T1, typename T2>
void someInterface(T1 t1, T2 t2) { /* ... */ }
template<typename T1, typename T2, typename T3>
void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
#endif

Макросы символов

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

class MyClass ClimbingStats_FINAL
{
    ClimbingStats_CONSTEXPR int someInterface() { return 42; }
};

Макрос ClimbingStats_FINAL будет раскрываться как final, если компилятор (и его флаги) поддерживает функцию cxx_final, а макрос ClimbingStats_CONSTEXPR будет раскрываться как constexpr, если cxx_constexpr поддерживается.

Если BARE_FEATURES cxx_final было передано в качестве аргумента, ключевое слово final будет определено и для старых компиляторов.

Следующие функции генерируют соответствующие определения символов, и если они доступны как BARE_FEATURES:

Макросы реализации совместимости

Некоторые функции подходят для обертывания в макрос с реализацией обратной совместимости, если компилятор не поддерживает данную функцию.

Когда функция cxx_static_assert не предоставляется компилятором, реализация обратной совместимости доступна через <PREFIX>_STATIC_ASSERT(COND) и <PREFIX>_STATIC_ASSERT_MSG(COND, MSG) макросы, похожие на функции. Макросы расширяются до static_assert, где данная функция компилятора доступна, и до реализации обратной совместимости в противном случае. В первом варианте условие строит в поле сообщения static_assert. Во втором варианте сообщение MSG передается в поле сообщения static_assert, или игнорируется, если используется реализация обратной совместимости.

Функция cxx_attribute_deprecated предоставляет определение макроса <PREFIX>_DEPRECATED, которое расширяется либо до стандартного атрибута [[deprecated]], либо до специфичной для компилятора декорации, такой как __attribute__((__deprecated__)), используемой компиляторами GNU.

Функция cxx_alignas предоставляет определение макроса <PREFIX>_ALIGNAS, которое расширяется либо до стандартной декорации alignas, либо до специфичной для компилятора декорации, такой как __attribute__ ((__aligned__)), используемой компиляторами GNU.

Функция cxx_alignof предоставляет определение макроса <PREFIX>_ALIGNOF, которое расширяется либо до стандартной декорации alignof, либо до специфичной для компилятора декорации, такой как __alignof__, используемой компиляторами GNU.

Случай использования, который возникает с такими макросами устаревания, заключается в устаревании целой библиотеки. В этом случае все публичные API в библиотеке могут быть помечены макросом <PREFIX>_DEPRECATED. Это приводит к очень шумному выводу сборки при сборке самой библиотеки, поэтому макрос может быть определен как пустой в этом случае при сборке устаревшей библиотеки:

add_library(compat_support ${srcs})
target_compile_definitions(compat_support
  PRIVATE
    CompatSupport_DEPRECATED=
)