ECMInstalledLibraryCheck

Generates a check to test artifacts of the library installation, like the self-containedness of the CMake config files as well as of the official public headers in the deployed directory layout.

ecm_add_installed_library_check(<library_target>
    [PACKAGE_NAME <package_name>]
    [PACKAGE_VERSION <package_version>]
    {NO_PACKAGE_VERSION]
    [PACKAGE_TARGET_NAMESPACE <package_target_namespace>]
    [NO_PACKAGE_TARGET_NAMESPACE]
    [COMPILE_DEFINITIONS <definition> [...]]
    [EXTRA_DEPENDENCIES <dependency> [<version>] [...]]
    [EXTRA_LINK_LIBRARIES <library> [...]]
)

The function creates a target <library_target>_installed_library_check which can be invoked after the installation to check if the installed library artifacts are self-contained when used by a consumer. All these targets are added as dependency to a target all_installed_library_check, which is created at the level where this module is included, if there is none yet.

The check generates a CMake project with a dummy library which searches the given package for any specified version, links to the exported target as imported from the package’s CMake config file and as its sources add for each given include strings a source file with just the content #include <include_string>. Additionally checks are added to the CMake code and the source files for any CMake variables, compile definitions and preprocessor macros as configured by the additional functions (see below). This project then is configured with CMake and all these sources are built. The check is considered as passed, when the build completes.

PACKAGE_NAME specifies the name of the CMake package to check for. The default is ${PROJECT_NAME}.

PACKAGE_VERSION specifies the version of the CMake package to check for. The default is ${PROJECT_VERSION} if set and NO_PACKAGE_VERSION not being used, otherwise none.

NO_PACKAGE_VERSION defines that the CMake package has no version to check for.

PACKAGE_TARGET_NAMESPACE specifies what namespace the exported target name of the library is placed in. The default is the value estimated for the package name, unless NO_PACKAGE_TARGET_NAMESPACE is set.

NO_PACKAGE_TARGET_NAMESPACE defines that the library target is exported in the package without any namespace.

COMPILE_DEFINITIONS can be used to set custom definitions for the test builds against the headers.

EXTRA_DEPENDENCIES can be used to add custom dependencies to search for with find_package(). This can be used if the current dependencies declared in the installed CMake config file are not complete, but can not be changed.

EXTRA_LINK_LIBRARIES can be used to add custom libraries to link to with target_link_libraries(). This can be used if the current list of libraries in the public interface is not complete, but can not be changed.

ecm_installed_library_check_include_strings(<library_target>
    HEADERS <header> [...]
    [PREFIX <prefix>]
)

This function registers include strings with the check, by listing files which will be used as official public headers.

HEADERS specifies the header files whose base names will be available as public include strings. The actual path of any file listed is ignored, it also does not need to reference any existing file.

PREFIX specifies a prefix which consumers need to prepend to the base names of the headers passed to HEADERS. The argument <prefix> is specified without a trailing “/”. Default is none.

ecm_installed_library_check_cmake_variable(<library_target>
    NAME <name>
    [VALUE <value>]
    [UNDEFINED]
    [TYPE <type>]
)

This function registers a CMake variable with the check which should be tested for presence and its value after the library’s CMake package has been found.

NAME specifies the name of a variable expected to be set after finding the package.

VALUE specifies the value expected to be set for the variable. For variables of the type BOOL the usual evaluation of CMake to a boolean value is checked. If this argument is not passed, the variable. is only tested for being defined.

UNDEFINED specifies if the variable should be tested for being undefined.

TYPE specifies the type of the variable. The options are BOOL, STRING. Default is STRING.

ecm_installed_library_check_compile_definition(<library_target>
    NAME <name>
    [VALUE <value>]
    [UNDEFINED]
)

This function registers a compile definition with the check which should be tested for being set on the imported library target.

NAME specifies the name of the compile definition to test.

VALUE specifies the value expected to be set for the compile definition. If this argument is not passed, the compile definition is only tested for being defined. Only numeric values are supported.

UNDEFINED specifies if the compile definition should be tested for being undefined.

ecm_installed_library_check_preprocessor_macro(<library_target>
    NAME <name>
    [VALUE <value>]
    [UNDEFINED]
)

This function registers a preprocessor macro with the check which should be tested for being present with all registered include strings.

NAME specifies the name of the macro to test.

VALUE specifies the value expected to be set for the macro. If this argument is not passed, the macro is only tested for being defined. Only numeric values are supported.

UNDEFINED specifies if the macro should be tested for being undefined.

ecm_installed_library_check_version_preprocessor_macros(<library_target>
    [PREFIX <prefix>]
    [VERSION <version>]
)

This function is a convenience utility to register a usual set of preprocessor macros with the check which should be tested for being present with all registered include strings and match the given version. Such macros are e.g. created by the macro ecm_setup_version() from the module ECMSetupVersion when using the VERSION_HEADER argument to generate a version header.

PREFIX specifies the prefix of the version macros to test. The expected macro names are:

• <prefix>_VERSION (hexadecimal number in 0xMMmmpp format)

• <prefix>_VERSION_MAJOR

• <prefix>_VERSION_MINOR

• <prefix>_VERSION_PATCH

Default is the library target name in upper case.

VERSION specifies the version string “<major>.<minor>.<patch>” with the expected version values. The default is any “VERSION” property set on the target, otherwise any package version defined for the check, or otherwise ${PROJECT_VERSION}.

Example usage:

# add a non-default target "MyLib_installed_library_check",
# which will test for a CMake config file for "MyPackage",
# at version "1.0",  with the imported library target
# "MyPackage::MyLib" and whose include strings (headers)
# can be used self-contained when linking the target
ecm_add_installed_library_check(MyLib
    PACKAGE_NAME "MyPackage"
    PACKAGE_VERSION "1.0"
)

# for any <MLFoo> etc. includes
ecm_installed_library_check_include_strings(MyLib
    HEADERS
        /absolute/path/MLFoo
        relative/path/MLBar
        # etc
)

# for any <ML/Foo> etc. includes
ecm_installed_library_check_include_strings(MyLib
    HEADERS
        /absolute/path/Foo
        relative/path/Bar
        # etc
    PREFIX ML
)

Since 6.30