reactos/CMake
1
0
Fork 0
mirror of https://github.com/reactos/CMake.git synced 2024-11-30 15:00:41 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
7aa97b948f
CMake/Modules/FeatureSummary.cmake
Brad King 7aa97b948f FeatureSummary: Add include() to examples 
Since this module's documentation already includes complete usage
examples, make them more complete by showing the include() explicitly.

Issue: #16309
2016-09-15 11:34:34 -04:00

592 lines
22 KiB
CMake
Raw Blame History

#[=======================================================================[.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 feature for a build tree such as::
-- 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.
Functions
^^^^^^^^^
#]=======================================================================]
#=============================================================================
# Copyright 2007-2015 Kitware, Inc.
#
# Distributed under the OSI-approved BSD License (the "License");
# see accompanying file Copyright.txt for details.
#
# This software is distributed WITHOUT ANY WARRANTY; without even the
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the License for more information.
#=============================================================================
# (To distribute this file outside of CMake, substitute the full
# License text for the above reference.)
include("${CMAKE_CURRENT_LIST_DIR}/CMakeParseArguments.cmake")
function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet)
set(_type "ANY")
if("${_property}" MATCHES "REQUIRED_")
set(_type "REQUIRED")
elseif("${_property}" MATCHES "RECOMMENDED_")
set(_type "RECOMMENDED")
elseif("${_property}" MATCHES "RUNTIME_")
set(_type "RUNTIME")
elseif("${_property}" MATCHES "OPTIONAL_")
set(_type "OPTIONAL")
endif()
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(_EnabledFeatures)
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)
set(_currentType OPTIONAL)
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)
# skip QUIET packages, except if they are REQUIRED or INCLUDE_QUIET_PACKAGES has been set
if((NOT "${_currentType}" STREQUAL "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
::
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)
)
The ``feature_summary()`` macro can be used to print information about
enabled or disabled packages or 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 ``set_package_properties()``
to add more useful information, like e.g. a download URL for the
respective package or their purpose in the project.
The ``WHAT`` option is the only mandatory option. Here you specify 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
``OPTIONAL_PACKAGES_FOUND``
only those packages which have been found which have the type OPTIONAL
``OPTIONAL_PACKAGES_NOT_FOUND``
only those packages which have not been found which have the type OPTIONAL
``RECOMMENDED_PACKAGES_FOUND``
only those packages which have been found which have the type RECOMMENDED
``RECOMMENDED_PACKAGES_NOT_FOUND``
only those packages which have not been found which have the type RECOMMENDED
``REQUIRED_PACKAGES_FOUND``
only those packages which have been found which have the type REQUIRED
``REQUIRED_PACKAGES_NOT_FOUND``
only those packages which have not been found which have the type REQUIRED
``RUNTIME_PACKAGES_FOUND``
only those packages which have been found which have the type RUNTIME
``RUNTIME_PACKAGES_NOT_FOUND``
only those packages which have not been found which have the type RUNTIME
With the exception of the ``ALL`` value, these values can be combined
in order to customize the output. For example:
.. code-block:: cmake
feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
If a ``FILENAME`` is given, the information is printed into this file. If
``APPEND`` is used, it is appended to this file, otherwise the file is
overwritten if it already existed. If the VAR option is used, the
information is "printed" into the specified variable. If ``FILENAME`` is
not used, the information is printed to the terminal. Using the
``DESCRIPTION`` option a description or headline can be set which will be
printed above the actual content. If ``INCLUDE_QUIET_PACKAGES`` is given,
packages which have been searched with ``find_package(... QUIET)`` will
also be listed. By default they are skipped. If
``FATAL_ON_MISSING_REQUIRED_PACKAGES`` is given, CMake will abort if a
package which is marked as ``REQUIRED`` has not been found.
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 QUIET packages:
.. code-block:: cmake
include(FeatureSummary)
feature_summary(WHAT ENABLED_FEATURES
INCLUDE_QUIET_PACKAGES
DESCRIPTION "Enabled Features:"
VAR enabledFeaturesText)
message(STATUS "${enabledFeaturesText}")
#]=======================================================================]
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)
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()
set(validWhatParts "ENABLED_FEATURES"
"DISABLED_FEATURES"
"PACKAGES_FOUND"
"PACKAGES_NOT_FOUND"
"OPTIONAL_PACKAGES_FOUND"
"OPTIONAL_PACKAGES_NOT_FOUND"
"RECOMMENDED_PACKAGES_FOUND"
"RECOMMENDED_PACKAGES_NOT_FOUND"
"REQUIRED_PACKAGES_FOUND"
"REQUIRED_PACKAGES_NOT_FOUND"
"RUNTIME_PACKAGES_FOUND"
"RUNTIME_PACKAGES_NOT_FOUND")
list(FIND validWhatParts "${_FS_WHAT}" indexInList)
if(NOT "${indexInList}" STREQUAL "-1")
_FS_GET_FEATURE_SUMMARY( ${_FS_WHAT} _featureSummary ${_FS_INCLUDE_QUIET_PACKAGES} )
set(_fullText "${_FS_DESCRIPTION}${_featureSummary}\n")
if (("${_FS_WHAT}" STREQUAL "REQUIRED_PACKAGES_NOT_FOUND") AND _featureSummary)
set(requiredPackagesNotFound TRUE)
endif()
else()
if("${_FS_WHAT}" STREQUAL "ALL")
set(allWhatParts "ENABLED_FEATURES"
"RUNTIME_PACKAGES_FOUND"
"OPTIONAL_PACKAGES_FOUND"
"RECOMMENDED_PACKAGES_FOUND"
"REQUIRED_PACKAGES_FOUND"
"DISABLED_FEATURES"
"RUNTIME_PACKAGES_NOT_FOUND"
"OPTIONAL_PACKAGES_NOT_FOUND"
"RECOMMENDED_PACKAGES_NOT_FOUND"
"REQUIRED_PACKAGES_NOT_FOUND"
)
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(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:")
set(title_OPTIONAL_PACKAGES_FOUND "The following OPTIONAL packages have been found:")
set(title_OPTIONAL_PACKAGES_NOT_FOUND "The following OPTIONAL packages have not been found:")
set(title_RECOMMENDED_PACKAGES_FOUND "The following RECOMMENDED packages have been found:")
set(title_RECOMMENDED_PACKAGES_NOT_FOUND "The following RECOMMENDED packages have not been found:")
set(title_REQUIRED_PACKAGES_FOUND "The following REQUIRED packages have been found:")
set(title_REQUIRED_PACKAGES_NOT_FOUND "The following REQUIRED packages have not been found:")
set(title_RUNTIME_PACKAGES_FOUND "The following RUNTIME packages have been found:")
set(title_RUNTIME_PACKAGES_NOT_FOUND "The following RUNTIME packages have not been found:")
set(_fullText "${_FS_DESCRIPTION}")
foreach(part ${allWhatParts})
set(_tmp)
_FS_GET_FEATURE_SUMMARY( ${part} _tmp ${_FS_INCLUDE_QUIET_PACKAGES})
if(_tmp)
string(APPEND _fullText "\n-- ${title_${part}}\n${_tmp}\n")
if("${part}" STREQUAL "REQUIRED_PACKAGES_NOT_FOUND")
set(requiredPackagesNotFound TRUE)
endif()
endif()
endforeach()
endif()
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()
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
::
set_package_properties(<name> PROPERTIES
[ URL <url> ]
[ DESCRIPTION <description> ]
[ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
[ PURPOSE <purpose> ]
)
Use this macro to set up information about the named package, which
can then be displayed via FEATURE_SUMMARY(). This can be done either
directly in the Find-module or in the project which uses the module
after the find_package() call. The features for which information can
be set are added automatically by the find_package() command.
``URL <url>``
This should be the homepage of the package, or something similar.
Ideally this is set already directly in the Find-module.
``DESCRIPTION <description>``
A short description what that package is, at most one sentence.
Ideally this is set already directly in the Find-module.
``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 severly limited. If a ``REQUIRED`` package is not
available at buildtime, the project may not even build. This can be
combined with the ``FATAL_ON_MISSING_REQUIRED_PACKAGES`` argument for
``feature_summary()``. 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 Find-module, but must be set in the project.
``PURPOSE <purpose>``
This describes which features this package enables in the
project, i.e. it tells the user what functionality he gets 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
Find-module, but must be set in the project.
Example for setting the info for a package:
.. code-block:: cmake
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")
#]=======================================================================]
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()
# handle the TYPE
if(NOT _SPP_TYPE)
set(_SPP_TYPE OPTIONAL)
endif()
# List the supported types, according to their priority
set(validTypes "RUNTIME" "OPTIONAL" "RECOMMENDED" "REQUIRED" )
list(FIND validTypes ${_SPP_TYPE} _typeIndexInList)
if("${_typeIndexInList}" STREQUAL "-1" )
message(FATAL_ERROR "Bad package property type ${_SPP_TYPE} used in SET_PACKAGE_PROPERTIES(). "
"Valid types are OPTIONAL, RECOMMENDED, REQUIRED and RUNTIME." )
endif()
get_property(_previousType GLOBAL PROPERTY _CMAKE_${_name}_TYPE)
list(FIND validTypes "${_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()
endfunction()
#[=======================================================================[.rst:
.. command:: add_feature_info
::
add_feature_info(<name> <enabled> <description>)
Use this macro to add information about a feature with the given ``<name>``.
``<enabled>`` contains whether this feature is enabled or not.
``<description>`` is a text describing the feature. The information can
be displayed using ``feature_summary()`` for ``ENABLED_FEATURES`` and
``DISABLED_FEATURES`` respectively.
Example for setting the info for a feature:
.. code-block:: cmake
option(WITH_FOO "Help for foo" ON)
add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
#]=======================================================================]
function(ADD_FEATURE_INFO _name _enabled _desc)
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}" )
endfunction()
# The stuff below is only kept for compatibility
#[=======================================================================[.rst:
Legacy Macros
^^^^^^^^^^^^^
The following macros are provided for compatibility with previous
CMake versions:
.. command:: set_package_info
::
set_package_info(<name> <description> [ <url> [<purpose>] ])
Use this macro to set up information about the named package, which
can then be displayed via ``feature_summary()``. This can be done either
directly in the Find-module or in the project which uses the module
after the :command:`find_package` call. The features for which information
can be set are added automatically by the ``find_package()`` command.
#]=======================================================================]
function(SET_PACKAGE_INFO _name _desc)
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
::
set_feature_info(<name> <description> [<url>])
Does the same as::
set_package_info(<name> <description> <url>)
#]=======================================================================]
function(SET_FEATURE_INFO)
SET_PACKAGE_INFO(${ARGN})
endfunction()
#[=======================================================================[.rst:
.. command:: print_enabled_features
::
print_enabled_features()
Does the same as
.. code-block:: cmake
feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
#]=======================================================================]
function(PRINT_ENABLED_FEATURES)
FEATURE_SUMMARY(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
endfunction()
#[=======================================================================[.rst:
.. command:: print_disabled_features
::
print_disabled_features()
Does the same as
.. code-block:: cmake
feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
#]=======================================================================]
function(PRINT_DISABLED_FEATURES)
FEATURE_SUMMARY(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
endfunction()
Reference in New Issue View Git Blame Copy Permalink