echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
CMake/Modules/FeatureSummary.cmake
Kitware Robot 1772622772 LICENSE: Replace references to Copyright.txt with LICENSE.rst 
```
git grep -lz 'Copyright.txt or https://cmake.org/licensing ' |
  while IFS= read -r -d $'\0' f ; do
    sed -i '/Copyright.txt or https:\/\/cmake.org\/licensing / {
              s/Copyright.txt/LICENSE.rst/
            }' "$f" ; done
```
2025-03-03 10:43:35 -05:00

860 lines
31 KiB
CMake
Raw Permalink Blame History

# 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
--------------
Functions for generating a summary of enabled/disabled features.
These functions 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
^^^^^^^^^^^^^^^^^
.. 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 this value.
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.
#]=======================================================================]
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()
#[=======================================================================[.rst:
Functions
^^^^^^^^^
#]=======================================================================]
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()
#[=======================================================================[.rst:
.. command:: feature_summary
.. code-block:: cmake
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)
)
This function 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, like e.g.
a homepage URL for the respective package or their purpose in the project.
The options 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.
``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>``.
``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.
The :variable:`FeatureSummary_DEFAULT_PKG_TYPE` global property can be
modified to change the default package type assigned when not explicitly
assigned by the user.
``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.
Example 1, append everything to a file:
.. code-block:: cmake
include(FeatureSummary)
feature_summary(WHAT ALL
FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
Example 2, print the enabled features into the 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 3, add custom package type and print 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)
#]=======================================================================]
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()
#[=======================================================================[.rst:
.. command:: set_package_properties
.. code-block:: cmake
set_package_properties(<name> PROPERTIES
[URL <url>]
[DESCRIPTION <description>]
[TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)]
[PURPOSE <purpose>]
)
Use this function to configure and provide information about the package named
``<name>``, which can then be displayed using the
:command:`feature_summary()` command. This can be performed 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.
``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 is ``OPTIONAL``. In this case it is a package which can be used
by the project when available at buildtime, but it also work without.
``RECOMMENDED`` 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.
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")
#]=======================================================================]
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()
#[=======================================================================[.rst:
.. command:: add_feature_info
.. code-block:: cmake
add_feature_info(<name> <enabled> <description>)
Use this function to add information about a feature identified with a given
``<name>``. The ``<enabled>`` contains whether this feature is enabled or
not. It can be a variable or a list of conditions.
``<description>`` is a text describing the feature. The information can
be displayed using :command:`feature_summary()` for ``ENABLED_FEATURES`` and
``DISABLED_FEATURES`` respectively.
.. versionchanged:: 3.8
``<enabled>`` can be a list of conditions.
.. versionchanged:: 4.0
Full :ref:`Condition Syntax` is now supported for ``<enabled>``.
See policy :policy:`CMP0183`.
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
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"
)
Example for setting feature info depending on a full condition syntax:
Unlike semicolon-separated list of conditions, this enables using entire
condition syntax as being the ``if`` clause argument, such as grouping
conditions with parens and similar.
.. code-block:: cmake
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"
)
#]=======================================================================]
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
#[=======================================================================[.rst:
Deprecated Functions
^^^^^^^^^^^^^^^^^^^^
The following legacy and deprecated functions are provided for backward
compatibility with previous CMake versions:
.. command:: set_package_info
.. deprecated:: 3.8
.. code-block:: cmake
set_package_info(<name> <description> [ <url> [<purpose>] ])
Set up information about the package ``<name>``, which can then be displayed
via :command:`feature_summary()`. This can be done 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.
This function is deprecated. Use the :command:`set_package_properties()`, and
:command:`add_feature_info()` functions instead.
#]=======================================================================]
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()
#[=======================================================================[.rst:
.. command:: set_feature_info
.. deprecated:: 3.8
.. code-block:: cmake
set_feature_info(<name> <description> [<url>])
Does the same as:
.. code-block:: cmake
set_package_info(<name> <description> [<url>])
#]=======================================================================]
function(SET_FEATURE_INFO)
message(DEPRECATION "SET_FEATURE_INFO is deprecated. Use ADD_FEATURE_INFO instead.")
set_package_info(${ARGN})
endfunction()
#[=======================================================================[.rst:
.. command:: print_enabled_features
.. deprecated:: 3.8
.. code-block:: cmake
print_enabled_features()
Does the same as:
.. code-block:: cmake
feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
#]=======================================================================]
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()
#[=======================================================================[.rst:
.. command:: print_disabled_features
.. deprecated:: 3.8
.. code-block:: cmake
print_disabled_features()
Does the same as:
.. code-block:: cmake
feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
#]=======================================================================]
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()
Reference in New Issue View Git Blame Copy Permalink