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
 1## check if the directory 'blt' exists in the project
 2blt_assert_exists( DIRECTORIES ${PROJECT_SOURCE_DIR}/cmake/blt )
 3
 4## check if the file 'SetupBLT.cmake' file exists
 5blt_assert_exists( FILES ${PROJECT_SOURCE_DIR}/cmake/blt/SetupBLT.cmake )
 6
 7## checks can also be bundled in one call
 8blt_assert_exists( DIRECTORIES ${PROJECT_SOURCE_DIR}/cmake/blt
 9                   FILES ${PROJECT_SOURCE_DIR}/cmake/blt/SetupBLT.cmake )
10
11## check if the CMake targets `foo` and `bar` exist
12blt_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
 1set(mylist A B)
 2
 3set(ENABLE_C TRUE)
 4blt_list_append( TO mylist ELEMENTS C IF ${ENABLE_C} ) # Appends 'C'
 5
 6set(ENABLE_D TRUE)
 7blt_list_append( TO mylist ELEMENTS D IF ENABLE_D ) # Appends 'D'
 8
 9set(ENABLE_E FALSE)
10blt_list_append( TO mylist ELEMENTS E IF ENABLE_E ) # Does not append 'E'
11
12unset(_undefined)
13blt_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
1set(mylist A B A)
2blt_list_remove_duplicates( TO mylist )

blt_convert_to_system_includes

blt_convert_to_system_includes(TARGET <target>)

Converts existing interface includes to system interface includes.

Example
1## convert to system includes for the foo target
2blt_convert_to_system_includes(TARGET foo)