Flags

cmany allows you to transparently pass flags to all or some of the builds. These flags can be compiler flags, preprocessor defines or CMake cache variables. Specifying flags is an important cmany usage pattern, which is used also when specifying Per-item flags.

Note

The examples below apply the flags across the board to all the individual builds produced with the cmany command. For example, this will add -Wall to all of the 9 resulting builds:

$ cmany b --compilers clang++,g++,icpc \
          --build-types Debug,Release,MinSizeRel \
          --cxxflags "-Wall"

If you want to add flags only to certain builds, it’s cool! One of the main motivations of cmany is being able to easily do that, and it offers two different solutions. You can use variants. You can also set flags per Per-item flags, so that when one specific build item (such as a compiler or operating system) is used, then the flags are also used in the resulting build.

CMake cache variables

To set cmake cache variables use --cmake-vars/-V. For example:

$ cmany b -V CMAKE_VERBOSE_MAKEFILE=1,PROJECT_FOO=BAR

This is equivalent to the following sequence of commands:

$ cmake -D CMAKE_VERBOSE_MAKEFILE=1 -D PROJECT_FOO=BAR ../..
$ cmake --build .

Note the use of the comma to separate the variables. This is for consistency with the rest of the cmany options, namely (for example) those selecting compilers or build types. You can also use separate invocations:

$ cmany b -V CMAKE_VERBOSE_MAKEFILE=1 -V PROJECT_FOO=BAR

which will have the same result as above.

When specified as above, CMake cache variables will apply to all builds. If you want to add CMake cache variables only to certain builds by associating them with particular build items, you can use the pattern 'item_name: <flags...>'. For example, this will enable the cmake variable ENABLE_X64_ASM only when x86_64 is used:

$ cmany b -s x86,'x86_64: -V ENABLE_X64_ASM=1'

CMake’s cache variables are typed, and this sometimes can affect subtly the outcome of a build. cmany will try to guess the type variable type (ie, whether it is a BOOL, PATH, FILEPATH or STRING), based on its name and value. You can override this behaviour by using the standard CMake syntax for specifying the variable type:

$ cmany b -V CMAKE_VERBOSE_MAKEFILE:BOOL=1,PROJECT_FOO:STRING=BAR

Preprocessor macros

To add preprocessor macros, use the option --defines/-D:

$ cmany b -D MY_MACRO=1,FOO=BAR

The command above has the same meaning of:

$ cmake -D CMAKE_CXX_FLAGS="-D MYMACRO=1 -D FOO=BAR" ../..
$ cmake --build .

Note also that --defines/-D can be used repeatedly, with the same result:

$ cmany b -D MY_MACRO=1 -D FOO=BAR

To add macros only to certain build items, use the 'item_name: <flags...>' pattern. For example, this will add the macro XDEBUG only to the Debug build type:

$ cmany b -t Release,'Debug: -D XDEBUG'

C++ compiler flags

To add C++ compiler flags to a cmany build, use the option --cxxflags/-X. To prevent these flags being interpreted as cmany command options, use quotes or single quotes (or flag aliases, see below):

$ cmany b -X "-Wall","-O3"      # add -Wall -O3 to all builds

The command above has the same meaning of:

$ cmake -D CMAKE_CXX_FLAGS="-Wall -O3" ..
$ cmake --build .

Note that --cxxflags/-X can be used repeatedly, with the same result:

$ cmany b -X "-Wall" -X "-O3"

To add C++ compiler flags only to certain build items, use the 'item_name: <flags...>' pattern. For example, this will add the -ffast-math flag only to the Release build type:

$ cmany b -t 'Release: -X "-ffast-math"',Debug

C compiler flags

To add C compiler flags, use the option --cflags/-C. As with C++ flags, to prevent interpretation by cmany, use single or double quotes to escape the compiler flags (or use flag aliases, see below):

$ cmany b -C "-Wall","-O3"

The command above has the same meaning of:

$ cmake -D CMAKE_C_FLAGS="-Wall -O3" ..
$ cmake --build .

Note that --cflags/-C can be chained, with the same result:

$ cmany b -C "-Wall" -C "-O3"

To add C compiler flags only to certain build items, use the 'item_name: <flags...>' pattern. For example, this will add the -ffast-math flag only to the Release build type:

$ cmany b -t 'Release: -C -ffast-math',Debug

Linker flags

For now, cmany has no explicit support for linker flags. But you can set linker flags through the cmake cache variable mechanism:

$ cmany b -V '-DCMAKE_LINKER_FLAGS="....linker flags...."'

You may also have noticed that CMake cache variables will allow you to specify macros and compiler flags as well via -DCMAKE_CXX_FLAGS=.... Yes, that’s right, you can also do that. But not only is it less verbose when passing macros and flags through --defines/--cflags/--cxxflags: there is a strong reason to prefer it this way: flag aliases, introduced below.

Flag aliases

For simplicity of use, cmany comes with a predefined set of flag aliases which you can use. A flag alias is a name which maps to specific flags for each compiler. For example, if you want to enable maximum warnings there is the wall alias (shown here in the yml markup which cmany uses to define it):

wall:
    desc: turn on all warnings
    gcc,clang,icc: -Wall
    vs: /Wall

or eg the avx alias if you want to enable AVX SIMD processing:

avx:
    desc: enable AVX instructions
    gcc,clang,icc: -mavx
    vs: /arch:avx

This allows use of the aliases instead of the flags directly, thus insulating you from differences between compilers. Using the aliases will also produce easier commands, because less quoting is needed to prevent the flags from being read by the shell. For example, the following command will translate to g++ -mavx -Wall with gcc, clang or icc, but with Visual Studio it will translate instead to cl.exe /Wall /arch:avx:

$ cmany b --cxxflags avx,wall

As a comparison, direct use of the flags would result in these commands:

$ cmany b --cxxflags '-Wall','-mavx'          # for gcc
$ cmany b --cxxflags '/Wall','/arch:avx'      # for VS

Note that flag aliases are translated only when they are given through --cxxflags/-cflags. Do not use aliases with --cmake-vars CMAKE_CXX_FLAGS=..., as cmany will not translate them there.

Built-in flag aliases

cmany provides some built-in flag aliases to simplify working with different compilers at the same time. Currently, you can see them in the file conf/cmany.yml (see the current version at github).

Defining more flag aliases

Being able to define your own flag aliases is in the roadmap. For now, you can submit PRs for adding aliases.

Toolchains

To use cmake toolchain use the option -T/--toolchain. Usually, this will be done inside a systems build item, -s/--systems; see the Systems section in the build items document.

Build exclusion arguments

Note that arguments for excluding builds can be used wherever flag arguments can be used. This makes it easier to declare incompatibility between build items. See an example in this help page.