ECMInstalledLibraryCheck — Extra CMake Modules 6.31.0 documentation

# 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