FeatureSummary

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

Этот модуль предоставляет макросы feature_summary(), set_package_properties() и add_feature_info(). Для совместимости он также по-прежнему предоставляет set_package_info(), set_feature_info(), print_enabled_features() и print_disabled_features().

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

-- 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.

FEATURE_SUMMARY( [FILENAME <file>]
                 [APPEND]
                 [VAR <variable_name>]
                 [INCLUDE_QUIET_PACKAGES]
                 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
                 [DESCRIPTION "Found packages:"]
                 WHAT (ALL | PACKAGES_FOUND | PACKAGES_NOT_FOUND
                      | ENABLED_FEATURES | DISABLED_FEATURES)
               )

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

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

ALL

вывести всё

ENABLED_FEATURES

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

DISABLED_FEATURES

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

PACKAGES_FOUND

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

PACKAGES_NOT_FOUND

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

OPTIONAL_PACKAGES_FOUND

только те пакеты, которые были найдены и имеют тип OPTIONAL

OPTIONAL_PACKAGES_NOT_FOUND

только те пакеты, которые не были найдены и имеют тип OPTIONAL

RECOMMENDED_PACKAGES_FOUND

только те пакеты, которые были найдены и имеют тип RECOMMENDED

RECOMMENDED_PACKAGES_NOT_FOUND

только те пакеты, которые не были найдены и имеют тип RECOMMENDED

REQUIRED_PACKAGES_FOUND

только те пакеты, которые были найдены и имеют тип REQUIRED

REQUIRED_PACKAGES_NOT_FOUND

только те пакеты, которые не были найдены и имеют тип REQUIRED

RUNTIME_PACKAGES_FOUND

только те пакеты, которые были найдены и имеют тип RUNTIME

RUNTIME_PACKAGES_NOT_FOUND

только те пакеты, которые не были найдены и имеют тип RUNTIME

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

feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)

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

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

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

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

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

SET_PACKAGE_PROPERTIES(<name> PROPERTIES
                       [ URL <url> ]
                       [ DESCRIPTION <description> ]
                       [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
                       [ PURPOSE <purpose> ]
                      )

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

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

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

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

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/")

set_package_properties(LibXml2 PROPERTIES
                       TYPE RECOMMENDED
                       PURPOSE "Enables HTML-import in MyWordProcessor")
...
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(<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(<name> <description> [<url> [<purpose>] ] )

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

PRINT_ENABLED_FEATURES()

Делает то же, что и FEATURE_SUMMARY(WHAT ENABLED_FEATURES DESCRIPTION “Включенные функции:”)

PRINT_DISABLED_FEATURES()

Делает то же, что и FEATURE_SUMMARY(WHAT DISABLED_FEATURES DESCRIPTION “Отключенные функции:”)

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

Делает то же, что и SET_PACKAGE_INFO(<name> <description> <url> )