@c -item/itemx, text after all (sub/sub)section titles, etc..
@c -consider putting the lists of options on pp 17--> etc in columns or
@c some such.
-@c -spellcheck
-@c -continuity of phrasing; ie, bit-field vs bitfield in rtl.texi
@c -overfulls. do a search for "mew" in the files, and you will see
@c overfulls that i noted but could not deal with.
@c -have to add text: beginning of chapter 8
@c
@c anything else? --mew 10feb93
+@c For consistency, use the following:
+@c - "back end" as a noun, "back-end" as an adjective.
+@c - "bit-field" not "bitfield" or "bit field" (following the C and C++
+@c standards).
+@c - "built-in" as an adjective ("built-in function"), or sometimes
+@c "built in", not "builtin" (which isn't a word).
+@c - "front end" as a noun, "front-end" as an adjective.
+@c - "GCC" for the GNU Compiler Collection, both generally
+@c and as the GNU C Compiler in the context of compiling C;
+@c "G++" for the C++ compiler; "gcc" and "g++" (lowercase),
+@c marked up with @command, for the commands for compilation when the
+@c emphasis is on those; "GNU C" and "GNU C++" for language dialects;
+@c and try to avoid the older term "GNU CC".
+
@macro gcctabopt{body}
@code{\body\}
@end macro
@settitle Porting the GNU Compiler Collection
@end ifclear
+@c Create a separate index for command line options.
+@defcodeindex op
+@c Merge the standard indexes into a single one.
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@c \global\normaloffset =0.75in
@c @end tex
+@c Change the font used for @def... commands, since the default
+@c proportional one used is bad for names starting __.
+@tex
+\global\setfont\defbf\ttbshape{10}{\magstep1}
+@end tex
+
@ifnottex
@dircategory Programming
@direntry
@sp 2
@center Richard M. Stallman
@sp 3
-@center Last updated 9 May 2001
+@center Last updated 22 June 2001
@sp 1
@c The version number appears five times more in this file.
* Installation:: How to configure, compile and install GCC.
* C Extensions:: GNU extensions to the C language family.
* C++ Extensions:: GNU extensions to the C++ language.
-* Objective C:: GNU Objective-C runtime features.
+* Objective-C:: GNU Objective-C runtime features.
* Gcov:: gcov: a GCC test coverage program.
* Trouble:: If you have trouble installing GCC.
* Bugs:: How, why and where to report bugs.
* Portability:: Goals of GCC's portability features.
* Interface:: Function-call interface of GCC output.
* Passes:: Order of passes, what they do, and what each file is for.
-* Trees:: The source representation used by the C and C++ front-ends.
+* Trees:: The source representation used by the C and C++ front ends.
* RTL:: The intermediate representation that most passes work on.
* Machine Desc:: How to write machine description instruction patterns.
-* Target Macros:: How to write the machine description C macros.
+* Target Macros:: How to write the machine description C macros and functions.
* Config:: Writing the @file{xm-@var{machine}.h} file.
* Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
@end ifset
* GNU Free Documentation License:: How you can copy and share this manual.
* Contributors:: People who have contributed to GCC.
+* Option Index:: Index to command line options.
* Index:: Index of concepts and symbol names.
@end menu
@ifset USING
@node G++ and GCC
-@chapter Compile C, C++, Objective C, Fortran, Java or CHILL
+@chapter Compile C, C++, Objective-C, Fortran, Java or CHILL
-@cindex Objective C
-Several versions of the compiler (C, C++, Objective C, Fortran, Java
+@cindex Objective-C
+@cindex Fortran
+@cindex Java
+@cindex CHILL
+Several versions of the compiler (C, C++, Objective-C, Fortran, Java
and CHILL) are integrated; this is why we use the name
-``GNU Compiler Collection''. GCC can compile programs written in any of these
-languages. The Fortran, CHILL, and Java compilers are described in
+``GNU Compiler Collection''. GCC can compile programs written in any of these
+languages. The Fortran, CHILL, and Java compilers are described in
separate manuals.
@cindex GCC
affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
Front ends for other languages, such as Ada 95 and Pascal exist but
-have not yet been integrated into GCC. These front-ends, like that for C++,
+have not yet been integrated into GCC@. These front ends, like that for C++,
are built in subdirectories of GCC and link to it. The result is an
integrated compiler that can compile programs written in C, C++,
-Objective C, or any of the languages for which you have installed front
+Objective-C, or any of the languages for which you have installed front
ends.
In this manual, we only discuss the options for the C, Objective-C, and
give you comprehensive C++ source-level editing capabilities
(@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
-@c FIXME! Someone who knows something about Objective C ought to put in
+@c FIXME! Someone who knows something about Objective-C ought to put in
@c a paragraph or two about it here, and move the index entry down when
@c there is more to point to than the general mention in the 1st par.
GCC supports three versions of the C standard, although support for
the most recent version is not yet complete.
+@opindex std
+@opindex ansi
+@opindex pedantic
+@opindex pedantic-errors
The original ANSI C standard (X3.159-1989) was ratified in 1989 and
published in 1990. This standard was ratified as an ISO standard
(ISO/IEC 9899:1990) later in 1990. There were no technical
occasionally as @dfn{C90}, from the dates of ratification. The ANSI
standard, but not the ISO standard, also came with a Rationale
document. To select this standard in GCC, use one of the options
-@samp{-ansi}, @samp{-std=c89} or @samp{-std=iso9899:1990}; to obtain
+@option{-ansi}, @option{-std=c89} or @option{-std=iso9899:1990}; to obtain
all the diagnostics required by the standard, you should also specify
-@samp{-pedantic} (or @samp{-pedantic-errors} if you want them to be
+@option{-pedantic} (or @option{-pedantic-errors} if you want them to be
errors rather than warnings). @xref{C Dialect Options,,Options
Controlling C Dialect}.
but otherwise concerned the library. This amendment is commonly known
as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
@dfn{C95}. To select this standard in GCC, use the option
-@samp{-std=iso9899:199409} (with, as for other standard versions,
-@samp{-pedantic} to receive all required diagnostics).
+@option{-std=iso9899:199409} (with, as for other standard versions,
+@option{-pedantic} to receive all required diagnostics).
A new edition of the ISO C standard was published in 1999 as ISO/IEC
9899:1999, and is commonly known as @dfn{C99}. GCC has incomplete
support for this standard version; see
@uref{http://gcc.gnu.org/c99status.html} for details. To select this
-standard, use @samp{-std=c99} or @samp{-std=iso9899:1999}. (While in
+standard, use @option{-std=c99} or @option{-std=iso9899:1999}. (While in
development, drafts of this standard version were referred to as
@dfn{C9X}.)
+@opindex traditional
GCC also has some limited support for traditional (pre-ISO) C with the
-@samp{-traditional} option. This support may be of use for compiling
+@option{-traditional} option. This support may be of use for compiling
some very old programs that have not been updated to ISO C, but should
not be used for new programs. It will not work with some modern C
libraries such as the GNU C library.
By default, GCC provides some extensions to the C language that on
rare occasions conflict with the C standard. @xref{C
Extensions,,Extensions to the C Language Family}. Use of the
-@samp{-std} options listed above will disable these extensions where
+@option{-std} options listed above will disable these extensions where
they conflict with the C standard version selected. You may also
select an extended version of the C language explicitly with
-@samp{-std=gnu89} (for C89 with GNU extensions) or @samp{-std=gnu99}
+@option{-std=gnu89} (for C89 with GNU extensions) or @option{-std=gnu99}
(for C99 with GNU extensions). The default, if no C language dialect
-options are given, is @samp{-std=gnu89}; this will change to
-@samp{-std=gnu99} in some future release when the C99 support is
+options are given, is @option{-std=gnu89}; this will change to
+@option{-std=gnu99} in some future release when the C99 support is
complete. Some features that are part of the C99 standard are
accepted as extensions in C89 mode.
program using the facilities of an operating system would normally be
in a hosted implementation.
-GNU CC aims towards being usable as a conforming freestanding
+@opindex ffreestanding
+GCC aims towards being usable as a conforming freestanding
implementation, or as the compiler for a conforming hosted
implementation. By default, it will act as the compiler for a hosted
implementation, defining @code{__STDC_HOSTED__} as @code{1} and
presuming that when the names of ISO C functions are used, they have
the semantics defined in the standard. To make it act as a conforming
freestanding implementation for a freestanding environment, use the
-option @samp{-ffreestanding}; it will then define
+option @option{-ffreestanding}; it will then define
@code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
meanings of function names from the standard library. To build an OS
kernel, you may well still need to make your own arrangements for
linking and startup. @xref{C Dialect Options,,Options Controlling C
Dialect}.
-GNU CC does not provide the library facilities required only of hosted
+GCC does not provide the library facilities required only of hosted
implementations, nor yet all the facilities required by C99 of
freestanding implementations; to use the facilities of a hosted
environment, you will need to find them elsewhere (for example, in the
@c FIXME: details of C++ standard.
-There is no formal written standard for Objective-C. The most
+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
+@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.
@xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
-Fortran}, for details of the Fortran language supported by GCC.
+Fortran}, for details of the Fortran language supported by GCC@.
@xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj},
for details of compatibility between @code{gcj} and the Java Platform.
@cindex installation trouble
@cindex known causes of trouble
-This section describes known problems that affect users of GCC. Most
+This section describes known problems that affect users of GCC@. Most
of these are not GCC bugs per se---if they were, we would fix them.
But the result for a user may be like the result of a bug.
@menu
* Actual Bugs:: Bugs we will fix later.
-* Installation Problems:: Problems that manifest when you install GCC.
* Cross-Compiler Problems:: Common problems of cross compiling with GCC.
* Interoperation:: Problems using GCC with other compilers,
and with certain linkers, assemblers and debuggers.
* External Bugs:: Problems compiling certain programs.
* Incompatibilities:: GCC is incompatible with traditional C.
-* Fixed Headers:: GNU C uses corrected versions of system header files.
+* Fixed Headers:: GCC uses corrected versions of system header files.
This is necessary, but doesn't always work smoothly.
-* Standard Libraries:: GNU C uses the system C library, which might not be
+* Standard Libraries:: GCC uses the system C library, which might not be
compliant with the ISO C standard.
* Disappointments:: Regrettable things we can't change, but not quite bugs.
* C++ Misunderstandings:: Common misunderstandings with GNU C++.
prototypes.
@item
-When @samp{-pedantic-errors} is specified, GCC will incorrectly give
+@opindex pedantic-errors
+When @option{-pedantic-errors} is specified, GCC will incorrectly give
an error message when a function name is specified in an expression
involving the comma operator.
@end itemize
-@node Installation Problems
-@section Installation Problems
-
-This is a list of problems (and some apparent problems which don't
-really mean anything is wrong) that show up during installation of GNU
-CC.
-
-@itemize @bullet
-@item
-On certain systems, defining certain environment variables such as
-@code{CC} can interfere with the functioning of @code{make}.
-
-@item
-If you encounter seemingly strange errors when trying to build the
-compiler in a directory other than the source directory, it could be
-because you have previously configured the compiler in the source
-directory. Make sure you have done all the necessary preparations.
-@xref{Other Dir}.
-
-@item
-If you build GCC on a BSD system using a directory stored in a System
-V file system, problems may occur in running @code{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
-that type mismatches occur, this could be the cause.
-
-The solution is not to use such a directory for building GCC.
-
-@item
-Some commands executed when making the compiler may fail (return a
-non-zero status) and be ignored by @code{make}. These failures, which
-are often due to files that were not found, are expected, and can safely
-be ignored.
-
-@item
-It is normal to have warnings in compiling certain files about
-unreachable code and about enumeration type clashes. These files' names
-begin with @samp{insn-}. Also, @file{real.c} may get some warnings that
-you can ignore.
-
-@item
-Sometimes @code{make} recompiles parts of the compiler when installing
-the compiler. In one case, this was traced down to a bug in
-@code{make}. Either ignore the problem or switch to GNU Make.
-
-@item
-On GNU/Linux SLS 1.01, there is a problem with @file{libc.a}: it does not
-contain the obstack functions. However, GCC assumes that the obstack
-functions are in @file{libc.a} when it is the GNU C library. To work
-around this problem, change the @code{__GNU_LIBRARY__} conditional
-around line 31 to @samp{#if 1}.
-
-@item
-On SCO systems, when compiling GCC with the system's compiler,
-do not use @samp{-O}. Some versions of the system's compiler miscompile
-GCC with @samp{-O}.
-
-@cindex @code{genflags}, crash on Sun 4
-@item
-Sometimes on a Sun 4 you may observe a crash in the program
-@code{genflags} or @code{genoutput} while building GCC. This is said to
-be due to a bug in @code{sh}. You can probably get around it by running
-@code{genflags} or @code{genoutput} manually and then retrying the
-@code{make}.
-
-@item
-On Solaris 2, executables of GCC version 2.0.2 are commonly
-available, but they have a bug that shows up when compiling current
-versions of GCC: undefined symbol errors occur during assembly if you
-use @samp{-g}.
-
-The solution is to compile the current version of GCC without
-@samp{-g}. That makes a working compiler which you can use to recompile
-with @samp{-g}.
-
-@item
-Solaris 2 comes with a number of optional OS packages. Some of these
-packages are needed to use GCC fully. If you did not install all
-optional packages when installing Solaris, you will need to verify that
-the packages that GCC needs are installed.
-
-To check whether an optional package is installed, use
-the @code{pkginfo} command. To add an optional package, use the
-@code{pkgadd} command. For further details, see the Solaris
-documentation.
-
-For Solaris 2.0 and 2.1, GCC needs six packages: @samp{SUNWarc},
-@samp{SUNWbtool}, @samp{SUNWesu}, @samp{SUNWhea}, @samp{SUNWlibm}, and
-@samp{SUNWtoo}.
-
-For Solaris 2.2, GCC needs an additional seventh package: @samp{SUNWsprot}.
-
-@item
-On Solaris 2, trying to use the linker and other tools in
-@file{/usr/ucb} to install GCC has been observed to cause trouble.
-For example, the linker may hang indefinitely. The fix is to remove
-@file{/usr/ucb} from your @code{PATH}.
-
-@item
-If you use the 1.31 version of the MIPS assembler (such as was shipped
-with Ultrix 3.1), you will need to use the -fno-delayed-branch switch
-when optimizing floating point code. Otherwise, the assembler will
-complain when the GCC compiler fills a branch delay slot with a
-floating point instruction, such as @code{add.d}.
-
-@item
-If on a MIPS system you get an error message saying ``does not have gp
-sections for all it's [sic] sectons [sic]'', don't worry about it. This
-happens whenever you use GAS with the MIPS linker, but there is not
-really anything wrong, and it is okay to use the output file. You can
-stop such warnings by installing the GNU linker.
-
-It would be nice to extend GAS to produce the gp tables, but they are
-optional, and there should not be a warning about their absence.
-
-@item
-Users have reported some problems with version 2.0 of the MIPS
-compiler tools that were shipped with Ultrix 4.1. Version 2.10
-which came with Ultrix 4.2 seems to work fine.
-
-Users have also reported some problems with version 2.20 of the
-MIPS compiler tools that were shipped with RISC/os 4.x. The earlier
-version 2.11 seems to work fine.
-
-@item
-Some versions of the MIPS linker will issue an assertion failure
-when linking code that uses @code{alloca} against shared
-libraries on RISC-OS 5.0, and DEC's OSF/1 systems. This is a bug
-in the linker, that is supposed to be fixed in future revisions.
-To protect against this, GCC passes @samp{-non_shared} to the
-linker unless you pass an explicit @samp{-shared} or
-@samp{-call_shared} switch.
-
-@item
-On System V release 3, you may get this error message
-while linking:
-
-@smallexample
-ld fatal: failed to write symbol name @var{something}
- in strings table for file @var{whatever}
-@end smallexample
-
-This probably indicates that the disk is full or your ULIMIT won't allow
-the file to be as large as it needs to be.
-
-This problem can also result because the kernel parameter @code{MAXUMEM}
-is too small. If so, you must regenerate the kernel and make the value
-much larger. The default value is reported to be 1024; a value of 32768
-is said to work. Smaller values may also work.
-
-@item
-On System V, if you get an error like this,
-
-@example
-/usr/local/lib/bison.simple: In function `yyparse':
-/usr/local/lib/bison.simple:625: virtual memory exhausted
-@end example
-
-@noindent
-that too indicates a problem with disk space, ULIMIT, or @code{MAXUMEM}.
-
-@item
-Current GCC versions probably do not work on version 2 of the NeXT
-operating system.
-
-@item
-On NeXTStep 3.0, the Objective C compiler does not work, due,
-apparently, to a kernel bug that it happens to trigger. This problem
-does not happen on 3.1.
-
-@item
-On the Tower models 4@var{n}0 and 6@var{n}0, by default a process is not
-allowed to have more than one megabyte of memory. GCC cannot compile
-itself (or many other programs) with @samp{-O} in that much memory.
-
-To solve this problem, reconfigure the kernel adding the following line
-to the configuration file:
-
-@smallexample
-MAXUMEM = 4096
-@end smallexample
-
-@item
-On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a bug
-in the assembler that must be fixed before GCC can be built. This
-bug manifests itself during the first stage of compilation, while
-building @file{libgcc2.a}:
-
-@smallexample
-_floatdisf
-cc1: warning: `-g' option not supported on this version of GCC
-cc1: warning: `-g1' option not supported on this version of GCC
-./xgcc: Internal compiler error: program as got fatal signal 11
-@end smallexample
-
-A patched version of the assembler is available as the file
-@uref{ftp://altdorf.ai.mit.edu/archive/cph/hpux-8.0-assembler}. If you
-have HP software support, the patch can also be obtained directly from
-HP, as described in the following note:
-
-@quotation
-This is the patched assembler, to patch SR#1653-010439, where the
-assembler aborts on floating point constants.
-
-The bug is not really in the assembler, but in the shared library
-version of the function ``cvtnum(3c)''. The bug on ``cvtnum(3c)'' is
-SR#4701-078451. Anyway, the attached assembler uses the archive
-library version of ``cvtnum(3c)'' and thus does not exhibit the bug.
-@end quotation
-
-This patch is also known as PHCO_4484.
-
-@item
-On HP-UX version 8.05, but not on 8.07 or more recent versions,
-the @code{fixproto} shell script triggers a bug in the system shell.
-If you encounter this problem, upgrade your operating system or
-use BASH (the GNU shell) to run @code{fixproto}.
-
-@item
-There may be similar problems on System V Release 3.1 on 386 systems.
-
-@item
-On the Intel Paragon (an i860 machine), if you are using operating
-system version 1.0, you will get warnings or errors about redefinition
-of @code{va_arg} when you build GCC.
-
-If this happens, then you need to link most programs with the library
-@file{iclib.a}. You must also modify @file{stdio.h} as follows: before
-the lines
-
-@example
-#if defined(__i860__) && !defined(_VA_LIST)
-#include <va_list.h>
-@end example
-
-@noindent
-insert the line
-
-@example
-#if __PGC__
-@end example
-
-@noindent
-and after the lines
-
-@example
-extern int vprintf(const char *, va_list );
-extern int vsprintf(char *, const char *, va_list );
-#endif
-@end example
-
-@noindent
-insert the line
-
-@example
-#endif /* __PGC__ */
-@end example
-
-These problems don't exist in operating system version 1.1.
-
-@item
-On the Altos 3068, programs compiled with GCC won't work unless you
-fix a kernel bug. This happens using system versions V.2.2 1.0gT1 and
-V.2.2 1.0e and perhaps later versions as well. See the file
-@file{README.ALTOS}.
-
-@item
-You will get several sorts of compilation and linking errors on the
-we32k if you don't follow the special instructions. @xref{Configurations}.
-
-@item
-A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto
-program to report an error of the form:
-
-@example
-./fixproto: sh internal 1K buffer overflow
-@end example
-
-To fix this, change the first line of the fixproto script to look like:
-
-@example
-#!/bin/ksh
-@end example
-@end itemize
-
@node Cross-Compiler Problems
@section Cross-Compiler Problems
@node Interoperation
@section Interoperation
-This section lists various difficulties encountered in using GNU C or
-GNU C++ together with other compilers or with the assemblers, linkers,
+This section lists various difficulties encountered in using GCC
+together with other compilers or with the assemblers, linkers,
libraries and debuggers on certain systems.
@itemize @bullet
@item
-Objective C does not work on the RS/6000.
+Objective-C does not work on the RS/6000.
@item
-GNU C++ does not do name mangling in the same way as other C++
+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.
@item
@cindex DBX
DBX rejects some files produced by GCC, though it accepts similar
-constructs in output from PCC. Until someone can supply a coherent
+constructs in output from PCC@. Until someone can supply a coherent
description of what is valid DBX input and what is not, there is
nothing I can do about these problems. You are on your own.
@item
-The GNU assembler (GAS) does not support PIC. To generate PIC code, you
+The GNU assembler (GAS) does not support PIC@. To generate PIC code, you
must use some other assembler, such as @file{/bin/as}.
@item
be run.
@item
-Use of @samp{-I/usr/include} may cause trouble.
+Use of @option{-I/usr/include} may cause trouble.
Many systems come with header files that won't work with GCC unless
corrected by @code{fixincludes}. The corrected header files go in a new
directory; GCC searches this directory before @file{/usr/include}.
-If you use @samp{-I/usr/include}, this tells GCC to search
+If you use @option{-I/usr/include}, this tells GCC to search
@file{/usr/include} earlier on, before the corrected headers. The
result is that you get the uncorrected header files.
If you encounter this, you can work around the problem by declaring
variables @code{volatile} in the function that calls @code{vfork}, until
the problem goes away, or by not declaring them @code{register} and not
-using @samp{-O} for those source files.
+using @option{-O} for those source files.
@end ignore
@item
-On some SGI systems, when you use @samp{-lgl_s} as an option,
+On some SGI systems, when you use @option{-lgl_s} as an option,
it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
-Naturally, this does not happen when you use GCC.
+Naturally, this does not happen when you use GCC@.
You must specify all three options explicitly.
@item
@code{double *} to a function compiled with GCC, dereferencing the
pointer may cause a fatal signal.
-One way to solve this problem is to compile your entire program with GNU
-CC. Another solution is to modify the function that is compiled with
+One way to solve this problem is to compile your entire program with GCC@.
+Another solution is to modify the function that is compiled with
Sun CC to copy the argument into a local variable; local variables
are always properly aligned. A third solution is to modify the function
that uses the pointer to dereference it via the following function
@item
Sun forgot to include a static version of @file{libdl.a} with some
versions of SunOS (mainly 4.1). This results in undefined symbols when
-linking static binaries (that is, if you use @samp{-static}). If you
+linking static binaries (that is, if you use @option{-static}). If you
see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
when linking, compile and link against the file
@file{mit/util/misc/dlsym.c} from the MIT version of X windows.
@item
On the HP PA machine, ADB sometimes fails to work on functions compiled
-with GCC. Specifically, it fails to work on functions that use
+with GCC@. Specifically, it fails to work on functions that use
@code{alloca} or variable-size arrays. This is because GCC doesn't
generate HP-UX unwind descriptors for such functions. It may even be
impossible to generate them.
@item
-Debugging (@samp{-g}) is not supported on the HP PA machine, unless you use
+Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
the preliminary GNU tools (@pxref{Installation}).
@item
@item
The current version of the assembler (@file{/bin/as}) for the RS/6000
-has certain problems that prevent the @samp{-g} option in GCC from
-working. Note that @file{Makefile.in} uses @samp{-g} by default when
+has certain problems that prevent the @option{-g} option in GCC from
+working. Note that @file{Makefile.in} uses @option{-g} by default when
compiling @file{libgcc2.c}.
IBM has produced a fixed version of the assembler. The upgraded
@noindent
If the command exits normally, the assembler fix already is installed.
-If the assembler complains that "-u" is an unknown flag, you need to
+If the assembler complains that @option{-u} is an unknown flag, you need to
order the fix.
@item
will cause the linker to report an undefined symbol @code{foo}.
Although this behavior differs from most other systems, it is not a
bug because redefining an @code{extern} variable as @code{static}
-is undefined in ISO C.
+is undefined in ISO C@.
@item
AIX on the RS/6000 provides support (NLS) for environments outside of
the United States. Compilers and assemblers use NLS to support
locale-specific representations of various objects including
-floating-point numbers ("." vs "," for separating decimal fractions).
+floating-point numbers (@samp{.} vs @samp{,} for separating decimal fractions).
There have been problems reported where the library linked with GCC does
not produce the same floating-point formats that the assembler accepts.
-If you have this problem, set the LANG environment variable to "C" or
-"En_US".
+If you have this problem, set the @env{LANG} environment variable to
+@samp{C} or @samp{En_US}.
@item
-Even if you specify @samp{-fdollars-in-identifiers},
+@opindex fdollars-in-identifiers
+Even if you specify @option{-fdollars-in-identifiers},
you cannot successfully use @samp{$} in identifiers on the RS/6000 due
to a restriction in the IBM assembler. GAS supports these
identifiers.
@item
On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC
version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2
-by requesting PTF 421749 from IBM.
+by requesting PTF 421749 from IBM@.
@item
+@opindex mno-serialize-volatile
There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
occurs when the @samp{fldcr} instruction is used. GCC uses
@samp{fldcr} on the 88100 to serialize volatile memory references. Use
-the option @samp{-mno-serialize-volatile} if your version of the
+the option @option{-mno-serialize-volatile} if your version of the
assembler has this bug.
@item
@smallexample
#ifndef _SIZE_T
#define _SIZE_T
-@var{actual typedef here}
+@var{actual-typedef-here}
#endif
@end smallexample
@cindex RT PC
@cindex IBM RT PC
@item
+@opindex mhc-struct-return
On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
convention for structure and union returning. Use the option
-@samp{-mhc-struct-return} to tell GCC to use a convention compatible
+@option{-mhc-struct-return} to tell GCC to use a convention compatible
with it.
@cindex Vax calling convention
@cindex Ultrix calling convention
@item
+@opindex fcall-saved
On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
by function calls. However, the C compiler uses conventions compatible
with BSD Unix: registers 2 through 5 may be clobbered by function calls.
@end smallexample
The first specifies where to find the library @file{libgcc.a}
-specified with the @samp{-lgcc} option.
+specified with the @option{-lgcc} option.
-GCC does linking by invoking @code{ld}, just as @code{cc} does, and
+GCC does linking by invoking @command{ld}, just as @command{cc} does, and
there is no reason why it @emph{should} matter which compilation program
-you use to invoke @code{ld}. If someone tracks this problem down,
+you use to invoke @command{ld}. If someone tracks this problem down,
it can probably be fixed easily.
@item
on. If you think this may be happening to you, try using the GNU
assembler; GAS version 2.1 supports ECOFF on Irix.
-Or use the @samp{-noasmopt} option when you compile GCC with itself,
+@opindex noasmopt
+Or use the @option{-noasmopt} option when you compile GCC with itself,
and then again when you compile your program. (This is a temporary
kludge to turn off assembler optimization on Irix.) If this proves to
be what you need, edit the assembler spec in the file @file{specs} so
-that it unconditionally passes @samp{-O0} to the assembler, and never
-passes @samp{-O2} or @samp{-O3}.
+that it unconditionally passes @option{-O0} to the assembler, and never
+passes @option{-O2} or @option{-O3}.
@end itemize
@node External Bugs
Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
because of problems in DEC's versions of the X11 header files
@file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
-@samp{-I/usr/include/mit} to use the MIT versions of the header files,
-using the @samp{-traditional} switch to turn off ISO C, or fixing the
+@option{-I/usr/include/mit} to use the MIT versions of the header files,
+using the @option{-traditional} switch to turn off ISO C, or fixing the
header files by adding this:
@example
@node Incompatibilities
@section Incompatibilities of GCC
@cindex incompatibilities of GCC
+@opindex traditional
There are several noteworthy incompatibilities between GNU C and K&R
-(non-ISO) versions of C. The @samp{-traditional} option
+(non-ISO) versions of C@. The @option{-traditional} option
eliminates many of these incompatibilities, @emph{but not all}, by
-telling GNU C to behave like a K&R C compiler.
+telling GCC to behave like a K&R C compiler.
@itemize @bullet
@cindex string constants
This is because @code{sscanf} incorrectly tries to write into the string
constant. Likewise @code{fscanf} and @code{scanf}.
+@opindex fwritable-strings
The best solution to these problems is to change the program to use
@code{char}-array variables with initialization strings for these
purposes instead of string constants. But if this is not possible,
-you can use the @samp{-fwritable-strings} flag, which directs GCC
+you can use the @option{-fwritable-strings} flag, which directs GCC
to handle string constants the same way most C compilers do.
-@samp{-traditional} also has this effect, among others.
+@option{-traditional} also has this effect, among others.
@item
@code{-2147483648} is positive.
@noindent
will produce output @code{"a"} regardless of what the argument @var{a} is.
-The @samp{-traditional} option directs GCC to handle such cases
+The @option{-traditional} option directs GCC to handle such cases
(among others) in the old-fashioned (non-ISO) fashion.
@cindex @code{setjmp} incompatibilities
its first value is restored; otherwise, it keeps the last value stored
in it.
-If you use the @samp{-W} option with the @samp{-O} option, you will
+@opindex W
+If you use the @option{-W} option with the @option{-O} option, you will
get a warning when GCC thinks such a problem might be possible.
-The @samp{-traditional} option directs GNU C to put variables in
+The @option{-traditional} option directs GCC to put variables in
the stack by default, rather than in registers, in functions that
call @code{setjmp}. This results in the behavior found in
traditional C compilers.
@item
Programs that use preprocessing directives in the middle of macro
-arguments do not work with GCC. For example, a program like this
+arguments do not work with GCC@. For example, a program like this
will not work:
@example
@end example
ISO C does not permit such a construct. It would make sense to support
-it when @samp{-traditional} is used, but it is too much work to
+it when @option{-traditional} is used, but it is too much work to
implement.
@item
-K&R compilers allow comments to cross over an inclusion boundary (i.e.
-started in an include file and ended in the including file). I think
+K&R compilers allow comments to cross over an inclusion boundary
+(i.e.@: started in an include file and ended in the including file). I think
this would be quite ugly and can't imagine it could be needed.
@cindex external declaration scope
In some other C compilers, a @code{extern} declaration affects all the
rest of the file even if it happens within a block.
-The @samp{-traditional} option directs GNU C to treat all @code{extern}
+The @option{-traditional} option directs GCC to treat all @code{extern}
declarations as global, like traditional compilers.
@item
In ISO C, this is not allowed: @code{long} and other type modifiers
require an explicit @code{int}. Because this criterion is expressed
-by Bison grammar rules rather than C code, the @samp{-traditional}
+by Bison grammar rules rather than C code, the @option{-traditional}
flag cannot alter it.
@cindex typedef names as function parameters
difficulty described immediately above applies here too.
@item
-When in @samp{-traditional} mode, GCC allows the following erroneous
+When in @option{-traditional} mode, GCC allows the following erroneous
pair of declarations to appear together in a given scope:
@example
@item
GCC treats all characters of identifiers as significant, even when in
-@samp{-traditional} mode. According to K&R-1 (2.2), ``No more than the
+@option{-traditional} mode. According to K&R-1 (2.2), ``No more than the
first eight characters are significant, although more may be used.''.
Also according to K&R-1 (2.2), ``An identifier is a sequence of letters
and digits; the first character must be a letter. The underscore _
The best solution to such a problem is to put the text into an actual
C comment delimited by @samp{/*@dots{}*/}. However,
-@samp{-traditional} suppresses these error messages.
+@option{-traditional} suppresses these error messages.
@item
Many user programs contain the declaration @samp{long time ();}. In the
compatible convention when returning structures and unions in memory,
but still returns small structures and unions in registers.
+@opindex fpcc-struct-return
You can tell GCC to use a compatible convention for all structure and
-union returning with the option @samp{-fpcc-struct-return}.
+union returning with the option @option{-fpcc-struct-return}.
@cindex preprocessing tokens
@cindex preprocessing numbers
@item
-GNU C complains about program fragments such as @samp{0x74ae-0x4000}
+GCC complains about program fragments such as @samp{0x74ae-0x4000}
which appear to be two hexadecimal constants separated by the minus
operator. Actually, this string is a single @dfn{preprocessing token}.
-Each such token must correspond to one token in C. Since this does not,
-GNU C prints an error message. Although it may appear obvious that what
+Each such token must correspond to one token in C@. Since this does not,
+GCC prints an error message. Although it may appear obvious that what
is meant is an operator and two values, the ISO C standard specifically
requires that this be treated as erroneous.
@item
If you update the system's header files, such as by installing a new
system version, the fixed header files of GCC are not automatically
-updated. The easiest way to update them is to reinstall GCC. (If
+updated. The easiest way to update them is to reinstall GCC@. (If
you want to be clever, look in the makefile and you can find a
shortcut.)
@node Standard Libraries
@section Standard Libraries
+@opindex Wall
GCC by itself attempts to be a conforming freestanding implementation.
@xref{Standards,,Language Standards Supported by GCC}, for details of
what this means. Beyond the library facilities required of such an
implementation, the rest of the C library is supplied by the vendor of
the operating system. If that C library doesn't conform to the C
standards, then your programs might get warnings (especially when using
-@samp{-Wall}) that you don't expect.
+@option{-Wall}) that you don't expect.
For example, the @code{sprintf} function on SunOS 4.1.3 returns
@code{char *} while the C standard says that @code{sprintf} returns an
shown above.
@item
-Accesses to bitfields even in volatile objects works by accessing larger
+Accesses to bit-fields even in volatile objects works by accessing larger
objects, such as a byte or a word. You cannot rely on what size of
-object is accessed in order to read or write the bitfield; it may even
-vary for a given bitfield according to the precise usage.
+object is accessed in order to read or write the bit-field; it may even
+vary for a given bit-field according to the precise usage.
If you care about controlling the amount of memory that is accessed, use
-volatile but do not use bitfields.
+volatile but do not use bit-fields.
@item
GCC comes with shell scripts to fix certain known problems in system
Compiled code moves values between memory and floating point registers
at its convenience, and moving them into memory truncates them.
-You can partially avoid this problem by using the @samp{-ffloat-store}
+@opindex ffloat-store
+You can partially avoid this problem by using the @option{-ffloat-store}
option (@pxref{Optimize Options}).
@item
you expect it to, leaving a pointer to garbage. The most common place
where this problem crops up is in classes like string classes,
especially ones that define a conversion function to type @code{char *}
-or @code{const char *} -- which is one reason why the standard
+or @code{const char *}---which is one reason why the standard
@code{string} class requires you to call the @code{c_str} member
function. However, any class that returns a pointer to some internal
structure is potentially subject to this problem.
f ()
@{
const char *p = strfunc().c_str();
- ...
+ @dots{}
charfunc (p);
- ...
+ @dots{}
charfunc (p);
@}
@end example
@subsection Implicit Copy-Assignment for Virtual Bases
When a base class is virtual, only one subobject of the base class
-belongs to each full object. Also, the constructors and destructors are
-invoked only once, and called from the most-derived class. However, such
-objects behave unspecified when being assigned. For example:
+belongs to each full object. Also, the constructors and destructors are
+invoked only once, and called from the most-derived class. However, such
+objects behave unspecified when being assigned. For example:
@example
struct Base@{
@end example
The C++ standard specifies that @samp{Base::Base} is only called once
-when constructing or copy-constructing a Derived object. It is
+when constructing or copy-constructing a Derived object. It is
unspecified whether @samp{Base::operator=} is called more than once when
the implicit copy-assignment for Derived objects is invoked (as it is
inside @samp{func} in the example).
-g++ implements the "intuitive" algorithm for copy-assignment: assign all
-direct bases, then assign all members. In that algorithm, the virtual
-base subobject can be encountered many times. In the example, copying
+g++ implements the ``intuitive'' algorithm for copy-assignment: assign all
+direct bases, then assign all members. In that algorithm, the virtual
+base subobject can be encountered many times. In the example, copying
proceeds in the following order: @samp{val}, @samp{name} (via
@code{strdup}), @samp{bval}, and @samp{name} again.
If application code relies on copy-assignment, a user-defined
-copy-assignment operator removes any uncertainties. With such an
+copy-assignment operator removes any uncertainties. With such an
operator, the application can define whether and how the virtual base
subobject is assigned.
@node Protoize Caveats
-@section Caveats of using @code{protoize}
+@section Caveats of using @command{protoize}
-The conversion programs @code{protoize} and @code{unprotoize} can
+The conversion programs @command{protoize} and @command{unprotoize} can
sometimes change a source file in a way that won't work unless you
rearrange it.
@itemize @bullet
@item
-@code{protoize} can insert references to a type name or type tag before
+@command{protoize} can insert references to a type name or type tag before
the definition, or in a file where they are not defined.
If this happens, compiler error messages should show you where the new
references are, so fixing the file by hand is straightforward.
@item
-There are some C constructs which @code{protoize} cannot figure out.
+There are some C constructs which @command{protoize} cannot figure out.
For example, it can't determine argument types for declaring a
-pointer-to-function variable; this you must do by hand. @code{protoize}
+pointer-to-function variable; this you must do by hand. @command{protoize}
inserts a comment containing @samp{???} each time it finds such a
variable; so you can find all such variables by searching for this
string. ISO C does not require declaring the argument types of
pointer-to-function types.
@item
-Using @code{unprotoize} can easily introduce bugs. If the program
+Using @command{unprotoize} can easily introduce bugs. If the program
relied on prototypes to bring about conversion of arguments, these
conversions will not take place in the program without prototypes.
-One case in which you can be sure @code{unprotoize} is safe is when
-you are removing prototypes that were made with @code{protoize}; if
+One case in which you can be sure @command{unprotoize} is safe is when
+you are removing prototypes that were made with @command{protoize}; if
the program worked before without any prototypes, it will work again
without them.
+@opindex Wconversion
You can find all the places where this problem might occur by compiling
-the program with the @samp{-Wconversion} option. It prints a warning
+the program with the @option{-Wconversion} option. It prints a warning
whenever an argument is converted.
@item
them manually.
@item
-@code{protoize} cannot get the argument types for a function whose
+@command{protoize} cannot get the argument types for a function whose
definition was not actually compiled due to preprocessing conditionals.
-When this happens, @code{protoize} changes nothing in regard to such
-a function. @code{protoize} tries to detect such instances and warn
+When this happens, @command{protoize} changes nothing in regard to such
+a function. @command{protoize} tries to detect such instances and warn
about them.
-You can generally work around this problem by using @code{protoize} step
-by step, each time specifying a different set of @samp{-D} options for
+You can generally work around this problem by using @command{protoize} step
+by step, each time specifying a different set of @option{-D} options for
compilation, until all of the functions have been converted. There is
no automatic way to verify that you have got them all, however.
problem.
@item
-@code{unprotoize} can become confused when trying to convert a function
+@command{unprotoize} can become confused when trying to convert a function
definition or declaration which contains a declaration for a
pointer-to-function formal argument which has the same name as the
function being defined or declared. We recommend you avoid such choices
useful.
@item
-Making @samp{-fshort-enums} the default.
+@opindex fshort-enums
+Making @option{-fshort-enums} the default.
This would cause storage layout to be incompatible with most other C
compilers. And it doesn't seem very important, given that you can get
you can specify a field width explicitly.
@item
-Making bitfields unsigned by default on particular machines where ``the
+Making bit-fields unsigned by default on particular machines where ``the
ABI standard'' says to do so.
-The ISO C standard leaves it up to the implementation whether a bitfield
+The ISO C standard leaves it up to the implementation whether a bit-field
declared plain @code{int} is signed or not. This in effect creates two
-alternative dialects of C.
+alternative dialects of C@.
+@opindex fsigned-bitfields
+@opindex funsigned-bitfields
The GNU C compiler supports both dialects; you can specify the signed
-dialect with @samp{-fsigned-bitfields} and the unsigned dialect with
-@samp{-funsigned-bitfields}. However, this leaves open the question of
+dialect with @option{-fsigned-bitfields} and the unsigned dialect with
+@option{-funsigned-bitfields}. However, this leaves open the question of
which dialect to use by default.
-Currently, the preferred dialect makes plain bitfields signed, because
+Currently, the preferred dialect makes plain bit-fields signed, because
this is simplest. Since @code{int} is the same as @code{signed int} in
-every other context, it is cleanest for them to be the same in bitfields
+every other context, it is cleanest for them to be the same in bit-fields
as well.
Some computer manufacturers have published Application Binary Interface
-standards which specify that plain bitfields should be unsigned. It is
-a mistake, however, to say anything about this issue in an ABI. This is
-because the handling of plain bitfields distinguishes two dialects of C.
+standards which specify that plain bit-fields should be unsigned. It is
+a mistake, however, to say anything about this issue in an ABI@. This is
+because the handling of plain bit-fields distinguishes two dialects of C@.
Both dialects are meaningful on every type of machine. Whether a
-particular object file was compiled using signed bitfields or unsigned
+particular object file was compiled using signed bit-fields or unsigned
is of no concern to other object files, even if they access the same
-bitfields in the same data structures.
+bit-fields in the same data structures.
A given program is written in one or the other of these two dialects.
The program stands a chance to work on most any machine if it is
Many users appreciate the GNU C compiler because it provides an
environment that is uniform across machines. These users would be
-inconvenienced if the compiler treated plain bitfields differently on
+inconvenienced if the compiler treated plain bit-fields differently on
certain machines.
Occasionally users write programs intended only for a particular machine
program to run on more than one type of machine cannot possibly benefit
from this kind of compatibility.
-This is why GCC does and will treat plain bitfields in the same
+This is why GCC does and will treat plain bit-fields in the same
fashion on all types of machines (by default).
-There are some arguments for making bitfields unsigned by default on all
+There are some arguments for making bit-fields unsigned by default on all
machines. If, for example, this becomes a universal de facto standard,
it would make sense for GCC to go along with it. This is something
to be considered in the future.
(Of course, users strongly concerned about portability should indicate
-explicitly in each bitfield whether it is signed or not. In this way,
+explicitly in each bit-field whether it is signed or not. In this way,
they write programs which have the same meaning in both C dialects.)
@item
-Undefining @code{__STDC__} when @samp{-ansi} is not used.
+@opindex ansi
+@opindex traditional
+@opindex std
+Undefining @code{__STDC__} when @option{-ansi} is not used.
Currently, GCC defines @code{__STDC__} as long as you don't use
-@samp{-traditional}. This provides good results in practice.
+@option{-traditional}. This provides good results in practice.
Programmers normally use conditionals on @code{__STDC__} to ask whether
it is safe to use certain features of ISO C, such as function
-prototypes or ISO token concatenation. Since plain @samp{gcc} supports
+prototypes or ISO token concatenation. Since plain @command{gcc} supports
all the features of ISO C, the correct answer to these questions is
``yes''.
does not completely conform to the ISO C standard somehow violates the
standard. This is illogical. The standard is a standard for compilers
that claim to support ISO C, such as @samp{gcc -ansi}---not for other
-compilers such as plain @samp{gcc}. Whatever the ISO C standard says
-is relevant to the design of plain @samp{gcc} without @samp{-ansi} only
+compilers such as plain @command{gcc}. Whatever the ISO C standard says
+is relevant to the design of plain @command{gcc} without @option{-ansi} only
for pragmatic reasons, not as a requirement.
GCC normally defines @code{__STDC__} to be 1, and in addition
defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
-or a @option{-std} option for strict conformance to some version of ISO C.
+or a @option{-std} option for strict conformance to some version of ISO C@.
On some hosts, system include files use a different convention, where
@code{__STDC__} is normally 0, but is 1 if the user specifies strict
conformance to the C Standard. GCC follows the host convention when
They would not work otherwise.
In addition, many header files are written to provide prototypes in ISO
-C but not in traditional C. Many of these header files can work without
+C but not in traditional C@. Many of these header files can work without
change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
is not defined, they will all fail, and will all need to be changed to
test explicitly for C++ as well.
cannot produce an empty one, which holds for C but is not always the
case for C++.
-Moreover, with @samp{-funroll-loops} small ``empty'' loops are already
+@opindex funroll-loops
+Moreover, with @option{-funroll-loops} small ``empty'' loops are already
removed, so the current behavior is both sub-optimal and inconsistent
and will change in the future.
Some ISO C testsuites report failure when the compiler does not produce
an error message for a certain program.
+@opindex pedantic-errors
ISO C requires a ``diagnostic'' message for certain kinds of invalid
programs, but a warning is defined by GCC to count as a diagnostic. If
GCC produces a warning but not an error, that is correct ISO C support.
If test suites call this ``failure'', they should be run with the GCC
-option @samp{-pedantic-errors}, which will turn these warnings into
+option @option{-pedantic-errors}, which will turn these warnings into
errors.
@end itemize
@itemize @w{}
@item
-@emph{Errors} report problems that make it impossible to compile your
+@dfn{Errors} report problems that make it impossible to compile your
program. GCC reports errors with the source file name and line
number where the problem is apparent.
@item
-@emph{Warnings} report other unusual conditions in your code that
+@dfn{Warnings} report other unusual conditions in your code that
@emph{may} indicate a problem, although compilation can (and does)
proceed. Warning messages also report the source file name and line
number, but include the text @samp{warning:} to distinguish them
Warnings may indicate danger points where you should check to make sure
that your program really does what you intend; or the use of obsolete
features; or the use of nonstandard features of GNU C or C++. Many
-warnings are issued only if you ask for them, with one of the @samp{-W}
-options (for instance, @samp{-Wall} requests a variety of useful
+warnings are issued only if you ask for them, with one of the @option{-W}
+options (for instance, @option{-Wall} requests a variety of useful
warnings).
+@opindex pedantic
+@opindex pedantic-errors
GCC always tries to compile your program if possible; it never
gratuitously rejects a program whose meaning is clear merely because
(for instance) it fails to conform to a standard. In some cases,
however, the C and C++ standards specify that certain extensions are
forbidden, and a diagnostic @emph{must} be issued by a conforming
-compiler. The @samp{-pedantic} option tells GCC to issue warnings in
-such cases; @samp{-pedantic-errors} says to make them errors instead.
+compiler. The @option{-pedantic} option tells GCC to issue warnings in
+such cases; @option{-pedantic-errors} says to make them errors instead.
This does not mean that @emph{all} non-ISO constructs get warnings
or errors.
it may not. (If it does not, look in the service directory; see
@ref{Service}.) In any case, the principal function of a bug report is
to help the entire community by making the next version of GCC work
-better. Bug reports are your contribution to the maintenance of GCC.
+better. Bug reports are your contribution to the maintenance of GCC@.
Since the maintainers are very overloaded, we cannot respond to every
bug report. However, if the bug has not been fixed, we are likely to
@itemize @bullet
@item
-The version of GCC. You can get this by running it with the
-@samp{-v} option.
+The version of GCC@. You can get this by running it with the
+@option{-v} option.
Without this, we won't know whether there is any point in looking for
-the bug in the current version of GCC.
+the bug in the current version of GCC@.
@item
A complete input file that will reproduce the bug. If the bug is in the
C preprocessor, send a source file and any header files that it
requires. If the bug is in the compiler proper (@file{cc1}), send the
-preprocessor output generated by adding @samp{-save-temps} to the
+preprocessor output generated by adding @option{-save-temps} to the
compilation command (@pxref{Debugging Options}). When you do this, use
-the same @samp{-I}, @samp{-D} or @samp{-U} options that you used in
-actual compilation. Then send the @var{input}.i or @var{input}.ii files
+the same @option{-I}, @option{-D} or @option{-U} options that you used in
+actual compilation. Then send the @var{input}.i or @var{input}.ii files
generated.
A single statement is not enough of an example. In order to compile it,
@item
The command arguments you gave GCC to compile that example
-and observe the bug. For example, did you use @samp{-O}? To guarantee
+and observe the bug. For example, did you use @option{-O}? To guarantee
you won't omit something important, list all the options.
If we were to try to guess the arguments, we would probably guess wrong
@item
Details of any other deviations from the standard procedure for installing
-GCC.
+GCC@.
@item
A description of what behavior you observe that you believe is
@item
If you send examples of assembler code output from GCC,
-please use @samp{-g} when you make them. The debugging information
+please use @option{-g} when you make them. The debugging information
includes source line numbers which are essential for correlating the
output with the input.
@cindex gccbug script
To simplify creation of bug reports, and to allow better tracking of
-reports, we use the GNATS bug tracking system. Part of that system is
-the @code{gccbug} script. This is a Unix shell script, so you need a
-shell to run it. It is normally installed in the same directory where
+reports, we use the GNATS bug tracking system. Part of that system is
+the @code{gccbug} script. This is a Unix shell script, so you need a
+shell to run it. It is normally installed in the same directory where
@code{gcc} is installed.
The gccbug script is derived from send-pr, @pxref{using
-send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
+send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
invoked, it starts a text editor so you can fill out the various fields
-of the report. When the you quit the editor, the report is automatically
+of the report. When the you quit the editor, the report is automatically
send to the bug reporting address.
A number of fields in this bug report form are specific to GCC, and are
Please follow these guidelines so we can study your patches efficiently.
If you don't follow these guidelines, your information might still be
-useful, but using it will take extra work. Maintaining GNU C is a lot
+useful, but using it will take extra work. Maintaining GCC is a lot
of work in the best of circumstances, and we can't keep up unless you do
your best to help.
for us to install reliably. More than that, they make it hard for us to
study the diffs to decide whether we want to install them. Unidiff
format is better than contextless diffs, but not as easy to read as
-@samp{-c} format.
+@option{-c} format.
If you have GNU diff, use @samp{diff -cp}, which shows the name of the
function that each change occurs in.
@chapter Using GCC on VMS
@c prevent bad page break with this line
-Here is how to use GCC on VMS.
+Here is how to use GCC on VMS@.
@menu
* Include Files and VMS:: Where the preprocessor looks for the include files.
the include file.
@item
-If the file specification is not a valid VMS filename (i.e. does not
+If the file specification is not a valid VMS filename (i.e.@: does not
contain a device or a directory specifier, and contains a @samp{/}
character), the preprocessor tries to convert it from Unix syntax to
VMS syntax.
@end example
@noindent
-are a common source of incompatibility between VAX-C and GCC. VAX-C
+are a common source of incompatibility between VAX-C and GCC@. VAX-C
treats this much like a standard @code{#include <foobar.h>} directive.
That is incompatible with the ISO C behavior implemented by GCC: to
expand the name @code{foobar} as a macro. Macro expansion should
@findex GLOBALVALUEDEF
@findex GLOBALVALUEREF
GCC does not provide the @code{globalref}, @code{globaldef} and
-@code{globalvalue} keywords of VAX-C. You can get the same effect with
+@code{globalvalue} keywords of VAX-C@. You can get the same effect with
an obscure feature of GAS, the GNU assembler. (This requires GAS
version 1.39 or later.) The following macros allow you to use this
feature in a fairly natural way:
by VMS as a status code indicating a normal successful completion.
Version 1 of GCC did not provide this default.
-GCC on VMS works only with the GNU assembler, GAS. You need version
+GCC on VMS works only with the GNU assembler, GAS@. You need version
1.37 or later of GAS in order to produce value debugging information for
the VMS debugger. Use the ordinary VMS linker with the object files
-produced by GAS.
+produced by GAS@.
@cindex shared VMS run time system
@cindex @file{VAXCRTL}
libraries (such as Xlib) which were generated by another compiler. You
can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
it makes external C functions and variables case-independent as is usual
-on VMS. Alternatively, you could write all references to the functions
+on VMS@. Alternatively, you could write all references to the functions
and variables in such libraries using lower case; this will work on VMS,
but is not portable to other systems. The compiler option @samp{/NAMES}
also provides control over global name handling.
-Function and variable names are handled somewhat differently with GNU
-C++. The GNU C++ compiler performs @dfn{name mangling} on function
+Function and variable names are handled somewhat differently with G++.
+The GNU C++ compiler performs @dfn{name mangling} on function
names, which means that it adds information to the function name to
describe the data types of the arguments that the function takes. One
result of this is that the name of a function can become very long.
installed, such as TCL or dejagnu.
@item bootstrap
-Builds gcc three times - once with the native compiler, once with the
+Builds gcc three times---once with the native compiler, once with the
native-built compiler it just built, and once with the compiler it built
the second time. In theory, the last two should produce the same
results, which @code{make compare} can check. Each step of this process
-is called a "stage", and the results of each stage N (N=1..3) are copied
-to a subdirectory @file{stageN/}.
+is called a ``stage'', and the results of each stage @var{N}
+(@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}.
@item bootstrap-lean
Like @code{bootstrap}, except that the various stages are removed once
@item bubblestrap
Once bootstrapped, this incrementally rebuilds each of the three stages,
-one at a time. It does this by "bubbling" the stages up from their
-stubdirectories, rebuilding them, and copying them back to their
+one at a time. It does this by ``bubbling'' the stages up from their
+subdirectories, rebuilding them, and copying them back to their
subdirectories. This will allow you to, for example, quickly rebuild a
bootstrapped compiler after changing the sources, without having to do a
full bootstrap.
@item cleanstrap
Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}).
-@item stageN (N=1..4)
-For each stage, moves the appropriate files to the stageN subdirectory.
+@item stage@var{N} (@var{N} = 1@dots{}4)
+For each stage, moves the appropriate files to the @file{stage@var{N}}
+subdirectory.
-@item unstageN (N=1..4)
-Undoes the corresponding @code{stageN}.
+@item unstage@var{N} (@var{N} = 1@dots{}4)
+Undoes the corresponding @code{stage@var{N}}.
-@item restageN (N=1..4)
-Undoes the corresponding @code{stageN} and rebuilds it with the
+@item restage@var{N} (@var{N} = 1@dots{}4)
+Undoes the corresponding @code{stage@var{N}} and rebuilds it with the
appropriate flags.
@item compare
change is practical only if you are switching to GCC as the sole C
compiler for the system. We may implement register argument passing on
certain machines once we have a complete GNU system so that we can
-compile the libraries with GCC.
+compile the libraries with GCC@.
On some machines (particularly the Sparc), certain types of arguments
are passed ``by invisible reference''. This means that the value is
@cindex arithmetic libraries
@cindex math libraries
+@opindex msoft-float
Code compiled with GCC may call certain library routines. Most of
them handle arithmetic for which there are no instructions. This
includes multiply and divide on some machines, and floating point
operations on any machine for which floating point support is disabled
-with @samp{-msoft-float}. Some standard parts of the C library, such as
+with @option{-msoft-float}. Some standard parts of the C library, such as
@code{bcopy} or @code{memcpy}, are also called automatically. The usual
function call interface is used for calling the library routines.
they appear in @file{libgcc2.c}. Others must be hand-written in
assembly language for each processor. Wherever they are defined, they
are compiled into the support library, @file{libgcc.a}, which is
-automatically searched when you link programs with GCC.
+automatically searched when you link programs with GCC@.
@end ifset
@ifset INTERNALS
closing files, and sequencing the passes.
@cindex parsing pass
-The parsing pass is invoked only once, to parse the entire input. The RTL
-intermediate code for a function is generated as the function is parsed, a
-statement at a time. Each statement is read in as a syntax tree and then
-converted to RTL; then the storage for the tree for the statement is
-reclaimed. Storage for types (and the expressions for their sizes),
-declarations, and a representation of the binding contours and how they nest,
-remain until the function is finished being compiled; these are all needed
-to output the debugging information.
+The parsing pass is invoked only once, to parse the entire input. A
+high level tree representation is then generated from the input,
+one function at a time. This tree code is then transformed into RTL
+intermediate code, and processed. The files involved in transforming
+the trees into RTL are @file{expr.c}, @file{expmed.c}, and
+@file{stmt.c}.
+@c Note, the above files aren't strictly the only files involved. It's
+@c all over the place (function.c, final.c,etc). However, those are
+@c the files that are supposed to be directly involved, and have
+@c their purpose listed as such, so i've only listed them.
+The order of trees that are processed, is not
+necessarily the same order they are generated from
+the input, due to deferred inlining, and other considerations.
@findex rest_of_compilation
@findex rest_of_decl_compilation
within @code{rest_of_compilation}. When that function returns from
compiling a function definition, the storage used for that function
definition's compilation is entirely freed, unless it is an inline
-function
+function, or was deferred for some reason (this can occur in
+templates, for example).
@ifset USING
(@pxref{Inline,,An Inline Function is As Fast As a Macro}).
@end ifset
Here is a list of all the passes of the compiler and their source files.
Also included is a description of where debugging dumps can be requested
-with @samp{-d} options.
+with @option{-d} options.
@itemize @bullet
@item
Parsing. This pass reads the entire text of a function definition,
-constructing partial syntax trees. This and RTL generation are no longer
-truly separate passes (formerly they were), but it is easier to think
-of them as separate.
+constructing a high level tree representation. (Because of the semantic
+analysis that takes place during this pass, it does more than is
+formally considered to be parsing.)
The tree representation does not entirely follow C syntax, because it is
intended to support other languages as well.
tree node that represents an expression has a data type attached.
Variables are represented as declaration nodes.
-@cindex constant folding
-@cindex arithmetic simplifications
-@cindex simplifications, arithmetic
-Constant folding and some arithmetic simplifications are also done
-during this pass.
-
The language-independent source files for parsing are
@file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}.
There are also header files @file{tree.h} and @file{tree.def}
-which define the format of the tree representation.@refill
+which define the format of the tree representation.
+
+C Preprocessing, for language front ends, that want or require it, is
+performed by cpplib, which is covered in seperate documentation. In
+particular, the internals are covered in @xref{Top, ,Cpplib internals, cppinternals, Cpplib Internals}.
+
@c Avoiding overfull is tricky here.
The source files to parse C are
-@file{c-parse.in},
-@file{c-decl.c},
-@file{c-typeck.c},
@file{c-aux-info.c},
@file{c-convert.c},
-and @file{c-lang.c}
-along with header files
-@file{c-lex.h}, and
-@file{c-tree.h}.
+@file{c-decl.c},
+@file{c-errors.c},
+@file{c-lang.c},
+@file{c-parse.in},
+and
+@file{c-typeck.c},
+along with a header file
+@file{c-tree.h}
+and some files shared with Objective-C and C++.
The source files for parsing C++ are in @file{cp/}.
They are @file{parse.y},
@file{except.c},@*
@file{expr.c}, @file{init.c}, @file{lex.c},
@file{method.c}, @file{ptree.c},@*
-@file{search.c}, @file{tree.c},
+@file{search.c}, @file{spew.c}, @*
+@file{semantics.c}, @file{tree.c},
@file{typeck2.c}, and
@file{typeck.c}, along with header files @file{cp-tree.def},
@file{cp-tree.h}, and @file{decl.h}.
-The special source files for parsing Objective C are in @file{objc/}.
+The special source files for parsing Objective-C are in @file{objc/}.
They are @file{objc-parse.y}, @file{objc-act.c}, @file{objc-tree.def}, and
@file{objc-act.h}. Certain C-specific files are used for this as
well.
-The file @file{c-common.c} is also used for all of the above languages.
+The files
+@file{c-common.c},
+@file{c-common.def},
+@file{c-dump.c},
+@file{c-format.c},
+@file{c-lex.c},
+@file{c-pragma.c},
+and
+@file{c-semantics.c},
+along with header files
+@file{c-common.h},
+@file{c-dump.h},
+@file{c-lex.h},
+and
+@file{c-pragma.h},
+are also used for all of the above languages.
+
+
+@cindex Tree optimization
+@item
+Tree optimization. This is the optimization of the tree
+representation, before converting into RTL code.
+
+@cindex inline on trees, automatic
+Currently, the main optimization performed here is tree-based
+inlining.
+This is implemented for C++ in @file{cp/optimize.c}. Note that
+tree based inlining turns off rtx based inlining (since it's more
+powerful, it would be a waste of time to do rtx based inlining in
+addition).
+The C front end currently does not perform tree based inlining.
+
+@cindex constant folding
+@cindex arithmetic simplifications
+@cindex simplifications, arithmetic
+Constant folding and some arithmetic simplifications are also done
+during this pass, on the tree representation.
+The routines that perform these tasks are located in @file{fold-const.c}.
@cindex RTL generation
@item
RTL generation. This is the conversion of syntax tree into RTL code.
-It is actually done statement-by-statement during parsing, but for
-most purposes it can be thought of as a separate pass.
@cindex target-parameter-dependent code
This is where the bulk of target-parameter-dependent code is found,
Also, the file
@file{insn-emit.c}, generated from the machine description by the
program @code{genemit}, is used in this pass. The header file
-@file{expr.h} is used for communication within this pass.@refill
+@file{expr.h} is used for communication within this pass.
@findex genflags
@findex gencodes
The header files @file{insn-flags.h} and @file{insn-codes.h},
generated from the machine description by the programs @code{genflags}
and @code{gencodes}, tell this pass which standard names are available
-for use and which patterns correspond to them.@refill
+for use and which patterns correspond to them.
Aside from debugging information output, none of the following passes
refers to the tree structure representation of the function (only
part of which is saved).
-@cindex inline, automatic
+@cindex inline on rtx, automatic
The decision of whether the function can and should be expanded inline
in its subsequent callers is made at the end of rtl generation. The
function must meet certain criteria, currently related to the size of
the function and the types and number of parameters it has. Note that
this function may contain loops, recursive calls to itself
(tail-recursive functions can be inlined!), gotos, in short, all
-constructs supported by GCC. The file @file{integrate.c} contains
+constructs supported by GCC@. The file @file{integrate.c} contains
the code to save a function's rtl for later inlining and to inline that
rtl when the function is called. The header file @file{integrate.h}
is also used for this purpose.
-The option @samp{-dr} causes a debugging dump of the RTL code after
+@opindex dr
+The option @option{-dr} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.rtl} to
the input file name.
+@c Should the exception handling pass be talked about here?
+
+@cindex sibling call optimization
+@item
+Sibiling call optimization. This pass performs tail recursion
+elimination, and tail and sibling call optimizations. The purpose of
+these optimizations is to reduce the overhead of function calls,
+whenever possible.
+
+The source file of this pass is @file{sibcall.c}
+
+@opindex di
+The option @option{-di} causes a debugging dump of the RTL code after
+this pass is run. This dump file's name is made by appending
+@samp{.sibling} to the input file name.
+
@cindex jump optimization
@cindex unreachable code
@cindex dead code
The source file of this pass is @file{jump.c}.
-The option @samp{-dj} causes a debugging dump of the RTL code after
+@opindex dj
+The option @option{-dj} causes a debugging dump of the RTL code after
this pass is run for the first time. This dump file's name is made by
appending @samp{.jump} to the input file name.
@cindex jump threading
@item
+@opindex fthread-jumps
Jump threading. This pass detects a condition jump that branches to an
identical or inverse test. Such jumps can be @samp{threaded} through
the second conditional test. The source code for this pass is in
@file{jump.c}. This optimization is only performed if
-@samp{-fthread-jumps} is enabled.
+@option{-fthread-jumps} is enabled.
@cindex common subexpression elimination
@cindex constant propagation
@item
Common subexpression elimination. This pass also does constant
-propagation. Its source file is @file{cse.c}. If constant
-propagation causes conditional jumps to become unconditional or to
-become no-ops, jump optimization is run again when CSE is finished.
+propagation. Its source files are @file{cse.c}, and @file{cselib.c}.
+If constant propagation causes conditional jumps to become
+unconditional or to become no-ops, jump optimization is run again when
+CSE is finished.
-The option @samp{-ds} causes a debugging dump of the RTL code after
+@opindex ds
+The option @option{-ds} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.cse} to
the input file name.
+@cindex SSA optimizations
+@cindex Single Static Assignment optimizations
+@opindex fssa
+@item
+Static Single Assignment (SSA) based optimization passes. The
+SSA conversion passes (to/from) are turned on by the @option{-fssa}
+option (it is also done automatically if you enable an SSA optimization pass).
+These passes utilize a form called Static Single Assignment. In SSA form,
+each variable (pseudo register) is only set once, giving you def-use
+and use-def chains for free, and enabling a lot more optimization
+passes to be run in linear time.
+Conversion to and from SSA form is handled by functions in
+@file{ssa.c}.
+
+@opindex de
+The option @option{-de} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.ssa} to
+the input file name.
+@itemize @bullet
+@cindex SSA DCE
+@cindex DCE, SSA based
+@cindex dead code elimination
+@opindex fdce
+@item
+Dead Code Elimination. Turned on by the @option{-fdce} option.
+This pass performs elimination of code considered unnecessary because it
+is never executed. It operates in linear time.
+
+@opindex dX
+The option @option{-dX} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.dce} to
+the input file name.
+@end itemize
@cindex global common subexpression elimination
@cindex constant propagation
@cindex copy propagation
@item
-Global common subexpression elimination. This pass performs GCSE
-using Morel-Renvoise Partial Redundancy Elimination, with the exception
-that it does not try to move invariants out of loops - that is left to
-the loop optimization pass. This pass also performs global constant
-and copy propagation.
-
-The source file for this pass is gcse.c.
-
-The option @samp{-dG} causes a debugging dump of the RTL code after
+Global common subexpression elimination. This pass performs two
+different types of GCSE depending on whether you are optimizing for
+size or not (LCM based GCSE tends to increase code size for a gain in
+speed, while Morel-Renvoise based GCSE does not).
+When optimizing for size, GCSE is done using Morel-Renvoise Partial
+Redundancy Elimination, with the exception that it does not try to move
+invariants out of loops---that is left to the loop optimization pass.
+If MR PRE GCSE is done, code hoisting (aka unification) is also done, as
+well as load motion.
+If you are optimizing for speed, LCM (lazy code motion) based GCSE is
+done. LCM is based on the work of Knoop, Ruthing, and Steffen. LCM
+based GCSE also does loop invariant code motion. We also perform load
+and store motion when optimizing for speed.
+Regardless of which type of GCSE is used, the GCSE pass also performs
+global constant and copy propagation.
+
+The source file for this pass is @file{gcse.c}, and the LCM routines
+are in @file{lcm.c}.
+
+@opindex dG
+The option @option{-dG} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.gcse} to
the input file name.
Its source files are @file{loop.c} and @file{unroll.c}, plus the header
@file{loop.h} used for communication between them. Loop unrolling uses
some functions in @file{integrate.c} and the header @file{integrate.h}.
+Loop dependency analysis routines are contained in @file{dependence.c}.
-The option @samp{-dL} causes a debugging dump of the RTL code after
+@opindex dL
+The option @option{-dL} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.loop} to
the input file name.
@item
-If @samp{-frerun-cse-after-loop} was enabled, a second common
+@opindex frerun-cse-after-loop
+If @option{-frerun-cse-after-loop} was enabled, a second common
subexpression elimination pass is performed after the loop optimization
pass. Jump threading is also done again at this time if it was specified.
-The option @samp{-dt} causes a debugging dump of the RTL code after
+@opindex dt
+The option @option{-dt} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.cse2} to
the input file name.
combines memory references with add or subtract instructions to make
autoincrement or autodecrement addressing.
-The option @samp{-df} causes a debugging dump of the RTL code after
+@opindex df
+The option @option{-df} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.flow} to
the input file name. If stupid register allocation is in use, this
dump file reflects the full results of such allocation.
the instructions by substitution, simplifies the result using algebra,
and then attempts to match the result against the machine description.
-The option @samp{-dc} causes a debugging dump of the RTL code after
+@opindex dc
+The option @option{-dc} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.combine}
to the input file name.
+@cindex if conversion
+@item
+If-conversion is a transformation that transforms control dependencies
+into data dependencies (IE it transforms conditional code into a
+single control stream).
+It is implemented in the file @file{ifcvt.c}.
+
+@opindex dE
+The option @option{-dE} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.ce} to
+the input file name.
+
@cindex register movement
@item
-Register movement (@file{regmove.c}). This pass looks for cases where
+Register movement (@file{regmove.c}). This pass looks for cases where
matching constraints would force an instruction to need a reload, and
this reload would be a register to register move. It then attempts
to change the registers used by the instruction to avoid the move
instruction.
-The option @samp{-dN} causes a debugging dump of the RTL code after
+@opindex dN
+The option @option{-dN} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.regmove}
to the input file name.
Instruction scheduling is performed twice. The first time is immediately
after instruction combination and the second is immediately after reload.
-The option @samp{-dS} causes a debugging dump of the RTL code after this
+@opindex dS
+The option @option{-dS} causes a debugging dump of the RTL code after this
pass is run for the first time. The dump file's name is made by
appending @samp{.sched} to the input file name.
block. Because the basic block is linear, it can use fast and
powerful techniques to do a very good job.
-The option @samp{-dl} causes a debugging dump of the RTL code after
+@opindex dl
+The option @option{-dl} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.lreg} to
the input file name.
Source files are @file{reload.c} and @file{reload1.c}, plus the header
@file{reload.h} used for communication between them.
-The option @samp{-dg} causes a debugging dump of the RTL code after
+@opindex dg
+The option @option{-dg} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.greg} to
the input file name.
Instruction scheduling is repeated here to try to avoid pipeline stalls
due to memory loads generated for spilled pseudo registers.
-The option @samp{-dR} causes a debugging dump of the RTL code after
+@opindex dR
+The option @option{-dR} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.sched2}
to the input file name.
+@cindex basic block reordering
+@cindex reordering, block
+@item
+Basic block reordering. This pass implements profile guided code
+positioning. If profile information is not available, various types of
+static analysis are performed to make the predictions normally coming
+from the profile feedback (IE execution frequency, branch probability,
+etc). It is implemented in the file @file{bb-reorder.c}, and the
+various prediction routines are in @file{predict.c}.
+
+@opindex dB
+The option @option{-dB} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.bbro} to
+the input file name.
+
@cindex cross-jumping
@cindex no-op move instructions
@item
Jump optimization is repeated, this time including cross-jumping
and deletion of no-op move instructions.
-The option @samp{-dJ} causes a debugging dump of the RTL code after
+@opindex dJ
+The option @option{-dJ} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.jump2}
to the input file name.
instructions that can go into the delay slots of other instructions,
usually jumps and calls. The source file name is @file{reorg.c}.
-The option @samp{-dd} causes a debugging dump of the RTL code after
+@opindex dd
+The option @option{-dd} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.dbr}
to the input file name.
for the floating-point registers of the Intel 80387 coprocessor. The
source file name is @file{reg-stack.c}.
-The options @samp{-dk} causes a debugging dump of the RTL code after
+@opindex dk
+The options @option{-dk} causes a debugging dump of the RTL code after
this pass. This dump file's name is made by appending @samp{.stack}
to the input file name.
also responsible for identifying spurious test and compare
instructions. Machine-specific peephole optimizations are performed
at the same time. The function entry and exit sequences are generated
-directly as assembler code in this pass; they never exist as RTL.
+directly as assembler code in this pass; they never exist as RTL@.
The source files are @file{final.c} plus @file{insn-output.c}; the
latter is generated automatically from the machine description by the
Debugging information output. This is run after final because it must
output the stack slot offsets for pseudo registers that did not get
hard registers. Source files are @file{dbxout.c} for DBX symbol table
-format, @file{sdbout.c} for SDB symbol table format, and
-@file{dwarfout.c} for DWARF symbol table format.
+format, @file{sdbout.c} for SDB symbol table format, @file{dwarfout.c}
+for DWARF symbol table format, and the files @file{dwarf2out.c} and
+@file{dwarf2asm.c} for DWARF2 symbol table format.
@end itemize
Some additional files are used by all or many passes:
All the passes that work with RTL use the header files @file{rtl.h}
and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
@code{gen*} also use these files to read and work with the machine
-description RTL.
+description RTL@.
@findex genconfig
@item
@file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
and @file{insn-extract.c} that are generated automatically from the
machine description by the tools @file{genrecog} and
-@file{genextract}.@refill
+@file{genextract}.
@item
Several passes use the header files @file{regs.h} which defines the
@file{insn-attr.h}, which is generated from the machine description by
the program @file{genattr}. The file @file{insn-attrtab.c} contains
subroutines to obtain the attribute values for insns. It is generated
-from the machine description by the program @file{genattrtab}.@refill
+from the machine description by the program @file{genattrtab}.
@end itemize
@end ifset
@table @code
@findex USG
@item USG
-Define this macro if the host system is System V.
+Define this macro if the host system is System V@.
@findex VMS
@item VMS
-Define this macro if the host system is VMS.
+Define this macro if the host system is VMS@.
@findex FATAL_EXIT_CODE
@item FATAL_EXIT_CODE
A C expression for the number of bits in @code{long} on the host
machine.
+@findex HOST_BITS_PER_LONGLONG
+@item HOST_BITS_PER_LONGLONG
+A C expression for the number of bits in @code{long long} on the host
+machine.
+
@findex ONLY_INT_FIELDS
@item ONLY_INT_FIELDS
Define this macro to indicate that the host compiler only supports
-@code{int} bit fields, rather than other integral types, including
+@code{int} bit-fields, rather than other integral types, including
@code{enum}, as do most C compilers.
@findex OBSTACK_CHUNK_SIZE
@findex USE_C_ALLOCA
@item USE_C_ALLOCA
Define this macro to indicate that the compiler is running with the
-@code{alloca} implemented in C. This version of @code{alloca} can be
+@code{alloca} implemented in C@. This version of @code{alloca} can be
found in the file @file{alloca.c}; to use it, you must also alter the
@file{Makefile} variable @code{ALLOCA}. (This is done automatically
for the systems on which we know it is needed.)
@findex MULTIBYTE_CHARS
@item MULTIBYTE_CHARS
Define this macro to enable support for multibyte characters in the
-input to GCC. This requires that the host system support the ISO C
+input to GCC@. This requires that the host system support the ISO C
library functions for converting multibyte characters to wide
characters.
names, the character you specify will be used. GCC will test for
both slash and the character you specify when parsing filenames.
+@findex DIR_SEPARATOR_2
+@item DIR_SEPARATOR_2
+If your system uses an alternative character other than
+@samp{DIR_SEPARATOR} to separate directory names within a file
+specification, define this macro to be a C character constant specifying
+that character. If you define this macro, GCC will test for slash,
+@samp{DIR_SEPARATOR}, and @samp{DIR_SEPARATOR_2} when parsing filenames.
+
@findex TARGET_OBJECT_SUFFIX
@item TARGET_OBJECT_SUFFIX
Define this macro to be a C string representing the suffix for object
@item UPDATE_PATH_HOST_CANONICALIZE (@var{path}, @var{key})
If defined, a C statement (sans semicolon) that performs host-dependent
canonicalization when a path used in a compilation driver or preprocessor is
-canonicalized. @var{path} is the path to be canonicalized, and @var{key} is
-a translation prefix when its value isn't @code{NULL}. If the C statement
+canonicalized. @var{path} is the path to be canonicalized, and @var{key} is
+a translation prefix when its value isn't @code{NULL}. If the C statement
does canonicalize @var{path}, the new path should be returned.
@end table
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: @samp{-m68000},
-@samp{-m68020}, @samp{-msoft-float}, @samp{-m68000 -msoft-float}, and
+@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
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 @samp{-mcall-aix} option
-and either of the @samp{-fleading-underscore} or @samp{-mlittle} options
+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
@code{*mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*}.
free software added up to a complete system because the GNU Project
had been working since 1984 to make one. The GNU Manifesto
had set forth the goal of developing a free Unix-like system, called
-GNU. By the time Linux was written, the system was almost finished.
+GNU@. By the time Linux was written, the system was almost finished.
Most free software projects have the goal of developing a particular
program for a particular job. For example, Linus Torvalds set out to
major components without which there could be no system. Linux itself
was about 3%. So if you were going to pick a name for the system
based on who wrote the programs in the system, the most appropriate
-single choice would be ``GNU''.
+single choice would be ``GNU''@.
But we don't think that is the right way to consider the question.
The GNU Project was not, is not, a project to develop specific
@include contrib.texi
@c ---------------------------------------------------------------------
-@c Node Index
+@c Indexes
@c ---------------------------------------------------------------------
+@node Option Index
+@unnumbered Option Index
+
+GCC's command line options are indexed here without any initial @samp{-}
+or @samp{--}. Where an option has both positive and negative forms
+(such as @option{-f@var{option}} and @option{-fno-@var{option}}),
+relevant entries in the manual are indexed under the most appropriate
+form; it may sometimes be useful to look up both forms.
+
+@printindex op
+
@node Index
@unnumbered Index