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