Utility Macros¶

blt_assert_exists¶

blt_assert_exists(
  [DIRECTORIES <dir1> [<dir2> ...] ]
  [FILES <file1> [<file2> ...] ]
  [TARGETS <target1> [<target2> ...] ] )

Checks if the specified directory, file and/or cmake target exists and throws an error message.

Note

The behavior for checking if a given file or directory exists is well-defined only for absolute paths.

Example¶

## check if the directory 'blt' exists in the project
blt_assert_exists( DIRECTORIES ${PROJECT_SOURCE_DIR}/cmake/blt )

## check if the file 'SetupBLT.cmake' file exists
blt_assert_exists( FILES ${PROJECT_SOURCE_DIR}/cmake/blt/SetupBLT.cmake )

## checks can also be bundled in one call
blt_assert_exists( DIRECTORIES ${PROJECT_SOURCE_DIR}/cmake/blt
                   FILES ${PROJECT_SOURCE_DIR}/cmake/blt/SetupBLT.cmake )

## check if the CMake targets `foo` and `bar` exist
blt_assert_exists( TARGETS foo bar )

blt_append_custom_compiler_flag¶

blt_append_custom_compiler_flag(
                   FLAGS_VAR  flagsVar       (required)
                   DEFAULT    defaultFlag    (optional)
                   GNU        gnuFlag        (optional)
                   CLANG      clangFlag      (optional)
                   INTEL      intelFlag      (optional)
                   INTELLLVM  intelLLVMFlag  (optional)
                   XL         xlFlag         (optional)
                   MSVC       msvcFlag       (optional)
                   MSVC_INTEL msvcIntelFlag  (optional)
                   PGI        pgiFlag        (optional)
                   CRAY       crayFlag       (optional))

Appends compiler-specific flags to a given variable of flags

If a custom flag is given for the current compiler, we use that. Otherwise, we will use the DEFAULT flag (if present).

If ENABLE_FORTRAN is ON, any flagsVar with fortran (any capitalization) in its name will pick the compiler family (GNU,CLANG, INTEL, etc) based on the fortran compiler family type. This allows mixing C and Fortran compiler families, e.g. using Intel fortran compilers with clang C compilers.

When using the Intel toolchain within Visual Studio, we use the MSVC_INTEL flag, when provided, with a fallback to the MSVC flag.

blt_check_code_compiles¶

blt_check_code_compiles(CODE_COMPILES  <variable>
                        VERBOSE_OUTPUT <ON|OFF (default OFF)>
                        SOURCE_STRING  <quoted C++ program>)

This macro checks if a snippet of C++ code compiles.

CODE_COMPILES: The boolean variable that will be filled with the compilation result.
VERBOSE_OUTPUT: Optional parameter to output debug information (Default: OFF)
SOURCE_STRING: The source snippet to compile.

SOURCE_STRING must be a valid C++ program with a main() function and must be passed in as a quoted string variable. Otherwise, CMake will convert the string into a list and lose the semicolons. You can use any CMake method of sending a string, but we recommend the bracket argument method shown below so you do not have to escape your quotes:

blt_check_code_compiles(CODE_COMPILES  hello_world_compiled
                        SOURCE_STRING
[=[
#include <iostream>

int main(int, char**)
{

    std::cout << "Hello World!" << std::endl;

    return 0;
}
]=])

blt_find_libraries¶

blt_find_libraries( FOUND_LIBS <FOUND_LIBS variable name>
                    NAMES      [libname1 [libname2 ...]]
                    REQUIRED   [TRUE (default) | FALSE ]
                    PATHS      [path1 [path2 ...]])

This command is used to find a list of libraries.

If the libraries are found the results are appended to the given FOUND_LIBS variable name. NAMES lists the names of the libraries that will be searched for in the given PATHS.

If REQUIRED is set to TRUE, BLT will produce an error message if any of the given libraries are not found. The default value is TRUE.

PATH lists the paths in which to search for NAMES. No system paths will be searched.

blt_list_append¶

blt_list_append(TO       <list>
                ELEMENTS [<element>...]
                IF       <bool>)

Appends elements to a list if the specified bool evaluates to true.

This macro is essentially a wrapper around CMake’s list(APPEND ...) command which allows inlining a conditional check within the same call for clarity and convenience.

This macro requires specifying:

The target list to append to by passing TO <list>

A condition to check by passing IF <bool>

The list of elements to append by passing ELEMENTS [<element>...]

Note

The argument passed to the IF option has to be a single boolean value and cannot be a boolean expression since CMake cannot evaluate those inline.

Example¶

set(mylist A B)

set(ENABLE_C TRUE)
blt_list_append( TO mylist ELEMENTS C IF ${ENABLE_C} ) # Appends 'C'

set(ENABLE_D TRUE)
blt_list_append( TO mylist ELEMENTS D IF ENABLE_D ) # Appends 'D'

set(ENABLE_E FALSE)
blt_list_append( TO mylist ELEMENTS E IF ENABLE_E ) # Does not append 'E'

unset(_undefined)
blt_list_append( TO mylist ELEMENTS F IF _undefined ) # Does not append 'F'

blt_list_remove_duplicates¶

blt_list_remove_duplicates(TO <list>)

Removes duplicate elements from the given TO list.

This macro is essentially a wrapper around CMake’s list(REMOVE_DUPLICATES ...) command but doesn’t throw an error if the list is empty or not defined.

Example¶

set(mylist A B A)
blt_list_remove_duplicates( TO mylist )

blt_find_target_dependencies¶

set(_target_list "")
blt_find_target_dependencies(TARGET <target> TLIST _target_list)

Recursively adds all link libraries and interface link libraries of the given target to the given list. Handles CMake targets and BLT registered libraries.

blt_convert_to_system_includes¶

blt_convert_to_system_includes(TARGET   <target>
                               TARGETS  [<target>...]
                               CHILDREN [TRUE | FALSE (default)]
                               [QUIET])

Converts existing interface includes to system interface includes. Warns if a target does not exist unless QUIET is specified. Recurses through link libraries and interface link libraries if CHILDREN TRUE is specified.

Note

The argument TARGET will be deprecated in the near future. Until then, if both TARGET and TARGETS is given, all given target include directories will be converted.

Example¶

blt_convert_to_system_includes(TARGETS foo)