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