diff --git a/Help/policy/CMP0183.rst b/Help/policy/CMP0183.rst index 6804c3be6a..f2d660156a 100644 --- a/Help/policy/CMP0183.rst +++ b/Help/policy/CMP0183.rst @@ -5,7 +5,7 @@ CMP0183 :command:`add_feature_info` supports full :ref:`Condition Syntax`. -The ```` parameter accepts a :ref:`semicolon-separated list `` parameter accepts a :ref:`semicolon-separated list ` of conditions. CMake 3.31 and lower evaluate each ``condition`` as ``if(${condition})``, which does not properly handle conditions with nested paren groups. CMake 4.0 and above instead prefer diff --git a/Modules/FeatureSummary.cmake b/Modules/FeatureSummary.cmake index c4b27da9ec..6b83903d14 100644 --- a/Modules/FeatureSummary.cmake +++ b/Modules/FeatureSummary.cmake @@ -7,32 +7,45 @@ include_guard(GLOBAL) FeatureSummary -------------- -Functions for generating a summary of enabled/disabled features. +.. only:: html -These functions can be used to generate a summary of enabled and disabled -packages and/or features for a build tree such as:: + .. contents:: - -- The following features have been enabled: +This module provides commands for generating a summary of enabled/disabled +features. - * Example, usage example +Load this module in CMake with: - -- The following OPTIONAL packages have been found: +.. code-block:: cmake - * LibXml2 (required version >= 2.4), XML library, - Enables HTML-import in MyWordProcessor - Enables odt-export in MyWordProcessor - * PNG, image library, - Enables saving screenshots + include(FeatureSummary) - -- The following OPTIONAL packages have not been found: +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:: - * Lua, the Lua scripting language, - Enables macros in MyWordProcessor - * OpenGL, Open Graphics Library + -- The following features have been enabled: + + * Example, usage example + + -- The following OPTIONAL packages have been found: + + * LibXml2 (required version >= 2.4), XML library, + Enables HTML-import in MyWordProcessor + Enables odt-export in MyWordProcessor + * PNG, image library, + Enables saving screenshots + + -- The following OPTIONAL packages have not been found: + + * Lua, the Lua scripting language, + 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 @@ -69,8 +82,9 @@ Global Properties 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. + 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. @@ -88,6 +102,519 @@ Global Properties The following _DESCRIPTION> have been found: If not set, default string `` 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 + | _PACKAGES_FOUND | _PACKAGES_NOT_FOUND + | ENABLED_FEATURES | DISABLED_FEATURES) + [FILENAME ] + [APPEND] + [VAR ] + [INCLUDE_QUIET_PACKAGES] + [FATAL_ON_MISSING_REQUIRED_PACKAGES] + [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 ```` defined by the + :variable:`FeatureSummary_PKG_TYPES` global property, the following + information can also be used: + + ``_PACKAGES_FOUND`` + The list of only packages of type ```` which have been found. + ``_PACKAGES_NOT_FOUND`` + The list of only packages of 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 `` + If this option is given, the information is printed into this file instead + of the terminal. Relative ```` 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 ```` provided + by the ``FILENAME`` option, otherwise the file is overwritten if it already + exists. + + ``VAR `` + If this option is given, the information is stored into the specified + variable ```` 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 `` + 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 ``. + + ``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( + + PROPERTIES + [URL ] + [DESCRIPTION ] + [TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)] + [PURPOSE ] + ) + + Use this command to configure and provide information about the package + named ````, which can then be displayed using the + :command:`feature_summary()` command. This command can be called either + directly within the corresponding :ref:`Find module ` 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: + + ```` + The name of the package. For example, as specified in the + :command:`find_package()` argument. + + ``PROPERTIES`` + Specifies the properties to set: + + ``URL `` + This should be the homepage of the package, or something similar. + Ideally this is set already directly in the + :ref:`Find module `. + + ``DESCRIPTION `` + A short description what that package is, at most one sentence. + Ideally this is set already directly in the + :ref:`Find module `. + + ``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 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 `, but must be set in + the project. + + The accepted types can be changed by setting the + :variable:`FeatureSummary_PKG_TYPES` global property. + + ``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 `, but must be set in the + project. + +Adding Feature Info +""""""""""""""""""" + +.. command:: add_feature_info + + Adds feature information: + + .. code-block:: cmake + + add_feature_info( ) + + Use this command to add information about a feature identified with a given + ````. + + .. rubric:: The arguments are: + + ```` + Identification name for a feature being added. + + ```` + Specifies the conditions that determine whether this feature is enabled + or disabled. + + The ```` argument can be: + + * A single condition (such as a variable name). + + * .. versionadded:: 3.8 + A :ref:`semicolon-separated list ` of multiple + conditions. + + * .. versionadded:: 4.0 + A full :ref:`Condition Syntax` as used in an ``if()`` + clause. See policy :policy:`CMP0183`. This enables using entire + condition syntax (such as grouping conditions with parens and + similar). + + ```` + 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( [ []]) + + ```` + Name of the package. + + ```` + A short description of the package. + + ```` + Homepage of the package. + + ```` + The purpose of the package. + + This command can be used either directly in the + :ref:`Find module ` 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( []) + + Does the same as: + + .. code-block:: cmake + + set_package_info( []) + +.. 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) @@ -105,15 +632,7 @@ 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) @@ -208,155 +727,6 @@ function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet) set(${_var} "${_currentFeatureText}" PARENT_SCOPE) endfunction() - -#[=======================================================================[.rst: -.. command:: feature_summary - - .. code-block:: cmake - - feature_summary([FILENAME ] - [APPEND] - [VAR ] - [INCLUDE_QUIET_PACKAGES] - [FATAL_ON_MISSING_REQUIRED_PACKAGES] - [DESCRIPTION | DEFAULT_DESCRIPTION] - [QUIET_ON_EMPTY] - WHAT (ALL - | PACKAGES_FOUND | PACKAGES_NOT_FOUND - | _PACKAGES_FOUND | _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 ```` defined by the - :variable:`FeatureSummary_PKG_TYPES` global property, the following - information can also be used: - - ``_PACKAGES_FOUND`` - The list of only packages of type ```` which have been found. - ``_PACKAGES_NOT_FOUND`` - The list of only packages of 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 `` - If this option is given, the information is printed into this file instead - of the terminal. Relative ```` 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 ```` provided - by the ``FILENAME`` option, otherwise the file is overwritten if it already - exists. - - ``VAR `` - If this option is given, the information is stored into the specified - variable ```` instead of the terminal. - - ``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 ``. - - ``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( args...) set(options APPEND @@ -498,93 +868,8 @@ function(FEATURE_SUMMARY) 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( PROPERTIES - [URL ] - [DESCRIPTION ] - [TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)] - [PURPOSE ] - ) - - Use this function to configure and provide information about the package named - ````, which can then be displayed using the - :command:`feature_summary()` command. This can be performed either directly - within the corresponding :ref:`Find module ` 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 `` - This should be the homepage of the package, or something similar. - Ideally this is set already directly in the - :ref:`Find module `. - - ``DESCRIPTION `` - A short description what that package is, at most one sentence. - Ideally this is set already directly in the - :ref:`Find module `. - - ``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 `, but must be set in the project. - The accepted types can be changed by setting the - :variable:`FeatureSummary_PKG_TYPES` global property. - - ``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 `, 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.") @@ -609,7 +894,6 @@ function(SET_PACKAGE_PROPERTIES _name _props) 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}") @@ -619,7 +903,6 @@ function(SET_PACKAGE_PROPERTIES _name _props) 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}" ) @@ -648,68 +931,8 @@ function(SET_PACKAGE_PROPERTIES _name _props) set_property(GLOBAL PROPERTY _CMAKE_${_name}_TYPE "${_SPP_TYPE}" ) endif() endif() - endfunction() -#[=======================================================================[.rst: -.. command:: add_feature_info - - .. code-block:: cmake - - add_feature_info( ) - - Use this function to add information about a feature identified with a given - ````. The ```` contains whether this feature is enabled or - not. It can be a variable or a list of conditions. - ```` 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 - ```` can be a list of conditions. - - .. versionchanged:: 4.0 - Full :ref:`Condition Syntax` is now supported for ````. - 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 @@ -749,34 +972,8 @@ function(ADD_FEATURE_INFO _name _depends _desc) 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( [ [] ]) - - Set up information about the package ````, which can then be displayed - via :command:`feature_summary()`. This can be done either directly in the - :ref:`Find module ` 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) @@ -796,62 +993,17 @@ function(SET_PACKAGE_INFO _name _desc) endif() endfunction() -#[=======================================================================[.rst: -.. command:: set_feature_info - - .. deprecated:: 3.8 - - .. code-block:: cmake - - set_feature_info( []) - - Does the same as: - - .. code-block:: cmake - - set_package_info( []) -#]=======================================================================] 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:\")")