|
131
|
1 @c Copyright (C) 1988-2018 Free Software Foundation, Inc.
|
|
0
|
2 @c This is part of the GCC manual.
|
|
|
3 @c For copying conditions, see the file gcc.texi.
|
|
|
4
|
|
|
5 @node Fragments
|
|
|
6 @chapter Makefile Fragments
|
|
|
7 @cindex makefile fragment
|
|
|
8
|
|
|
9 When you configure GCC using the @file{configure} script, it will
|
|
|
10 construct the file @file{Makefile} from the template file
|
|
|
11 @file{Makefile.in}. When it does this, it can incorporate makefile
|
|
|
12 fragments from the @file{config} directory. These are used to set
|
|
|
13 Makefile parameters that are not amenable to being calculated by
|
|
|
14 autoconf. The list of fragments to incorporate is set by
|
|
|
15 @file{config.gcc} (and occasionally @file{config.build}
|
|
|
16 and @file{config.host}); @xref{System Config}.
|
|
|
17
|
|
|
18 Fragments are named either @file{t-@var{target}} or @file{x-@var{host}},
|
|
|
19 depending on whether they are relevant to configuring GCC to produce
|
|
|
20 code for a particular target, or to configuring GCC to run on a
|
|
|
21 particular host. Here @var{target} and @var{host} are mnemonics
|
|
|
22 which usually have some relationship to the canonical system name, but
|
|
|
23 no formal connection.
|
|
|
24
|
|
|
25 If these files do not exist, it means nothing needs to be added for a
|
|
|
26 given target or host. Most targets need a few @file{t-@var{target}}
|
|
|
27 fragments, but needing @file{x-@var{host}} fragments is rare.
|
|
|
28
|
|
|
29 @menu
|
|
|
30 * Target Fragment:: Writing @file{t-@var{target}} files.
|
|
|
31 * Host Fragment:: Writing @file{x-@var{host}} files.
|
|
|
32 @end menu
|
|
|
33
|
|
|
34 @node Target Fragment
|
|
|
35 @section Target Makefile Fragments
|
|
|
36 @cindex target makefile fragment
|
|
|
37 @cindex @file{t-@var{target}}
|
|
|
38
|
|
|
39 Target makefile fragments can set these Makefile variables.
|
|
|
40
|
|
|
41 @table @code
|
|
|
42 @findex LIBGCC2_CFLAGS
|
|
|
43 @item LIBGCC2_CFLAGS
|
|
|
44 Compiler flags to use when compiling @file{libgcc2.c}.
|
|
|
45
|
|
|
46 @findex LIB2FUNCS_EXTRA
|
|
|
47 @item LIB2FUNCS_EXTRA
|
|
|
48 A list of source file names to be compiled or assembled and inserted
|
|
|
49 into @file{libgcc.a}.
|
|
|
50
|
|
|
51 @findex CRTSTUFF_T_CFLAGS
|
|
|
52 @item CRTSTUFF_T_CFLAGS
|
|
|
53 Special flags used when compiling @file{crtstuff.c}.
|
|
|
54 @xref{Initialization}.
|
|
|
55
|
|
|
56 @findex CRTSTUFF_T_CFLAGS_S
|
|
|
57 @item CRTSTUFF_T_CFLAGS_S
|
|
|
58 Special flags used when compiling @file{crtstuff.c} for shared
|
|
|
59 linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
|
|
|
60 in @code{EXTRA-PARTS}.
|
|
|
61 @xref{Initialization}.
|
|
|
62
|
|
|
63 @findex MULTILIB_OPTIONS
|
|
|
64 @item MULTILIB_OPTIONS
|
|
|
65 For some targets, invoking GCC in different ways produces objects
|
|
|
66 that can not be linked together. For example, for some targets GCC
|
|
|
67 produces both big and little endian code. For these targets, you must
|
|
|
68 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
|
|
|
69 each set of incompatible options. When GCC invokes the linker, it
|
|
|
70 arranges to link in the right version of @file{libgcc.a}, based on
|
|
|
71 the command line options used.
|
|
|
72
|
|
|
73 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
|
|
|
74 special versions of @file{libgcc.a} must be built. Write options that
|
|
|
75 are mutually incompatible side by side, separated by a slash. Write
|
|
|
76 options that may be used together separated by a space. The build
|
|
|
77 procedure will build all combinations of compatible options.
|
|
|
78
|
|
|
79 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
|
|
|
80 msoft-float}, @file{Makefile} will build special versions of
|
|
|
81 @file{libgcc.a} using the following sets of options: @option{-m68000},
|
|
|
82 @option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
|
|
|
83 @samp{-m68020 -msoft-float}.
|
|
|
84
|
|
|
85 @findex MULTILIB_DIRNAMES
|
|
|
86 @item MULTILIB_DIRNAMES
|
|
|
87 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
|
|
|
88 directory names that should be used to hold the various libraries.
|
|
|
89 Write one element in @code{MULTILIB_DIRNAMES} for each element in
|
|
|
90 @code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
|
|
|
91 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
|
|
|
92 as spaces.
|
|
|
93
|
|
111
|
94 @code{MULTILIB_DIRNAMES} describes the multilib directories using GCC
|
|
|
95 conventions and is applied to directories that are part of the GCC
|
|
|
96 installation. When multilib-enabled, the compiler will add a
|
|
|
97 subdirectory of the form @var{prefix}/@var{multilib} before each
|
|
|
98 directory in the search path for libraries and crt files.
|
|
|
99
|
|
0
|
100 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
|
|
|
101 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
|
|
|
102 @samp{m68000 m68020 msoft-float}. You may specify a different value if
|
|
|
103 you desire a different set of directory names.
|
|
|
104
|
|
|
105 @findex MULTILIB_MATCHES
|
|
|
106 @item MULTILIB_MATCHES
|
|
|
107 Sometimes the same option may be written in two different ways. If an
|
|
|
108 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
|
|
|
109 any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
|
|
|
110 items of the form @samp{option=option} to describe all relevant
|
|
|
111 synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
|
|
|
112
|
|
|
113 @findex MULTILIB_EXCEPTIONS
|
|
|
114 @item MULTILIB_EXCEPTIONS
|
|
|
115 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
|
|
|
116 specified, there are combinations that should not be built. In that
|
|
|
117 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
|
|
|
118 in shell case syntax that should not be built.
|
|
|
119
|
|
|
120 For example the ARM processor cannot execute both hardware floating
|
|
|
121 point instructions and the reduced size THUMB instructions at the same
|
|
|
122 time, so there is no need to build libraries with both of these
|
|
|
123 options enabled. Therefore @code{MULTILIB_EXCEPTIONS} is set to:
|
|
|
124 @smallexample
|
|
|
125 *mthumb/*mhard-float*
|
|
|
126 @end smallexample
|
|
|
127
|
|
111
|
128 @findex MULTILIB_REQUIRED
|
|
|
129 @item MULTILIB_REQUIRED
|
|
|
130 Sometimes when there are only a few combinations are required, it would
|
|
|
131 be a big effort to come up with a @code{MULTILIB_EXCEPTIONS} list to
|
|
|
132 cover all undesired ones. In such a case, just listing all the required
|
|
|
133 combinations in @code{MULTILIB_REQUIRED} would be more straightforward.
|
|
|
134
|
|
|
135 The way to specify the entries in @code{MULTILIB_REQUIRED} is same with
|
|
|
136 the way used for @code{MULTILIB_EXCEPTIONS}, only this time what are
|
|
|
137 required will be specified. Suppose there are multiple sets of
|
|
|
138 @code{MULTILIB_OPTIONS} and only two combinations are required, one
|
|
|
139 for ARMv7-M and one for ARMv7-R with hard floating-point ABI and FPU, the
|
|
|
140 @code{MULTILIB_REQUIRED} can be set to:
|
|
|
141 @smallexample
|
|
|
142 @code{MULTILIB_REQUIRED} = mthumb/march=armv7-m
|
|
|
143 @code{MULTILIB_REQUIRED} += march=armv7-r/mfloat-abi=hard/mfpu=vfpv3-d16
|
|
|
144 @end smallexample
|
|
|
145
|
|
|
146 The @code{MULTILIB_REQUIRED} can be used together with
|
|
|
147 @code{MULTILIB_EXCEPTIONS}. The option combinations generated from
|
|
|
148 @code{MULTILIB_OPTIONS} will be filtered by @code{MULTILIB_EXCEPTIONS}
|
|
|
149 and then by @code{MULTILIB_REQUIRED}.
|
|
|
150
|
|
|
151 @findex MULTILIB_REUSE
|
|
|
152 @item MULTILIB_REUSE
|
|
|
153 Sometimes it is desirable to reuse one existing multilib for different
|
|
|
154 sets of options. Such kind of reuse can minimize the number of multilib
|
|
|
155 variants. And for some targets it is better to reuse an existing multilib
|
|
|
156 than to fall back to default multilib when there is no corresponding multilib.
|
|
|
157 This can be done by adding reuse rules to @code{MULTILIB_REUSE}.
|
|
|
158
|
|
|
159 A reuse rule is comprised of two parts connected by equality sign. The left
|
|
|
160 part is the option set used to build multilib and the right part is the option
|
|
|
161 set that will reuse this multilib. Both parts should only use options
|
|
|
162 specified in @code{MULTILIB_OPTIONS} and the equality signs found in options
|
|
|
163 name should be replaced with periods. An explicit period in the rule can be
|
|
|
164 escaped by preceding it with a backslash. The order of options in the left
|
|
|
165 part matters and should be same with those specified in
|
|
|
166 @code{MULTILIB_REQUIRED} or aligned with the order in @code{MULTILIB_OPTIONS}.
|
|
|
167 There is no such limitation for options in the right part as we don't build
|
|
|
168 multilib from them.
|
|
|
169
|
|
|
170 @code{MULTILIB_REUSE} is different from @code{MULTILIB_MATCHES} in that it
|
|
|
171 sets up relations between two option sets rather than two options. Here is an
|
|
|
172 example to demo how we reuse libraries built in Thumb mode for applications built
|
|
|
173 in ARM mode:
|
|
|
174 @smallexample
|
|
|
175 @code{MULTILIB_REUSE} = mthumb/march.armv7-r=marm/march.armv7-r
|
|
|
176 @end smallexample
|
|
|
177
|
|
|
178 Before the advent of @code{MULTILIB_REUSE}, GCC select multilib by comparing command
|
|
|
179 line options with options used to build multilib. The @code{MULTILIB_REUSE} is
|
|
|
180 complementary to that way. Only when the original comparison matches nothing it will
|
|
|
181 work to see if it is OK to reuse some existing multilib.
|
|
|
182
|
|
0
|
183 @findex MULTILIB_EXTRA_OPTS
|
|
|
184 @item MULTILIB_EXTRA_OPTS
|
|
|
185 Sometimes it is desirable that when building multiple versions of
|
|
|
186 @file{libgcc.a} certain options should always be passed on to the
|
|
|
187 compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
|
|
|
188 of options to be used for all builds. If you set this, you should
|
|
|
189 probably set @code{CRTSTUFF_T_CFLAGS} to a dash followed by it.
|
|
|
190
|
|
111
|
191 @findex MULTILIB_OSDIRNAMES
|
|
|
192 @item MULTILIB_OSDIRNAMES
|
|
|
193 If @code{MULTILIB_OPTIONS} is used, this variable specifies
|
|
|
194 a list of subdirectory names, that are used to modify the search
|
|
|
195 path depending on the chosen multilib. Unlike @code{MULTILIB_DIRNAMES},
|
|
|
196 @code{MULTILIB_OSDIRNAMES} describes the multilib directories using
|
|
|
197 operating systems conventions, and is applied to the directories such as
|
|
|
198 @code{lib} or those in the @env{LIBRARY_PATH} environment variable.
|
|
|
199 The format is either the same as of
|
|
|
200 @code{MULTILIB_DIRNAMES}, or a set of mappings. When it is the same
|
|
|
201 as @code{MULTILIB_DIRNAMES}, it describes the multilib directories
|
|
|
202 using operating system conventions, rather than GCC conventions. When it is a set
|
|
|
203 of mappings of the form @var{gccdir}=@var{osdir}, the left side gives
|
|
|
204 the GCC convention and the right gives the equivalent OS defined
|
|
|
205 location. If the @var{osdir} part begins with a @samp{!},
|
|
|
206 GCC will not search in the non-multilib directory and use
|
|
|
207 exclusively the multilib directory. Otherwise, the compiler will
|
|
|
208 examine the search path for libraries and crt files twice; the first
|
|
|
209 time it will add @var{multilib} to each directory in the search path,
|
|
|
210 the second it will not.
|
|
|
211
|
|
|
212 For configurations that support both multilib and multiarch,
|
|
|
213 @code{MULTILIB_OSDIRNAMES} also encodes the multiarch name, thus
|
|
|
214 subsuming @code{MULTIARCH_DIRNAME}. The multiarch name is appended to
|
|
|
215 each directory name, separated by a colon (e.g.
|
|
|
216 @samp{../lib32:i386-linux-gnu}).
|
|
|
217
|
|
|
218 Each multiarch subdirectory will be searched before the corresponding OS
|
|
|
219 multilib directory, for example @samp{/lib/i386-linux-gnu} before
|
|
|
220 @samp{/lib/../lib32}. The multiarch name will also be used to modify the
|
|
|
221 system header search path, as explained for @code{MULTIARCH_DIRNAME}.
|
|
|
222
|
|
|
223 @findex MULTIARCH_DIRNAME
|
|
|
224 @item MULTIARCH_DIRNAME
|
|
|
225 This variable specifies the multiarch name for configurations that are
|
|
|
226 multiarch-enabled but not multilibbed configurations.
|
|
|
227
|
|
|
228 The multiarch name is used to augment the search path for libraries, crt
|
|
|
229 files and system header files with additional locations. The compiler
|
|
|
230 will add a multiarch subdirectory of the form
|
|
|
231 @var{prefix}/@var{multiarch} before each directory in the library and
|
|
|
232 crt search path. It will also add two directories
|
|
|
233 @code{LOCAL_INCLUDE_DIR}/@var{multiarch} and
|
|
|
234 @code{NATIVE_SYSTEM_HEADER_DIR}/@var{multiarch}) to the system header
|
|
|
235 search path, respectively before @code{LOCAL_INCLUDE_DIR} and
|
|
|
236 @code{NATIVE_SYSTEM_HEADER_DIR}.
|
|
|
237
|
|
|
238 @code{MULTIARCH_DIRNAME} is not used for configurations that support
|
|
|
239 both multilib and multiarch. In that case, multiarch names are encoded
|
|
|
240 in @code{MULTILIB_OSDIRNAMES} instead.
|
|
|
241
|
|
|
242 More documentation about multiarch can be found at
|
|
|
243 @uref{https://wiki.debian.org/Multiarch}.
|
|
0
|
244
|
|
|
245 @findex SPECS
|
|
|
246 @item SPECS
|
|
|
247 Unfortunately, setting @code{MULTILIB_EXTRA_OPTS} is not enough, since
|
|
|
248 it does not affect the build of target libraries, at least not the
|
|
|
249 build of the default multilib. One possible work-around is to use
|
|
|
250 @code{DRIVER_SELF_SPECS} to bring options from the @file{specs} file
|
|
|
251 as if they had been passed in the compiler driver command line.
|
|
|
252 However, you don't want to be adding these options after the toolchain
|
|
|
253 is installed, so you can instead tweak the @file{specs} file that will
|
|
|
254 be used during the toolchain build, while you still install the
|
|
|
255 original, built-in @file{specs}. The trick is to set @code{SPECS} to
|
|
|
256 some other filename (say @file{specs.install}), that will then be
|
|
|
257 created out of the built-in specs, and introduce a @file{Makefile}
|
|
|
258 rule to generate the @file{specs} file that's going to be used at
|
|
|
259 build time out of your @file{specs.install}.
|
|
|
260
|
|
|
261 @item T_CFLAGS
|
|
|
262 These are extra flags to pass to the C compiler. They are used both
|
|
|
263 when building GCC, and when compiling things with the just-built GCC@.
|
|
|
264 This variable is deprecated and should not be used.
|
|
|
265 @end table
|
|
|
266
|
|
|
267 @node Host Fragment
|
|
|
268 @section Host Makefile Fragments
|
|
|
269 @cindex host makefile fragment
|
|
|
270 @cindex @file{x-@var{host}}
|
|
|
271
|
|
|
272 The use of @file{x-@var{host}} fragments is discouraged. You should only
|
|
|
273 use it for makefile dependencies.
|
