Spec-Zone.ru › CMake 3.15

FeatureSummary

Функции для генерации сводки включённых/выключённых функций.

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

-- The following OPTIONAL packages have been found:
LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
   * Enables HTML-import in MyWordProcessor
   * Enables odt-export in MyWordProcessor
PNG, A PNG image library., <http://www.libpng.org/pub/png/>
   * Enables saving screenshots
-- The following OPTIONAL packages have not been found:
Lua51, The Lua scripting language., <http://www.lua.org>
   * Enables macros in MyWordProcessor
Foo, Foo provides cool stuff.

Глобальные свойства

FeatureSummary_PKG_TYPES

Глобальное свойство FeatureSummary_PKG_TYPES определяет тип пакетов, используемых FeatureSummary.

Порядок в этом списке важен: первый тип пакета в списке — наименее важный, последний — наиболее важный. Тип пакета может быть изменён только на более высокий тип.

Типовые типы пакетов — , RUNTIME, OPTIONAL, RECOMMENDED и REQUIRED, и их важность — RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED.

FeatureSummary_REQUIRED_PKG_TYPES

Глобальное свойство FeatureSummary_REQUIRED_PKG_TYPES определяет, какие типы пакетов являются обязательными.

Если один или несколько пакетов в этих категориях не найдены, CMake прервёт работу при вызове feature_summary() с опцией ‘FATAL_ON_MISSING_REQUIRED_PACKAGES’.

Значение по умолчанию для этого глобального свойства — REQUIRED.

FeatureSummary_DEFAULT_PKG_TYPE

Глобальное свойство FeatureSummary_DEFAULT_PKG_TYPE определяет тип пакета по умолчанию. При вызове feature_summary(), если пользователь не задал тип пакета явно, пакет будет отнесён к этой категории.

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

Значение по умолчанию для этого глобального свойства — OPTIONAL.

FeatureSummary_<TYPE>_DESCRIPTION

Глобальное свойство FeatureSummary_<TYPE>_DESCRIPTION может быть определено для каждого типа, чтобы заменить имя типа указанной строкой всякий раз, когда тип пакета используется в строке вывода.

Если не установлено, используется строка «<TYPE> пакетов».

Функции

feature_summary 
feature_summary( [FILENAME <file>]
                 [APPEND]
                 [VAR <variable_name>]
                 [INCLUDE_QUIET_PACKAGES]
                 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
                 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
                 [QUIET_ON_EMPTY]
                 WHAT (ALL
                      | PACKAGES_FOUND | PACKAGES_NOT_FOUND
                      | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
                      | ENABLED_FEATURES | DISABLED_FEATURES)
               )

Макрос feature_summary() может быть использован для вывода информации об включённых или выключенных пакетах или функциях проекта. По умолчанию выводятся только имена функций/пакетов и их требуемая версия, если она была указана. Используйте set_package_properties() для добавления более полезной информации, например, ссылки для скачивания соответствующего пакета или его назначения в проекте.

Опция WHAT — единственная обязательная опция. Здесь вы указываете, какая информация будет выведена:

ALL

вывести всё

ENABLED_FEATURES

список всех включённых функций

DISABLED_FEATURES

список всех выключенных функций

PACKAGES_FOUND

список всех найденных пакетов

PACKAGES_NOT_FOUND

список всех ненайденных пакетов

Для каждого типа пакета <TYPE>, определённого глобальным свойством FeatureSummary_PKG_TYPES, также можно использовать:

<TYPE>_PACKAGES_FOUND

только те найденные пакеты, которые имеют тип <TYPE>

<TYPE>_PACKAGES_NOT_FOUND

только те ненайденные пакеты, которые имеют тип <TYPE>

За исключением значения ALL, эти значения можно комбинировать, чтобы настроить вывод. Например:

feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)

Если указан FILENAME, информация выводится в этот файл. Если используется APPEND, она добавляется в этот файл, в противном случае файл перезаписывается, если он уже существует. Если используется опция VAR, информация «выводится» в указанную переменную. Если FILENAME не используется, информация выводится в терминал. Используя опцию DESCRIPTION, можно установить описание или заголовок, который будет выведен над фактическим содержимым. Если запрашивался только один тип пакета, заголовок не выводится, если не задан явно с помощью DESCRIPTION для использования пользовательской строки или DEFAULT_DESCRIPTION для использования стандартного заголовка для запрошенного типа. Если INCLUDE_QUIET_PACKAGES указан, будут перечислены пакеты, которые были проверены с find_package(... QUIET). По умолчанию они пропускаются. Если указано FATAL_ON_MISSING_REQUIRED_PACKAGES, CMake прервётся, если не найден пакет, помеченный как один из типов пакетов, перечисленных в глобальном свойстве FeatureSummary_REQUIRED_PKG_TYPES. Значение по умолчанию для глобального свойства FeatureSummary_REQUIRED_PKG_TYPES — REQUIRED.

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

Если используется опция QUIET_ON_EMPTY, если был запрошен только один тип пакета и не было найдено пакетов, относящихся к этой категории, то не выводится никакой вывод (включая DESCRIPTION) и не добавляется в переменную VAR.

Пример 1, добавить всё в файл:

include(FeatureSummary)
feature_summary(WHAT ALL
                FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)

Пример 2, вывести включённые функции в переменную enabledFeaturesText, включая QUIET пакеты:

include(FeatureSummary)
feature_summary(WHAT ENABLED_FEATURES
                INCLUDE_QUIET_PACKAGES
                DESCRIPTION "Enabled Features:"
                VAR enabledFeaturesText)
message(STATUS "${enabledFeaturesText}")

Пример 3, изменить типы пакетов по умолчанию и вывести только непустые категории:

include(FeatureSummary)
set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
find_package(FOO)
set_package_properties(FOO PROPERTIES TYPE BUILD)
feature_summary(WHAT BUILD_PACKAGES_FOUND
                Description "Build tools found:"
                QUIET_ON_EMPTY)
feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
                Description "Build tools not found:"
                QUIET_ON_EMPTY)
set_package_properties 
set_package_properties(<name> PROPERTIES
                       [ URL <url> ]
                       [ DESCRIPTION <description> ]
                       [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
                       [ PURPOSE <purpose> ]
                      )

Используйте этот макрос для настройки информации о названном пакете, который затем можно отобразить с помощью FEATURE_SUMMARY(). Это можно сделать как непосредственно в модуле Find, так и в проекте, использующем модуль после вызова find_package(). Функции, для которых информация может быть установлена, добавляются автоматически командой find_package().

URL <url>

Это должна быть домашняя страница пакета или что-то подобное. В идеале это уже установлено непосредственно в модуле Find.

DESCRIPTION <description>

Краткое описание пакета, не более одного предложения. В идеале это уже установлено непосредственно в модуле Find.

TYPE <type>

Тип зависимости проекта от данного пакета. По умолчанию OPTIONAL. В этом случае это пакет, который может быть использован проектом, если он доступен во время сборки, но он также работает и без него. RECOMMENDED аналогичен OPTIONAL, т. е. проект будет собран, если пакет отсутствует, но функциональность результирующих библиотек будет сильно ограничена. Если пакет REQUIRED недоступен во время сборки, проект может вообще не собраться. Это можно комбинировать с аргументом FATAL_ON_MISSING_REQUIRED_PACKAGES для feature_summary(). Наконец, пакет RUNTIME — это пакет, который вообще не используется во время сборки, но который необходим для фактического выполнения результирующих библиотек. Таким образом, если такой пакет отсутствует, проект всё ещё может быть собран, но он может не работать впоследствии. Если set_package_properties() вызывается несколько раз для одного и того же пакета с различными типами, то TYPE изменяется только на более высокие типы (RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED), более низкие типы игнорируются. Свойство TYPE специфично для проекта, поэтому его нельзя установить в модуле Find, а необходимо установить в проекте. Принимаемые типы могут быть изменены путём установки глобального свойства FeatureSummary_PKG_TYPES.

PURPOSE <purpose>

Это описывает, какие функции данный пакет включает в проект, т. е. сообщает пользователю, какая функциональность будет доступна в результирующих бинарниках. Если set_package_properties() вызывается несколько раз для пакета, все свойства PURPOSE добавляются в список назначений пакета в проекте. Как и свойство TYPE, свойство PURPOSE специфично для проекта, поэтому его нельзя устанавливать в модуле Find, а нужно устанавливать в проекте.

Пример установки информации для пакета:

find_package(LibXml2)
set_package_properties(LibXml2 PROPERTIES
                       DESCRIPTION "A XML processing library."
                       URL "http://xmlsoft.org/")
# or
set_package_properties(LibXml2 PROPERTIES
                       TYPE RECOMMENDED
                       PURPOSE "Enables HTML-import in MyWordProcessor")
# or
set_package_properties(LibXml2 PROPERTIES
                       TYPE OPTIONAL
                       PURPOSE "Enables odt-export in MyWordProcessor")

find_package(DBUS)
set_package_properties(DBUS PROPERTIES
  TYPE RUNTIME
  PURPOSE "Necessary to disable the screensaver during a presentation")
add_feature_info 
add_feature_info(<name> <enabled> <description>)

Используйте этот макрос для добавления информации о функции с заданным <name>. <enabled> содержит информацию о том, включена ли данная функция или нет. Это может быть переменная или список условий. <description> — это текст, описывающий функцию. Информация может быть отображена с помощью feature_summary() для ENABLED_FEATURES и DISABLED_FEATURES соответственно.

Пример установки информации о функции:

option(WITH_FOO "Help for foo" ON)
add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")

Устаревшие макросы

Следующие макросы предоставляются для совместимости с предыдущими версиями CMake:

set_package_info 
set_package_info(<name> <description> [ <url> [<purpose>] ])

Используйте этот макрос для настройки информации о названном пакете, который затем можно отобразить с помощью feature_summary(). Это можно сделать как непосредственно в модуле Find, так и в проекте, использующем модуль после вызова find_package(). Функции, для которых информация может быть установлена, добавляются автоматически командой find_package().

set_feature_info 
set_feature_info(<name> <description> [<url>])

Делает то же самое, что и:

set_package_info(<name> <description> <url>)
END_OF_DOCUMENT_MARKER
print_enabled_features 
print_enabled_features()

Делает то же, что

feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
print_disabled_features 
print_disabled_features()

Делает то же, что

feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")

© 2000–2020 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.15/module/FeatureSummary.html

Spec-Zone.ru

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