$(docdir)/invoke.texi $(docdir)/extend.texi $(docdir)/md.texi \
$(docdir)/objc.texi $(docdir)/gcov.texi $(docdir)/trouble.texi \
$(docdir)/bugreport.texi $(docdir)/service.texi \
- $(docdir)/contribute.texi $(docdir)/vms.texi \
+ $(docdir)/contribute.texi $(docdir)/vms.texi $(docdir)/compat.texi \
$(docdir)/include/funding.texi $(docdir)/gnu.texi \
$(docdir)/include/gpl.texi $(docdir)/include/fdl.texi \
$(docdir)/contrib.texi $(docdir)/cppenv.texi $(docdir)/cppopts.texi
the adjusted @code{this} pointer must be adjusted again. The complete
calculation is given by the following pseudo-code:
-@example
+@smallexample
this += THUNK_DELTA
if (THUNK_VCALL_OFFSET)
this += (*((ptrdiff_t **) this))[THUNK_VCALL_OFFSET]
-@end example
+@end smallexample
Finally, the thunk should jump to the location given
by @code{DECL_INITIAL}; this will always be an expression for the
The nine trigraphs and their replacements are
-@example
+@smallexample
Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??-
Replacement: [ ] @{ @} # \ ^ | ~
-@end example
+@end smallexample
@end ifclear
@item -remap
called @dfn{trampolines}. A paper describing them is available as
@noindent
-@uref{http://people.debian.org/~karlheg/Usenix88-lexic.pdf}.
+@uref{http://people.debian.org/~aaronl/Usenix88-lexic.pdf}.
A nested function can jump to a label inherited from a containing
function, provided the label was explicitly declared in the containing
defining the macro is similar to that of a function. Here is an
example:
-@example
+@smallexample
#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
-@end example
+@end smallexample
Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
such a macro, it represents the zero or more tokens until the closing
To help solve this problem, CPP behaves specially for variable arguments
used with the token paste operator, @samp{##}. If instead you write
-@example
+@smallexample
#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
-@end example
+@end smallexample
and if the variable arguments are omitted or empty, the @samp{##}
operator causes the preprocessor to remove the comma before it. If you
subobject corresponding to the closest surrounding brace pair. For
example, with the @samp{struct point} declaration above:
-@example
+@smallexample
struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
-@end example
+@end smallexample
@noindent
If the same field is initialized multiple times, it will have value from
In the following example, @code{A} would normally be created before
@code{B}, but the @code{init_priority} attribute has reversed that order:
-@example
+@smallexample
Some_Class A __attribute__ ((init_priority (2000)));
Some_Class B __attribute__ ((init_priority (543)));
-@end example
+@end smallexample
@noindent
Note that the particular values of @var{priority} do not matter; only their
when Java exceptions are thrown through it, GCC will guess incorrectly.
Sample problematic code is:
-@example
+@smallexample
struct S @{ ~S(); @};
extern void bar(); // is written in Java, and may throw exceptions
void foo()
S s;
bar();
@}
-@end example
+@end smallexample
@noindent
The usual effect of an incorrect guess is a link failure, complaining of
* C Extensions:: GNU extensions to the C language family.
* C++ Extensions:: GNU extensions to the C++ language.
* Objective-C:: GNU Objective-C runtime features.
+* Compatibility:: Binary Compatibility
* Gcov:: gcov: a GCC test coverage program.
* Trouble:: If you have trouble using GCC.
* Bugs:: How, why and where to report bugs.
@include invoke.texi
@include extend.texi
@include objc.texi
+@include compat.texi
@include gcov.texi
@include trouble.texi
@include bugreport.texi
@var{suffix}) are prepended (appended) before further transformations
can happen with a special transformation script @var{pattern}.
-As currently implemented, this options only take effect for native
+As currently implemented, these options only take effect for native
builds; cross compiler binaries' names are not transformed even when a
-transformation is explicitly asked for by one of this options.
+transformation is explicitly asked for by one of these options.
For native builds, some of the installed programs are also installed
with the target alias in front of their name, as in
contain any of the system's standard header files. If it did contain
them, certain programs would be miscompiled (including GNU Emacs, on
certain targets), because this would override and nullify the header
-file corrections made by the @code{fixincludes} script.
+file corrections made by the @command{fixincludes} script.
Indications are that people who use this option use it based on mistaken
ideas of what it is for. People use it as if it specified where to
assembler installed on your system, you may want to use this option in
connection with @option{--with-as=@var{pathname}}.
-The systems where it makes a difference whether you use the GNU assembler are
-@samp{hppa1.0-@var{any}-@var{any}}, @samp{hppa1.1-@var{any}-@var{any}},
-@samp{i386-@var{any}-sysv}, @samp{i386-@var{any}-isc},
-@samp{i860-@var{any}-bsd}, @samp{m68k-bull-sysv},
-@samp{m68k-hp-hpux}, @samp{m68k-sony-bsd},
-@samp{m68k-altos-sysv}, @samp{m68000-hp-hpux},
-@samp{m68000-att-sysv}, @samp{@var{any}-lynx-lynxos},
-and @samp{mips-@var{any}}.
-On any other system, @option{--with-gnu-as} has no effect.
+The following systems are the only ones where it makes a difference
+whether you use the GNU assembler. On any other system,
+@option{--with-gnu-as} has no effect.
+
+@itemize bullet
+@item @samp{hppa1.0-@var{any}-@var{any}}
+@item @samp{hppa1.1-@var{any}-@var{any}}
+@item @samp{i386-@var{any}-sysv}
+@item @samp{i386-@var{any}-isc}
+@item @samp{i860-@var{any}-bsd}
+@item @samp{m68k-bull-sysv}
+@item @samp{m68k-hp-hpux}
+@item @samp{m68k-sony-bsd}
+@item @samp{m68k-altos-sysv}
+@item @samp{m68000-hp-hpux}
+@item @samp{m68000-att-sysv}
+@item @samp{@var{any}-lynx-lynxos}
+@item @samp{mips-@var{any}}
+@end itemize
On the systems listed above (except for the HP-PA, for ISC on the
386, and for @samp{mips-sgi-irix5.*}), if you use the GNU assembler,
@item --with-headers=@var{dir}
Specifies a directory
which has target include files.
-@emph{This options is required} when building a cross
+@emph{This option is required} when building a cross
compiler, if @file{@var{prefix}/@var{target}/sys-include} doesn't pre-exist.
These include files will be copied into the @file{gcc} install directory.
-Fixincludes will be run on these files to make them compatible with
+@command{fixincludes} will be run on these files to make them compatible with
GCC.
@item --with-libs=``@var{dir1} @var{dir2} @dots{} @var{dirN}''
Specifies a list of directories which contain the target runtime
directory. Make sure you have done all the necessary preparations.
If you build GCC on a BSD system using a directory stored in an old System
-V file system, problems may occur in running @code{fixincludes} if the
+V file system, problems may occur in running @command{fixincludes} if the
System V file system doesn't support symbolic links. These problems
result in a failure to fix the declaration of @code{size_t} in
@file{sys/types.h}. If you find that @code{size_t} is a signed type and
stage2 of the 3-stage bootstrap of the compiler are deleted as
soon as they are no longer needed.
-
If you want to save additional space during the bootstrap and in
the final installation as well, you can build the compiler binaries
-without debugging information with @samp{make CFLAGS='-O' LIBCFLAGS='-g
--O2' LIBCXXFLAGS='-g -O2 -fno-implicit-templates' bootstrap}. This will save
+without debugging information as in the following example. This will save
roughly 40% of disk space both for the bootstrap and the final installation.
(Libraries will still contain debugging information.)
+@example
+ make CFLAGS='-O' LIBCFLAGS='-g -O2' \
+ LIBCXXFLAGS='-g -O2 -fno-implicit-templates' bootstrap
+@end example
+
If you wish to use non-default GCC flags when compiling the stage2 and
stage3 compilers, set @code{BOOT_CFLAGS} on the command line when doing
@samp{make bootstrap}. Non-default optimization flags are less well
Additional build tools (such as @command{gnatmake}) or a working GNAT
run-time library installation are usually @emph{not} required. However,
-if you want to boostrap the compiler using a minimal version of GNAT,
+if you want to bootstrap the compiler using a minimal version of GNAT,
you have to issue the following commands before invoking @samp{make
-boostrap} (this assumes that you start with an unmodified and consistent
+bootstrap} (this assumes that you start with an unmodified and consistent
source distribution):
@example
info format in @file{@var{infodir}} (normally @file{@var{prefix}/info}).
If you built a released version of GCC using @samp{make bootstrap} then please
-quickly review the build status page for
-@uref{http://gcc.gnu.org/gcc-3.1/buildstat.html,,3.1},
-@uref{http://gcc.gnu.org/gcc-3.0/buildstat.html,,3.0}, or
-@uref{http://gcc.gnu.org/gcc-2.95/buildstat.html,,2.95}.
+quickly review the build status page for your release, available from
+@uref{http://gcc.gnu.org/buildstat.html}.
If your system is not listed for the version of GCC that you built,
send a note to
@email{gcc@@gcc.gnu.org} indicating
simplest way to do so is by providing @option{--with-as} and
@option{--with-ld} to @file{configure}, e.g.@:
-@samp{configure --with-as=/opt/ctl/bin/cam --with-ld=/opt/ctl/bin/cld
---enable-languages=c}
+@example
+ configure --with-as=/opt/ctl/bin/cam --with-ld=/opt/ctl/bin/cld \
+ --enable-languages=c
+@end example
The comparison test during @samp{make bootstrap} fails on Unicos/Mk
because the assembler inserts timestamps into object files. You should
In principle, @option{--enable-threads} is now compatible with
@option{--enable-libgcj} on FreeBSD@. However, it has only been built
-and tested on i386-*-freebsd4.5 and alpha-*-freebsd5.0. The static
+and tested on @samp{i386-*-freebsd4.5} and @samp{alpha-*-freebsd5.0}.
+The static
library may be incorrectly built (symbols are missing at link time).
There is a rare timing-based startup hang (probably involves an
assupmtion about the thread library). Multi-threaded boehm-gc (required for
libjava) exposes severe threaded signal-handling bugs on FreeBSD before
4.5-RELEASE. The alpha port may not fully bootstrap without some manual
-intervention: gcjh will crash with a floating-point exception while
+intervention: @command{gcjh} will crash with a floating-point exception while
generating @file{java/lang/Double.h} (just copy the version built on
-i386-*-freebsd* and rerun the top-level gmake with no arguments and it
+@samp{i386-*-freebsd*} and rerun the top-level @command{gmake} with no
+arguments and it
should properly complete the bootstrap). Other CPU architectures
supported by FreeBSD will require additional configuration tuning in, at
the very least, both boehm-gc and libffi.
You must use GNU binutils 2.11 or above with the 32-bit port. Thread
support is not currently implemented, so @option{--enable-threads} does
-not work. See @uref{http://gcc.gnu.org/ml/gcc-prs/2002-01/msg00551.html}
-and @uref{http://gcc.gnu.org/ml/gcc-bugs/2002-01/msg00663.html}.
+not work. See:
+
+@itemize
+@item @uref{http://gcc.gnu.org/ml/gcc-prs/2002-01/msg00551.html}
+@item @uref{http://gcc.gnu.org/ml/gcc-bugs/2002-01/msg00663.html}.
+@end itemize
+
GCC 2.95.x is not supported under HP-UX 11 and cannot be used to
compile GCC 3.0 and up. Refer to @uref{binaries.html,,binaries} for
information about obtaining precompiled GCC binaries for HP-UX.
building a cross compiler. The easiest way to do this is with a configure
command like this:
-@samp{CC=/udk/usr/ccs/bin/cc @var{/your/path/to}/gcc/configure
---host=i686-pc-udk --target=i686-pc-udk --program-prefix=udk-}
+@example
+ CC=/udk/usr/ccs/bin/cc @var{/your/path/to}/gcc/configure \
+ --host=i686-pc-udk --target=i686-pc-udk --program-prefix=udk-
+@end example
@emph{You should substitute @samp{i686} in the above command with the appropriate
processor for your host.}
registration required).
Versions of the assembler prior to ``cctools-364'' cannot handle the
-4-argument form of rlwinm and related mask-using instructions. Darwin
+4-argument form of @code{rlwinm} and related mask-using instructions. Darwin
1.3 (Mac OS X 10.0) uses cctools-353 for instance. To get cctools-364,
check out @file{cctools} with tag @samp{Apple-364}, build it, and
install the assembler as @file{usr/bin/as}. See
Sun @command{as} 4.x is broken in that it cannot cope with long symbol names.
A typical error message might look similar to the following:
-@samp{/usr/ccs/bin/as: "/var/tmp/ccMsw135.s", line 11041:
-error: can't compute value of an expression involving an external symbol.}
+@smallexample
+/usr/ccs/bin/as: "/var/tmp/ccMsw135.s", line 11041: error:
+ can't compute value of an expression involving an external symbol.
+@end smallexample
This is Sun bug 4237974. This is fixed with patch 108908-02 for Solaris
2.6 and has been fixed in later (5.x) versions of the assembler,
-fallow-single-precision -fcond-mismatch @gol
-fsigned-bitfields -fsigned-char @gol
-funsigned-bitfields -funsigned-char @gol
--fwritable-strings -fshort-wchar}
+-fwritable-strings}
@item C++ Language Options
@xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
-frerun-cse-after-loop -frerun-loop-opt @gol
-fschedule-insns -fschedule-insns2 @gol
-fsingle-precision-constant -fssa -fssa-ccp -fssa-dce @gol
--fstrength-reduce -fstrict-aliasing -fthread-jumps -ftrapv @gol
--funroll-all-loops -funroll-loops @gol
+-fstrength-reduce -fstrict-aliasing -fthread-jumps @gol
+-ftrapv -funroll-all-loops -funroll-loops @gol
--param @var{name}=@var{value}
-O -O0 -O1 -O2 -O3 -Os}
-mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
-mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
-mcall-aix -mcall-sysv -mcall-netbsd @gol
--maix-struct-return -msvr4-struct-return
+-maix-struct-return -msvr4-struct-return @gol
-mabi=altivec -mabi=no-altivec @gol
-mprototype -mno-prototype @gol
-msim -mmvme -mads -myellowknife -memb -msdata @gol
@emph{D30V Options}
@gccoptlist{
--mextmem -mextmemory -monchip -mno-asm-optimize -masm-optimize @gol
--mbranch-cost=@var{n} -mcond-exec=@var{n}}
+-mextmem -mextmemory -monchip -mno-asm-optimize @gol
+-masm-optimize -mbranch-cost=@var{n} -mcond-exec=@var{n}}
@emph{S/390 and zSeries Options}
@gccoptlist{
-fno-common -fno-ident -fno-gnu-linker @gol
-fpcc-struct-return -fpic -fPIC @gol
-freg-struct-return -fshared-data -fshort-enums @gol
--fshort-double -fvolatile @gol
+-fshort-double -fshort-wchar -fvolatile @gol
-fvolatile-global -fvolatile-static @gol
-fverbose-asm -fpack-struct -fstack-check @gol
-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
to use single precision operations when the operands are single
precision, use this option. This option has no effect when compiling
with ISO or GNU C conventions (the default).
-
-@item -fshort-wchar
-@opindex fshort-wchar
-Override the underlying type for @samp{wchar_t} to be @samp{short
-unsigned int} instead of the default for the target. This option is
-useful for building programs to run under WINE@.
@end table
@node C++ Dialect Options
Return ``short'' @code{struct} and @code{union} values in memory like
longer ones, rather than in registers. This convention is less
efficient, but it has the advantage of allowing intercallability between
-GCC-compiled files and files compiled with other compilers.
+GCC-compiled files and files compiled with other compilers, particularly
+the Portable C Compiler (pcc).
The precise convention for returning structures in memory depends
on the target configuration macros.
Short structures and unions are those whose size and alignment match
that of some integer type.
+@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
+switch is not binary compatible with code compiled with the
+@option{-freg-struct-return} switch.
+Use it to conform to a non-default application binary interface.
+
@item -freg-struct-return
@opindex freg-struct-return
Return @code{struct} and @code{union} values in registers when possible.
the principal compiler. In those cases, we can choose the standard, and
we chose the more efficient register return alternative.
+@strong{Warning:} code compiled with the @option{-freg-struct-return}
+switch is not binary compatible with code compiled with the
+@option{-fpcc-struct-return} switch.
+Use it to conform to a non-default application binary interface.
+
@item -fshort-enums
@opindex fshort-enums
Allocate to an @code{enum} type only as many bytes as it needs for the
declared range of possible values. Specifically, the @code{enum} type
will be equivalent to the smallest integer type which has enough room.
+@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Use it to conform to a non-default application binary interface.
+
@item -fshort-double
@opindex fshort-double
Use the same size for @code{double} as for @code{float}.
+@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Use it to conform to a non-default application binary interface.
+
+@item -fshort-wchar
+@opindex fshort-wchar
+Override the underlying type for @samp{wchar_t} to be @samp{short
+unsigned int} instead of the default for the target. This option is
+useful for building programs to run under WINE@.
+
+@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Use it to conform to a non-default application binary interface.
+
@item -fshared-data
@opindex fshared-data
Requests that the data and non-@code{const} variables of this
@item -fpack-struct
@opindex fpack-struct
-Pack all structure members together without holes. Usually you would
-not want to use this option, since it makes the code suboptimal, and
-the offsets of structure members won't agree with system libraries.
+Pack all structure members together without holes.
+
+@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Additionally, it makes the code suboptimial.
+Use it to conform to a non-default application binary interface.
@item -finstrument-functions
@opindex finstrument-functions
change the way C symbols are represented in the object file. One use
is to help link with legacy assembly code.
-Be warned that you should know what you are doing when invoking this
-option, and that not all targets provide complete support for it.
+@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
+generate code that is not binary compatible with code generated without that
+switch. Use it to conform to a non-default application binary interface.
+Not all targets provide complete support for this switch.
@end table
@c man end
of the @file{.exp} file, optionally followed by (for some tests) an equals
and a file wildcard, like:
-@example
+@smallexample
make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
-@end example
+@end smallexample
Note that running the testsuite may require additional tools be
installed, such as TCL or dejagnu.
either wrap around or use saturating addition depending on the value
of a special control register:
-@example
+@smallexample
(parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
(reg:SI 4)] 0))
(use (reg:SI 1))])
-@end example
+@end smallexample
@noindent
Here is an example of its use:
-@example
+@smallexample
(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
(reg:SI 48))))
-@end example
+@end smallexample
This says to modify pseudo register 42 by adding the contents of pseudo
register 48 to it, after the use of what ever 42 points to.
There is no formal written standard for Objective-C@. The most
authoritative manual is ``Object-Oriented Programming and the
-Objective-C Language'', available at a number of web sites;
-@uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/} has a
-recent version, while @uref{http://www.toodarkpark.org/computers/objc/}
-is an older example. @uref{http://www.gnustep.org} includes useful
-information as well.
+Objective-C Language'', available at a number of web sites
+
+@itemize
+@item
+@uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/}
+is a recent version
+@item
+@uref{http://www.toodarkpark.org/computers/objc/}
+is an older example
+@item
+@uref{http://www.gnustep.org}
+has additional useful information
+@end itemize
@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm,
GNAT Reference Manual}, for information on standard
multilibs. Example nonsensical definition, where @code{-malt-abi},
@code{-EB}, and @code{-mspoo} cause different multilibs to be chosen:
-@example
+@smallexample
#define TARGET_OPTION_TRANSLATE_TABLE \
@{ "-fast", "-march=fast-foo -malt-abi -I/usr/fast-foo" @}, \
@{ "-compat", "-EB -malign=4 -mspoo" @}
-@end example
+@end smallexample
@findex CPP_SPEC
@item CPP_SPEC
@itemize @bullet
@item
-G++ does not do name mangling in the same way as other C++
-compilers. This means that object files compiled with one compiler
-cannot be used with another.
+On many platforms, GCC supports a different ABI for C++ than do other
+compilers, so the object files compiled by GCC cannot be used with object
+files generated by another C++ compiler.
-This effect is intentional, to protect you from more subtle problems.
+An area where the difference is most apparent is name mangling. The use
+of different name mangling is intentional, to protect you from more subtle
+problems.
Compilers differ as to many internal details of C++ implementation,
including: how class instances are laid out, how multiple inheritance is
implemented, and how virtual function calls are handled. If the name
projects / thirdparty / gcc.git / commitdiff
