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

NAMErequired

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

VERSIONoptional

minimum required package version

COMPONENTSoptional

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

EXACToptional, requires VERSION

require the exact version rather than a minimum version

URLoptional

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

DESCRIPTIONoptional

literal string or name of CMake variable describing the package

TYPEoptional, one of RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED

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

PURPOSEoptional

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

FAILURE_MSGoptional

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

REQUIREDoptional (equivalent to TYPE REQUIRED, and overrides TYPE argument)

fail if package cannot be found

QUIEToptional

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.