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