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() для добавления более полезной информации, например, 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>

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

URL <url>

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

DESCRIPTION <description>

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

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 специфично для проекта, поэтому его нельзя установить в модуле поиска, а нужно установить в проекте. Доступные типы можно изменить, установив глобальное свойство FeatureSummary_PKG_TYPES.

PURPOSE <purpose>

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

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

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_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:")