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