gcc/doc/fragments.texi

@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
@c 1999, 2000, 2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.

@node Fragments
@chapter Makefile Fragments
@cindex makefile fragment

When you configure GCC using the @file{configure} script,
it will construct the file @file{Makefile} from
the template file @file{Makefile.in}.  When it does this, it will
incorporate makefile fragment files from the @file{config} directory,
named @file{t-@var{target}} and @file{x-@var{host}}.  If these files do
not exist, it means nothing needs to be added for a given target or
host.

@menu
* Target Fragment:: Writing the @file{t-@var{target}} file.
* Host Fragment::   Writing the @file{x-@var{host}} file.
@end menu

@node Target Fragment
@section The Target Makefile Fragment
@cindex target makefile fragment
@cindex @file{t-@var{target}}

The target makefile fragment, @file{t-@var{target}}, defines special
target dependent variables and targets used in the @file{Makefile}:

@table @code
@findex LIBGCC2_CFLAGS
@item LIBGCC2_CFLAGS
Compiler flags to use when compiling @file{libgcc2.c}.

@findex LIB2FUNCS_EXTRA
@item LIB2FUNCS_EXTRA
A list of source file names to be compiled or assembled and inserted
into @file{libgcc.a}.

@findex Floating Point Emulation
@item Floating Point Emulation
To have GCC include software floating point libraries in @file{libgcc.a}
define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
@smallexample
# We want fine grained libraries, so use the new code
# to build the floating point emulation libraries.
FPBIT = fp-bit.c
DPBIT = dp-bit.c


fp-bit.c: $(srcdir)/config/fp-bit.c
        echo '#define FLOAT' > fp-bit.c
        cat $(srcdir)/config/fp-bit.c >> fp-bit.c

dp-bit.c: $(srcdir)/config/fp-bit.c
        cat $(srcdir)/config/fp-bit.c > dp-bit.c
@end smallexample

You may need to provide additional #defines at the beginning of @file{fp-bit.c}
and @file{dp-bit.c} to control target endianness and other options.


@findex CRTSTUFF_T_CFLAGS
@item CRTSTUFF_T_CFLAGS
Special flags used when compiling @file{crtstuff.c}.
@xref{Initialization}.

@findex CRTSTUFF_T_CFLAGS_S
@item CRTSTUFF_T_CFLAGS_S
Special flags used when compiling @file{crtstuff.c} for shared
linking.  Used if you use @file{crtbeginS.o} and @file{crtendS.o}
in @code{EXTRA-PARTS}.
@xref{Initialization}.

@findex MULTILIB_OPTIONS
@item MULTILIB_OPTIONS
For some targets, invoking GCC in different ways produces objects
that can not be linked together.  For example, for some targets GCC
produces both big and little endian code.  For these targets, you must
arrange for multiple versions of @file{libgcc.a} to be compiled, one for
each set of incompatible options.  When GCC invokes the linker, it
arranges to link in the right version of @file{libgcc.a}, based on
the command line options used.

The @code{MULTILIB_OPTIONS} macro lists the set of options for which
special versions of @file{libgcc.a} must be built.  Write options that
are mutually incompatible side by side, separated by a slash.  Write
options that may be used together separated by a space.  The build
procedure will build all combinations of compatible options.

For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
msoft-float}, @file{Makefile} will build special versions of
@file{libgcc.a} using the following sets of options:  @option{-m68000},
@option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
@samp{-m68020 -msoft-float}.

@findex MULTILIB_DIRNAMES
@item MULTILIB_DIRNAMES
If @code{MULTILIB_OPTIONS} is used, this variable specifies the
directory names that should be used to hold the various libraries.
Write one element in @code{MULTILIB_DIRNAMES} for each element in
@code{MULTILIB_OPTIONS}.  If @code{MULTILIB_DIRNAMES} is not used, the
default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
as spaces.

For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
@samp{m68000 m68020 msoft-float}.  You may specify a different value if
you desire a different set of directory names.

@findex MULTILIB_MATCHES
@item MULTILIB_MATCHES
Sometimes the same option may be written in two different ways.  If an
option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
any synonyms.  In that case, set @code{MULTILIB_MATCHES} to a list of
items of the form @samp{option=option} to describe all relevant
synonyms.  For example, @samp{m68000=mc68000 m68020=mc68020}.

@findex MULTILIB_EXCEPTIONS
@item MULTILIB_EXCEPTIONS
Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
specified, there are combinations that should not be built.  In that
case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
in shell case syntax that should not be built.

For example, in the PowerPC embedded ABI support, it is not desirable
to build libraries compiled with the @option{-mcall-aix} option
and either of the @option{-fleading-underscore} or @option{-mlittle} options
at the same time.  Therefore @code{MULTILIB_EXCEPTIONS} is set to
@smallexample
*mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*
@end smallexample

@findex MULTILIB_EXTRA_OPTS
@item MULTILIB_EXTRA_OPTS
Sometimes it is desirable that when building multiple versions of
@file{libgcc.a} certain options should always be passed on to the
compiler.  In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
of options to be used for all builds.
@end table

@node Host Fragment
@section The Host Makefile Fragment
@cindex host makefile fragment
@cindex @file{x-@var{host}}

The host makefile fragment, @file{x-@var{host}}, defines special host
dependent variables and targets used in the @file{Makefile}:

@table @code
@findex CC
@item CC
The compiler to use when building the first stage.

@findex INSTALL
@item INSTALL
The install program to use.
@end table