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.

Функции

feature_summary

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, добавить всё в файл:

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

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

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