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.
