1@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
2@c 1999, 2000, 2001, 2003, 2004, 2005, 2008, 2011
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
96For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
97msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
98@samp{m68000 m68020 msoft-float}.  You may specify a different value if
99you desire a different set of directory names.
100
101@findex MULTILIB_MATCHES
102@item MULTILIB_MATCHES
103Sometimes the same option may be written in two different ways.  If an
104option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
105any synonyms.  In that case, set @code{MULTILIB_MATCHES} to a list of
106items of the form @samp{option=option} to describe all relevant
107synonyms.  For example, @samp{m68000=mc68000 m68020=mc68020}.
108
109@findex MULTILIB_EXCEPTIONS
110@item MULTILIB_EXCEPTIONS
111Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
112specified, there are combinations that should not be built.  In that
113case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
114in shell case syntax that should not be built.
115
116For example the ARM processor cannot execute both hardware floating
117point instructions and the reduced size THUMB instructions at the same
118time, so there is no need to build libraries with both of these
119options enabled.  Therefore @code{MULTILIB_EXCEPTIONS} is set to:
120@smallexample
121*mthumb/*mhard-float*
122@end smallexample
123
124@findex MULTILIB_EXTRA_OPTS
125@item MULTILIB_EXTRA_OPTS
126Sometimes it is desirable that when building multiple versions of
127@file{libgcc.a} certain options should always be passed on to the
128compiler.  In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
129of options to be used for all builds.  If you set this, you should
130probably set @code{CRTSTUFF_T_CFLAGS} to a dash followed by it.
131
132@findex SPECS
133@item SPECS
134Unfortunately, setting @code{MULTILIB_EXTRA_OPTS} is not enough, since
135it does not affect the build of target libraries, at least not the
136build of the default multilib.  One possible work-around is to use
137@code{DRIVER_SELF_SPECS} to bring options from the @file{specs} file
138as if they had been passed in the compiler driver command line.
139However, you don't want to be adding these options after the toolchain
140is installed, so you can instead tweak the @file{specs} file that will
141be used during the toolchain build, while you still install the
142original, built-in @file{specs}.  The trick is to set @code{SPECS} to
143some other filename (say @file{specs.install}), that will then be
144created out of the built-in specs, and introduce a @file{Makefile}
145rule to generate the @file{specs} file that's going to be used at
146build time out of your @file{specs.install}.
147
148@item T_CFLAGS
149These are extra flags to pass to the C compiler.  They are used both
150when building GCC, and when compiling things with the just-built GCC@.
151This variable is deprecated and should not be used.
152@end table
153
154@node Host Fragment
155@section Host Makefile Fragments
156@cindex host makefile fragment
157@cindex @file{x-@var{host}}
158
159The use of @file{x-@var{host}} fragments is discouraged.  You should only
160use it for makefile dependencies.
161