gcc/doc/fragments.texi

   1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
   2 @c 1999, 2000, 2001 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}; @xref{System Config}.
  17
  18 Fragments are named either @file{t-@var{target}} or @file{x-@var{host}},
  19 depending on whether they are relevant to configuring GCC to produce
  20 code for a particular target, or to configuring GCC to run on a
  21 particular host.  Here @var{target} and @var{host} are mnemonics
  22 which usually have some relationship to the canonical system name, but
  23 no formal connection.
  24
  25 If these files do not exist, it means nothing needs to be added for a
  26 given target or host.  Most targets need a few @file{t-@var{target}}
  27 fragments, 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
  39 Target makefile fragments can set these Makefile variables.
  40
  41 @table @code
  42 @findex LIBGCC2_CFLAGS
  43 @item LIBGCC2_CFLAGS
  44 Compiler flags to use when compiling @file{libgcc2.c}.
  45
  46 @findex LIB2FUNCS_EXTRA
  47 @item LIB2FUNCS_EXTRA
  48 A list of source file names to be compiled or assembled and inserted
  49 into @file{libgcc.a}.
  50
  51 @findex Floating Point Emulation
  52 @item Floating Point Emulation
  53 To have GCC include software floating point libraries in @file{libgcc.a}
  54 define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
  55 @smallexample
  56 # We want fine grained libraries, so use the new code
  57 # to build the floating point emulation libraries.
  58 FPBIT = fp-bit.c
  59 DPBIT = dp-bit.c
  60
  61
  62 fp-bit.c: $(srcdir)/config/fp-bit.c
  63         echo '#define FLOAT' > fp-bit.c
  64         cat $(srcdir)/config/fp-bit.c >> fp-bit.c
  65
  66 dp-bit.c: $(srcdir)/config/fp-bit.c
  67         cat $(srcdir)/config/fp-bit.c > dp-bit.c
  68 @end smallexample
  69
  70 You may need to provide additional #defines at the beginning of @file{fp-bit.c}
  71 and @file{dp-bit.c} to control target endianness and other options.
  72
  73
  74 @findex CRTSTUFF_T_CFLAGS
  75 @item CRTSTUFF_T_CFLAGS
  76 Special flags used when compiling @file{crtstuff.c}.
  77 @xref{Initialization}.
  78
  79 @findex CRTSTUFF_T_CFLAGS_S
  80 @item CRTSTUFF_T_CFLAGS_S
  81 Special flags used when compiling @file{crtstuff.c} for shared
  82 linking.  Used if you use @file{crtbeginS.o} and @file{crtendS.o}
  83 in @code{EXTRA-PARTS}.
  84 @xref{Initialization}.
  85
  86 @findex MULTILIB_OPTIONS
  87 @item MULTILIB_OPTIONS
  88 For some targets, invoking GCC in different ways produces objects
  89 that can not be linked together.  For example, for some targets GCC
  90 produces both big and little endian code.  For these targets, you must
  91 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
  92 each set of incompatible options.  When GCC invokes the linker, it
  93 arranges to link in the right version of @file{libgcc.a}, based on
  94 the command line options used.
  95
  96 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
  97 special versions of @file{libgcc.a} must be built.  Write options that
  98 are mutually incompatible side by side, separated by a slash.  Write
  99 options that may be used together separated by a space.  The build
 100 procedure will build all combinations of compatible options.
 101
 102 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
 103 msoft-float}, @file{Makefile} will build special versions of
 104 @file{libgcc.a} using the following sets of options:  @option{-m68000},
 105 @option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
 106 @samp{-m68020 -msoft-float}.
 107
 108 @findex MULTILIB_DIRNAMES
 109 @item MULTILIB_DIRNAMES
 110 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
 111 directory names that should be used to hold the various libraries.
 112 Write one element in @code{MULTILIB_DIRNAMES} for each element in
 113 @code{MULTILIB_OPTIONS}.  If @code{MULTILIB_DIRNAMES} is not used, the
 114 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
 115 as spaces.
 116
 117 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
 118 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
 119 @samp{m68000 m68020 msoft-float}.  You may specify a different value if
 120 you desire a different set of directory names.
 121
 122 @findex MULTILIB_MATCHES
 123 @item MULTILIB_MATCHES
 124 Sometimes the same option may be written in two different ways.  If an
 125 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
 126 any synonyms.  In that case, set @code{MULTILIB_MATCHES} to a list of
 127 items of the form @samp{option=option} to describe all relevant
 128 synonyms.  For example, @samp{m68000=mc68000 m68020=mc68020}.
 129
 130 @findex MULTILIB_EXCEPTIONS
 131 @item MULTILIB_EXCEPTIONS
 132 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
 133 specified, there are combinations that should not be built.  In that
 134 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
 135 in shell case syntax that should not be built.
 136
 137 For example, in the PowerPC embedded ABI support, it is not desirable
 138 to build libraries compiled with the @option{-mcall-aix} option
 139 and either of the @option{-fleading-underscore} or @option{-mlittle} options
 140 at the same time.  Therefore @code{MULTILIB_EXCEPTIONS} is set to
 141 @smallexample
 142 *mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*
 143 @end smallexample
 144
 145 @findex MULTILIB_EXTRA_OPTS
 146 @item MULTILIB_EXTRA_OPTS
 147 Sometimes it is desirable that when building multiple versions of
 148 @file{libgcc.a} certain options should always be passed on to the
 149 compiler.  In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
 150 of options to be used for all builds.
 151 @end table
 152
 153 @node Host Fragment
 154 @section Host Makefile Fragments
 155 @cindex host makefile fragment
 156 @cindex @file{x-@var{host}}
 157
 158 The use of @file{x-@var{host}} fragments is discouraged.  You should do
 159 so only if there is no other mechanism to get the behavior desired.
 160 Host fragments should never forcibly override variables set by the
 161 configure script, as they may have been adjusted by the user.
 162
 163 Variables provided for host fragments to set include:
 164
 165 @table @code
 166
 167 @item X_CFLAGS
 168 @itemx X_CPPFLAGS
 169 These are extra flags to pass to the C compiler and preprocessor,
 170 respectively.  They are used both when building GCC, and when compiling
 171 things with the just-built GCC.
 172
 173 @item XCFLAGS
 174 These are extra flags to use when building the compiler.  They are not
 175 used when compiling @file{libgcc.a}.  However, they @emph{are} used when
 176 recompiling the compiler with itself in later stages of a bootstrap.
 177
 178 @item BOOT_LDFLAGS
 179 Flags to be passed to the linker when recompiling the compiler with
 180 itself in later stages of a bootstrap.  You might need to use this if,
 181 for instance, one of the front ends needs more text space than the
 182 linker provides by default.
 183
 184 @item EXTRA_PROGRAMS
 185 A list of additional programs required to use the compiler on this host,
 186 which should be compiled with GCC and installed alongside the front
 187 ends.  If you set this variable, you must also provide rules to build
 188 the extra programs.
 189
 190 @end table