Combinators

Combinators#

The combinators module combines cmake functions and aims to reduce repetitive build configuration code.

toolbelt_check_symbol#

A wrapper function around check_cxx_symbol_exists, or check_symbol_exists that adds compile time definitions using add_compile_definitions.

toolbelt_check_symbol(
    SYMBOL <symbol>
    VAR <var>
    FILES [<file>...]
    [C]
)

By default, this checks if the given SYMBOL can be found after including FILES using check_cxx_symbol_exists. A cached result is written to VAR and a compile-time definition with the same name as VAR is created if this check succeeds. Setting the C flag uses check_symbol_exists instead.

This function calls the check function and compile definitions function directly. All features of those commands are supported, such as setting the CMAKE_REQUIRED_* variables.

Examples#

Check if a symbol exists in stdlib.h#

Checks if the "exit" symbol can be found in "stdlib.h":

toolbelt_check_symbol(
    SYMBOL "exit"
    FILES "stdlib.h"
    VAR EXIT_EXISTS
)

This causes the following program to exit with 0 if the symbol exists:

int main() {
#if defined(EXIT_EXISTS)
    return 0;
#else
    return 1;
#endif
}

toolbelt_check_includes#

A wrapper function around check_include_files which adds compile time definitions using add_compile_definitions.

toolbelt_check_includes(
    VAR <var>
    INCLUDES <file>...
    [LANGUAGE C | CXX]
)

By default, this checks that the given INCLUDES can be included in a source file. A cached result is written to VAR and a compile-time definition with the same name as VAR is created if this check succeeds. Setting LANGUAGE to C or CXX uses the C or C++ compiler respectively. If LANGUAGE is not set the C compiler is preferred if it is available.

This function calls check_include_files and add_compile_definitions directly. All features of those commands are supported.

Examples#

Check if stdlib.h can be included#

Check if "stdlib.h" can be included using the C++ compiler:

toolbelt_check_includes(
    VAR STDLIB_EXISTS
    INCLUDES "stdlib.h"
    LANGUAGE CXX
)

This causes the following program to exit with 0 if the check succeeds:

int main() {
#if defined(STDLIB_EXISTS)
    return 0;
#else
    return 1;
#endif
}

toolbelt_add_dep#

A wrapper function around find_package which links a dependency to a target using target_link_libraries.

toolbelt_add_dep(
    <target>
    <dependency>
    [VERSION version]
    [VISIBILITY visibility]
    [LINK_COMPONENTS link_components...]
    [FIND_PACKAGE_ARGS extra_args...]
)

This function calls find_package with the dependency and version and determines the components to add by comparing IMPORTED_TARGETS before and after calling find_package. All new components are linked to the target using target_link_libraries with an optional VISIBILITY.

Set LINK_COMPONENTS to manually specify which components should be linked to the target, overriding the components found using the IMPORTED_TARGETS logic. This option is useful if only a subset of components declared by find_package should be linked to target.

Important

Some find_package modules declare extra targets which may not be intended to be used in target_link_libraries.

This function calls the find_package and target_link_libraries directly, so all features of those commands are supported. Set FIND_PACKAGE_ARGS to pass additional arguments to find_package.

Note

LINK_COMPONENTS is not passed to find_package, instead use FIND_PACKAGE_ARGS to specify COMPONENTS that find_package should use.

Examples#

Find only some components#

This finds the Interpreter and Development components of Python and links all found components to :cmake`target`:

toolbelt_add_dep(
    target
    Python
    FIND_PACKAGE_ARGS COMPONENTS Interpreter Development
)

toolbelt_setup_gtest#

A convenience function which links GTest and an optional testing library to a test executable and calls gtest_discover_tests to find tests.

toolbelt_setup_gtest(
    <test_executable>
    [ADD_LIBRARIES add_libraries...]
)

The test_executable specifies the executable to discover tests with and ADD_LIBRARIES specifies additional libraries which should be linked to test_executable.

Note

This function does not call enable_testing. enable_testing should be called from the source directory where the tests are defined.

Examples#

Discover tests for an executable#

This discovers tests for test_executable and links additional_library to the executable.

setup_gtest(
    "test_executable"
    ADD_LIBRARIES "additional_library"
)
Contents