gcc/doc/fragments.texi

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