gcc/doc/fragments.texi

   1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
   2 @c 1999, 2000, 2001, 2003 Free Software Foundation, Inc.
   3 @c This is part of the GCC manual.
   4 @c For copying conditions, see the file gcc.texi.
   5
   6 @node Fragments
   7 @chapter Makefile Fragments
   8 @cindex makefile fragment
   9
  10 When you configure GCC using the @file{configure} script, it will
  11 construct the file @file{Makefile} from the template file
  12 @file{Makefile.in}.  When it does this, it can incorporate makefile
  13 fragments from the @file{config} directory.  These are used to set
  14 Makefile parameters that are not amenable to being calculated by
  15 autoconf.  The list of fragments to incorporate is set by
  16 @file{config.gcc} (and occasionally @file{config.build}
  17 and @file{config.host}); @xref{System Config}.
  18
  19 Fragments are named either @file{t-@var{target}} or @file{x-@var{host}},
  20 depending on whether they are relevant to configuring GCC to produce
  21 code for a particular target, or to configuring GCC to run on a
  22 particular host.  Here @var{target} and @var{host} are mnemonics
  23 which usually have some relationship to the canonical system name, but
  24 no formal connection.
  25
  26 If these files do not exist, it means nothing needs to be added for a
  27 given target or host.  Most targets need a few @file{t-@var{target}}
  28 fragments, but needing @file{x-@var{host}} fragments is rare.
  29
  30 @menu
  31 * Target Fragment:: Writing @file{t-@var{target}} files.
  32 * Host Fragment::   Writing @file{x-@var{host}} files.
  33 @end menu
  34
  35 @node Target Fragment
  36 @section Target Makefile Fragments
  37 @cindex target makefile fragment
  38 @cindex @file{t-@var{target}}
  39
  40 Target makefile fragments can set these Makefile variables.
  41
  42 @table @code
  43 @findex LIBGCC2_CFLAGS
  44 @item LIBGCC2_CFLAGS
  45 Compiler flags to use when compiling @file{libgcc2.c}.
  46
  47 @findex LIB2FUNCS_EXTRA
  48 @item LIB2FUNCS_EXTRA
  49 A list of source file names to be compiled or assembled and inserted
  50 into @file{libgcc.a}.
  51
  52 @findex Floating Point Emulation
  53 @item Floating Point Emulation
  54 To have GCC include software floating point libraries in @file{libgcc.a}
  55 define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
  56 @smallexample
  57 # We want fine grained libraries, so use the new code
  58 # to build the floating point emulation libraries.
  59 FPBIT = fp-bit.c
  60 DPBIT = dp-bit.c
  61
  62
  63 fp-bit.c: $(srcdir)/config/fp-bit.c
  64         echo '#define FLOAT' > fp-bit.c
  65         cat $(srcdir)/config/fp-bit.c >> fp-bit.c
  66
  67 dp-bit.c: $(srcdir)/config/fp-bit.c
  68         cat $(srcdir)/config/fp-bit.c > dp-bit.c
  69 @end smallexample
  70
  71 You may need to provide additional #defines at the beginning of @file{fp-bit.c}
  72 and @file{dp-bit.c} to control target endianness and other options.
  73
  74
  75 @findex CRTSTUFF_T_CFLAGS
  76 @item CRTSTUFF_T_CFLAGS
  77 Special flags used when compiling @file{crtstuff.c}.
  78 @xref{Initialization}.
  79
  80 @findex CRTSTUFF_T_CFLAGS_S
  81 @item CRTSTUFF_T_CFLAGS_S
  82 Special flags used when compiling @file{crtstuff.c} for shared
  83 linking.  Used if you use @file{crtbeginS.o} and @file{crtendS.o}
  84 in @code{EXTRA-PARTS}.
  85 @xref{Initialization}.
  86
  87 @findex MULTILIB_OPTIONS
  88 @item MULTILIB_OPTIONS
  89 For some targets, invoking GCC in different ways produces objects
  90 that can not be linked together.  For example, for some targets GCC
  91 produces both big and little endian code.  For these targets, you must
  92 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
  93 each set of incompatible options.  When GCC invokes the linker, it
  94 arranges to link in the right version of @file{libgcc.a}, based on
  95 the command line options used.
  96
  97 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
  98 special versions of @file{libgcc.a} must be built.  Write options that
  99 are mutually incompatible side by side, separated by a slash.  Write
 100 options that may be used together separated by a space.  The build
 101 procedure will build all combinations of compatible options.
 102
 103 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
 104 msoft-float}, @file{Makefile} will build special versions of
 105 @file{libgcc.a} using the following sets of options:  @option{-m68000},
 106 @option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
 107 @samp{-m68020 -msoft-float}.
 108
 109 @findex MULTILIB_DIRNAMES
 110 @item MULTILIB_DIRNAMES
 111 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
 112 directory names that should be used to hold the various libraries.
 113 Write one element in @code{MULTILIB_DIRNAMES} for each element in
 114 @code{MULTILIB_OPTIONS}.  If @code{MULTILIB_DIRNAMES} is not used, the
 115 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
 116 as spaces.
 117
 118 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
 119 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
 120 @samp{m68000 m68020 msoft-float}.  You may specify a different value if
 121 you desire a different set of directory names.
 122
 123 @findex MULTILIB_MATCHES
 124 @item MULTILIB_MATCHES
 125 Sometimes the same option may be written in two different ways.  If an
 126 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
 127 any synonyms.  In that case, set @code{MULTILIB_MATCHES} to a list of
 128 items of the form @samp{option=option} to describe all relevant
 129 synonyms.  For example, @samp{m68000=mc68000 m68020=mc68020}.
 130
 131 @findex MULTILIB_EXCEPTIONS
 132 @item MULTILIB_EXCEPTIONS
 133 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
 134 specified, there are combinations that should not be built.  In that
 135 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
 136 in shell case syntax that should not be built.
 137
 138 For example the ARM processor cannot execute both hardware floating
 139 point instructions and the reduced size THUMB instructions at the same
 140 time, so there is no need to build libraries with both of these
 141 options enabled.  Therefore @code{MULTILIB_EXCEPTIONS} is set to:
 142 @smallexample
 143 *mthumb/*mhard-float*
 144 @end smallexample
 145
 146 @findex MULTILIB_EXTRA_OPTS
 147 @item MULTILIB_EXTRA_OPTS
 148 Sometimes it is desirable that when building multiple versions of
 149 @file{libgcc.a} certain options should always be passed on to the
 150 compiler.  In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
 151 of options to be used for all builds.  If you set this, you should
 152 probably set @code{CRTSTUFF_T_CFLAGS} to a dash followed by it.
 153
 154 @findex SPECS
 155 @item SPECS
 156 Unfortunately, setting @code{MULTILIB_EXTRA_OPTS} is not enough, since
 157 it does not affect the build of target libraries, at least not the
 158 build of the default multilib.  One possible work-around is to use
 159 @code{DRIVER_SELF_SPECS} to bring options from the @file{specs} file
 160 as if they had been passed in the compiler driver command line.
 161 However, you don't want to be adding these options after the toolchain
 162 is installed, so you can instead tweak the @file{specs} file that will
 163 be used during the toolchain build, while you still install the
 164 original, built-in @file{specs}.  The trick is to set @code{SPECS} to
 165 some other filename (say @file{specs.install}), that will then be
 166 created out of the built-in specs, and introduce a @file{Makefile}
 167 rule to generate the @file{specs} file that's going to be used at
 168 build time out of your @file{specs.install}.
 169 @end table
 170
 171 @node Host Fragment
 172 @section Host Makefile Fragments
 173 @cindex host makefile fragment
 174 @cindex @file{x-@var{host}}
 175
 176 The use of @file{x-@var{host}} fragments is discouraged.  You should do
 177 so only if there is no other mechanism to get the behavior desired.
 178 Host fragments should never forcibly override variables set by the
 179 configure script, as they may have been adjusted by the user.
 180
 181 Variables provided for host fragments to set include:
 182
 183 @table @code
 184
 185 @item X_CFLAGS
 186 @itemx X_CPPFLAGS
 187 These are extra flags to pass to the C compiler and preprocessor,
 188 respectively.  They are used both when building GCC, and when compiling
 189 things with the just-built GCC.
 190
 191 @item XCFLAGS
 192 These are extra flags to use when building the compiler.  They are not
 193 used when compiling @file{libgcc.a}.  However, they @emph{are} used when
 194 recompiling the compiler with itself in later stages of a bootstrap.
 195
 196 @item BOOT_LDFLAGS
 197 Flags to be passed to the linker when recompiling the compiler with
 198 itself in later stages of a bootstrap.  You might need to use this if,
 199 for instance, one of the front ends needs more text space than the
 200 linker provides by default.
 201
 202 @item EXTRA_PROGRAMS
 203 A list of additional programs required to use the compiler on this host,
 204 which should be compiled with GCC and installed alongside the front
 205 ends.  If you set this variable, you must also provide rules to build
 206 the extra programs.
 207
 208 @end table