1zmk.Toolchain(5)              Programmer's Manual             zmk.Toolchain(5)
2

NAME

4     Toolchain — module providing information and configuration about compiler
5     toolchain
6

SYNOPSIS

8     include z.mk
9
10     $(eval $(call ZMK.Import,Toolchain))
11

DESCRIPTION

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

TARGETS

18     This module does not provide any targets.
19

VARIABLES

21     This module provides the following variables.
22
23     Please take note that make supports target-specific variables, where a
24     specific variable, for example CFLAGS or LDLIBS takes a particular value
25     only while building a specific target as well as all the targets that it
26     depends on. This scheme is removes the need for additional variables man‐
27     ually customized to a specific target.
28
29   CC
30     The C compiler.
31
32   CPP
33     The pre-processor, responsible for macros and include directives.
34
35   CXX
36     The C++ compiler.
37
38   CFLAGS
39     Configuration options for the C compiler.
40
41     This variable should be used to pass options such as -Wall, -O2, or
42     -fpic.  Please refer to your compiler manual for details.
43
44     This variable is often abused, mainly for simplicity, as a kitchen-sink
45     that holds all of the compiler and linker options. This is discouraged.
46
47   CPPFLAGS
48     Configurations options for the pre-processor.
49
50     This variable should be used to provide command line options that alter
51     the include search path, such as -I, or define a pre-processor macro,
52     such as -D.
53
54   CXXFLAGS
55     Configuration options for the C++ compiler. This variable the equivalent
56     of CFLAGS for the C++ compiler.
57
58   OBJCFLAGS
59     Configuration options for the Objective C compiler. This variable the
60     equivalent of CFLAGS for the Objective C compiler.
61
62   ARFLAGS
63     Configuration options for the ar program.
64
65   TARGET_ARCH
66     Compiler options for performing architecture selection.
67
68     This variable is not used by zmk. Cross compilation is supported by se‐
69     lecting a cross-compiling CC or CXX.
70
71   LDLIBS
72     Additional libraries to link with.
73
74     Libraries are provided in the form -lfoo where foo is the name of the li‐
75     brary, without the prefix lib.  Given the choice of static and dynamic
76     libraries, the linker will prefer dynamic linking. You can a specific li‐
77     brary statically with the following option sequence.  -Wl,-dn -lfoo
78     -Wl,-dy.  The first segment -Wl,-dn turns off dynamic linking -lfoo links
79     to the library libfoo.a while the final -Wl,-dy turns dynamic linking
80     back again. Note that using this sequence the final executable is not en‐
81     tirely statically linked. If libfoo.a has any additional dependences
82     those must be linked as well, either dynamically or statically.
83
84   LDFLAGS
85     Configuration options for the linker.
86
87     This variable should be used to provide command line options that alter
88     the linker search path, such as -L, or customize linker behavior. Note
89     that the linker is not invoked directly, but through the compiler front-
90     end. For example, when using gcc, one would typically pass -Wl,foo in or‐
91     der to pass the option foo to the linker.
92
93   exe
94     The suffix for executables. It is either empty or has the value .exe, if
95     the image format of the resulting executable is either PE or MZ.
96
97     This variable is automatically used by zmk when building executables.
98
99   Toolchain.SysRoot
100     Path of the root directory where the compiler looks for headers and li‐
101     braries. A non-empty value causes --sysroot=$(Toolchain.SysRoot) to be
102     passed to the compiler whenever it is used for compiling, linking or pre-
103     processing.
104
105     The default value is $(Configure.SysRoot), namely the preference from the
106     configuration system.
107
108   Toolchain.DependencyTracking
109     Expands to yes, if compilation of C, C++ and Objective C source files
110     will automatically generate dependency rules for Make.
111
112     The default value is $(Configure.DependencyTracking), namely the prefer‐
113     ence from the configuration system.
114
115   Toolchain.ImageFormat
116     Identifier or the application image format generated by both the C com‐
117     piler or the C++ compiler. If the two compilers produce different image
118     formats, for example because one is a cross-compiler the effective value
119     is Mixed.
120
121   Toolchain.IsCross
122     Expands to yes if programs created by either the C compiler or the C++
123     compiler cannot be executed on the machine performing the build.
124
125   Toolchain.IsGcc
126     Expands to yes, if both the C and C++ compilers are from the GNU Compiler
127     Collection.
128
129   Toolchain.IsClang
130     Expands to yes, if both the C and C++ compilers are from the clang
131     project.
132
133   Toolchain.IsWatcom
134     Expands to yes, if both the C and C++ compilers are from the Open Watcom
135     compiler.
136
137   Toolchain.CC.IsAvaiable
138     Expands to yes if the C compiler is available.
139
140   Toolchain.CC.ImageFormat
141     Identifier or the application image format generated by the C compiler.
142     Refer to the documentation of OS.ImageFormat for a description of known
143     formats.
144
145     Unless cross-compiling, the default value is $(OS.ImageFormat).
146
147   Toolchain.CC.IsCross
148     Expands to yes if programs created by the C compiler cannot be executed
149     on the machine performing the build.
150
151   Toolchain.CC.IsGcc
152     Expands to yes, if the selected C compiler is the GNU Compiler
153     Collection.  This variable, as well as several others documented below,
154     can be used to conditionally enable compiler specific options in a manner
155     that does not break when another compiler is used.
156
157   Toolchain.CC.IsClang
158     Expands to yes, if the selected C compiler is clang.
159
160   Toolchain.CC.IsWatcom
161     Expands to yes, if the selected C compiler is the Open Watcom compiler.
162
163   Toolchain.CC.IsTcc
164     Expands to yes, if the selected C compiler is the Tiny C Compiler.
165
166   Toolchain.CXX.IsAvaiable
167     Expands to yes if the C++ compiler is available.
168
169   Toolchain.CXX.ImageFormat
170     Identifier or the application image format generated by the C++ compiler.
171
172     Unless cross-compiling, the default value is $(OS.ImageFormat).
173
174   Toolchain.CXX.IsCross
175     Expands to yes if programs created by the C++ compiler cannot be executed
176     on the machine performing the build.
177
178   Toolchain.CXX.IsGcc
179     Expands to yes, if the selected C++ compiler is the GNU Compiler
180     Collection.
181
182   Toolchain.CXX.IsClang
183     Expands to yes, if the selected C++ compiler is clang.
184
185   Toolchain.CXX.IsWatcom
186     Expands to yes, if the selected C++ compiler is the Open Watcom compiler.
187

EXAMPLES

HISTORY

190     The Toolchain module first appeared in zmk 0.3
191

AUTHORS

193     Zygmunt Krynicki <me@zygoon.pl>
194
195zmk 0.5                           May 3, 2020                          zmk 0.5
Impressum