| 1 |
@c Copyright (C) 1988-2023 Free Software Foundation, Inc. |
| 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 cannot 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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}. |
| 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. |