ecbuild_add_option¶

Add a CMake configuration option, which may depend on a list of packages.

ecbuild_add_option( FEATURE <name>
                    [ DEFAULT ON|OFF ]
                    [ DESCRIPTION <description> ]
                    [ REQUIRED_PACKAGES <package1> [<package2> ...] ]
                    [ CONDITION <condition> ]
                    [ ADVANCED ] [ NO_TPL ] )

Options¶

FEATURErequired

name of the feature / option

DEFAULToptional, defaults to ON

if set to ON, the feature is enabled even if not explicitly requested

DESCRIPTIONoptional

string describing the feature (shown in summary and stored in the cache)

REQUIRED_PACKAGESoptional

list of packages required to be found for this feature to be enabled

The package specification can have one of two forms. Either

"<package> [ <version> ... ]"

to search for a given package using the CMake find_package mechanism. The entire specification must be enclosed in quotes and is passed on verbatim. Any options of find_package are supported.

The other specification must start with PROJECT like this

"PROJECT <name> [ VERSION <version> ... ]"

and is used to search for an ecBuild project via ecbuild_use_package. The entire specification must be enclosed in quotes and is passed on verbatim. Any options of ecbuild_use_package are supported.

Note

Arguments inside the package string that require quoting need to use the bracket argument syntax introduced in CMake 3.0 since regular quotes even when escaped are swallowed by the CMake parser.

Alternatively, the name of a CMake variable containing the string can be passed, which will be expanded by ecbuild_find_package:

set( ECCODES_FAIL_MSG
     "grib_api can be used instead (select with -DENABLE_ECCODES=OFF)" )
ecbuild_add_option( FEATURE ECCODES
                    DESCRIPTION "Use eccodes instead of grib_api"
                    REQUIRED_PACKAGES "PROJECT eccodes REQUIRED FAILURE_MSG ECCODES_FAIL_MSG"
                    DEFAULT ON )

CONDITIONoptional

conditional expression which must evaluate to true for this option to be enabled (must be valid in a CMake if statement)

ADVANCEDoptional

mark the feature as advanced

NO_TPLoptional

do not add any REQUIRED_PACKAGES to the list of third party libraries

Usage¶

Features with DEFAULT OFF need to be explcitly enabled by the user with -DENABLE_<FEATURE>=ON. If a feature is enabled, all REQUIRED_PACKAGES are found and CONDITION is met, ecBuild sets the variable HAVE_<FEATURE> to ON. This is the variable to use to check for the availability of the feature.

If a feature is explicitly enabled but the required packages are not found, configuration fails. This only applies when configuring from clean cache. With an already populated cache, use -DENABLE_<FEATURE>=REQUIRE to make the feature a required feature (this cannot be done via the CMake GUI).