2013-05-30 Ed Smith-Rowland <3dw4rd@verizon.net>

[official-gcc.git] / gcc / doc / fragments.texi

@c Copyright (C) 1988-2013 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 can incorporate makefile
fragments from the @file{config} directory.  These are used to set
Makefile parameters that are not amenable to being calculated by
autoconf.  The list of fragments to incorporate is set by
@file{config.gcc} (and occasionally @file{config.build}
and @file{config.host}); @xref{System Config}.

Fragments are named either @file{t-@var{target}} or @file{x-@var{host}},
depending on whether they are relevant to configuring GCC to produce
code for a particular target, or to configuring GCC to run on a
particular host.  Here @var{target} and @var{host} are mnemonics
which usually have some relationship to the canonical system name, but
no formal connection.

If these files do not exist, it means nothing needs to be added for a
given target or host.  Most targets need a few @file{t-@var{target}}
fragments, but needing @file{x-@var{host}} fragments is rare.

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

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

Target makefile fragments can set these Makefile variables.

@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 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.

@code{MULTILIB_DIRNAMES} describes the multilib directories using GCC
conventions and is applied to directories that are part of the GCC
installation.  When multilib-enabled, the compiler will add a
subdirectory of the form @var{prefix}/@var{multilib} before each
directory in the search path for libraries and crt files.

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 the ARM processor cannot execute both hardware floating
point instructions and the reduced size THUMB instructions at the same
time, so there is no need to build libraries with both of these
options enabled.  Therefore @code{MULTILIB_EXCEPTIONS} is set to:
@smallexample
*mthumb/*mhard-float*
@end smallexample

@findex MULTILIB_REQUIRED
@item MULTILIB_REQUIRED
Sometimes when there are only a few combinations are required, it would
be a big effort to come up with a @code{MULTILIB_EXCEPTIONS} list to
cover all undesired ones.  In such a case, just listing all the required
combinations in @code{MULTILIB_REQUIRED} would be more straightforward.

The way to specify the entries in @code{MULTILIB_REQUIRED} is same with
the way used for @code{MULTILIB_EXCEPTIONS}, only this time what are
required will be specified.  Suppose there are multiple sets of
@code{MULTILIB_OPTIONS} and only two combinations are required, one
for ARMv7-M and one for ARMv7-R with hard floating-point ABI and FPU, the
@code{MULTILIB_REQUIRED} can be set to:
@smallexample
@code{MULTILIB_REQUIRED} =  mthumb/march=armv7-m
@code{MULTILIB_REQUIRED} += march=armv7-r/mfloat-abi=hard/mfpu=vfpv3-d16
@end smallexample

The @code{MULTILIB_REQUIRED} can be used together with
@code{MULTILIB_EXCEPTIONS}.  The option combinations generated from
@code{MULTILIB_OPTIONS} will be filtered by @code{MULTILIB_EXCEPTIONS}
and then by @code{MULTILIB_REQUIRED}.

@findex MULTILIB_REUSE
@item MULTILIB_REUSE
Sometimes it is desirable to reuse one existing multilib for different
sets of options.  Such kind of reuse can minimize the number of multilib
variants.  And for some targets it is better to reuse an existing multilib
than to fall back to default multilib when there is no corresponding multilib.
This can be done by adding reuse rules to @code{MULTILIB_REUSE}.

A reuse rule is comprised of two parts connected by equality sign.  The left part
is option set used to build multilib and the right part is option set that will
reuse this multilib.  The order of options in the left part matters and should be
same with those specified in @code{MULTILIB_REQUIRED} or aligned with order in
@code{MULTILIB_OPTIONS}.  There is no such limitation for options in right part
as we don't build multilib from them.  But the equality sign in both parts should
be replaced with period.

The @code{MULTILIB_REUSE} is different from @code{MULTILIB_MATCHES} in that it
sets up relations between two option sets rather than two options.  Here is an
example to demo how we reuse libraries built in Thumb mode for applications built
in ARM mode:
@smallexample
@code{MULTILIB_REUSE} = mthumb/march.armv7-r=marm/march.armv7-r
@end smallexample

Before the advent of @code{MULTILIB_REUSE}, GCC select multilib by comparing command
line options with options used to build multilib.  The @code{MULTILIB_REUSE} is
complementary to that way.  Only when the original comparison matches nothing it will
work to see if it is OK to reuse some existing multilib.

@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.  If you set this, you should
probably set @code{CRTSTUFF_T_CFLAGS} to a dash followed by it.

@findex MULTILIB_OSDIRNAMES
@item MULTILIB_OSDIRNAMES
If @code{MULTILIB_OPTIONS} is used, this variable specifies 
a list of subdirectory names, that are used to modify the search
path depending on the chosen multilib.  Unlike @code{MULTILIB_DIRNAMES},
@code{MULTILIB_OSDIRNAMES} describes the multilib directories using
operating systems conventions, and is applied to the directories such as
@code{lib} or those in the @env{LIBRARY_PATH} environment variable.
The format is either the same as of
@code{MULTILIB_DIRNAMES}, or a set of mappings.  When it is the same
as @code{MULTILIB_DIRNAMES}, it describes the multilib directories
using operating system conventions, rather than GCC conventions.  When it is a set
of mappings of the form @var{gccdir}=@var{osdir}, the left side gives
the GCC convention and the right gives the equivalent OS defined
location.  If the @var{osdir} part begins with a @samp{!},
GCC will not search in the non-multilib directory and use
exclusively the multilib directory.  Otherwise, the compiler will
examine the search path for libraries and crt files twice; the first
time it will add @var{multilib} to each directory in the search path,
the second it will not.

For configurations that support both multilib and multiarch,
@code{MULTILIB_OSDIRNAMES} also encodes the multiarch name, thus
subsuming @code{MULTIARCH_DIRNAME}.  The multiarch name is appended to
each directory name, separated by a colon (e.g.
@samp{../lib32:i386-linux-gnu}).

Each multiarch subdirectory will be searched before the corresponding OS
multilib directory, for example @samp{/lib/i386-linux-gnu} before
@samp{/lib/../lib32}.  The multiarch name will also be used to modify the
system header search path, as explained for @code{MULTIARCH_DIRNAME}.

@findex MULTIARCH_DIRNAME
@item MULTIARCH_DIRNAME
This variable specifies the multiarch name for configurations that are
multiarch-enabled but not multilibbed configurations.

The multiarch name is used to augment the search path for libraries, crt
files and system header files with additional locations.  The compiler
will add a multiarch subdirectory of the form
@var{prefix}/@var{multiarch} before each directory in the library and
crt search path.  It will also add two directories
@code{LOCAL_INCLUDE_DIR}/@var{multiarch} and
@code{NATIVE_SYSTEM_HEADER_DIR}/@var{multiarch}) to the system header
search path, respectively before @code{LOCAL_INCLUDE_DIR} and
@code{NATIVE_SYSTEM_HEADER_DIR}.

@code{MULTIARCH_DIRNAME} is not used for configurations that support
both multilib and multiarch.  In that case, multiarch names are encoded
in @code{MULTILIB_OSDIRNAMES} instead.

More documentation about multiarch can be found at
@uref{http://wiki.debian.org/Multiarch}.

@findex SPECS
@item SPECS
Unfortunately, setting @code{MULTILIB_EXTRA_OPTS} is not enough, since
it does not affect the build of target libraries, at least not the
build of the default multilib.  One possible work-around is to use
@code{DRIVER_SELF_SPECS} to bring options from the @file{specs} file
as if they had been passed in the compiler driver command line.
However, you don't want to be adding these options after the toolchain
is installed, so you can instead tweak the @file{specs} file that will
be used during the toolchain build, while you still install the
original, built-in @file{specs}.  The trick is to set @code{SPECS} to
some other filename (say @file{specs.install}), that will then be
created out of the built-in specs, and introduce a @file{Makefile}
rule to generate the @file{specs} file that's going to be used at
build time out of your @file{specs.install}.

@item T_CFLAGS
These are extra flags to pass to the C compiler.  They are used both
when building GCC, and when compiling things with the just-built GCC@.
This variable is deprecated and should not be used.
@end table

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

The use of @file{x-@var{host}} fragments is discouraged.  You should only
use it for makefile dependencies.