NAME

       Toolchain — module providing information and configuration about compiler toolchain

SYNOPSIS

       include z.mk

       $(eval $(call ZMK.Import,Toolchain))

DESCRIPTION

       The  Toolchain  module  encapsulates  information  about the used C and C++ compilers.  This knowledge is
       mainly consumed internally by other modules and templates, but can be used directly to  construct  custom
       rules.

TARGETS

       This module does not provide any targets.

VARIABLES

       This module provides the following variables.

       Please  take  note  that  make supports target-specific variables, where a specific variable, for example
       CFLAGS or LDLIBS takes a particular value only while building a  specific  target  as  well  as  all  the
       targets  that it depends on. This scheme is removes the need for additional variables manually customized
       to a specific target.

   CC
       The C compiler.

   CPP
       The pre-processor, responsible for macros and include directives.

   CXX
       The C++ compiler.

   CFLAGS
       Configuration options for the C compiler.

       This variable should be used to pass options such as -Wall, -O2, or -fpic.  Please refer to your compiler
       manual for details.

       This variable is often abused, mainly for simplicity, as a kitchen-sink that holds all  of  the  compiler
       and linker options. This is discouraged.

   CPPFLAGS
       Configurations options for the pre-processor.

       This  variable should be used to provide command line options that alter the include search path, such as
       -I, or define a pre-processor macro, such as -D.

   CXXFLAGS
       Configuration options for the C++ compiler. This variable the equivalent of CFLAGS for the C++ compiler.

   OBJCFLAGS
       Configuration options for the Objective C compiler. This  variable  the  equivalent  of  CFLAGS  for  the
       Objective C compiler.

   ARFLAGS
       Configuration options for the ar program.

   TARGET_ARCH
       Compiler options for performing architecture selection.

       This  variable  is  not  used by zmk. Cross compilation is supported by selecting a cross-compiling CC or
       CXX.

   LDLIBS
       Additional libraries to link with.

       Libraries are provided in the form -lfoo where foo is the name of the library, without  the  prefix  lib.
       Given  the  choice  of  static  and  dynamic libraries, the linker will prefer dynamic linking. You can a
       specific library statically with the following  option  sequence.   -Wl,-dn  -lfoo  -Wl,-dy.   The  first
       segment  -Wl,-dn  turns  off  dynamic linking -lfoo links to the library libfoo.a while the final -Wl,-dy
       turns dynamic linking back again. Note that using this sequence the  final  executable  is  not  entirely
       statically  linked.  If  libfoo.a  has  any  additional  dependences those must be linked as well, either
       dynamically or statically.

   LDFLAGS
       Configuration options for the linker.

       This variable should be used to provide command line options that alter the linker search path,  such  as
       -L,  or customize linker behavior. Note that the linker is not invoked directly, but through the compiler
       front-end. For example, when using gcc, one would typically pass -Wl,foo in order to pass the option  foo
       to the linker.

   exe
       The  suffix  for  executables.  It  is  either  empty  or  has the value .exe, if the image format of the
       resulting executable is either PE or MZ.

       This variable is automatically used by zmk when building executables.

   Toolchain.SysRoot
       Path of the root directory where the compiler looks for headers and libraries. A non-empty  value  causes
       --sysroot=$(Toolchain.SysRoot) to be passed to the compiler whenever it is used for compiling, linking or
       pre-processing.

       The default value is $(Configure.SysRoot), namely the preference from the configuration system.

   Toolchain.DependencyTracking
       Expands  to  yes,  if  compilation  of  C,  C++  and Objective C source files will automatically generate
       dependency rules for Make.

       The default value is  $(Configure.DependencyTracking),  namely  the  preference  from  the  configuration
       system.

   Toolchain.ImageFormat
       Identifier  or  the application image format generated by both the C compiler or the C++ compiler. If the
       two compilers produce different image formats, for example because one is a cross-compiler the  effective
       value is Mixed.

   Toolchain.IsCross
       Expands to yes if programs created by either the C compiler or the C++ compiler cannot be executed on the
       machine performing the build.

   Toolchain.IsGcc
       Expands to yes, if both the C and C++ compilers are from the GNU Compiler Collection.

   Toolchain.IsClang
       Expands to yes, if both the C and C++ compilers are from the clang project.

   Toolchain.IsWatcom
       Expands to yes, if both the C and C++ compilers are from the Open Watcom compiler.

   Toolchain.CC.IsAvaiable
       Expands to yes if the C compiler is available.

   Toolchain.CC.ImageFormat
       Identifier  or  the  application  image format generated by the C compiler. Refer to the documentation of
       OS.ImageFormat for a description of known formats.

       Unless cross-compiling, the default value is $(OS.ImageFormat).

   Toolchain.CC.IsCross
       Expands to yes if programs created by the C compiler cannot be executed on  the  machine  performing  the
       build.

   Toolchain.CC.IsGcc
       Expands  to  yes,  if  the selected C compiler is the GNU Compiler Collection.  This variable, as well as
       several others documented below, can be used to conditionally  enable  compiler  specific  options  in  a
       manner that does not break when another compiler is used.

   Toolchain.CC.IsClang
       Expands to yes, if the selected C compiler is clang.

   Toolchain.CC.IsWatcom
       Expands to yes, if the selected C compiler is the Open Watcom compiler.

   Toolchain.CC.IsTcc
       Expands to yes, if the selected C compiler is the Tiny C Compiler.

   Toolchain.CXX.IsAvaiable
       Expands to yes if the C++ compiler is available.

   Toolchain.CXX.ImageFormat
       Identifier or the application image format generated by the C++ compiler.

       Unless cross-compiling, the default value is $(OS.ImageFormat).

   Toolchain.CXX.IsCross
       Expands  to  yes if programs created by the C++ compiler cannot be executed on the machine performing the
       build.

   Toolchain.CXX.IsGcc
       Expands to yes, if the selected C++ compiler is the GNU Compiler Collection.

   Toolchain.CXX.IsClang
       Expands to yes, if the selected C++ compiler is clang.

   Toolchain.CXX.IsWatcom
       Expands to yes, if the selected C++ compiler is the Open Watcom compiler.

EXAMPLES

HISTORY

       The Toolchain module first appeared in zmk 0.3

AUTHORS

       Zygmunt Krynicki <me@zygoon.pl>

zmk 0.5.1                                          May 3, 2020                                  zmk.Toolchain(5)