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

Новое в версии 3.9.

Глобальное свойство 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() для добавления более полезной информации, например, URL для загрузки соответствующего пакета или его назначения в проекте.

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

ALL: вывод всей информации
ENABLED_FEATURES: список всех включённых функций
DISABLED_FEATURES: список всех выключенных функций
PACKAGES_FOUND: список всех найденных пакетов
PACKAGES_NOT_FOUND: список всех ненайденных пакетов

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

<TYPE>_PACKAGES_FOUND: только найденные пакеты типа <TYPE>
<TYPE>_PACKAGES_NOT_FOUND: только ненайденные пакеты типа <TYPE>

Изменено в версии 3.1: За исключением значения 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.

Новое в версии 3.9: Параметр DEFAULT_DESCRIPTION.

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

Новое в версии 3.8: Если используется параметр 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, TYPE изменяется только на более высокие TYPE (RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED), более низкие TYPE игнорируются. Свойство 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 соответственно.

Изменено в версии 3.8: <enabled> может быть списком условий.

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

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_package(). Функции, для которых можно установить информацию, добавляются автоматически командой find_package().

set_feature_info

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

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

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

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–2022 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.23/module/FeatureSummary.html