gcc.texi

GCC

\input texinfo  @c -*-texinfo-*-
@c %**start of header
@setfilename gcc.info
@c @setfilename usegcc.info
@c @setfilename portgcc.info
@c To produce the full manual, use the "gcc.info" setfilename, and
@c make sure the following do NOT begin with '@c' (and the @clear lines DO)
@set INTERNALS
@set USING
@c To produce a user-only manual, use the "usegcc.info" setfilename, and
@c make sure the following does NOT begin with '@c':
@c @clear INTERNALS
@c To produce a porter-only manual, use the "portgcc.info" setfilename,
@c and make sure the following does NOT begin with '@c':
@c @clear USING

@c (For FSF printing, turn on smallbook, comment out finalout below;
@c that is all that is needed.)

@c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition.
@c @smallbook

@c i also commented out the finalout command, so if there *are* any
@c overfulls, you'll (hopefully) see the rectangle in the right hand
@c margin. -mew 15june93
@c @finalout

@c NOTE: checks/things to do:
@c
@c -have bob do a search in all seven files for "mew" (ideally --mew,
@c  but i may have forgotten the occasional "--"..).
@c     Just checked... all have `--'!  Bob 22Jul96
@c     Use this to search:   grep -n '\-\-mew' *.texi
@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 -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 - "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 (not yet
@c   consistently followed).

@macro gcctabopt{body}
@code{\body\}
@end macro
@macro gccoptlist{body}
@smallexample
\body\
@end smallexample
@end macro
@c Makeinfo handles the above macro OK, TeX needs manual line breaks;
@c they get lost at some point in handling the macro.  But if @macro is
@c used here rather than @alias, it produces double line breaks.
@iftex
@alias gol = *
@end iftex
@ifnottex
@macro gol
@end macro
@end ifnottex

@ifset INTERNALS
@ifset USING
@settitle Using and Porting the GNU Compiler Collection (GCC)
@end ifset
@end ifset
@c seems reasonable to assume at least one of INTERNALS or USING is set...
@ifclear INTERNALS
@settitle Using the GNU Compiler Collection
@end ifclear
@ifclear USING
@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
@syncodeindex pg cp
@syncodeindex tp cp

@c %**end of header

@c Use with @@smallbook.

@c Cause even numbered pages to be printed on the left hand side of
@c the page and odd numbered pages to be printed on the right hand
@c side of the page.  Using this, you can print on both sides of a
@c sheet of paper and have the text on the same part of the sheet.

@c The text on right hand pages is pushed towards the right hand
@c margin and the text on left hand pages is pushed toward the left
@c hand margin.
@c (To provide the reverse effect, set bindingoffset to -0.75in.)

@c @tex
@c \global\bindingoffset=0.75in
@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
* gcc: (gcc).                  The GNU Compiler Collection.
@end direntry
@ifset INTERNALS
@ifset USING
This file documents the use and the internals of the GNU compiler.
@end ifset
@end ifset
@ifclear USING
This file documents the internals of the GNU compiler.
@end ifclear
@ifclear INTERNALS
This file documents the use of the GNU compiler.
@end ifclear
@sp 1
Published by the Free Software Foundation@*
59 Temple Place - Suite 330@*
Boston, MA 02111-1307 USA
@sp 1
@c When you update the list of years below, search for copyright{} and
@c update the other copy too.
Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001 Free Software Foundation, Inc.
@sp 1
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'' and ``Funding
Free Software'', the Front-Cover texts being (a) (see below), and with
the Back-Cover Texts being (b) (see below).  A copy of the license is
included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@end ifnottex

@setchapternewpage odd
@c @finalout
@titlepage
@ifset INTERNALS
@ifset USING
@center @titlefont{Using and Porting the GNU Compiler Collection}

@end ifset
@end ifset
@ifclear INTERNALS
@title Using the GNU Compiler Collection
@end ifclear
@ifclear USING
@title Porting the GNU Compiler Collection
@end ifclear
@sp 2
@center Richard M. Stallman
@sp 3
@center Last updated 14 June 2001
@sp 1
@c The version number appears five times more in this file.

@center for gcc-3.0
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
1999, 2000, 2001  Free Software Foundation, Inc.
@sp 2
For GCC Version 3.0@*
@sp 1
Published by the Free Software Foundation @*
59 Temple Place - Suite 330@*
Boston, MA 02111-1307, USA@*
Last printed April, 1998.@*
Printed copies are available for $50 each.@*
ISBN 1-882114-37-X
@sp 1
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'', the Front-Cover
texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
``GNU Free Documentation License''.

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@end titlepage
@summarycontents
@contents
@page

@node Top, G++ and GCC,, (DIR)
@top Introduction
@cindex introduction

@ifset INTERNALS
@ifset USING
This manual documents how to run, install and port the GNU
compiler, as well as its new features and incompatibilities, and how to
report bugs.  It corresponds to GCC version 3.0.
@end ifset
@end ifset

@ifclear INTERNALS
This manual documents how to run and install the GNU compiler,
as well as its new features and incompatibilities, and how to report
bugs.  It corresponds to GCC version 3.0.
@end ifclear
@ifclear USING
This manual documents how to port the GNU compiler,
as well as its new features and incompatibilities, and how to report
bugs.  It corresponds to GCC version 3.0.
@end ifclear

@menu
@ifset USING
* G++ and GCC::     You can compile C or C++ programs.
* Standards::       Language standards supported by GCC.
* Invoking GCC::    Command options supported by @samp{gcc}.
* 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.
* Gcov::	    gcov: a GCC test coverage program.
* Trouble::         If you have trouble installing GCC.
* Bugs::            How, why and where to report bugs.
* Service::         How to find suppliers of support for GCC.
* Contributing::    How to contribute to testing and developing GCC.
* VMS::             Using GCC on VMS.
* Makefile::        List of Makefile targets.
@end ifset
@ifset INTERNALS
* 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.
* 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.
* Config::          Writing the @file{xm-@var{machine}.h} file.
* Fragments::       Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
@end ifset

* Funding::         How to help assure funding for free software.
* GNU/Linux::       Linux and the GNU Project

* Copying::         GNU General Public License says
                     how you can copy and share GCC.
* 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

@cindex Objective C
@cindex Fortran
@cindex Java
Several versions of the compiler (C, C++, Objective C, Fortran, Java) are integrated; this is why we use the name
``GNU Compiler Collection''. GCC can compile programs written in any of these
languages. The Fortran and Java compilers are described in
separate manuals.

@cindex GCC
``GCC'' is a common shorthand term for the GNU Compiler Collection.  This is both
the most general name for the compiler, and the name used when the
emphasis is on compiling C programs (as the abbreviation formerly
stood for ``GNU C Compiler'').

@cindex C++
@cindex G++
When referring to C++ compilation, it is usual to call the compiler
``G++''.  Since there is only one compiler, it is also accurate to call
it ``GCC'' no matter what the language context; however, the term
``G++'' is more useful when the emphasis is on compiling C++ programs.

We use the name ``GCC'' to refer to the compilation system as a
whole, and more specifically to the language-independent part of the
compiler.  For example, we refer to the optimization options as
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++,
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
ends.

In this manual, we only discuss the options for the C, Objective-C, and
C++ compilers and those of the GCC core.  Consult the documentation
of the other front ends for the options to use when compiling programs
written in other languages.

@cindex compiler compared to C++ preprocessor
@cindex intermediate C version, nonexistent
@cindex C intermediate output, nonexistent
G++ is a @emph{compiler}, not merely a preprocessor.  G++ builds object
code directly from your C++ program source.  There is no intermediate C
version of the program.  (By contrast, for example, some other
implementations use a program that generates a C program from your C++
source.)  Avoiding an intermediate C representation of the program means
that you get better object code, and better debugging information.  The