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 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 CRTSTUFF_T_CFLAGS
  53 @item CRTSTUFF_T_CFLAGS
  54 Special flags used when compiling @file{crtstuff.c}.
  55 @xref{Initialization}.
  56
  57 @findex CRTSTUFF_T_CFLAGS_S
  58 @item CRTSTUFF_T_CFLAGS_S
  59 Special flags used when compiling @file{crtstuff.c} for shared
  60 linking.  Used if you use @file{crtbeginS.o} and @file{crtendS.o}
  61 in @code{EXTRA-PARTS}.
  62 @xref{Initialization}.
  63
  64 @findex MULTILIB_OPTIONS
  65 @item MULTILIB_OPTIONS
  66 For some targets, invoking GCC in different ways produces objects
  67 that can not be linked together.  For example, for some targets GCC
  68 produces both big and little endian code.  For these targets, you must
  69 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
  70 each set of incompatible options.  When GCC invokes the linker, it
  71 arranges to link in the right version of @file{libgcc.a}, based on
  72 the command line options used.
  73
  74 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
  75 special versions of @file{libgcc.a} must be built.  Write options that
  76 are mutually incompatible side by side, separated by a slash.  Write
  77 options that may be used together separated by a space.  The build
  78 procedure will build all combinations of compatible options.
  79
  80 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
  81 msoft-float}, @file{Makefile} will build special versions of
  82 @file{libgcc.a} using the following sets of options:  @option{-m68000},
  83 @option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
  84 @samp{-m68020 -msoft-float}.
  85
  86 @findex MULTILIB_DIRNAMES
  87 @item MULTILIB_DIRNAMES
  88 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
  89 directory names that should be used to hold the various libraries.
  90 Write one element in @code{MULTILIB_DIRNAMES} for each element in
  91 @code{MULTILIB_OPTIONS}.  If @code{MULTILIB_DIRNAMES} is not used, the
  92 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
  93 as spaces.
  94
  95 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
  96 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
  97 @samp{m68000 m68020 msoft-float}.  You may specify a different value if
  98 you desire a different set of directory names.
  99
 100 @findex MULTILIB_MATCHES
 101 @item MULTILIB_MATCHES
 102 Sometimes the same option may be written in two different ways.  If an
 103 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
 104 any synonyms.  In that case, set @code{MULTILIB_MATCHES} to a list of
 105 items of the form @samp{option=option} to describe all relevant
 106 synonyms.  For example, @samp{m68000=mc68000 m68020=mc68020}.
 107
 108 @findex MULTILIB_EXCEPTIONS
 109 @item MULTILIB_EXCEPTIONS
 110 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
 111 specified, there are combinations that should not be built.  In that
 112 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
 113 in shell case syntax that should not be built.
 114
 115 For example the ARM processor cannot execute both hardware floating
 116 point instructions and the reduced size THUMB instructions at the same
 117 time, so there is no need to build libraries with both of these
 118 options enabled.  Therefore @code{MULTILIB_EXCEPTIONS} is set to:
 119 @smallexample
 120 *mthumb/*mhard-float*
 121 @end smallexample
 122
 123 @findex MULTILIB_EXTRA_OPTS
 124 @item MULTILIB_EXTRA_OPTS
 125 Sometimes it is desirable that when building multiple versions of
 126 @file{libgcc.a} certain options should always be passed on to the
 127 compiler.  In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
 128 of options to be used for all builds.  If you set this, you should
 129 probably set @code{CRTSTUFF_T_CFLAGS} to a dash followed by it.
 130
 131 @findex NATIVE_SYSTEM_HEADER_DIR
 132 @item NATIVE_SYSTEM_HEADER_DIR
 133 If the default location for system headers is not @file{/usr/include},
 134 you must set this to the directory containing the headers.  This value
 135 should match the value of the @code{SYSTEM_INCLUDE_DIR} macro.
 136
 137 @findex SPECS
 138 @item SPECS
 139 Unfortunately, setting @code{MULTILIB_EXTRA_OPTS} is not enough, since
 140 it does not affect the build of target libraries, at least not the
 141 build of the default multilib.  One possible work-around is to use
 142 @code{DRIVER_SELF_SPECS} to bring options from the @file{specs} file
 143 as if they had been passed in the compiler driver command line.
 144 However, you don't want to be adding these options after the toolchain
 145 is installed, so you can instead tweak the @file{specs} file that will
 146 be used during the toolchain build, while you still install the
 147 original, built-in @file{specs}.  The trick is to set @code{SPECS} to
 148 some other filename (say @file{specs.install}), that will then be
 149 created out of the built-in specs, and introduce a @file{Makefile}
 150 rule to generate the @file{specs} file that's going to be used at
 151 build time out of your @file{specs.install}.
 152
 153 @item T_CFLAGS
 154 These are extra flags to pass to the C compiler.  They are used both
 155 when building GCC, and when compiling things with the just-built GCC@.
 156 This variable is deprecated and should not be used.
 157 @end table
 158
 159 @node Host Fragment
 160 @section Host Makefile Fragments
 161 @cindex host makefile fragment
 162 @cindex @file{x-@var{host}}
 163
 164 The use of @file{x-@var{host}} fragments is discouraged.  You should only
 165 use it for makefile dependencies.