# 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

`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:

      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:

      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:

      include(FeatureSummary)
      feature_summary(WHAT ENABLED_FEATURES
                      INCLUDE_QUIET_PACKAGES
                      DESCRIPTION "Enabled Features:"
                      VAR enabledFeaturesText)
      message(STATUS "${enabledFeaturesText}")

`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:

      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")

`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:

      option(WITH_FOO "Help for foo" ON)
      add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")

## Legacy Macros

The following macros are provided for compatibility with previous CMake versions:

`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 `find_package()` call. The features for which information can be set are added automatically by the `find_package()` command.

`set_feature_info`

      set_feature_info(<name> <description> [<url>])

  Does the same as:

      set_package_info(<name> <description> <url>)

`print_enabled_features`

      print_enabled_features()

  Does the same as

      feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")

`print_disabled_features`

      print_disabled_features()

  Does the same as

      feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")