mirror of
https://github.com/Kitware/CMake.git
synced 2025-10-14 02:08:27 +08:00
361af2b480
- Refactored and synced module documentation. - Moved all documentation to the top header comment to make it easier to manage and adjust. - Added table of contents. - Added intro code block showing how to use this module. - Described arguments of commands as a list. - Used word "commands" instead of "functions". - Added separate examples section with more examples.
1012 lines
32 KiB
CMake
1012 lines
32 KiB
CMake
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
|
|
# file LICENSE.rst or https://cmake.org/licensing for details.
|
|
|
|
include_guard(GLOBAL)
|
|
|
|
#[=======================================================================[.rst:
|
|
FeatureSummary
|
|
--------------
|
|
|
|
.. only:: html
|
|
|
|
.. contents::
|
|
|
|
This module provides commands for generating a summary of enabled/disabled
|
|
features.
|
|
|
|
Load this module in CMake with:
|
|
|
|
.. code-block:: cmake
|
|
|
|
include(FeatureSummary)
|
|
|
|
Commands provided by this module can be used to generate a summary of enabled
|
|
and disabled packages and/or features for a build tree such as::
|
|
|
|
-- The following features have been enabled:
|
|
|
|
* Example, usage example
|
|
|
|
-- The following OPTIONAL packages have been found:
|
|
|
|
* LibXml2 (required version >= 2.4), XML library, <http://xmlsoft.org>
|
|
Enables HTML-import in MyWordProcessor
|
|
Enables odt-export in MyWordProcessor
|
|
* PNG, image library, <http://www.libpng.org/pub/png/>
|
|
Enables saving screenshots
|
|
|
|
-- The following OPTIONAL packages have not been found:
|
|
|
|
* Lua, the Lua scripting language, <https://www.lua.org>
|
|
Enables macros in MyWordProcessor
|
|
* OpenGL, Open Graphics Library
|
|
|
|
Global Properties
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
The following global properties are used by this module:
|
|
|
|
.. variable:: FeatureSummary_PKG_TYPES
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
This global property defines a
|
|
:ref:`semicolon-separated list <CMake Language Lists>` of package types used
|
|
by the ``FeatureSummary`` module.
|
|
|
|
The order in this list is important, the first package type in the list has
|
|
the lowest importance, while the last has the highest importance. The type of
|
|
a package can only be changed to a type with higher importance.
|
|
|
|
The default package types are ``RUNTIME``, ``OPTIONAL``, ``RECOMMENDED`` and
|
|
``REQUIRED``, with their importance ranked as
|
|
``RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED``.
|
|
|
|
.. variable:: FeatureSummary_REQUIRED_PKG_TYPES
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
This global property defines a
|
|
:ref:`semicolon-separated list <CMake Language Lists>` of package types that
|
|
are considered required.
|
|
|
|
If one or more packages in these categories are not found, CMake will abort
|
|
when the :command:`feature_summary()` command is called with the
|
|
``FATAL_ON_MISSING_REQUIRED_PACKAGES`` option enabled.
|
|
|
|
The default value for this global property is ``REQUIRED``.
|
|
|
|
.. variable:: FeatureSummary_DEFAULT_PKG_TYPE
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
This global property defines the default package type.
|
|
|
|
When the :command:`feature_summary()` command is called, and the user has
|
|
not explicitly set a type of some package, its type will be set to the
|
|
value of this property.
|
|
|
|
This value must be one of the types defined in the
|
|
:variable:`FeatureSummary_PKG_TYPES` global property.
|
|
|
|
The default value for this global property is ``OPTIONAL``.
|
|
|
|
.. variable:: FeatureSummary_<TYPE>_DESCRIPTION
|
|
|
|
.. versionadded:: 3.9
|
|
|
|
This global property can be defined for each package ``<TYPE>`` to a string
|
|
that will be used in the output titles of the
|
|
:command:`feature_summary()` command. For example::
|
|
|
|
The following <FeatureSummary_<TYPE>_DESCRIPTION> have been found:
|
|
|
|
If not set, default string ``<TYPE> packages`` is used.
|
|
|
|
Commands
|
|
^^^^^^^^
|
|
|
|
This module provides the following commands:
|
|
|
|
* :command:`feature_summary`
|
|
* :command:`set_package_properties`
|
|
* :command:`add_feature_info`
|
|
|
|
Printing Feature Summary
|
|
""""""""""""""""""""""""
|
|
|
|
.. command:: feature_summary
|
|
|
|
Prints information about enabled or disabled packages and features of a
|
|
project:
|
|
|
|
.. code-block:: cmake
|
|
|
|
feature_summary(
|
|
WHAT (ALL
|
|
| PACKAGES_FOUND | PACKAGES_NOT_FOUND
|
|
| <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
|
|
| ENABLED_FEATURES | DISABLED_FEATURES)
|
|
[FILENAME <file>]
|
|
[APPEND]
|
|
[VAR <variable-name>]
|
|
[INCLUDE_QUIET_PACKAGES]
|
|
[FATAL_ON_MISSING_REQUIRED_PACKAGES]
|
|
[DESCRIPTION <description> | DEFAULT_DESCRIPTION]
|
|
[QUIET_ON_EMPTY]
|
|
)
|
|
|
|
This command can be used to print information about enabled or disabled
|
|
packages and features of a project. By default, only the names of the
|
|
features/packages will be printed and their required version when one was
|
|
specified. Use :command:`set_package_properties()` to add more useful
|
|
information, e.g., a homepage URL for the respective package or their
|
|
purpose in the project.
|
|
|
|
.. rubric:: The arguments are:
|
|
|
|
``WHAT``
|
|
This is the only mandatory option. It specifies what information will be
|
|
printed:
|
|
|
|
``ALL``
|
|
Print everything.
|
|
``ENABLED_FEATURES``
|
|
The list of all features which are enabled.
|
|
``DISABLED_FEATURES``
|
|
The list of all features which are disabled.
|
|
``PACKAGES_FOUND``
|
|
The list of all packages which have been found.
|
|
``PACKAGES_NOT_FOUND``
|
|
The list of all packages which have not been found.
|
|
|
|
For each package type ``<TYPE>`` defined by the
|
|
:variable:`FeatureSummary_PKG_TYPES` global property, the following
|
|
information can also be used:
|
|
|
|
``<TYPE>_PACKAGES_FOUND``
|
|
The list of only packages of type ``<TYPE>`` which have been found.
|
|
``<TYPE>_PACKAGES_NOT_FOUND``
|
|
The list of only packages of type ``<TYPE>`` which have not been found.
|
|
|
|
.. versionchanged:: 3.1
|
|
The ``WHAT`` option is now a multi-value keyword, so that these values can
|
|
be combined, with the exception of the ``ALL`` value, in order to
|
|
customize the output. For example:
|
|
|
|
.. code-block:: cmake
|
|
|
|
feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
|
|
|
|
``FILENAME <file>``
|
|
If this option is given, the information is printed into this file instead
|
|
of the terminal. Relative ``<file>`` path is interpreted as being relative
|
|
to the current source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).
|
|
|
|
``APPEND``
|
|
If this option is given, the output is appended to the ``<file>`` provided
|
|
by the ``FILENAME`` option, otherwise the file is overwritten if it already
|
|
exists.
|
|
|
|
``VAR <variable-name>``
|
|
If this option is given, the information is stored into the specified
|
|
variable ``<variable-name>`` instead of the terminal.
|
|
|
|
``INCLUDE_QUIET_PACKAGES``
|
|
If this option is given, packages which have been searched with
|
|
:command:`find_package(... QUIET)` will also be listed. By default they are
|
|
skipped.
|
|
|
|
``FATAL_ON_MISSING_REQUIRED_PACKAGES``
|
|
If this option is given, CMake will abort with fatal error if a package
|
|
which is marked as one of the package types listed in the
|
|
:variable:`FeatureSummary_REQUIRED_PKG_TYPES` global property has not been
|
|
found.
|
|
|
|
``DESCRIPTION <description>``
|
|
A description or headline which will be printed above the actual content.
|
|
Without this option, if only one package type was requested, no title is
|
|
printed, unless a custom string is explicitly set using this option or
|
|
``DEFAULT_DESCRIPTION`` option is used that outputs a default title for the
|
|
requested type.
|
|
|
|
``DEFAULT_DESCRIPTION``
|
|
.. versionadded:: 3.9
|
|
|
|
The default description or headline to be printed above the content as
|
|
opposed to the customizable ``DESCRIPTION <description>``.
|
|
|
|
``QUIET_ON_EMPTY``
|
|
.. versionadded:: 3.8
|
|
|
|
If this option is given, when only one package type was requested, and no
|
|
packages belonging to that category were found, then no output (including
|
|
the ``DESCRIPTION``) is printed nor added to the ``FILENAME``, or the
|
|
``VAR`` variable.
|
|
|
|
Package Properties
|
|
""""""""""""""""""
|
|
|
|
.. command:: set_package_properties
|
|
|
|
Sets package properties:
|
|
|
|
.. code-block:: cmake
|
|
|
|
set_package_properties(
|
|
<PackageName>
|
|
PROPERTIES
|
|
[URL <url>]
|
|
[DESCRIPTION <description>]
|
|
[TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)]
|
|
[PURPOSE <purpose>]
|
|
)
|
|
|
|
Use this command to configure and provide information about the package
|
|
named ``<PackageName>``, which can then be displayed using the
|
|
:command:`feature_summary()` command. This command can be called either
|
|
directly within the corresponding :ref:`Find module <Find Modules>` or in
|
|
the project that uses the module after invoking the :command:`find_package()`
|
|
call. The features for which information can be set are determined
|
|
automatically after the :command:`find_package()` command.
|
|
|
|
.. rubric:: The arguments are:
|
|
|
|
``<PackageName>``
|
|
The name of the package. For example, as specified in the
|
|
:command:`find_package(<PackageName>)` argument.
|
|
|
|
``PROPERTIES``
|
|
Specifies the properties to set:
|
|
|
|
``URL <url>``
|
|
This should be the homepage of the package, or something similar.
|
|
Ideally this is set already directly in the
|
|
:ref:`Find module <Find Modules>`.
|
|
|
|
``DESCRIPTION <description>``
|
|
A short description what that package is, at most one sentence.
|
|
Ideally this is set already directly in the
|
|
:ref:`Find module <Find Modules>`.
|
|
|
|
``TYPE <type>``
|
|
What type of dependency has the using project on that package.
|
|
|
|
Default ``<type>`` is ``OPTIONAL``. In this case it is a package
|
|
which can be used by the project when available at buildtime, but the
|
|
project also works without it.
|
|
|
|
``RECOMMENDED`` package type is similar to ``OPTIONAL``, i.e. the
|
|
project will build if the package is not present, but the
|
|
functionality of the resulting binaries will be severely limited. If
|
|
a ``REQUIRED`` package is not available at buildtime, the project may
|
|
not even build. This can be combined with the
|
|
:command:`feature_summary(FATAL_ON_MISSING_REQUIRED_PACKAGES)` command
|
|
option.
|
|
|
|
Last, a ``RUNTIME`` package is a package which is actually not used
|
|
at all during the build, but which is required for actually running
|
|
the resulting binaries. So if such a package is missing, the project
|
|
can still be built, but it may not work later on.
|
|
|
|
If ``set_package_properties()`` is called multiple times for the same
|
|
package with different TYPEs, the ``TYPE`` is only changed to higher
|
|
TYPEs (``RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED``), lower TYPEs
|
|
are ignored. The ``TYPE`` property is project-specific, so it cannot
|
|
be set by the :ref:`Find module <Find Modules>`, but must be set in
|
|
the project.
|
|
|
|
The accepted types can be changed by setting the
|
|
:variable:`FeatureSummary_PKG_TYPES` global property.
|
|
|
|
``PURPOSE <purpose>``
|
|
This describes which features this package enables in the project,
|
|
i.e. it tells the user what functionality they get in the resulting
|
|
binaries. If ``set_package_properties()`` is called multiple times
|
|
for a package, all ``PURPOSE`` properties are appended to a list of
|
|
purposes of the package in the project. As the ``TYPE`` property,
|
|
also the ``PURPOSE`` property is project-specific, so it cannot be
|
|
set by the :ref:`Find module <Find Modules>`, but must be set in the
|
|
project.
|
|
|
|
Adding Feature Info
|
|
"""""""""""""""""""
|
|
|
|
.. command:: add_feature_info
|
|
|
|
Adds feature information:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_feature_info(<name> <condition> <description>)
|
|
|
|
Use this command to add information about a feature identified with a given
|
|
``<name>``.
|
|
|
|
.. rubric:: The arguments are:
|
|
|
|
``<name>``
|
|
Identification name for a feature being added.
|
|
|
|
``<condition>``
|
|
Specifies the conditions that determine whether this feature is enabled
|
|
or disabled.
|
|
|
|
The ``<condition>`` argument can be:
|
|
|
|
* A single condition (such as a variable name).
|
|
|
|
* .. versionadded:: 3.8
|
|
A :ref:`semicolon-separated list <CMake Language Lists>` of multiple
|
|
conditions.
|
|
|
|
* .. versionadded:: 4.0
|
|
A full :ref:`Condition Syntax` as used in an ``if(<condition>)``
|
|
clause. See policy :policy:`CMP0183`. This enables using entire
|
|
condition syntax (such as grouping conditions with parens and
|
|
similar).
|
|
|
|
``<description>``
|
|
A text describing the feature. This information can be displayed using
|
|
:command:`feature_summary()` for ``ENABLED_FEATURES`` and
|
|
``DISABLED_FEATURES`` respectively.
|
|
|
|
Deprecated Commands
|
|
"""""""""""""""""""
|
|
|
|
The following legacy and deprecated commands are provided for backward
|
|
compatibility with previous CMake versions:
|
|
|
|
.. command:: set_package_info
|
|
|
|
.. deprecated:: 3.8
|
|
Use the :command:`set_package_properties`, and :command:`add_feature_info`
|
|
commands instead.
|
|
|
|
Sets up information about the specified package, which can then be displayed
|
|
via :command:`feature_summary()`:
|
|
|
|
.. code-block:: cmake
|
|
|
|
set_package_info(<PackageName> <description> [<url> [<purpose>]])
|
|
|
|
``<PackageName>``
|
|
Name of the package.
|
|
|
|
``<description>``
|
|
A short description of the package.
|
|
|
|
``<url>``
|
|
Homepage of the package.
|
|
|
|
``<purpose>``
|
|
The purpose of the package.
|
|
|
|
This command can be used either directly in the
|
|
:ref:`Find module <Find Modules>` or in the project which uses the
|
|
``FeatureSummary`` module after the :command:`find_package()` call. The
|
|
features for which information can be set are added automatically by the
|
|
``find_package()`` command.
|
|
|
|
.. command:: set_feature_info
|
|
|
|
.. deprecated:: 3.8
|
|
|
|
Sets feature info for a package:
|
|
|
|
.. code-block:: cmake
|
|
|
|
set_feature_info(<name> <description> [<url>])
|
|
|
|
Does the same as:
|
|
|
|
.. code-block:: cmake
|
|
|
|
set_package_info(<name> <description> [<url>])
|
|
|
|
.. command:: print_enabled_features
|
|
|
|
.. deprecated:: 3.8
|
|
|
|
Prints enabled features:
|
|
|
|
.. code-block:: cmake
|
|
|
|
print_enabled_features()
|
|
|
|
Does the same as:
|
|
|
|
.. code-block:: cmake
|
|
|
|
feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
|
|
|
|
.. command:: print_disabled_features
|
|
|
|
.. deprecated:: 3.8
|
|
|
|
Prints disabled features:
|
|
|
|
.. code-block:: cmake
|
|
|
|
print_disabled_features()
|
|
|
|
Does the same as:
|
|
|
|
.. code-block:: cmake
|
|
|
|
feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
|
|
|
|
Examples
|
|
^^^^^^^^
|
|
|
|
Example: Appending Feature Summary to a File
|
|
""""""""""""""""""""""""""""""""""""""""""""
|
|
|
|
In the following example, the feature summary output will be appended to
|
|
a specified file instead of printing:
|
|
|
|
.. code-block:: cmake
|
|
|
|
include(FeatureSummary)
|
|
feature_summary(WHAT ALL FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
|
|
|
|
Example: Storing Feature Summary in a Variable
|
|
""""""""""""""""""""""""""""""""""""""""""""""
|
|
|
|
In the following example, the feature summary of enabled features is stored
|
|
in a specified variable ``enabledFeaturesText``, including the ``QUIET``
|
|
packages:
|
|
|
|
.. code-block:: cmake
|
|
|
|
include(FeatureSummary)
|
|
|
|
feature_summary(
|
|
WHAT ENABLED_FEATURES
|
|
INCLUDE_QUIET_PACKAGES
|
|
DESCRIPTION "Enabled Features:"
|
|
VAR enabledFeaturesText
|
|
)
|
|
|
|
message(STATUS "${enabledFeaturesText}")
|
|
|
|
Example: Adding a Custom Package Type
|
|
"""""""""""""""""""""""""""""""""""""
|
|
|
|
In the following example a custom package type is added and printed only
|
|
the categories that are not empty:
|
|
|
|
.. code-block:: cmake
|
|
|
|
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
|
|
)
|
|
|
|
Example: Setting Package Info
|
|
"""""""""""""""""""""""""""""
|
|
|
|
Example for setting the info for a package:
|
|
|
|
.. code-block:: cmake
|
|
|
|
include(FeatureSummary)
|
|
|
|
find_package(LibXml2)
|
|
set_package_properties(
|
|
LibXml2
|
|
PROPERTIES
|
|
DESCRIPTION "XML 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"
|
|
)
|
|
|
|
Example: Printing Feature Summary
|
|
"""""""""""""""""""""""""""""""""
|
|
|
|
In the following example, this module is used to output feature summary at
|
|
the end of the configuration. If any required package is not found,
|
|
processing stops with an error message at the end of the configuration
|
|
phase.
|
|
|
|
.. code-block:: cmake
|
|
|
|
cmake_minimum_required(VERSION 3.15)
|
|
project(Example)
|
|
|
|
add_library(example example.c)
|
|
|
|
include(FeatureSummary)
|
|
|
|
find_package(CURL)
|
|
set_package_properties(CURL PROPERTIES TYPE REQUIRED)
|
|
target_link_libraries(example PRIVATE CURL::libcurl)
|
|
|
|
find_package(LibXml2 QUIET)
|
|
set_package_properties(LibXml2 PROPERTIES TYPE RECOMMENDED)
|
|
if(LibXml2_FOUND)
|
|
target_link_libraries(example PRIVATE LibXml2::LibXml2)
|
|
endif()
|
|
|
|
feature_summary(
|
|
WHAT ALL
|
|
INCLUDE_QUIET_PACKAGES
|
|
DESCRIPTION "Feature summary:"
|
|
FATAL_ON_MISSING_REQUIRED_PACKAGES
|
|
)
|
|
|
|
Examples: Setting Feature Info
|
|
""""""""""""""""""""""""""""""
|
|
|
|
Example for setting the info for a feature:
|
|
|
|
.. code-block:: cmake
|
|
|
|
include(FeatureSummary)
|
|
|
|
option(WITH_FOO "Help for foo" ON)
|
|
|
|
add_feature_info(Foo WITH_FOO "this feature provides very cool stuff")
|
|
|
|
Example for setting feature info based on a list of conditions:
|
|
|
|
.. code-block:: cmake
|
|
|
|
include(FeatureSummary)
|
|
|
|
option(WITH_FOO "Help for foo" ON)
|
|
option(WITH_BAR "Help for bar" OFF)
|
|
|
|
add_feature_info(
|
|
FooBar
|
|
"WITH_FOO;NOT WITH_BAR"
|
|
"this feature is enabled when WITH_FOO is ON and WITH_BAR turned OFF"
|
|
)
|
|
|
|
In the next example feature info are set depending on a full condition
|
|
syntax. Unlike semicolon-separated list of conditions, this enables using
|
|
entire condition syntax as being the ``if`` clause argument:
|
|
|
|
.. code-block:: cmake
|
|
|
|
include(FeatureSummary)
|
|
|
|
option(WITH_FOO "Help for foo" ON)
|
|
option(WITH_BAR "Help for bar" ON)
|
|
option(WITH_BAZ "Help for baz" OFF)
|
|
|
|
add_feature_info(
|
|
FooBarBaz
|
|
"WITH_FOO AND (WITH_BAR OR WITH_BAZ)"
|
|
"this feature is enabled when the entire condition is true"
|
|
)
|
|
#]=======================================================================]
|
|
|
|
get_property(_fsPkgTypeIsSet GLOBAL PROPERTY FeatureSummary_PKG_TYPES SET)
|
|
if(NOT _fsPkgTypeIsSet)
|
|
set_property(GLOBAL PROPERTY FeatureSummary_PKG_TYPES RUNTIME OPTIONAL RECOMMENDED REQUIRED)
|
|
endif()
|
|
|
|
get_property(_fsReqPkgTypesIsSet GLOBAL PROPERTY FeatureSummary_REQUIRED_PKG_TYPES SET)
|
|
if(NOT _fsReqPkgTypesIsSet)
|
|
set_property(GLOBAL PROPERTY FeatureSummary_REQUIRED_PKG_TYPES REQUIRED)
|
|
endif()
|
|
|
|
get_property(_fsDefaultPkgTypeIsSet GLOBAL PROPERTY FeatureSummary_DEFAULT_PKG_TYPE SET)
|
|
if(NOT _fsDefaultPkgTypeIsSet)
|
|
set_property(GLOBAL PROPERTY FeatureSummary_DEFAULT_PKG_TYPE OPTIONAL)
|
|
endif()
|
|
|
|
function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet)
|
|
get_property(_fsPkgTypes GLOBAL PROPERTY FeatureSummary_PKG_TYPES)
|
|
get_property(_fsDefaultPkgType GLOBAL PROPERTY FeatureSummary_DEFAULT_PKG_TYPE)
|
|
|
|
set(_type "ANY")
|
|
foreach(_fsPkgType ${_fsPkgTypes})
|
|
if("${_property}" MATCHES "${_fsPkgType}_PACKAGES_(NOT_)?FOUND")
|
|
set(_type "${_fsPkgType}")
|
|
break()
|
|
endif()
|
|
endforeach()
|
|
|
|
if("${_property}" MATCHES "PACKAGES_FOUND")
|
|
set(_property "PACKAGES_FOUND")
|
|
elseif("${_property}" MATCHES "PACKAGES_NOT_FOUND")
|
|
set(_property "PACKAGES_NOT_FOUND")
|
|
endif()
|
|
|
|
|
|
set(_currentFeatureText "")
|
|
get_property(_EnabledFeatures GLOBAL PROPERTY ${_property})
|
|
if(_EnabledFeatures)
|
|
list(REMOVE_DUPLICATES _EnabledFeatures)
|
|
endif()
|
|
|
|
foreach(_currentFeature ${_EnabledFeatures})
|
|
|
|
# does this package belong to the type we currently want to list ?
|
|
get_property(_currentType GLOBAL PROPERTY _CMAKE_${_currentFeature}_TYPE)
|
|
if(NOT _currentType)
|
|
list(FIND _fsPkgTypes "${_fsDefaultPkgType}" _defaultInPkgTypes)
|
|
if("${_defaultInPkgTypes}" STREQUAL "-1")
|
|
string(REGEX REPLACE ";([^;]+)$" " and \\1" _fsPkgTypes_msg "${_fsPkgTypes}")
|
|
string(REPLACE ";" ", " _fsPkgTypes_msg "${_fsPkgTypes_msg}")
|
|
message(FATAL_ERROR "Bad package property type ${_fsDefaultPkgType} used in global property FeatureSummary_DEFAULT_PKG_TYPE. "
|
|
"Valid types are ${_fsPkgTypes_msg}. "
|
|
"Either update FeatureSummary_DEFAULT_PKG_TYPE or add ${_fsDefaultPkgType} to the FeatureSummary_PKG_TYPES global property.")
|
|
endif()
|
|
set(_currentType ${_fsDefaultPkgType})
|
|
endif()
|
|
|
|
if("${_type}" STREQUAL ANY OR "${_type}" STREQUAL "${_currentType}")
|
|
# check whether the current feature/package should be in the output depending on whether it was QUIET or not
|
|
set(includeThisOne TRUE)
|
|
set(_required FALSE)
|
|
# skip QUIET packages, except if they are REQUIRED or INCLUDE_QUIET_PACKAGES has been set
|
|
get_property(_fsReqPkgTypes GLOBAL PROPERTY FeatureSummary_REQUIRED_PKG_TYPES)
|
|
foreach(_fsReqPkgType ${_fsReqPkgTypes})
|
|
if("${_currentType}" STREQUAL "${_fsReqPkgType}")
|
|
set(_required TRUE)
|
|
break()
|
|
endif()
|
|
endforeach()
|
|
if(NOT _required AND NOT _includeQuiet)
|
|
get_property(_isQuiet GLOBAL PROPERTY _CMAKE_${_currentFeature}_QUIET)
|
|
if(_isQuiet)
|
|
set(includeThisOne FALSE)
|
|
endif()
|
|
endif()
|
|
get_property(_isTransitiveDepend
|
|
GLOBAL PROPERTY _CMAKE_${_currentFeature}_TRANSITIVE_DEPENDENCY
|
|
)
|
|
if(_isTransitiveDepend)
|
|
set(includeThisOne FALSE)
|
|
endif()
|
|
|
|
if(includeThisOne)
|
|
|
|
string(APPEND _currentFeatureText "\n * ${_currentFeature}")
|
|
get_property(_info GLOBAL PROPERTY _CMAKE_${_currentFeature}_REQUIRED_VERSION)
|
|
if(_info)
|
|
string(APPEND _currentFeatureText " (required version ${_info})")
|
|
endif()
|
|
get_property(_info GLOBAL PROPERTY _CMAKE_${_currentFeature}_DESCRIPTION)
|
|
if(_info)
|
|
string(APPEND _currentFeatureText ", ${_info}")
|
|
endif()
|
|
get_property(_info GLOBAL PROPERTY _CMAKE_${_currentFeature}_URL)
|
|
if(_info)
|
|
string(APPEND _currentFeatureText ", <${_info}>")
|
|
endif()
|
|
|
|
get_property(_info GLOBAL PROPERTY _CMAKE_${_currentFeature}_PURPOSE)
|
|
foreach(_purpose ${_info})
|
|
string(APPEND _currentFeatureText "\n ${_purpose}")
|
|
endforeach()
|
|
|
|
endif()
|
|
|
|
endif()
|
|
|
|
endforeach()
|
|
set(${_var} "${_currentFeatureText}" PARENT_SCOPE)
|
|
endfunction()
|
|
|
|
function(FEATURE_SUMMARY)
|
|
# cmake_parse_arguments(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)
|
|
set(options APPEND
|
|
INCLUDE_QUIET_PACKAGES
|
|
FATAL_ON_MISSING_REQUIRED_PACKAGES
|
|
QUIET_ON_EMPTY
|
|
DEFAULT_DESCRIPTION)
|
|
set(oneValueArgs FILENAME
|
|
VAR
|
|
DESCRIPTION)
|
|
set(multiValueArgs WHAT)
|
|
|
|
cmake_parse_arguments(_FS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${_FIRST_ARG} ${ARGN})
|
|
|
|
if(_FS_UNPARSED_ARGUMENTS)
|
|
message(FATAL_ERROR "Unknown keywords given to FEATURE_SUMMARY(): \"${_FS_UNPARSED_ARGUMENTS}\"")
|
|
endif()
|
|
|
|
if(NOT _FS_WHAT)
|
|
message(FATAL_ERROR "The call to FEATURE_SUMMARY() doesn't set the required WHAT argument.")
|
|
endif()
|
|
|
|
if(_FS_DEFAULT_DESCRIPTION AND DEFINED _FS_DESCRIPTION)
|
|
message(WARNING "DEFAULT_DESCRIPTION option discarded since DESCRIPTION is set.")
|
|
set(_FS_DEFAULT_DESCRIPTION 0)
|
|
endif()
|
|
|
|
set(validWhatParts "ENABLED_FEATURES"
|
|
"DISABLED_FEATURES"
|
|
"PACKAGES_FOUND"
|
|
"PACKAGES_NOT_FOUND")
|
|
|
|
get_property(_fsPkgTypes GLOBAL PROPERTY FeatureSummary_PKG_TYPES)
|
|
get_property(_fsReqPkgTypes GLOBAL PROPERTY FeatureSummary_REQUIRED_PKG_TYPES)
|
|
foreach(_fsPkgType ${_fsPkgTypes})
|
|
list(APPEND validWhatParts "${_fsPkgType}_PACKAGES_FOUND"
|
|
"${_fsPkgType}_PACKAGES_NOT_FOUND")
|
|
endforeach()
|
|
|
|
set(title_ENABLED_FEATURES "The following features have been enabled:")
|
|
set(title_DISABLED_FEATURES "The following features have been disabled:")
|
|
set(title_PACKAGES_FOUND "The following packages have been found:")
|
|
set(title_PACKAGES_NOT_FOUND "The following packages have not been found:")
|
|
foreach(_fsPkgType ${_fsPkgTypes})
|
|
set(_fsPkgTypeDescription "${_fsPkgType} packages")
|
|
get_property(_fsPkgTypeDescriptionIsSet GLOBAL PROPERTY FeatureSummary_${_fsPkgType}_DESCRIPTION SET)
|
|
if(_fsPkgTypeDescriptionIsSet)
|
|
get_property(_fsPkgTypeDescription GLOBAL PROPERTY FeatureSummary_${_fsPkgType}_DESCRIPTION )
|
|
endif()
|
|
set(title_${_fsPkgType}_PACKAGES_FOUND "The following ${_fsPkgTypeDescription} have been found:")
|
|
set(title_${_fsPkgType}_PACKAGES_NOT_FOUND "The following ${_fsPkgTypeDescription} have not been found:")
|
|
endforeach()
|
|
|
|
list(FIND validWhatParts "${_FS_WHAT}" indexInList)
|
|
if(NOT "${indexInList}" STREQUAL "-1")
|
|
_FS_GET_FEATURE_SUMMARY( ${_FS_WHAT} _featureSummary ${_FS_INCLUDE_QUIET_PACKAGES} )
|
|
if(_featureSummary OR NOT _FS_QUIET_ON_EMPTY)
|
|
if(_FS_DEFAULT_DESCRIPTION)
|
|
set(_fullText "${title_${_FS_WHAT}}\n${_featureSummary}\n")
|
|
else()
|
|
set(_fullText "${_FS_DESCRIPTION}${_featureSummary}\n")
|
|
endif()
|
|
endif()
|
|
|
|
if(_featureSummary)
|
|
foreach(_fsReqPkgType ${_fsReqPkgTypes})
|
|
if("${_FS_WHAT}" STREQUAL "${_fsReqPkgType}_PACKAGES_NOT_FOUND")
|
|
set(requiredPackagesNotFound TRUE)
|
|
break()
|
|
endif()
|
|
endforeach()
|
|
endif()
|
|
|
|
else()
|
|
if("${_FS_WHAT}" STREQUAL "ALL")
|
|
|
|
set(allWhatParts "ENABLED_FEATURES")
|
|
foreach(_fsPkgType ${_fsPkgTypes})
|
|
list(APPEND allWhatParts "${_fsPkgType}_PACKAGES_FOUND")
|
|
endforeach()
|
|
list(APPEND allWhatParts "DISABLED_FEATURES")
|
|
foreach(_fsPkgType ${_fsPkgTypes})
|
|
list(APPEND allWhatParts "${_fsPkgType}_PACKAGES_NOT_FOUND")
|
|
endforeach()
|
|
else()
|
|
set(allWhatParts)
|
|
foreach(part ${_FS_WHAT})
|
|
list(FIND validWhatParts "${part}" indexInList)
|
|
if(NOT "${indexInList}" STREQUAL "-1")
|
|
list(APPEND allWhatParts "${part}")
|
|
else()
|
|
if("${part}" STREQUAL "ALL")
|
|
message(FATAL_ERROR "The WHAT argument of FEATURE_SUMMARY() contains ALL, which cannot be combined with other values.")
|
|
else()
|
|
message(FATAL_ERROR "The WHAT argument of FEATURE_SUMMARY() contains ${part}, which is not a valid value.")
|
|
endif()
|
|
endif()
|
|
endforeach()
|
|
endif()
|
|
|
|
set(_fullText "${_FS_DESCRIPTION}")
|
|
foreach(part ${allWhatParts})
|
|
set(_tmp)
|
|
_FS_GET_FEATURE_SUMMARY( ${part} _tmp ${_FS_INCLUDE_QUIET_PACKAGES})
|
|
if(_tmp)
|
|
if(_fullText)
|
|
string(APPEND _fullText "\n-- ")
|
|
endif()
|
|
string(APPEND _fullText "${title_${part}}\n${_tmp}\n")
|
|
foreach(_fsReqPkgType ${_fsReqPkgTypes})
|
|
if("${part}" STREQUAL "${_fsReqPkgType}_PACKAGES_NOT_FOUND")
|
|
set(requiredPackagesNotFound TRUE)
|
|
break()
|
|
endif()
|
|
endforeach()
|
|
endif()
|
|
endforeach()
|
|
endif()
|
|
|
|
if(_fullText OR NOT _FS_QUIET_ON_EMPTY)
|
|
if(_FS_FILENAME)
|
|
if(_FS_APPEND)
|
|
file(APPEND "${_FS_FILENAME}" "${_fullText}")
|
|
else()
|
|
file(WRITE "${_FS_FILENAME}" "${_fullText}")
|
|
endif()
|
|
|
|
else()
|
|
if(NOT _FS_VAR)
|
|
message(STATUS "${_fullText}")
|
|
endif()
|
|
endif()
|
|
|
|
if(_FS_VAR)
|
|
set(${_FS_VAR} "${_fullText}" PARENT_SCOPE)
|
|
endif()
|
|
endif()
|
|
|
|
if(requiredPackagesNotFound AND _FS_FATAL_ON_MISSING_REQUIRED_PACKAGES)
|
|
message(FATAL_ERROR "feature_summary() Error: REQUIRED package(s) are missing, aborting CMake run.")
|
|
endif()
|
|
endfunction()
|
|
|
|
function(SET_PACKAGE_PROPERTIES _name _props)
|
|
if(NOT "${_props}" STREQUAL "PROPERTIES")
|
|
message(FATAL_ERROR "PROPERTIES keyword is missing in SET_PACKAGE_PROPERTIES() call.")
|
|
endif()
|
|
|
|
set(options ) # none
|
|
set(oneValueArgs DESCRIPTION URL TYPE PURPOSE )
|
|
set(multiValueArgs ) # none
|
|
|
|
cmake_parse_arguments(_SPP "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
|
|
|
|
if(_SPP_UNPARSED_ARGUMENTS)
|
|
message(FATAL_ERROR "Unknown keywords given to SET_PACKAGE_PROPERTIES(): \"${_SPP_UNPARSED_ARGUMENTS}\"")
|
|
endif()
|
|
|
|
if(_SPP_DESCRIPTION)
|
|
get_property(_info GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION)
|
|
if(_info AND NOT "${_info}" STREQUAL "${_SPP_DESCRIPTION}")
|
|
message(STATUS "Warning: Property DESCRIPTION for package ${_name} already set to \"${_info}\", overriding it with \"${_SPP_DESCRIPTION}\"")
|
|
endif()
|
|
|
|
set_property(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_SPP_DESCRIPTION}" )
|
|
endif()
|
|
|
|
if(_SPP_URL)
|
|
get_property(_info GLOBAL PROPERTY _CMAKE_${_name}_URL)
|
|
if(_info AND NOT "${_info}" STREQUAL "${_SPP_URL}")
|
|
message(STATUS "Warning: Property URL already set to \"${_info}\", overriding it with \"${_SPP_URL}\"")
|
|
endif()
|
|
|
|
set_property(GLOBAL PROPERTY _CMAKE_${_name}_URL "${_SPP_URL}" )
|
|
endif()
|
|
|
|
# handle the PURPOSE: use APPEND, since there can be multiple purposes for one package inside a project
|
|
if(_SPP_PURPOSE)
|
|
set_property(GLOBAL APPEND PROPERTY _CMAKE_${_name}_PURPOSE "${_SPP_PURPOSE}" )
|
|
endif()
|
|
|
|
get_property(_fsPkgTypes GLOBAL PROPERTY FeatureSummary_PKG_TYPES)
|
|
get_property(_fsDefaultPkgType GLOBAL PROPERTY FeatureSummary_DEFAULT_PKG_TYPE)
|
|
|
|
# handle the TYPE
|
|
if(DEFINED _SPP_TYPE)
|
|
# Supported types are listed in FeatureSummary_PKG_TYPES according to their priority
|
|
get_property(_fsPkgTypes GLOBAL PROPERTY FeatureSummary_PKG_TYPES)
|
|
list(FIND _fsPkgTypes ${_SPP_TYPE} _typeIndexInList)
|
|
if("${_typeIndexInList}" STREQUAL "-1" )
|
|
string(REGEX REPLACE ";([^;]+)$" " and \\1" _fsPkgTypes_msg "${_fsPkgTypes}")
|
|
string(REPLACE ";" ", " _fsPkgTypes_msg "${_fsPkgTypes_msg}")
|
|
message(FATAL_ERROR "Bad package property type ${_SPP_TYPE} used in SET_PACKAGE_PROPERTIES(). "
|
|
"Valid types are ${_fsPkgTypes_msg}." )
|
|
endif()
|
|
|
|
get_property(_previousType GLOBAL PROPERTY _CMAKE_${_name}_TYPE)
|
|
list(FIND _fsPkgTypes "${_previousType}" _prevTypeIndexInList)
|
|
|
|
# make sure a previously set TYPE is not overridden with a lower new TYPE:
|
|
if("${_typeIndexInList}" GREATER "${_prevTypeIndexInList}")
|
|
set_property(GLOBAL PROPERTY _CMAKE_${_name}_TYPE "${_SPP_TYPE}" )
|
|
endif()
|
|
endif()
|
|
endfunction()
|
|
|
|
function(ADD_FEATURE_INFO _name _depends _desc)
|
|
cmake_policy(GET CMP0183 _CDO_CMP0183
|
|
PARENT_SCOPE # undocumented, do not use outside of CMake
|
|
)
|
|
set(_enabled 1)
|
|
if("x${_CDO_CMP0183}x" STREQUAL "xNEWx")
|
|
foreach(_d ${_depends})
|
|
cmake_language(EVAL CODE "
|
|
if(${_d})
|
|
else()
|
|
set(_enabled 0)
|
|
endif()"
|
|
)
|
|
endforeach()
|
|
else()
|
|
foreach(_d ${_depends})
|
|
string(REGEX REPLACE " +" ";" _d "${_d}")
|
|
if(${_d})
|
|
else()
|
|
set(_enabled 0)
|
|
break()
|
|
endif()
|
|
endforeach()
|
|
endif()
|
|
if (${_enabled})
|
|
set_property(GLOBAL APPEND PROPERTY ENABLED_FEATURES "${_name}")
|
|
else ()
|
|
set_property(GLOBAL APPEND PROPERTY DISABLED_FEATURES "${_name}")
|
|
endif ()
|
|
|
|
set_property(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_desc}" )
|
|
|
|
if("x${_CDO_CMP0183}x" STREQUAL "xx" AND "x${_depends}x" MATCHES "[^A-Za-z0-9_.; ]")
|
|
cmake_policy(GET_WARNING CMP0183 _CDO_CMP0183_WARNING)
|
|
message(AUTHOR_WARNING "${_CDO_CMP0183_WARNING}")
|
|
endif()
|
|
unset(_CDO_CMP0183)
|
|
endfunction()
|
|
|
|
# The stuff below is only kept for compatibility
|
|
|
|
function(SET_PACKAGE_INFO _name _desc)
|
|
message(DEPRECATION "SET_PACKAGE_INFO is deprecated. Use SET_PACKAGE_PROPERTIES instead.")
|
|
unset(_url)
|
|
unset(_purpose)
|
|
if(ARGC GREATER 2)
|
|
set(_url "${ARGV2}")
|
|
endif()
|
|
if(ARGC GREATER 3)
|
|
set(_purpose "${ARGV3}")
|
|
endif()
|
|
set_property(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_desc}" )
|
|
if(NOT _url STREQUAL "")
|
|
set_property(GLOBAL PROPERTY _CMAKE_${_name}_URL "${_url}" )
|
|
endif()
|
|
if(NOT _purpose STREQUAL "")
|
|
set_property(GLOBAL APPEND PROPERTY _CMAKE_${_name}_PURPOSE "${_purpose}" )
|
|
endif()
|
|
endfunction()
|
|
|
|
function(SET_FEATURE_INFO)
|
|
message(DEPRECATION "SET_FEATURE_INFO is deprecated. Use ADD_FEATURE_INFO instead.")
|
|
set_package_info(${ARGN})
|
|
endfunction()
|
|
|
|
function(PRINT_ENABLED_FEATURES)
|
|
message(DEPRECATION "PRINT_ENABLED_FEATURES is deprecated. Use
|
|
feature_summary(WHAT ENABLED_FEATURES DESCRIPTION \"Enabled features:\")")
|
|
feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
|
|
endfunction()
|
|
|
|
function(PRINT_DISABLED_FEATURES)
|
|
message(DEPRECATION "PRINT_DISABLED_FEATURES is deprecated. Use
|
|
feature_summary(WHAT DISABLED_FEATURES DESCRIPTION \"Disabled features:\")")
|
|
feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
|
|
endfunction()
|