.Dd May 3, 2020
.Os zmk 0.5.1
.Dt zmk.Toolchain 5 PRM
.Sh NAME
.Nm Toolchain
.Nd module providing information and configuration about compiler toolchain
.Sh SYNOPSIS
.Bd -literal
include z.mk

$(eval $(call ZMK.Import,Toolchain))
.Ed
.Sh DESCRIPTION
The
.Nm
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.
.Sh TARGETS
This module does not provide any targets.
.Sh VARIABLES
This module provides the following variables.
.Pp
Please take note that make supports
.Em target-specific variables ,
where a specific variable, for example
.Nm CFLAGS
or
.Nm 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.
.Ss CC
The C compiler.
.Ss CPP
The pre-processor, responsible for macros and include directives.
.Ss CXX
The C++ compiler.
.Ss CFLAGS
Configuration options for the C compiler.
.Pp
This variable should be used to pass options such as
.Em -Wall ,
.Em -O2 ,
or
.Em -fpic .
Please refer to your compiler manual for details.
.Pp
This variable is often abused, mainly for simplicity, as a kitchen-sink that
holds all of the compiler and linker options. This is discouraged.
.Ss CPPFLAGS
Configurations options for the pre-processor.
.Pp
This variable should be used to provide command line options that alter the include search path,
such as
.Em -I ,
or define a pre-processor macro, such as
.Em -D .
.Ss CXXFLAGS
Configuration options for the C++ compiler. This variable the equivalent of
.Nm CFLAGS
for the C++ compiler.
.Ss OBJCFLAGS
Configuration options for the Objective C compiler. This variable the
equivalent of
.Nm CFLAGS
for the Objective C compiler.
.Ss ARFLAGS
Configuration options for the
.Nm ar
program.
.Ss TARGET_ARCH
Compiler options for performing architecture selection.
.Pp
This variable is not used by zmk. Cross compilation is supported
by selecting a cross-compiling
.Nm CC
or
.Nm CXX .
.Ss LDLIBS
Additional libraries to link with.
.Pp
Libraries are provided in the form
.Em -lfoo
where
.Em foo
is the name of the library, without the prefix
.Em 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.
.Em -Wl,-dn -lfoo -Wl,-dy .
The first segment
.Em -Wl,-dn
turns off dynamic linking
.Em -lfoo
links to the library
.Em libfoo.a
while the final
.Em -Wl,-dy
turns dynamic linking back again. Note that using this sequence the final
executable is not entirely statically linked. If
.Em libfoo.a
has any additional dependences those must be linked as well, either dynamically
or statically.
.Ss LDFLAGS
Configuration options for the linker.
.Pp
This variable should be used to provide command line options that alter the
linker search path, such as
.Em -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
.Em -Wl,foo
in order to pass the option
.Em foo
to the linker.
.Ss exe
The suffix for executables. It is either empty or has the value
.Em .exe ,
if the
.Em image format
of the resulting executable is either
.Nm PE
or
.Nm MZ .
.Pp
This variable is automatically used by zmk when building executables.
\#
\# The following variables are specific to zmk.
\#
.Ss Toolchain.SysRoot
Path of the root directory where the compiler looks for
headers and libraries. A non-empty value causes
.Em --sysroot=$(Toolchain.SysRoot)
to be passed to the compiler whenever it is used for
compiling, linking or pre-processing.
.Pp
The default value is
.Em $(Configure.SysRoot) ,
namely the preference from the configuration system.
.Ss Toolchain.DependencyTracking
Expands to
.Em yes ,
if compilation of C, C++ and Objective C source files
will automatically generate dependency rules for Make.
.Pp
The default value is
.Em $(Configure.DependencyTracking) ,
namely the preference from the configuration system.
.Ss Toolchain.ImageFormat
Identifier or the application image format generated by
.Em both
the C compiler or the C++ compiler. If the two compilers produce different
image formats, for example because one is a
.Em cross-compiler
the effective value is
.Em Mixed .
.Ss Toolchain.IsCross
Expands to
.Em yes
if programs created by
.Em either
the C compiler or the C++ compiler cannot be executed on the machine
performing the build.
\#
\# Toolchain detection flags.
\#
.Ss Toolchain.IsGcc
Expands to
.Em yes ,
if both the C and C++ compilers are from the
.Em GNU Compiler Collection .
.Ss Toolchain.IsClang
Expands to
.Em yes ,
if both the C and C++ compilers are from the
.Em clang
project.
.Ss Toolchain.IsWatcom
Expands to
.Em yes ,
if both the C and C++ compilers are from the
.Em Open Watcom
compiler.
\#
\# Variables specific to either the C or the C++ compiler.
\#
.Ss Toolchain.CC.IsAvaiable
Expands to
.Em yes
if the C compiler is available.
.Ss Toolchain.CC.ImageFormat
Identifier or the application image format generated by the C
compiler. Refer to the documentation of
.Nm OS.ImageFormat
for a description of known formats.
.Pp
Unless
.Em cross-compiling ,
the default value is
.Em $(OS.ImageFormat) .
.Ss Toolchain.CC.IsCross
Expands to
.Em yes
if programs created by the C compiler cannot be executed on the
machine performing the build.
.Ss Toolchain.CC.IsGcc
Expands to
.Em yes ,
if the selected C compiler is the
.Em 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.
.Ss Toolchain.CC.IsClang
Expands to
.Em yes ,
if the selected C compiler is
.Em clang .
.Ss Toolchain.CC.IsWatcom
Expands to
.Em yes ,
if the selected C compiler is the
.Em Open Watcom
compiler.
.Ss Toolchain.CC.IsTcc
Expands to
.Em yes ,
if the selected C compiler is the
.Em Tiny C Compiler .
.Ss Toolchain.CXX.IsAvaiable
Expands to
.Em yes
if the C++ compiler is available.
.Ss Toolchain.CXX.ImageFormat
Identifier or the application image format generated by the C++ compiler.
.Pp
Unless
.Em cross-compiling ,
the default value is
.Em $(OS.ImageFormat) .
.Ss Toolchain.CXX.IsCross
Expands to
.Em yes
if programs created by the C++ compiler cannot be executed on the
machine performing the build.
.Ss Toolchain.CXX.IsGcc
Expands to
.Em yes ,
if the selected C++ compiler is the
.Em GNU Compiler Collection .
.Ss Toolchain.CXX.IsClang
Expands to
.Em yes ,
if the selected C++ compiler is
.Em clang .
.Ss Toolchain.CXX.IsWatcom
Expands to
.Em yes ,
if the selected C++ compiler is the
.Em Open Watcom
compiler.
.Sh EXAMPLES
.Sh HISTORY
The
.Nm
module first appeared in zmk 0.3
.Sh AUTHORS
.An "Zygmunt Krynicki" Aq Mt me@zygoon.pl