1*ec02198aSmrg@c Copyright (C) 1988-2020 Free Software Foundation, Inc. 210d565efSmrg@c This is part of the GCC manual. 310d565efSmrg@c For copying conditions, see the file gcc.texi. 410d565efSmrg 510d565efSmrg@node Fragments 610d565efSmrg@chapter Makefile Fragments 710d565efSmrg@cindex makefile fragment 810d565efSmrg 910d565efSmrgWhen you configure GCC using the @file{configure} script, it will 1010d565efSmrgconstruct the file @file{Makefile} from the template file 1110d565efSmrg@file{Makefile.in}. When it does this, it can incorporate makefile 1210d565efSmrgfragments from the @file{config} directory. These are used to set 1310d565efSmrgMakefile parameters that are not amenable to being calculated by 1410d565efSmrgautoconf. The list of fragments to incorporate is set by 1510d565efSmrg@file{config.gcc} (and occasionally @file{config.build} 1610d565efSmrgand @file{config.host}); @xref{System Config}. 1710d565efSmrg 1810d565efSmrgFragments are named either @file{t-@var{target}} or @file{x-@var{host}}, 1910d565efSmrgdepending on whether they are relevant to configuring GCC to produce 2010d565efSmrgcode for a particular target, or to configuring GCC to run on a 2110d565efSmrgparticular host. Here @var{target} and @var{host} are mnemonics 2210d565efSmrgwhich usually have some relationship to the canonical system name, but 2310d565efSmrgno formal connection. 2410d565efSmrg 2510d565efSmrgIf these files do not exist, it means nothing needs to be added for a 2610d565efSmrggiven target or host. Most targets need a few @file{t-@var{target}} 2710d565efSmrgfragments, but needing @file{x-@var{host}} fragments is rare. 2810d565efSmrg 2910d565efSmrg@menu 3010d565efSmrg* Target Fragment:: Writing @file{t-@var{target}} files. 3110d565efSmrg* Host Fragment:: Writing @file{x-@var{host}} files. 3210d565efSmrg@end menu 3310d565efSmrg 3410d565efSmrg@node Target Fragment 3510d565efSmrg@section Target Makefile Fragments 3610d565efSmrg@cindex target makefile fragment 3710d565efSmrg@cindex @file{t-@var{target}} 3810d565efSmrg 3910d565efSmrgTarget makefile fragments can set these Makefile variables. 4010d565efSmrg 4110d565efSmrg@table @code 4210d565efSmrg@findex LIBGCC2_CFLAGS 4310d565efSmrg@item LIBGCC2_CFLAGS 4410d565efSmrgCompiler flags to use when compiling @file{libgcc2.c}. 4510d565efSmrg 4610d565efSmrg@findex LIB2FUNCS_EXTRA 4710d565efSmrg@item LIB2FUNCS_EXTRA 4810d565efSmrgA list of source file names to be compiled or assembled and inserted 4910d565efSmrginto @file{libgcc.a}. 5010d565efSmrg 5110d565efSmrg@findex CRTSTUFF_T_CFLAGS 5210d565efSmrg@item CRTSTUFF_T_CFLAGS 5310d565efSmrgSpecial flags used when compiling @file{crtstuff.c}. 5410d565efSmrg@xref{Initialization}. 5510d565efSmrg 5610d565efSmrg@findex CRTSTUFF_T_CFLAGS_S 5710d565efSmrg@item CRTSTUFF_T_CFLAGS_S 5810d565efSmrgSpecial flags used when compiling @file{crtstuff.c} for shared 5910d565efSmrglinking. Used if you use @file{crtbeginS.o} and @file{crtendS.o} 6010d565efSmrgin @code{EXTRA-PARTS}. 6110d565efSmrg@xref{Initialization}. 6210d565efSmrg 6310d565efSmrg@findex MULTILIB_OPTIONS 6410d565efSmrg@item MULTILIB_OPTIONS 6510d565efSmrgFor some targets, invoking GCC in different ways produces objects 6610d565efSmrgthat cannot be linked together. For example, for some targets GCC 6710d565efSmrgproduces both big and little endian code. For these targets, you must 6810d565efSmrgarrange for multiple versions of @file{libgcc.a} to be compiled, one for 6910d565efSmrgeach set of incompatible options. When GCC invokes the linker, it 7010d565efSmrgarranges to link in the right version of @file{libgcc.a}, based on 7110d565efSmrgthe command line options used. 7210d565efSmrg 7310d565efSmrgThe @code{MULTILIB_OPTIONS} macro lists the set of options for which 7410d565efSmrgspecial versions of @file{libgcc.a} must be built. Write options that 7510d565efSmrgare mutually incompatible side by side, separated by a slash. Write 7610d565efSmrgoptions that may be used together separated by a space. The build 7710d565efSmrgprocedure will build all combinations of compatible options. 7810d565efSmrg 7910d565efSmrgFor example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020 8010d565efSmrgmsoft-float}, @file{Makefile} will build special versions of 8110d565efSmrg@file{libgcc.a} using the following sets of options: @option{-m68000}, 8210d565efSmrg@option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and 8310d565efSmrg@samp{-m68020 -msoft-float}. 8410d565efSmrg 8510d565efSmrg@findex MULTILIB_DIRNAMES 8610d565efSmrg@item MULTILIB_DIRNAMES 8710d565efSmrgIf @code{MULTILIB_OPTIONS} is used, this variable specifies the 8810d565efSmrgdirectory names that should be used to hold the various libraries. 8910d565efSmrgWrite one element in @code{MULTILIB_DIRNAMES} for each element in 9010d565efSmrg@code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the 9110d565efSmrgdefault value will be @code{MULTILIB_OPTIONS}, with all slashes treated 9210d565efSmrgas spaces. 9310d565efSmrg 9410d565efSmrg@code{MULTILIB_DIRNAMES} describes the multilib directories using GCC 9510d565efSmrgconventions and is applied to directories that are part of the GCC 9610d565efSmrginstallation. When multilib-enabled, the compiler will add a 9710d565efSmrgsubdirectory of the form @var{prefix}/@var{multilib} before each 9810d565efSmrgdirectory in the search path for libraries and crt files. 9910d565efSmrg 10010d565efSmrgFor example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020 10110d565efSmrgmsoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is 10210d565efSmrg@samp{m68000 m68020 msoft-float}. You may specify a different value if 10310d565efSmrgyou desire a different set of directory names. 10410d565efSmrg 10510d565efSmrg@findex MULTILIB_MATCHES 10610d565efSmrg@item MULTILIB_MATCHES 10710d565efSmrgSometimes the same option may be written in two different ways. If an 10810d565efSmrgoption is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about 10910d565efSmrgany synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of 11010d565efSmrgitems of the form @samp{option=option} to describe all relevant 11110d565efSmrgsynonyms. For example, @samp{m68000=mc68000 m68020=mc68020}. 11210d565efSmrg 11310d565efSmrg@findex MULTILIB_EXCEPTIONS 11410d565efSmrg@item MULTILIB_EXCEPTIONS 11510d565efSmrgSometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being 11610d565efSmrgspecified, there are combinations that should not be built. In that 11710d565efSmrgcase, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions 11810d565efSmrgin shell case syntax that should not be built. 11910d565efSmrg 12010d565efSmrgFor example the ARM processor cannot execute both hardware floating 12110d565efSmrgpoint instructions and the reduced size THUMB instructions at the same 12210d565efSmrgtime, so there is no need to build libraries with both of these 12310d565efSmrgoptions enabled. Therefore @code{MULTILIB_EXCEPTIONS} is set to: 12410d565efSmrg@smallexample 12510d565efSmrg*mthumb/*mhard-float* 12610d565efSmrg@end smallexample 12710d565efSmrg 12810d565efSmrg@findex MULTILIB_REQUIRED 12910d565efSmrg@item MULTILIB_REQUIRED 13010d565efSmrgSometimes when there are only a few combinations are required, it would 13110d565efSmrgbe a big effort to come up with a @code{MULTILIB_EXCEPTIONS} list to 13210d565efSmrgcover all undesired ones. In such a case, just listing all the required 13310d565efSmrgcombinations in @code{MULTILIB_REQUIRED} would be more straightforward. 13410d565efSmrg 13510d565efSmrgThe way to specify the entries in @code{MULTILIB_REQUIRED} is same with 13610d565efSmrgthe way used for @code{MULTILIB_EXCEPTIONS}, only this time what are 13710d565efSmrgrequired will be specified. Suppose there are multiple sets of 13810d565efSmrg@code{MULTILIB_OPTIONS} and only two combinations are required, one 13910d565efSmrgfor ARMv7-M and one for ARMv7-R with hard floating-point ABI and FPU, the 14010d565efSmrg@code{MULTILIB_REQUIRED} can be set to: 14110d565efSmrg@smallexample 14210d565efSmrg@code{MULTILIB_REQUIRED} = mthumb/march=armv7-m 14310d565efSmrg@code{MULTILIB_REQUIRED} += march=armv7-r/mfloat-abi=hard/mfpu=vfpv3-d16 14410d565efSmrg@end smallexample 14510d565efSmrg 14610d565efSmrgThe @code{MULTILIB_REQUIRED} can be used together with 14710d565efSmrg@code{MULTILIB_EXCEPTIONS}. The option combinations generated from 14810d565efSmrg@code{MULTILIB_OPTIONS} will be filtered by @code{MULTILIB_EXCEPTIONS} 14910d565efSmrgand then by @code{MULTILIB_REQUIRED}. 15010d565efSmrg 15110d565efSmrg@findex MULTILIB_REUSE 15210d565efSmrg@item MULTILIB_REUSE 15310d565efSmrgSometimes it is desirable to reuse one existing multilib for different 15410d565efSmrgsets of options. Such kind of reuse can minimize the number of multilib 15510d565efSmrgvariants. And for some targets it is better to reuse an existing multilib 15610d565efSmrgthan to fall back to default multilib when there is no corresponding multilib. 15710d565efSmrgThis can be done by adding reuse rules to @code{MULTILIB_REUSE}. 15810d565efSmrg 15910d565efSmrgA reuse rule is comprised of two parts connected by equality sign. The left 16010d565efSmrgpart is the option set used to build multilib and the right part is the option 16110d565efSmrgset that will reuse this multilib. Both parts should only use options 16210d565efSmrgspecified in @code{MULTILIB_OPTIONS} and the equality signs found in options 163c7a68eb7Smrgname should be replaced with periods. An explicit period in the rule can be 164c7a68eb7Smrgescaped by preceding it with a backslash. The order of options in the left 165c7a68eb7Smrgpart matters and should be same with those specified in 166c7a68eb7Smrg@code{MULTILIB_REQUIRED} or aligned with the order in @code{MULTILIB_OPTIONS}. 167c7a68eb7SmrgThere is no such limitation for options in the right part as we don't build 168c7a68eb7Smrgmultilib from them. 16910d565efSmrg 17010d565efSmrg@code{MULTILIB_REUSE} is different from @code{MULTILIB_MATCHES} in that it 17110d565efSmrgsets up relations between two option sets rather than two options. Here is an 17210d565efSmrgexample to demo how we reuse libraries built in Thumb mode for applications built 17310d565efSmrgin ARM mode: 17410d565efSmrg@smallexample 17510d565efSmrg@code{MULTILIB_REUSE} = mthumb/march.armv7-r=marm/march.armv7-r 17610d565efSmrg@end smallexample 17710d565efSmrg 17810d565efSmrgBefore the advent of @code{MULTILIB_REUSE}, GCC select multilib by comparing command 17910d565efSmrgline options with options used to build multilib. The @code{MULTILIB_REUSE} is 18010d565efSmrgcomplementary to that way. Only when the original comparison matches nothing it will 18110d565efSmrgwork to see if it is OK to reuse some existing multilib. 18210d565efSmrg 18310d565efSmrg@findex MULTILIB_EXTRA_OPTS 18410d565efSmrg@item MULTILIB_EXTRA_OPTS 18510d565efSmrgSometimes it is desirable that when building multiple versions of 18610d565efSmrg@file{libgcc.a} certain options should always be passed on to the 18710d565efSmrgcompiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list 18810d565efSmrgof options to be used for all builds. If you set this, you should 18910d565efSmrgprobably set @code{CRTSTUFF_T_CFLAGS} to a dash followed by it. 19010d565efSmrg 19110d565efSmrg@findex MULTILIB_OSDIRNAMES 19210d565efSmrg@item MULTILIB_OSDIRNAMES 19310d565efSmrgIf @code{MULTILIB_OPTIONS} is used, this variable specifies 19410d565efSmrga list of subdirectory names, that are used to modify the search 19510d565efSmrgpath depending on the chosen multilib. Unlike @code{MULTILIB_DIRNAMES}, 19610d565efSmrg@code{MULTILIB_OSDIRNAMES} describes the multilib directories using 19710d565efSmrgoperating systems conventions, and is applied to the directories such as 19810d565efSmrg@code{lib} or those in the @env{LIBRARY_PATH} environment variable. 19910d565efSmrgThe format is either the same as of 20010d565efSmrg@code{MULTILIB_DIRNAMES}, or a set of mappings. When it is the same 20110d565efSmrgas @code{MULTILIB_DIRNAMES}, it describes the multilib directories 20210d565efSmrgusing operating system conventions, rather than GCC conventions. When it is a set 20310d565efSmrgof mappings of the form @var{gccdir}=@var{osdir}, the left side gives 20410d565efSmrgthe GCC convention and the right gives the equivalent OS defined 20510d565efSmrglocation. If the @var{osdir} part begins with a @samp{!}, 20610d565efSmrgGCC will not search in the non-multilib directory and use 20710d565efSmrgexclusively the multilib directory. Otherwise, the compiler will 20810d565efSmrgexamine the search path for libraries and crt files twice; the first 20910d565efSmrgtime it will add @var{multilib} to each directory in the search path, 21010d565efSmrgthe second it will not. 21110d565efSmrg 21210d565efSmrgFor configurations that support both multilib and multiarch, 21310d565efSmrg@code{MULTILIB_OSDIRNAMES} also encodes the multiarch name, thus 21410d565efSmrgsubsuming @code{MULTIARCH_DIRNAME}. The multiarch name is appended to 2150fc04c29Smrgeach directory name, separated by a colon (e.g.@: 21610d565efSmrg@samp{../lib32:i386-linux-gnu}). 21710d565efSmrg 21810d565efSmrgEach multiarch subdirectory will be searched before the corresponding OS 21910d565efSmrgmultilib directory, for example @samp{/lib/i386-linux-gnu} before 22010d565efSmrg@samp{/lib/../lib32}. The multiarch name will also be used to modify the 22110d565efSmrgsystem header search path, as explained for @code{MULTIARCH_DIRNAME}. 22210d565efSmrg 22310d565efSmrg@findex MULTIARCH_DIRNAME 22410d565efSmrg@item MULTIARCH_DIRNAME 22510d565efSmrgThis variable specifies the multiarch name for configurations that are 22610d565efSmrgmultiarch-enabled but not multilibbed configurations. 22710d565efSmrg 22810d565efSmrgThe multiarch name is used to augment the search path for libraries, crt 22910d565efSmrgfiles and system header files with additional locations. The compiler 23010d565efSmrgwill add a multiarch subdirectory of the form 23110d565efSmrg@var{prefix}/@var{multiarch} before each directory in the library and 23210d565efSmrgcrt search path. It will also add two directories 23310d565efSmrg@code{LOCAL_INCLUDE_DIR}/@var{multiarch} and 23410d565efSmrg@code{NATIVE_SYSTEM_HEADER_DIR}/@var{multiarch}) to the system header 23510d565efSmrgsearch path, respectively before @code{LOCAL_INCLUDE_DIR} and 23610d565efSmrg@code{NATIVE_SYSTEM_HEADER_DIR}. 23710d565efSmrg 23810d565efSmrg@code{MULTIARCH_DIRNAME} is not used for configurations that support 23910d565efSmrgboth multilib and multiarch. In that case, multiarch names are encoded 24010d565efSmrgin @code{MULTILIB_OSDIRNAMES} instead. 24110d565efSmrg 24210d565efSmrgMore documentation about multiarch can be found at 24310d565efSmrg@uref{https://wiki.debian.org/Multiarch}. 24410d565efSmrg 24510d565efSmrg@findex SPECS 24610d565efSmrg@item SPECS 24710d565efSmrgUnfortunately, setting @code{MULTILIB_EXTRA_OPTS} is not enough, since 24810d565efSmrgit does not affect the build of target libraries, at least not the 24910d565efSmrgbuild of the default multilib. One possible work-around is to use 25010d565efSmrg@code{DRIVER_SELF_SPECS} to bring options from the @file{specs} file 25110d565efSmrgas if they had been passed in the compiler driver command line. 25210d565efSmrgHowever, you don't want to be adding these options after the toolchain 25310d565efSmrgis installed, so you can instead tweak the @file{specs} file that will 25410d565efSmrgbe used during the toolchain build, while you still install the 25510d565efSmrgoriginal, built-in @file{specs}. The trick is to set @code{SPECS} to 25610d565efSmrgsome other filename (say @file{specs.install}), that will then be 25710d565efSmrgcreated out of the built-in specs, and introduce a @file{Makefile} 25810d565efSmrgrule to generate the @file{specs} file that's going to be used at 25910d565efSmrgbuild time out of your @file{specs.install}. 26010d565efSmrg 26110d565efSmrg@item T_CFLAGS 26210d565efSmrgThese are extra flags to pass to the C compiler. They are used both 26310d565efSmrgwhen building GCC, and when compiling things with the just-built GCC@. 26410d565efSmrgThis variable is deprecated and should not be used. 26510d565efSmrg@end table 26610d565efSmrg 26710d565efSmrg@node Host Fragment 26810d565efSmrg@section Host Makefile Fragments 26910d565efSmrg@cindex host makefile fragment 27010d565efSmrg@cindex @file{x-@var{host}} 27110d565efSmrg 27210d565efSmrgThe use of @file{x-@var{host}} fragments is discouraged. You should only 27310d565efSmrguse it for makefile dependencies. 274