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>