Ucm

ucm - useful cmake macros

ucm is a collection of cmake macros that help with:

• managing compiler/linker flags
• collecting source files with grouping in IDEs that mimics the filesystem structure
• easy removing source files from already collected ones
• adding a precompiled header for targets
• unity builds of targets
• others... contribution is welcome!

Tested with MSVC/GCC/Clang.

cotire is an optional submodule for the ucm_add_target() macro either do git submodule update --init after cloning or include cotire in your cmake files before ucm.

Documentation

<a name="macros"></a>Macros:

• ucm_print_flags
• ucm_add_flags
• ucm_set_flags
• ucm_remove_flags
• ucm_add_linker_flags
• ucm_set_linker_flags
• ucm_set_runtime
• ucm_set_xcode_attrib
• ucm_add_files
• ucm_add_dirs
• ucm_count_sources
• ucm_include_file_in_sources
• ucm_dir_list
• ucm_remove_files
• ucm_remove_directories
• ucm_add_target

Macro notation: myMacro(NAME <name> [FLAG]) - NAME and a name after it are required and FLAG is optional (because in brackets).

<a name="ucm_print_flags"></a>macro ucm_print_flags()

Prints all relevant flags - for example with -DCMAKE_BUILD_TYPE=Debug given to cmake for makefiles:

CMAKE_C_FLAGS_DEBUG: -g
CMAKE_CXX_FLAGS_DEBUG: -g
CMAKE_C_FLAGS:  --save-temps -std=c++98 -pedantic -m64 -O2 -fvisibility=hidden
CMAKE_CXX_FLAGS:  --save-temps -std=c++98 -pedantic -m64 -O2 -fvisibility=hidden

or for a multi config generator like Visual Studio:

CMAKE_C_FLAGS_DEBUG: /D_DEBUG /MDd /Zi /Ob0 /Od /RTC1
CMAKE_CXX_FLAGS_DEBUG: /D_DEBUG /MDd /Zi /Ob0 /Od /RTC1
CMAKE_C_FLAGS_RELEASE: /MD /O2 /Ob2 /D NDEBUG
CMAKE_CXX_FLAGS_RELEASE: /MD /O2 /Ob2 /D NDEBUG
CMAKE_C_FLAGS:  /DWIN32 /D_WINDOWS /W3 /W4
CMAKE_CXX_FLAGS:  /DWIN32 /D_WINDOWS /W3 /GR /EHsc /W4

<a name="ucm_add_flags"></a>macro ucm_add_flags([C] [CXX] [CONFIG <config>] flag1 flag2 flag3...)

Append the flags to a different set depending on it's options - examples:

ucm_add_flags(-O3 -Wextra) # will add to CMAKE_C_FLAGS and CMAKE_CXX_FLAGS
ucm_add_flags(C -O3) # will add to CMAKE_C_FLAGS
ucm_add_flags(CXX -O3) # will add to CMAKE_CXX_FLAGS
ucm_add_flags(-O3 -Wall CONFIG Debug) # will add to CMAKE_C_FLAGS_DEBUG and CMAKE_CXX_FLAGS_DEBUG
ucm_add_flags(C -Wall CONFIG Debug Release) # will add to CMAKE_C_FLAGS_DEBUG and CMAKE_C_FLAGS_RELEASE

<a name="ucm_set_flags"></a>macro ucm_set_flags([C] [CXX] [CONFIG <config>] flag1 flag2 flag3...)

Removes the old and sets the new flags to a different set depending on it's options - examples:

ucm_set_flags(CXX) # will clear CMAKE_CXX_FLAGS
ucm_set_flags() # will clear both CMAKE_C_FLAGS and CMAKE_CXX_FLAGS
ucm_set_flags(CXX -O3) # will set CMAKE_CXX_FLAGS
ucm_set_flags(-O3 -Wall CONFIG Debug) # will set CMAKE_C_FLAGS_DEBUG and CMAKE_CXX_FLAGS_DEBUG

<a name="ucm_remove_flags"></a>macro ucm_remove_flags([C] [CXX] [CONFIG <config>] flag1 flag2 flag3...)

Removes the flags from a different set depending on it's options - examples:

ucm_remove_flags(CXX /EHsc /GR) # will remove from CMAKE_CXX_FLAGS
ucm_remove_flags(/W3) # will remove from both CMAKE_C_FLAGS and CMAKE_CXX_FLAGS
ucm_remove_flags(/RTC1 CONFIG Debug) # will remove from CMAKE_C_FLAGS_DEBUG and CMAKE_CXX_FLAGS_DEBUG

<a name="ucm_add_linker_flags"></a>macro ucm_add_linker_flags([EXE] [MODULE] [SHARED] [STATIC] [CONFIG <config>] flag1 flag2 flag3...)

Append the flags to a different set depending on it's options - examples:

ucm_add_linker_flags(/NXCOMPAT) # will add to CMAKE_<TYPE>_LINKER_FLAGS (TYPE is all 4 - exe/module/shared/static)
ucm_add_linker_flags(EXE /DYNAMICBASE CONFIG Release) # will add to CMAKE_EXE_LINKER_FLAGS_RELEASE only
ucm_add_flags(EXE /DYNAMICBASE CONFIG Debug Release) # will add to CMAKE_EXE_LINKER_FLAGS_DEBUG and CMAKE_EXE_LINKER_FLAGS_RELEASE

<a name="ucm_set_linker_flags"></a>macro ucm_set_linker_flags([EXE] [MODULE] [SHARED] [STATIC] [CONFIG <config>] flag1 flag2 flag3...)

Removes the old and sets the new flags to a different set depending on it's options - examples:

ucm_set_linker_flags(/NXCOMPAT) # will clear all CMAKE_<TYPE>_LINKER_FLAGS
ucm_set_linker_flags(EXE /DYNAMICBASE CONFIG Release) # will set CMAKE_EXE_LINKER_FLAGS_RELEASE only

<a name="ucm_set_runtime"></a>macro ucm_set_runtime([STATIC] [DYNAMIC])

Sets the runtime to static/dynamic - for example with Visual Studio as a generator:

ucm_print_flags()
ucm_set_runtime(STATIC)
ucm_print_flags()

will result in:

CMAKE_C_FLAGS_DEBUG: /D_DEBUG /MDd /Zi /Ob0 /Od /RTC1
CMAKE_CXX_FLAGS_DEBUG: /D_DEBUG /MDd /Zi /Ob0 /Od /RTC1
CMAKE_C_FLAGS_RELEASE: /MD /O2 /Ob2 /D NDEBUG
CMAKE_CXX_FLAGS_RELEASE: /MD /O2 /Ob2 /D NDEBUG
CMAKE_C_FLAGS:  /DWIN32 /D_WINDOWS /W3 /W4
CMAKE_CXX_FLAGS:  /DWIN32 /D_WINDOWS /W3 /GR /EHsc /W4

CMAKE_C_FLAGS_DEBUG: /D_DEBUG /MTd /Zi /Ob0 /Od /RTC1
CMAKE_CXX_FLAGS_DEBUG: /D_DEBUG /MTd /Zi /Ob0 /Od /RTC1
CMAKE_C_FLAGS_RELEASE: /MT /O2 /Ob2 /D NDEBUG
CMAKE_CXX_FLAGS_RELEASE: /MT /O2 /Ob2 /D NDEBUG
CMAKE_C_FLAGS:  /DWIN32 /D_WINDOWS /W3 /W4
CMAKE_CXX_FLAGS:  /DWIN32 /D_WINDOWS /W3 /GR /EHsc /W4

<a name="ucm_set_xcode_attrib"></a>macro ucm_set_xcode_attrib(name value [CLEAR] [CONFIG <config>])

Sets an Xcode attribute and optionally per-configuration:

ucm_set_xcode_attrib(DEBUG_INFORMATION_FORMAT "dwarf-with-dsym")
ucm_set_xcode_attrib(DEAD_CODE_STRIPPING "YES" CONFIG Debug Release)

will result in:

CMAKE_XCODE_ATTRIBUTE_DEBUG_INFORMATION_FORMAT: "dwarf-with-dsym"
CMAKE_XCODE_ATTRIBUTE_DEAD_CODE_STRIPPING[variant=Debug]: "YES"
CMAKE_XCODE_ATTRIBUTE_DEAD_CODE_STRIPPING[variant=Release]: "YES"

<a name="ucm_add_files"></a>macro ucm_add_files(src1 src2 scr3... TO <sources> [FILTER_POP <num>])

Adds the sources to the sources variable and sets up filters for the solution explorer of Visual Studio (probably for XCode/CodeBlocks too).

The filters will mimic the filesystem - if we have given dir1/test/a.cpp we would have by default dir1/test as nested filters in the solution explorer. This can be controlled with FILTER_POP - 1 would result in only test as a filter and 2 would result in no filter for a.cpp - see ucm_add_dirs for a visual example.

ucm_add_files("dir/some1.cpp" "dir/some1.h" TO sources)

<a name="ucm_add_dirs"></a>macro ucm_add_dirs(dir1 dir2 dir3... TO <sources> [RECURSIVE] [FILTER_POP <num>] [ADDITIONAL_EXT ext1 ext2 ...])

Adds all sources (sources and headers with all valid c/c++ extensions) from the directories given.

Can be recursive with the RECURSIVE flag.

Like ucm_add_files() filters for the solution explorer of IDEs can be controlled with FILTER_POP - example:

| CMake code | result | |--------------------------------------------------|----------------------------------| | ucm_add_dirs(util TO sources) | | | ucm_add_dirs(util TO sources FILTER_POP 1) | |

Additional extensions for collection can be added with the ADDITIONAL_EXT list.

<a name="ucm_count_sources"></a>macro ucm_count_sources(src1 src2 src3... RESULT <result>)

Given a list of sources - returns the number of source files (no headers - only valid source extensions) in the result.

set(sources "a.cpp;b.cpp;h.hpp")
ucm_count_sources(${sources} c.cpp d.cpp RESULT res) # would return 4 in res

<a name="ucm_include_file_in_sources"></a>macro ucm_include_file_in_sources(src1 src2 src3... HEADER <header>)

Includes the header in the source file with a compile flag (without modifying the file) either with -include "hdr.h" or with /FI"hdr.h" depending on the compiler.

ucm_include_file_in_sources(c.cc a.cc b.cc HEADER "common.h")

<a name="ucm_dir_list"></a>macro ucm_dir_list(<thedir> <result>)

Returns a list of subdirectories for a given directory.

ucm_dir_list("the/dir" result)

<a name="ucm_remove_files"></a>macro ucm_remove_files(src1 src2 src3... FROM <sources>)

Removes the given source files from the sources list - example:

ucm_add_dirs(utils REC TO sources)
ucm_remove_files(utils/deprecated.h FROM sources)

<a name="ucm_remove_directories"></a>macro ucm_remove_directories(dir1 dir2 dir3... FROM <sources> [MATCHES pttrn1 pttrn2])

Removes all source files from the given directories from the sources list (recursively) - example:

ucm_add_dirs(utils REC TO sources)
# and then remove only the ones we don't want
ucm_remove_directories(utils/deprecated uti