ecbuild_find_package

Find a package and import its configuration.

ecbuild_find_package( [ NAME ] <name>
                      [ [ VERSION ] <version> [ EXACT ] ]
                      [ COMPONENTS <component1> [ <component2> ... ] ]
                      [ URL <url> ]
                      [ DESCRIPTION <description> ]
                      [ TYPE <type> ]
                      [ PURPOSE <purpose> ]
                      [ FAILURE_MSG <message> ]
                      [ REQUIRED ]
                      [ QUIET ] )

Options

NAME : required

package name (used as Find<name>.cmake and <name>-config.cmake)

VERSION : optional

minimum required package version

COMPONENTS : optional

list of package components to find (behaviour depends on the package)

EXACT : optional, requires VERSION

require the exact version rather than a minimum version

URL : optional

homepage of the package (shown in summary and stored in the cache)

DESCRIPTION : optional

literal string or name of CMake variable describing the package

TYPE : optional, one of RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED

type of dependency of the project on this package (defaults to OPTIONAL)

PURPOSE : optional

literal string or name of CMake variable describing which functionality this package enables in the project

FAILURE_MSG : optional

literal string or name of CMake variable containing a message to be appended to the failure message if the package is not found

REQUIRED : optional (equivalent to TYPE REQUIRED, and overrides TYPE argument)

fail if package cannot be found

QUIET : optional

do not output package information if found

Input variables

The following CMake variables influence the behaviour if set (<name> is the package name as given, <NAME> is the capitalised version):

<name>_ROOT:install prefix path of the package <name>_PATH:install prefix path of the package, prefer <name>_ROOT <NAME>_PATH:install prefix path of the package, prefer <name>_ROOT <name>_DIR:directory containing the <name>-config.cmake file (usually <install-prefix>/lib/cmake/<name>), prefer <name>_ROOT CMAKE_PREFIX_PATH:  Specify this when most packages are installed in same prefix

The environment variables <name>_ROOT, <name>_PATH, <NAME>_PATH, <name>_DIR are taken into account only if the corresponding CMake variables are unset.

Note, some packages are found via Find<name>.cmake and may have their own mechanism of finding paths with other variables, e.g. <name>_HOME. See the corresponing Find<name>.cmake file for datails, or use cmake –help-module Find<name> if it is a standard CMake-recognized module.

Usage

The search proceeds as follows:

1. If <name> is a subproject of the top-level project, search for <name>-config.cmake in <name>_BINARY_DIR.

2. If Find<name>.cmake exists in CMAKE_MODULE_PATH, search using it.

3. If any paths have been specified by the user via CMake or environment variables as given above:

   • search for <name>-config.cmake in those paths only

   • fail if the package was not found in any of those paths

   • Search paths are in order from high to low priority:

     • <name>_DIR
     • <name>_ROOT
     • <name>_PATH
     • <NAME>_PATH
     • ENV{<name>_ROOT}
     • ENV{<name>_PATH}
     • ENV{<NAME>_PATH}
     • CMAKE_PREFIX_PATH
     • ENV{<name>_DIR}
     • ENV{CMAKE_PREFIX_PATH}
     • system paths

     See CMake documentation of find_package() for details on search

4. Fail if the package was not found and is REQUIRED.