1 \input texinfo @c -*-texinfo-*-
4 @c @setfilename usegcc.info
5 @c @setfilename portgcc.info
6 @c To produce the full manual, use the "gcc.info" setfilename, and
7 @c make sure the following do NOT begin with '@c' (and the @clear lines DO)
10 @c To produce a user-only manual, use the "usegcc.info" setfilename, and
11 @c make sure the following does NOT begin with '@c':
13 @c To produce a porter-only manual, use the "portgcc.info" setfilename,
14 @c and make sure the following does NOT begin with '@c':
17 @c (For FSF printing, turn on smallbook, comment out finalout below;
18 @c that is all that is needed.)
20 @c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition.
23 @c i also commented out the finalout command, so if there *are* any
24 @c overfulls, you'll (hopefully) see the rectangle in the right hand
25 @c margin. -mew 15june93
28 @c NOTE: checks/things to do:
30 @c -have bob do a search in all seven files for "mew" (ideally --mew,
31 @c but i may have forgotten the occasional "--"..).
32 @c Just checked... all have `--'! Bob 22Jul96
33 @c Use this to search: grep -n '\-\-mew' *.texi
34 @c -item/itemx, text after all (sub/sub)section titles, etc..
35 @c -consider putting the lists of options on pp 17--> etc in columns or
37 @c -overfulls. do a search for "mew" in the files, and you will see
38 @c overfulls that i noted but could not deal with.
39 @c -have to add text: beginning of chapter 8
42 @c anything else? --mew 10feb93
44 @macro gcctabopt{body}
47 @macro gccoptlist{body}
52 @c Makeinfo handles the above macro OK, TeX needs manual line breaks;
53 @c they get lost at some point in handling the macro. But if @macro is
54 @c used here rather than @alias, it produces double line breaks.
65 @settitle Using and Porting the GNU Compiler Collection (GCC)
68 @c seems reasonable to assume at least one of INTERNALS or USING is set...
70 @settitle Using the GNU Compiler Collection
73 @settitle Porting the GNU Compiler Collection
76 @c Create a separate index for command line options.
78 @c Merge the standard indexes into a single one.
87 @c Use with @@smallbook.
89 @c Cause even numbered pages to be printed on the left hand side of
90 @c the page and odd numbered pages to be printed on the right hand
91 @c side of the page. Using this, you can print on both sides of a
92 @c sheet of paper and have the text on the same part of the sheet.
94 @c The text on right hand pages is pushed towards the right hand
95 @c margin and the text on left hand pages is pushed toward the left
97 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
100 @c \global\bindingoffset=0.75in
101 @c \global\normaloffset =0.75in
104 @c Change the font used for @def... commands, since the default
105 @c proportional one used is bad for names starting __.
107 \global\setfont\defbf\ttbshape{10}{\magstep1}
111 @dircategory Programming
113 * gcc: (gcc). The GNU Compiler Collection.
117 This file documents the use and the internals of the GNU compiler.
121 This file documents the internals of the GNU compiler.
124 This file documents the use of the GNU compiler.
127 Published by the Free Software Foundation@*
128 59 Temple Place - Suite 330@*
129 Boston, MA 02111-1307 USA
131 @c When you update the list of years below, search for copyright{} and
132 @c update the other copy too.
133 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
134 1999, 2000, 2001 Free Software Foundation, Inc.
136 Permission is granted to copy, distribute and/or modify this document
137 under the terms of the GNU Free Documentation License, Version 1.1 or
138 any later version published by the Free Software Foundation; with the
139 Invariant Sections being ``GNU General Public License'' and ``Funding
140 Free Software'', the Front-Cover texts being (a) (see below), and with
141 the Back-Cover Texts being (b) (see below). A copy of the license is
142 included in the section entitled ``GNU Free Documentation License''.
144 (a) The FSF's Front-Cover Text is:
148 (b) The FSF's Back-Cover Text is:
150 You have freedom to copy and modify this GNU Manual, like GNU
151 software. Copies published by the Free Software Foundation raise
152 funds for GNU development.
155 @setchapternewpage odd
160 @center @titlefont{Using and Porting the GNU Compiler Collection}
165 @title Using the GNU Compiler Collection
168 @title Porting the GNU Compiler Collection
171 @center Richard M. Stallman
173 @center Last updated 22 June 2001
175 @c The version number appears five times more in this file.
179 @vskip 0pt plus 1filll
180 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
181 1999, 2000, 2001 Free Software Foundation, Inc.
183 For GCC Version 3.1@*
185 Published by the Free Software Foundation @*
186 59 Temple Place---Suite 330@*
187 Boston, MA 02111-1307, USA@*
188 Last printed April, 1998.@*
189 Printed copies are available for $50 each.@*
192 Permission is granted to copy, distribute and/or modify this document
193 under the terms of the GNU Free Documentation License, Version 1.1 or
194 any later version published by the Free Software Foundation; with the
195 Invariant Sections being ``GNU General Public License'', the Front-Cover
196 texts being (a) (see below), and with the Back-Cover Texts being (b)
197 (see below). A copy of the license is included in the section entitled
198 ``GNU Free Documentation License''.
200 (a) The FSF's Front-Cover Text is:
204 (b) The FSF's Back-Cover Text is:
206 You have freedom to copy and modify this GNU Manual, like GNU
207 software. Copies published by the Free Software Foundation raise
208 funds for GNU development.
214 @node Top, G++ and GCC,, (DIR)
220 This manual documents how to run, install and port the GNU
221 compiler, as well as its new features and incompatibilities, and how to
222 report bugs. It corresponds to GCC version 3.1.
227 This manual documents how to run and install the GNU compiler,
228 as well as its new features and incompatibilities, and how to report
229 bugs. It corresponds to GCC version 3.1.
232 This manual documents how to port the GNU compiler,
233 as well as its new features and incompatibilities, and how to report
234 bugs. It corresponds to GCC version 3.1.
239 * G++ and GCC:: You can compile C or C++ programs.
240 * Standards:: Language standards supported by GCC.
241 * Invoking GCC:: Command options supported by @samp{gcc}.
242 * Installation:: How to configure, compile and install GCC.
243 * C Implementation:: How GCC implements the ISO C specification.
244 * C Extensions:: GNU extensions to the C language family.
245 * C++ Extensions:: GNU extensions to the C++ language.
246 * Objective-C:: GNU Objective-C runtime features.
247 * Gcov:: gcov: a GCC test coverage program.
248 * Trouble:: If you have trouble installing GCC.
249 * Bugs:: How, why and where to report bugs.
250 * Service:: How to find suppliers of support for GCC.
251 * Contributing:: How to contribute to testing and developing GCC.
252 * VMS:: Using GCC on VMS.
253 * Makefile:: Additional Makefile and configure information.
256 * Portability:: Goals of GCC's portability features.
257 * Interface:: Function-call interface of GCC output.
258 * Passes:: Order of passes, what they do, and what each file is for.
259 * Trees:: The source representation used by the C and C++ front ends.
260 * RTL:: The intermediate representation that most passes work on.
261 * Machine Desc:: How to write machine description instruction patterns.
262 * Target Macros:: How to write the machine description C macros and functions.
263 * Config:: Writing the @file{xm-@var{machine}.h} file.
264 * Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
267 * Funding:: How to help assure funding for free software.
268 * GNU/Linux:: Linux and the GNU Project
270 * Copying:: GNU General Public License says
271 how you can copy and share GCC.
272 * GNU Free Documentation License:: How you can copy and share this manual.
273 * Contributors:: People who have contributed to GCC.
275 * Option Index:: Index to command line options.
276 * Index:: Index of concepts and symbol names.
281 @chapter Compile C, C++, Objective-C, Ada, CHILL, Fortran, or Java
288 Several versions of the compiler (C, C++, Objective-C, Ada, CHILL,
289 Fortran, and Java) are integrated; this is why we use the name
290 ``GNU Compiler Collection''. GCC can compile programs written in any of these
291 languages. The Ada, CHILL, Fortran, and Java compilers are described in
295 ``GCC'' is a common shorthand term for the GNU Compiler Collection. This is both
296 the most general name for the compiler, and the name used when the
297 emphasis is on compiling C programs (as the abbreviation formerly
298 stood for ``GNU C Compiler'').
302 When referring to C++ compilation, it is usual to call the compiler
303 ``G++''. Since there is only one compiler, it is also accurate to call
304 it ``GCC'' no matter what the language context; however, the term
305 ``G++'' is more useful when the emphasis is on compiling C++ programs.
309 Similarly, when we talk about Ada compilation, we usually call the
310 compiler ``GNAT'', for the same reasons.
312 We use the name ``GCC'' to refer to the compilation system as a
313 whole, and more specifically to the language-independent part of the
314 compiler. For example, we refer to the optimization options as
315 affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
317 Front ends for other languages, such as Mercury and Pascal exist but
318 have not yet been integrated into GCC@. These front ends, like that for C++,
319 are built in subdirectories of GCC and link to it. The result is an
320 integrated compiler that can compile programs written in C, C++,
321 Objective-C, or any of the languages for which you have installed front
324 In this manual, we only discuss the options for the C, Objective-C, and
325 C++ compilers and those of the GCC core. Consult the documentation
326 of the other front ends for the options to use when compiling programs
327 written in other languages.
329 @cindex compiler compared to C++ preprocessor
330 @cindex intermediate C version, nonexistent
331 @cindex C intermediate output, nonexistent
332 G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object
333 code directly from your C++ program source. There is no intermediate C
334 version of the program. (By contrast, for example, some other
335 implementations use a program that generates a C program from your C++
336 source.) Avoiding an intermediate C representation of the program means
337 that you get better object code, and better debugging information. The
338 GNU debugger, GDB, works with this information in the object code to
339 give you comprehensive C++ source-level editing capabilities
340 (@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
342 @c FIXME! Someone who knows something about Objective-C ought to put in
343 @c a paragraph or two about it here, and move the index entry down when
344 @c there is more to point to than the general mention in the 1st par.
347 @chapter Language Standards Supported by GCC
350 @cindex ANSI C standard
354 @cindex ANSI X3.159-1989
356 @cindex ISO C standard
371 @cindex Technical Corrigenda
373 @cindex Technical Corrigendum 1
375 @cindex Technical Corrigendum 2
377 @cindex freestanding implementation
378 @cindex freestanding environment
379 @cindex hosted implementation
380 @cindex hosted environment
381 @findex __STDC_HOSTED__
383 For each language compiled by GCC for which there is a standard, GCC
384 attempts to follow one or more versions of that standard, possibly
385 with some exceptions, and possibly with some extensions.
387 GCC supports three versions of the C standard, although support for
388 the most recent version is not yet complete.
393 @opindex pedantic-errors
394 The original ANSI C standard (X3.159-1989) was ratified in 1989 and
395 published in 1990. This standard was ratified as an ISO standard
396 (ISO/IEC 9899:1990) later in 1990. There were no technical
397 differences between these publications, although the sections of the
398 ANSI standard were renumbered and became clauses in the ISO standard.
399 This standard, in both its forms, is commonly known as @dfn{C89}, or
400 occasionally as @dfn{C90}, from the dates of ratification. The ANSI
401 standard, but not the ISO standard, also came with a Rationale
402 document. To select this standard in GCC, use one of the options
403 @option{-ansi}, @option{-std=c89} or @option{-std=iso9899:1990}; to obtain
404 all the diagnostics required by the standard, you should also specify
405 @option{-pedantic} (or @option{-pedantic-errors} if you want them to be
406 errors rather than warnings). @xref{C Dialect Options,,Options
407 Controlling C Dialect}.
409 Errors in the 1990 ISO C standard were corrected in two Technical
410 Corrigenda published in 1994 and 1996. GCC does not support the
413 An amendment to the 1990 standard was published in 1995. This
414 amendment added digraphs and @code{__STDC_VERSION__} to the language,
415 but otherwise concerned the library. This amendment is commonly known
416 as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
417 @dfn{C95}. To select this standard in GCC, use the option
418 @option{-std=iso9899:199409} (with, as for other standard versions,
419 @option{-pedantic} to receive all required diagnostics).
421 A new edition of the ISO C standard was published in 1999 as ISO/IEC
422 9899:1999, and is commonly known as @dfn{C99}. GCC has incomplete
423 support for this standard version; see
424 @uref{http://gcc.gnu.org/c99status.html} for details. To select this
425 standard, use @option{-std=c99} or @option{-std=iso9899:1999}. (While in
426 development, drafts of this standard version were referred to as
430 GCC also has some limited support for traditional (pre-ISO) C with the
431 @option{-traditional} option. This support may be of use for compiling
432 some very old programs that have not been updated to ISO C, but should
433 not be used for new programs. It will not work with some modern C
434 libraries such as the GNU C library.
436 By default, GCC provides some extensions to the C language that on
437 rare occasions conflict with the C standard. @xref{C
438 Extensions,,Extensions to the C Language Family}. Use of the
439 @option{-std} options listed above will disable these extensions where
440 they conflict with the C standard version selected. You may also
441 select an extended version of the C language explicitly with
442 @option{-std=gnu89} (for C89 with GNU extensions) or @option{-std=gnu99}
443 (for C99 with GNU extensions). The default, if no C language dialect
444 options are given, is @option{-std=gnu89}; this will change to
445 @option{-std=gnu99} in some future release when the C99 support is
446 complete. Some features that are part of the C99 standard are
447 accepted as extensions in C89 mode.
449 The ISO C standard defines (in clause 4) two classes of conforming
450 implementation. A @dfn{conforming hosted implementation} supports the
451 whole standard including all the library facilities; a @dfn{conforming
452 freestanding implementation} is only required to provide certain
453 library facilities: those in @code{<float.h>}, @code{<limits.h>},
454 @code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
455 @code{<iso646.h>}; and in C99, also those in @code{<stdbool.h>} and
456 @code{<stdint.h>}. In addition, complex types, added in C99, are not
457 required for freestanding implementations. The standard also defines
458 two environments for programs, a @dfn{freestanding environment},
459 required of all implementations and which may not have library
460 facilities beyond those required of freestanding implementations,
461 where the handling of program startup and termination are
462 implementation-defined, and a @dfn{hosted environment}, which is not
463 required, in which all the library facilities are provided and startup
464 is through a function @code{int main (void)} or @code{int main (int,
465 char *[])}. An OS kernel would be a freestanding environment; a
466 program using the facilities of an operating system would normally be
467 in a hosted implementation.
469 @opindex ffreestanding
470 GCC aims towards being usable as a conforming freestanding
471 implementation, or as the compiler for a conforming hosted
472 implementation. By default, it will act as the compiler for a hosted
473 implementation, defining @code{__STDC_HOSTED__} as @code{1} and
474 presuming that when the names of ISO C functions are used, they have
475 the semantics defined in the standard. To make it act as a conforming
476 freestanding implementation for a freestanding environment, use the
477 option @option{-ffreestanding}; it will then define
478 @code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
479 meanings of function names from the standard library. To build an OS
480 kernel, you may well still need to make your own arrangements for
481 linking and startup. @xref{C Dialect Options,,Options Controlling C
484 GCC does not provide the library facilities required only of hosted
485 implementations, nor yet all the facilities required by C99 of
486 freestanding implementations; to use the facilities of a hosted
487 environment, you will need to find them elsewhere (for example, in the
488 GNU C library). @xref{Standard Libraries,,Standard Libraries}.
490 For references to Technical Corrigenda, Rationale documents and
491 information concerning the history of C that is available online, see
492 @uref{http://gcc.gnu.org/readings.html}
494 @c FIXME: details of C++ standard.
496 There is no formal written standard for Objective-C@. The most
497 authoritative manual is ``Object-Oriented Programming and the
498 Objective-C Language'', available at a number of web sites;
499 @uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/} has a
500 recent version, while @uref{http://www.toodarkpark.org/computers/objc/}
501 is an older example. @uref{http://www.gnustep.org} includes useful
504 @xref{Top, GNAT Reference Manual, About This Guide, gnat_rm,
505 GNAT Reference Manual}, for information on standard
506 conformance and compatibility of the Ada compiler.
508 @xref{References,,Language Definition References, chill, GNU Chill},
509 for details of the CHILL standard.
511 @xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
512 Fortran}, for details of the Fortran language supported by GCC@.
514 @xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj},
515 for details of compatibility between @code{gcj} and the Java Platform.
519 @include install-old.texi
528 @chapter Known Causes of Trouble with GCC
530 @cindex installation trouble
531 @cindex known causes of trouble
533 This section describes known problems that affect users of GCC@. Most
534 of these are not GCC bugs per se---if they were, we would fix them.
535 But the result for a user may be like the result of a bug.
537 Some of these problems are due to bugs in other software, some are
538 missing features that are too much work to add, and some are places
539 where people's opinions differ as to what is best.
542 * Actual Bugs:: Bugs we will fix later.
543 * Cross-Compiler Problems:: Common problems of cross compiling with GCC.
544 * Interoperation:: Problems using GCC with other compilers,
545 and with certain linkers, assemblers and debuggers.
546 * External Bugs:: Problems compiling certain programs.
547 * Incompatibilities:: GCC is incompatible with traditional C.
548 * Fixed Headers:: GCC uses corrected versions of system header files.
549 This is necessary, but doesn't always work smoothly.
550 * Standard Libraries:: GCC uses the system C library, which might not be
551 compliant with the ISO C standard.
552 * Disappointments:: Regrettable things we can't change, but not quite bugs.
553 * C++ Misunderstandings:: Common misunderstandings with GNU C++.
554 * Protoize Caveats:: Things to watch out for when using @code{protoize}.
555 * Non-bugs:: Things we think are right, but some others disagree.
556 * Warnings and Errors:: Which problems in your code get warnings,
557 and which get errors.
561 @section Actual Bugs We Haven't Fixed Yet
565 The @code{fixincludes} script interacts badly with automounters; if the
566 directory of system header files is automounted, it tends to be
567 unmounted while @code{fixincludes} is running. This would seem to be a
568 bug in the automounter. We don't know any good way to work around it.
571 The @code{fixproto} script will sometimes add prototypes for the
572 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
573 @code{jmp_buf} type before that type is defined. To work around this,
574 edit the offending file and place the typedef in front of the
578 @opindex pedantic-errors
579 When @option{-pedantic-errors} is specified, GCC will incorrectly give
580 an error message when a function name is specified in an expression
581 involving the comma operator.
584 @node Cross-Compiler Problems
585 @section Cross-Compiler Problems
587 You may run into problems with cross compilation on certain machines,
592 Cross compilation can run into trouble for certain machines because
593 some target machines' assemblers require floating point numbers to be
594 written as @emph{integer} constants in certain contexts.
596 The compiler writes these integer constants by examining the floating
597 point value as an integer and printing that integer, because this is
598 simple to write and independent of the details of the floating point
599 representation. But this does not work if the compiler is running on
600 a different machine with an incompatible floating point format, or
601 even a different byte-ordering.
603 In addition, correct constant folding of floating point values
604 requires representing them in the target machine's format.
605 (The C standard does not quite require this, but in practice
606 it is the only way to win.)
608 It is now possible to overcome these problems by defining macros such
609 as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
610 work for each target machine.
612 @xref{Cross-compilation}.
615 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
616 gcc.info, Using and Porting GCC}.
620 At present, the program @file{mips-tfile} which adds debug
621 support to object files on MIPS systems does not work in a cross
626 @section Interoperation
628 This section lists various difficulties encountered in using GCC
629 together with other compilers or with the assemblers, linkers,
630 libraries and debuggers on certain systems.
634 Objective-C does not work on the RS/6000.
637 G++ does not do name mangling in the same way as other C++
638 compilers. This means that object files compiled with one compiler
639 cannot be used with another.
641 This effect is intentional, to protect you from more subtle problems.
642 Compilers differ as to many internal details of C++ implementation,
643 including: how class instances are laid out, how multiple inheritance is
644 implemented, and how virtual function calls are handled. If the name
645 encoding were made the same, your programs would link against libraries
646 provided from other compilers---but the programs would then crash when
647 run. Incompatible libraries are then detected at link time, rather than
651 Older GDB versions sometimes fail to read the output of GCC version
652 2. If you have trouble, get GDB version 4.4 or later.
656 DBX rejects some files produced by GCC, though it accepts similar
657 constructs in output from PCC@. Until someone can supply a coherent
658 description of what is valid DBX input and what is not, there is
659 nothing I can do about these problems. You are on your own.
662 The GNU assembler (GAS) does not support PIC@. To generate PIC code, you
663 must use some other assembler, such as @file{/bin/as}.
666 On some BSD systems, including some versions of Ultrix, use of profiling
667 causes static variable destructors (currently used only in C++) not to
671 @cindex @code{vfork}, for the Sun-4
673 There is a bug in @code{vfork} on the Sun-4 which causes the registers
674 of the child process to clobber those of the parent. Because of this,
675 programs that call @code{vfork} are likely to lose when compiled
676 optimized with GCC when the child code alters registers which contain
677 C variables in the parent. This affects variables which are live in the
678 parent across the call to @code{vfork}.
680 If you encounter this, you can work around the problem by declaring
681 variables @code{volatile} in the function that calls @code{vfork}, until
682 the problem goes away, or by not declaring them @code{register} and not
683 using @option{-O} for those source files.
687 On some SGI systems, when you use @option{-lgl_s} as an option,
688 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
689 Naturally, this does not happen when you use GCC@.
690 You must specify all three options explicitly.
693 On a Sparc, GCC aligns all values of type @code{double} on an 8-byte
694 boundary, and it expects every @code{double} to be so aligned. The Sun
695 compiler usually gives @code{double} values 8-byte alignment, with one
696 exception: function arguments of type @code{double} may not be aligned.
698 As a result, if a function compiled with Sun CC takes the address of an
699 argument of type @code{double} and passes this pointer of type
700 @code{double *} to a function compiled with GCC, dereferencing the
701 pointer may cause a fatal signal.
703 One way to solve this problem is to compile your entire program with GCC@.
704 Another solution is to modify the function that is compiled with
705 Sun CC to copy the argument into a local variable; local variables
706 are always properly aligned. A third solution is to modify the function
707 that uses the pointer to dereference it via the following function
708 @code{access_double} instead of directly with @samp{*}:
712 access_double (double *unaligned_ptr)
714 union d2i @{ double d; int i[2]; @};
716 union d2i *p = (union d2i *) unaligned_ptr;
727 Storing into the pointer can be done likewise with the same union.
730 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
731 may allocate memory that is only 4 byte aligned. Since GCC on the
732 Sparc assumes that doubles are 8 byte aligned, this may result in a
733 fatal signal if doubles are stored in memory allocated by the
734 @file{libmalloc.a} library.
736 The solution is to not use the @file{libmalloc.a} library. Use instead
737 @code{malloc} and related functions from @file{libc.a}; they do not have
741 Sun forgot to include a static version of @file{libdl.a} with some
742 versions of SunOS (mainly 4.1). This results in undefined symbols when
743 linking static binaries (that is, if you use @option{-static}). If you
744 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
745 when linking, compile and link against the file
746 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
749 The 128-bit long double format that the Sparc port supports currently
750 works by using the architecturally defined quad-word floating point
751 instructions. Since there is no hardware that supports these
752 instructions they must be emulated by the operating system. Long
753 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
754 kernel emulator uses an obsolete and incompatible format. Long doubles
755 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
756 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
757 does not enable them by default. Long doubles appear to work in Sun OS
761 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
762 compile GCC correctly. We do not yet know why. However, GCC
763 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
764 compile itself properly on 9.01.
767 On the HP PA machine, ADB sometimes fails to work on functions compiled
768 with GCC@. Specifically, it fails to work on functions that use
769 @code{alloca} or variable-size arrays. This is because GCC doesn't
770 generate HP-UX unwind descriptors for such functions. It may even be
771 impossible to generate them.
774 Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
775 the preliminary GNU tools (@pxref{Installation}).
778 Taking the address of a label may generate errors from the HP-UX
779 PA assembler. GAS for the PA does not have this problem.
782 Using floating point parameters for indirect calls to static functions
783 will not work when using the HP assembler. There simply is no way for GCC
784 to specify what registers hold arguments for static functions when using
785 the HP assembler. GAS for the PA does not have this problem.
788 In extremely rare cases involving some very large functions you may
789 receive errors from the HP linker complaining about an out of bounds
790 unconditional branch offset. This used to occur more often in previous
791 versions of GCC, but is now exceptionally rare. If you should run
792 into it, you can work around by making your function smaller.
795 GCC compiled code sometimes emits warnings from the HP-UX assembler of
799 (warning) Use of GR3 when
800 frame >= 8192 may cause conflict.
803 These warnings are harmless and can be safely ignored.
806 The current version of the assembler (@file{/bin/as}) for the RS/6000
807 has certain problems that prevent the @option{-g} option in GCC from
808 working. Note that @file{Makefile.in} uses @option{-g} by default when
809 compiling @file{libgcc2.c}.
811 IBM has produced a fixed version of the assembler. The upgraded
812 assembler unfortunately was not included in any of the AIX 3.2 update
813 PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request
814 PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
815 See the file @file{README.RS6000} for more details on these updates.
817 You can test for the presence of a fixed assembler by using the
825 If the command exits normally, the assembler fix already is installed.
826 If the assembler complains that @option{-u} is an unknown flag, you need to
830 On the IBM RS/6000, compiling code of the form
841 will cause the linker to report an undefined symbol @code{foo}.
842 Although this behavior differs from most other systems, it is not a
843 bug because redefining an @code{extern} variable as @code{static}
844 is undefined in ISO C@.
847 AIX on the RS/6000 provides support (NLS) for environments outside of
848 the United States. Compilers and assemblers use NLS to support
849 locale-specific representations of various objects including
850 floating-point numbers (@samp{.} vs @samp{,} for separating decimal fractions).
851 There have been problems reported where the library linked with GCC does
852 not produce the same floating-point formats that the assembler accepts.
853 If you have this problem, set the @env{LANG} environment variable to
854 @samp{C} or @samp{En_US}.
857 @opindex fdollars-in-identifiers
858 Even if you specify @option{-fdollars-in-identifiers},
859 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
860 to a restriction in the IBM assembler. GAS supports these
864 On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC
865 version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2
866 by requesting PTF 421749 from IBM@.
869 @opindex mno-serialize-volatile
870 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
871 occurs when the @samp{fldcr} instruction is used. GCC uses
872 @samp{fldcr} on the 88100 to serialize volatile memory references. Use
873 the option @option{-mno-serialize-volatile} if your version of the
874 assembler has this bug.
877 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
878 messages from the linker. These warning messages complain of mismatched
879 psect attributes. You can ignore them. @xref{VMS Install}.
882 On NewsOS version 3, if you include both of the files @file{stddef.h}
883 and @file{sys/types.h}, you get an error because there are two typedefs
884 of @code{size_t}. You should change @file{sys/types.h} by adding these
885 lines around the definition of @code{size_t}:
890 @var{actual-typedef-here}
896 On the Alliant, the system's own convention for returning structures
897 and unions is unusual, and is not compatible with GCC no matter
898 what options are used.
903 @opindex mhc-struct-return
904 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
905 convention for structure and union returning. Use the option
906 @option{-mhc-struct-return} to tell GCC to use a convention compatible
909 @cindex VAX calling convention
910 @cindex Ultrix calling convention
913 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
914 by function calls. However, the C compiler uses conventions compatible
915 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
917 GCC uses the same convention as the Ultrix C compiler. You can use
918 these options to produce code compatible with the Fortran compiler:
921 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
925 On the WE32k, you may find that programs compiled with GCC do not
926 work with the standard shared C library. You may need to link with
927 the ordinary C compiler. If you do so, you must specify the following
931 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
934 The first specifies where to find the library @file{libgcc.a}
935 specified with the @option{-lgcc} option.
937 GCC does linking by invoking @command{ld}, just as @command{cc} does, and
938 there is no reason why it @emph{should} matter which compilation program
939 you use to invoke @command{ld}. If someone tracks this problem down,
940 it can probably be fixed easily.
943 On the Alpha, you may get assembler errors about invalid syntax as a
944 result of floating point constants. This is due to a bug in the C
945 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid
946 floating point numbers, they sometimes print @samp{NaN}.
949 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
950 sometimes reorders instructions incorrectly when optimization is turned
951 on. If you think this may be happening to you, try using the GNU
952 assembler; GAS version 2.1 supports ECOFF on Irix.
955 Or use the @option{-noasmopt} option when you compile GCC with itself,
956 and then again when you compile your program. (This is a temporary
957 kludge to turn off assembler optimization on Irix.) If this proves to
958 be what you need, edit the assembler spec in the file @file{specs} so
959 that it unconditionally passes @option{-O0} to the assembler, and never
960 passes @option{-O2} or @option{-O3}.
964 @section Problems Compiling Certain Programs
966 @c prevent bad page break with this line
967 Certain programs have problems compiling.
971 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
972 because of problems in DEC's versions of the X11 header files
973 @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
974 @option{-I/usr/include/mit} to use the MIT versions of the header files,
975 using the @option{-traditional} switch to turn off ISO C, or fixing the
976 header files by adding this:
980 #define NeedFunctionPrototypes 0
985 On various 386 Unix systems derived from System V, including SCO, ISC,
986 and ESIX, you may get error messages about running out of virtual memory
987 while compiling certain programs.
989 You can prevent this problem by linking GCC with the GNU malloc
990 (which thus replaces the malloc that comes with the system). GNU malloc
991 is available as a separate package, and also in the file
992 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
994 If you have installed GNU malloc as a separate library package, use this
995 option when you relink GCC:
998 MALLOC=/usr/local/lib/libgmalloc.a
1001 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
1002 the object file to @file{gmalloc.o} and use this option when you relink
1010 @node Incompatibilities
1011 @section Incompatibilities of GCC
1012 @cindex incompatibilities of GCC
1013 @opindex traditional
1015 There are several noteworthy incompatibilities between GNU C and K&R
1016 (non-ISO) versions of C@. The @option{-traditional} option
1017 eliminates many of these incompatibilities, @emph{but not all}, by
1018 telling GCC to behave like a K&R C compiler.
1021 @cindex string constants
1022 @cindex read-only strings
1023 @cindex shared strings
1025 GCC normally makes string constants read-only. If several
1026 identical-looking string constants are used, GCC stores only one
1029 @cindex @code{mktemp}, and constant strings
1030 One consequence is that you cannot call @code{mktemp} with a string
1031 constant argument. The function @code{mktemp} always alters the
1032 string its argument points to.
1034 @cindex @code{sscanf}, and constant strings
1035 @cindex @code{fscanf}, and constant strings
1036 @cindex @code{scanf}, and constant strings
1037 Another consequence is that @code{sscanf} does not work on some systems
1038 when passed a string constant as its format control string or input.
1039 This is because @code{sscanf} incorrectly tries to write into the string
1040 constant. Likewise @code{fscanf} and @code{scanf}.
1042 @opindex fwritable-strings
1043 The best solution to these problems is to change the program to use
1044 @code{char}-array variables with initialization strings for these
1045 purposes instead of string constants. But if this is not possible,
1046 you can use the @option{-fwritable-strings} flag, which directs GCC
1047 to handle string constants the same way most C compilers do.
1048 @option{-traditional} also has this effect, among others.
1051 @code{-2147483648} is positive.
1053 This is because 2147483648 cannot fit in the type @code{int}, so
1054 (following the ISO C rules) its data type is @code{unsigned long int}.
1055 Negating this value yields 2147483648 again.
1058 GCC does not substitute macro arguments when they appear inside of
1059 string constants. For example, the following macro in GCC
1066 will produce output @code{"a"} regardless of what the argument @var{a} is.
1068 The @option{-traditional} option directs GCC to handle such cases
1069 (among others) in the old-fashioned (non-ISO) fashion.
1071 @cindex @code{setjmp} incompatibilities
1072 @cindex @code{longjmp} incompatibilities
1074 When you use @code{setjmp} and @code{longjmp}, the only automatic
1075 variables guaranteed to remain valid are those declared
1076 @code{volatile}. This is a consequence of automatic register
1077 allocation. Consider this function:
1091 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
1096 Here @code{a} may or may not be restored to its first value when the
1097 @code{longjmp} occurs. If @code{a} is allocated in a register, then
1098 its first value is restored; otherwise, it keeps the last value stored
1102 If you use the @option{-W} option with the @option{-O} option, you will
1103 get a warning when GCC thinks such a problem might be possible.
1105 The @option{-traditional} option directs GCC to put variables in
1106 the stack by default, rather than in registers, in functions that
1107 call @code{setjmp}. This results in the behavior found in
1108 traditional C compilers.
1111 Programs that use preprocessing directives in the middle of macro
1112 arguments do not work with GCC@. For example, a program like this
1123 ISO C does not permit such a construct. It would make sense to support
1124 it when @option{-traditional} is used, but it is too much work to
1128 K&R compilers allow comments to cross over an inclusion boundary
1129 (i.e.@: started in an include file and ended in the including file). I think
1130 this would be quite ugly and can't imagine it could be needed.
1132 @cindex external declaration scope
1133 @cindex scope of external declarations
1134 @cindex declaration scope
1136 Declarations of external variables and functions within a block apply
1137 only to the block containing the declaration. In other words, they
1138 have the same scope as any other declaration in the same place.
1140 In some other C compilers, a @code{extern} declaration affects all the
1141 rest of the file even if it happens within a block.
1143 The @option{-traditional} option directs GCC to treat all @code{extern}
1144 declarations as global, like traditional compilers.
1147 In traditional C, you can combine @code{long}, etc., with a typedef name,
1152 typedef long foo bar;
1155 In ISO C, this is not allowed: @code{long} and other type modifiers
1156 require an explicit @code{int}. Because this criterion is expressed
1157 by Bison grammar rules rather than C code, the @option{-traditional}
1158 flag cannot alter it.
1160 @cindex typedef names as function parameters
1162 PCC allows typedef names to be used as function parameters. The
1163 difficulty described immediately above applies here too.
1166 When in @option{-traditional} mode, GCC allows the following erroneous
1167 pair of declarations to appear together in a given scope:
1175 GCC treats all characters of identifiers as significant, even when in
1176 @option{-traditional} mode. According to K&R-1 (2.2), ``No more than the
1177 first eight characters are significant, although more may be used.''.
1178 Also according to K&R-1 (2.2), ``An identifier is a sequence of letters
1179 and digits; the first character must be a letter. The underscore _
1180 counts as a letter.'', but GCC also allows dollar signs in identifiers.
1184 PCC allows whitespace in the middle of compound assignment operators
1185 such as @samp{+=}. GCC, following the ISO standard, does not
1186 allow this. The difficulty described immediately above applies here
1192 GCC complains about unterminated character constants inside of
1193 preprocessing conditionals that fail. Some programs have English
1194 comments enclosed in conditionals that are guaranteed to fail; if these
1195 comments contain apostrophes, GCC will probably report an error. For
1196 example, this code would produce an error:
1200 You can't expect this to work.
1204 The best solution to such a problem is to put the text into an actual
1205 C comment delimited by @samp{/*@dots{}*/}. However,
1206 @option{-traditional} suppresses these error messages.
1209 Many user programs contain the declaration @samp{long time ();}. In the
1210 past, the system header files on many systems did not actually declare
1211 @code{time}, so it did not matter what type your program declared it to
1212 return. But in systems with ISO C headers, @code{time} is declared to
1213 return @code{time_t}, and if that is not the same as @code{long}, then
1214 @samp{long time ();} is erroneous.
1216 The solution is to change your program to use appropriate system headers
1217 (@code{<time.h>} on systems with ISO C headers) and not to declare
1218 @code{time} if the system header files declare it, or failing that to
1219 use @code{time_t} as the return type of @code{time}.
1221 @cindex @code{float} as function value type
1223 When compiling functions that return @code{float}, PCC converts it to
1224 a double. GCC actually returns a @code{float}. If you are concerned
1225 with PCC compatibility, you should declare your functions to return
1226 @code{double}; you might as well say what you mean.
1231 When compiling functions that return structures or unions, GCC
1232 output code normally uses a method different from that used on most
1233 versions of Unix. As a result, code compiled with GCC cannot call
1234 a structure-returning function compiled with PCC, and vice versa.
1236 The method used by GCC is as follows: a structure or union which is
1237 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
1238 with any other size is stored into an address supplied by the caller
1239 (usually in a special, fixed register, but on some machines it is passed
1240 on the stack). The machine-description macros @code{STRUCT_VALUE} and
1241 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
1243 By contrast, PCC on most target machines returns structures and unions
1244 of any size by copying the data into an area of static storage, and then
1245 returning the address of that storage as if it were a pointer value.
1246 The caller must copy the data from that memory area to the place where
1247 the value is wanted. GCC does not use this method because it is
1248 slower and nonreentrant.
1250 On some newer machines, PCC uses a reentrant convention for all
1251 structure and union returning. GCC on most of these machines uses a
1252 compatible convention when returning structures and unions in memory,
1253 but still returns small structures and unions in registers.
1255 @opindex fpcc-struct-return
1256 You can tell GCC to use a compatible convention for all structure and
1257 union returning with the option @option{-fpcc-struct-return}.
1259 @cindex preprocessing tokens
1260 @cindex preprocessing numbers
1262 GCC complains about program fragments such as @samp{0x74ae-0x4000}
1263 which appear to be two hexadecimal constants separated by the minus
1264 operator. Actually, this string is a single @dfn{preprocessing token}.
1265 Each such token must correspond to one token in C@. Since this does not,
1266 GCC prints an error message. Although it may appear obvious that what
1267 is meant is an operator and two values, the ISO C standard specifically
1268 requires that this be treated as erroneous.
1270 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
1271 begins with a digit and is followed by letters, underscores, digits,
1272 periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
1273 @samp{p-}, @samp{P+}, or @samp{P-} character sequences. (In strict C89
1274 mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
1275 appear in preprocessing numbers.)
1277 To make the above program fragment valid, place whitespace in front of
1278 the minus sign. This whitespace will end the preprocessing number.
1282 @section Fixed Header Files
1284 GCC needs to install corrected versions of some system header files.
1285 This is because most target systems have some header files that won't
1286 work with GCC unless they are changed. Some have bugs, some are
1287 incompatible with ISO C, and some depend on special features of other
1290 Installing GCC automatically creates and installs the fixed header
1291 files, by running a program called @code{fixincludes} (or for certain
1292 targets an alternative such as @code{fixinc.svr4}). Normally, you
1293 don't need to pay attention to this. But there are cases where it
1294 doesn't do the right thing automatically.
1298 If you update the system's header files, such as by installing a new
1299 system version, the fixed header files of GCC are not automatically
1300 updated. The easiest way to update them is to reinstall GCC@. (If
1301 you want to be clever, look in the makefile and you can find a
1305 On some systems, in particular SunOS 4, header file directories contain
1306 machine-specific symbolic links in certain places. This makes it
1307 possible to share most of the header files among hosts running the
1308 same version of SunOS 4 on different machine models.
1310 The programs that fix the header files do not understand this special
1311 way of using symbolic links; therefore, the directory of fixed header
1312 files is good only for the machine model used to build it.
1314 In SunOS 4, only programs that look inside the kernel will notice the
1315 difference between machine models. Therefore, for most purposes, you
1316 need not be concerned about this.
1318 It is possible to make separate sets of fixed header files for the
1319 different machine models, and arrange a structure of symbolic links so
1320 as to use the proper set, but you'll have to do this by hand.
1323 On Lynxos, GCC by default does not fix the header files. This is
1324 because bugs in the shell cause the @code{fixincludes} script to fail.
1326 This means you will encounter problems due to bugs in the system header
1327 files. It may be no comfort that they aren't GCC's fault, but it
1328 does mean that there's nothing for us to do about them.
1331 @node Standard Libraries
1332 @section Standard Libraries
1335 GCC by itself attempts to be a conforming freestanding implementation.
1336 @xref{Standards,,Language Standards Supported by GCC}, for details of
1337 what this means. Beyond the library facilities required of such an
1338 implementation, the rest of the C library is supplied by the vendor of
1339 the operating system. If that C library doesn't conform to the C
1340 standards, then your programs might get warnings (especially when using
1341 @option{-Wall}) that you don't expect.
1343 For example, the @code{sprintf} function on SunOS 4.1.3 returns
1344 @code{char *} while the C standard says that @code{sprintf} returns an
1345 @code{int}. The @code{fixincludes} program could make the prototype for
1346 this function match the Standard, but that would be wrong, since the
1347 function will still return @code{char *}.
1349 If you need a Standard compliant library, then you need to find one, as
1350 GCC does not provide one. The GNU C library (called @code{glibc})
1351 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
1352 GNU/Linux and HURD-based GNU systems; no recent version of it supports
1353 other systems, though some very old versions did. Version 2.2 of the
1354 GNU C library includes nearly complete C99 support. You could also ask
1355 your operating system vendor if newer libraries are available.
1357 @node Disappointments
1358 @section Disappointments and Misunderstandings
1360 These problems are perhaps regrettable, but we don't know any practical
1365 Certain local variables aren't recognized by debuggers when you compile
1368 This occurs because sometimes GCC optimizes the variable out of
1369 existence. There is no way to tell the debugger how to compute the
1370 value such a variable ``would have had'', and it is not clear that would
1371 be desirable anyway. So GCC simply does not mention the eliminated
1372 variable when it writes debugging information.
1374 You have to expect a certain amount of disagreement between the
1375 executable and your source code, when you use optimization.
1377 @cindex conflicting types
1378 @cindex scope of declaration
1380 Users often think it is a bug when GCC reports an error for code
1384 int foo (struct mumble *);
1386 struct mumble @{ @dots{} @};
1388 int foo (struct mumble *x)
1392 This code really is erroneous, because the scope of @code{struct
1393 mumble} in the prototype is limited to the argument list containing it.
1394 It does not refer to the @code{struct mumble} defined with file scope
1395 immediately below---they are two unrelated types with similar names in
1398 But in the definition of @code{foo}, the file-scope type is used
1399 because that is available to be inherited. Thus, the definition and
1400 the prototype do not match, and you get an error.
1402 This behavior may seem silly, but it's what the ISO standard specifies.
1403 It is easy enough for you to make your code work by moving the
1404 definition of @code{struct mumble} above the prototype. It's not worth
1405 being incompatible with ISO C just to avoid an error for the example
1409 Accesses to bit-fields even in volatile objects works by accessing larger
1410 objects, such as a byte or a word. You cannot rely on what size of
1411 object is accessed in order to read or write the bit-field; it may even
1412 vary for a given bit-field according to the precise usage.
1414 If you care about controlling the amount of memory that is accessed, use
1415 volatile but do not use bit-fields.
1418 GCC comes with shell scripts to fix certain known problems in system
1419 header files. They install corrected copies of various header files in
1420 a special directory where only GCC will normally look for them. The
1421 scripts adapt to various systems by searching all the system header
1422 files for the problem cases that we know about.
1424 If new system header files are installed, nothing automatically arranges
1425 to update the corrected header files. You will have to reinstall GCC
1426 to fix the new header files. More specifically, go to the build
1427 directory and delete the files @file{stmp-fixinc} and
1428 @file{stmp-headers}, and the subdirectory @code{include}; then do
1429 @samp{make install} again.
1432 @cindex floating point precision
1433 On 68000 and x86 systems, for instance, you can get paradoxical results
1434 if you test the precise values of floating point numbers. For example,
1435 you can find that a floating point value which is not a NaN is not equal
1436 to itself. This results from the fact that the floating point registers
1437 hold a few more bits of precision than fit in a @code{double} in memory.
1438 Compiled code moves values between memory and floating point registers
1439 at its convenience, and moving them into memory truncates them.
1441 @opindex ffloat-store
1442 You can partially avoid this problem by using the @option{-ffloat-store}
1443 option (@pxref{Optimize Options}).
1446 On the MIPS, variable argument functions using @file{varargs.h}
1447 cannot have a floating point value for the first argument. The
1448 reason for this is that in the absence of a prototype in scope,
1449 if the first argument is a floating point, it is passed in a
1450 floating point register, rather than an integer register.
1452 If the code is rewritten to use the ISO standard @file{stdarg.h}
1453 method of variable arguments, and the prototype is in scope at
1454 the time of the call, everything will work fine.
1457 On the H8/300 and H8/300H, variable argument functions must be
1458 implemented using the ISO standard @file{stdarg.h} method of
1459 variable arguments. Furthermore, calls to functions using @file{stdarg.h}
1460 variable arguments must have a prototype for the called function
1461 in scope at the time of the call.
1464 @node C++ Misunderstandings
1465 @section Common Misunderstandings with GNU C++
1467 @cindex misunderstandings in C++
1468 @cindex surprises in C++
1469 @cindex C++ misunderstandings
1470 C++ is a complex language and an evolving one, and its standard
1471 definition (the ISO C++ standard) was only recently completed. As a
1472 result, your C++ compiler may occasionally surprise you, even when its
1473 behavior is correct. This section discusses some areas that frequently
1474 give rise to questions of this sort.
1477 * Static Definitions:: Static member declarations are not definitions
1478 * Temporaries:: Temporaries may vanish before you expect
1479 * Copy Assignment:: Copy Assignment operators copy virtual bases twice
1482 @node Static Definitions
1483 @subsection Declare @emph{and} Define Static Members
1485 @cindex C++ static data, declaring and defining
1486 @cindex static data in C++, declaring and defining
1487 @cindex declaring static data in C++
1488 @cindex defining static data in C++
1489 When a class has static data members, it is not enough to @emph{declare}
1490 the static member; you must also @emph{define} it. For example:
1501 This declaration only establishes that the class @code{Foo} has an
1502 @code{int} named @code{Foo::bar}, and a member function named
1503 @code{Foo::method}. But you still need to define @emph{both}
1504 @code{method} and @code{bar} elsewhere. According to the ISO
1505 standard, you must supply an initializer in one (and only one) source
1512 Other C++ compilers may not correctly implement the standard behavior.
1513 As a result, when you switch to @code{g++} from one of these compilers,
1514 you may discover that a program that appeared to work correctly in fact
1515 does not conform to the standard: @code{g++} reports as undefined
1516 symbols any static data members that lack definitions.
1519 @subsection Temporaries May Vanish Before You Expect
1521 @cindex temporaries, lifetime of
1522 @cindex portions of temporary objects, pointers to
1523 It is dangerous to use pointers or references to @emph{portions} of a
1524 temporary object. The compiler may very well delete the object before
1525 you expect it to, leaving a pointer to garbage. The most common place
1526 where this problem crops up is in classes like string classes,
1527 especially ones that define a conversion function to type @code{char *}
1528 or @code{const char *}---which is one reason why the standard
1529 @code{string} class requires you to call the @code{c_str} member
1530 function. However, any class that returns a pointer to some internal
1531 structure is potentially subject to this problem.
1533 For example, a program may use a function @code{strfunc} that returns
1534 @code{string} objects, and another function @code{charfunc} that
1535 operates on pointers to @code{char}:
1539 void charfunc (const char *);
1544 const char *p = strfunc().c_str();
1553 In this situation, it may seem reasonable to save a pointer to the C
1554 string returned by the @code{c_str} member function and use that rather
1555 than call @code{c_str} repeatedly. However, the temporary string
1556 created by the call to @code{strfunc} is destroyed after @code{p} is
1557 initialized, at which point @code{p} is left pointing to freed memory.
1559 Code like this may run successfully under some other compilers,
1560 particularly obsolete cfront-based compilers that delete temporaries
1561 along with normal local variables. However, the GNU C++ behavior is
1562 standard-conforming, so if your program depends on late destruction of
1563 temporaries it is not portable.
1565 The safe way to write such code is to give the temporary a name, which
1566 forces it to remain until the end of the scope of the name. For
1570 string& tmp = strfunc ();
1571 charfunc (tmp.c_str ());
1574 @node Copy Assignment
1575 @subsection Implicit Copy-Assignment for Virtual Bases
1577 When a base class is virtual, only one subobject of the base class
1578 belongs to each full object. Also, the constructors and destructors are
1579 invoked only once, and called from the most-derived class. However, such
1580 objects behave unspecified when being assigned. For example:
1585 Base(char *n) : name(strdup(n))@{@}
1586 Base& operator= (const Base& other)@{
1588 name = strdup (other.name);
1592 struct A:virtual Base@{
1597 struct B:virtual Base@{
1602 struct Derived:public A, public B@{
1603 Derived():Base("Derived")@{@}
1606 void func(Derived &d1, Derived &d2)
1612 The C++ standard specifies that @samp{Base::Base} is only called once
1613 when constructing or copy-constructing a Derived object. It is
1614 unspecified whether @samp{Base::operator=} is called more than once when
1615 the implicit copy-assignment for Derived objects is invoked (as it is
1616 inside @samp{func} in the example).
1618 g++ implements the ``intuitive'' algorithm for copy-assignment: assign all
1619 direct bases, then assign all members. In that algorithm, the virtual
1620 base subobject can be encountered many times. In the example, copying
1621 proceeds in the following order: @samp{val}, @samp{name} (via
1622 @code{strdup}), @samp{bval}, and @samp{name} again.
1624 If application code relies on copy-assignment, a user-defined
1625 copy-assignment operator removes any uncertainties. With such an
1626 operator, the application can define whether and how the virtual base
1627 subobject is assigned.
1629 @node Protoize Caveats
1630 @section Caveats of using @command{protoize}
1632 The conversion programs @command{protoize} and @command{unprotoize} can
1633 sometimes change a source file in a way that won't work unless you
1638 @command{protoize} can insert references to a type name or type tag before
1639 the definition, or in a file where they are not defined.
1641 If this happens, compiler error messages should show you where the new
1642 references are, so fixing the file by hand is straightforward.
1645 There are some C constructs which @command{protoize} cannot figure out.
1646 For example, it can't determine argument types for declaring a
1647 pointer-to-function variable; this you must do by hand. @command{protoize}
1648 inserts a comment containing @samp{???} each time it finds such a
1649 variable; so you can find all such variables by searching for this
1650 string. ISO C does not require declaring the argument types of
1651 pointer-to-function types.
1654 Using @command{unprotoize} can easily introduce bugs. If the program
1655 relied on prototypes to bring about conversion of arguments, these
1656 conversions will not take place in the program without prototypes.
1657 One case in which you can be sure @command{unprotoize} is safe is when
1658 you are removing prototypes that were made with @command{protoize}; if
1659 the program worked before without any prototypes, it will work again
1662 @opindex Wconversion
1663 You can find all the places where this problem might occur by compiling
1664 the program with the @option{-Wconversion} option. It prints a warning
1665 whenever an argument is converted.
1668 Both conversion programs can be confused if there are macro calls in and
1669 around the text to be converted. In other words, the standard syntax
1670 for a declaration or definition must not result from expanding a macro.
1671 This problem is inherent in the design of C and cannot be fixed. If
1672 only a few functions have confusing macro calls, you can easily convert
1676 @command{protoize} cannot get the argument types for a function whose
1677 definition was not actually compiled due to preprocessing conditionals.
1678 When this happens, @command{protoize} changes nothing in regard to such
1679 a function. @command{protoize} tries to detect such instances and warn
1682 You can generally work around this problem by using @command{protoize} step
1683 by step, each time specifying a different set of @option{-D} options for
1684 compilation, until all of the functions have been converted. There is
1685 no automatic way to verify that you have got them all, however.
1688 Confusion may result if there is an occasion to convert a function
1689 declaration or definition in a region of source code where there is more
1690 than one formal parameter list present. Thus, attempts to convert code
1691 containing multiple (conditionally compiled) versions of a single
1692 function header (in the same vicinity) may not produce the desired (or
1695 If you plan on converting source files which contain such code, it is
1696 recommended that you first make sure that each conditionally compiled
1697 region of source code which contains an alternative function header also
1698 contains at least one additional follower token (past the final right
1699 parenthesis of the function header). This should circumvent the
1703 @command{unprotoize} can become confused when trying to convert a function
1704 definition or declaration which contains a declaration for a
1705 pointer-to-function formal argument which has the same name as the
1706 function being defined or declared. We recommend you avoid such choices
1707 of formal parameter names.
1710 You might also want to correct some of the indentation by hand and break
1711 long lines. (The conversion programs don't write lines longer than
1712 eighty characters in any case.)
1716 @section Certain Changes We Don't Want to Make
1718 This section lists changes that people frequently request, but which
1719 we do not make because we think GCC is better without them.
1723 Checking the number and type of arguments to a function which has an
1724 old-fashioned definition and no prototype.
1726 Such a feature would work only occasionally---only for calls that appear
1727 in the same file as the called function, following the definition. The
1728 only way to check all calls reliably is to add a prototype for the
1729 function. But adding a prototype eliminates the motivation for this
1730 feature. So the feature is not worthwhile.
1733 Warning about using an expression whose type is signed as a shift count.
1735 Shift count operands are probably signed more often than unsigned.
1736 Warning about this would cause far more annoyance than good.
1739 Warning about assigning a signed value to an unsigned variable.
1741 Such assignments must be very common; warning about them would cause
1742 more annoyance than good.
1745 Warning when a non-void function value is ignored.
1747 Coming as I do from a Lisp background, I balk at the idea that there is
1748 something dangerous about discarding a value. There are functions that
1749 return values which some callers may find useful; it makes no sense to
1750 clutter the program with a cast to @code{void} whenever the value isn't
1754 @opindex fshort-enums
1755 Making @option{-fshort-enums} the default.
1757 This would cause storage layout to be incompatible with most other C
1758 compilers. And it doesn't seem very important, given that you can get
1759 the same result in other ways. The case where it matters most is when
1760 the enumeration-valued object is inside a structure, and in that case
1761 you can specify a field width explicitly.
1764 Making bit-fields unsigned by default on particular machines where ``the
1765 ABI standard'' says to do so.
1767 The ISO C standard leaves it up to the implementation whether a bit-field
1768 declared plain @code{int} is signed or not. This in effect creates two
1769 alternative dialects of C@.
1771 @opindex fsigned-bitfields
1772 @opindex funsigned-bitfields
1773 The GNU C compiler supports both dialects; you can specify the signed
1774 dialect with @option{-fsigned-bitfields} and the unsigned dialect with
1775 @option{-funsigned-bitfields}. However, this leaves open the question of
1776 which dialect to use by default.
1778 Currently, the preferred dialect makes plain bit-fields signed, because
1779 this is simplest. Since @code{int} is the same as @code{signed int} in
1780 every other context, it is cleanest for them to be the same in bit-fields
1783 Some computer manufacturers have published Application Binary Interface
1784 standards which specify that plain bit-fields should be unsigned. It is
1785 a mistake, however, to say anything about this issue in an ABI@. This is
1786 because the handling of plain bit-fields distinguishes two dialects of C@.
1787 Both dialects are meaningful on every type of machine. Whether a
1788 particular object file was compiled using signed bit-fields or unsigned
1789 is of no concern to other object files, even if they access the same
1790 bit-fields in the same data structures.
1792 A given program is written in one or the other of these two dialects.
1793 The program stands a chance to work on most any machine if it is
1794 compiled with the proper dialect. It is unlikely to work at all if
1795 compiled with the wrong dialect.
1797 Many users appreciate the GNU C compiler because it provides an
1798 environment that is uniform across machines. These users would be
1799 inconvenienced if the compiler treated plain bit-fields differently on
1802 Occasionally users write programs intended only for a particular machine
1803 type. On these occasions, the users would benefit if the GNU C compiler
1804 were to support by default the same dialect as the other compilers on
1805 that machine. But such applications are rare. And users writing a
1806 program to run on more than one type of machine cannot possibly benefit
1807 from this kind of compatibility.
1809 This is why GCC does and will treat plain bit-fields in the same
1810 fashion on all types of machines (by default).
1812 There are some arguments for making bit-fields unsigned by default on all
1813 machines. If, for example, this becomes a universal de facto standard,
1814 it would make sense for GCC to go along with it. This is something
1815 to be considered in the future.
1817 (Of course, users strongly concerned about portability should indicate
1818 explicitly in each bit-field whether it is signed or not. In this way,
1819 they write programs which have the same meaning in both C dialects.)
1823 @opindex traditional
1825 Undefining @code{__STDC__} when @option{-ansi} is not used.
1827 Currently, GCC defines @code{__STDC__} as long as you don't use
1828 @option{-traditional}. This provides good results in practice.
1830 Programmers normally use conditionals on @code{__STDC__} to ask whether
1831 it is safe to use certain features of ISO C, such as function
1832 prototypes or ISO token concatenation. Since plain @command{gcc} supports
1833 all the features of ISO C, the correct answer to these questions is
1836 Some users try to use @code{__STDC__} to check for the availability of
1837 certain library facilities. This is actually incorrect usage in an ISO
1838 C program, because the ISO C standard says that a conforming
1839 freestanding implementation should define @code{__STDC__} even though it
1840 does not have the library facilities. @samp{gcc -ansi -pedantic} is a
1841 conforming freestanding implementation, and it is therefore required to
1842 define @code{__STDC__}, even though it does not come with an ISO C
1845 Sometimes people say that defining @code{__STDC__} in a compiler that
1846 does not completely conform to the ISO C standard somehow violates the
1847 standard. This is illogical. The standard is a standard for compilers
1848 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
1849 compilers such as plain @command{gcc}. Whatever the ISO C standard says
1850 is relevant to the design of plain @command{gcc} without @option{-ansi} only
1851 for pragmatic reasons, not as a requirement.
1853 GCC normally defines @code{__STDC__} to be 1, and in addition
1854 defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
1855 or a @option{-std} option for strict conformance to some version of ISO C@.
1856 On some hosts, system include files use a different convention, where
1857 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
1858 conformance to the C Standard. GCC follows the host convention when
1859 processing system include files, but when processing user files it follows
1860 the usual GNU C convention.
1863 Undefining @code{__STDC__} in C++.
1865 Programs written to compile with C++-to-C translators get the
1866 value of @code{__STDC__} that goes with the C compiler that is
1867 subsequently used. These programs must test @code{__STDC__}
1868 to determine what kind of C preprocessor that compiler uses:
1869 whether they should concatenate tokens in the ISO C fashion
1870 or in the traditional fashion.
1872 These programs work properly with GNU C++ if @code{__STDC__} is defined.
1873 They would not work otherwise.
1875 In addition, many header files are written to provide prototypes in ISO
1876 C but not in traditional C@. Many of these header files can work without
1877 change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
1878 is not defined, they will all fail, and will all need to be changed to
1879 test explicitly for C++ as well.
1882 Deleting ``empty'' loops.
1884 Historically, GCC has not deleted ``empty'' loops under the
1885 assumption that the most likely reason you would put one in a program is
1886 to have a delay, so deleting them will not make real programs run any
1889 However, the rationale here is that optimization of a nonempty loop
1890 cannot produce an empty one, which holds for C but is not always the
1893 @opindex funroll-loops
1894 Moreover, with @option{-funroll-loops} small ``empty'' loops are already
1895 removed, so the current behavior is both sub-optimal and inconsistent
1896 and will change in the future.
1899 Making side effects happen in the same order as in some other compiler.
1901 @cindex side effects, order of evaluation
1902 @cindex order of evaluation, side effects
1903 It is never safe to depend on the order of evaluation of side effects.
1904 For example, a function call like this may very well behave differently
1905 from one compiler to another:
1908 void func (int, int);
1914 There is no guarantee (in either the C or the C++ standard language
1915 definitions) that the increments will be evaluated in any particular
1916 order. Either increment might happen first. @code{func} might get the
1917 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
1920 Not allowing structures with volatile fields in registers.
1922 Strictly speaking, there is no prohibition in the ISO C standard
1923 against allowing structures with volatile fields in registers, but
1924 it does not seem to make any sense and is probably not what you wanted
1925 to do. So the compiler will give an error message in this case.
1928 Making certain warnings into errors by default.
1930 Some ISO C testsuites report failure when the compiler does not produce
1931 an error message for a certain program.
1933 @opindex pedantic-errors
1934 ISO C requires a ``diagnostic'' message for certain kinds of invalid
1935 programs, but a warning is defined by GCC to count as a diagnostic. If
1936 GCC produces a warning but not an error, that is correct ISO C support.
1937 If test suites call this ``failure'', they should be run with the GCC
1938 option @option{-pedantic-errors}, which will turn these warnings into
1943 @node Warnings and Errors
1944 @section Warning Messages and Error Messages
1946 @cindex error messages
1947 @cindex warnings vs errors
1948 @cindex messages, warning and error
1949 The GNU compiler can produce two kinds of diagnostics: errors and
1950 warnings. Each kind has a different purpose:
1954 @dfn{Errors} report problems that make it impossible to compile your
1955 program. GCC reports errors with the source file name and line
1956 number where the problem is apparent.
1959 @dfn{Warnings} report other unusual conditions in your code that
1960 @emph{may} indicate a problem, although compilation can (and does)
1961 proceed. Warning messages also report the source file name and line
1962 number, but include the text @samp{warning:} to distinguish them
1963 from error messages.
1966 Warnings may indicate danger points where you should check to make sure
1967 that your program really does what you intend; or the use of obsolete
1968 features; or the use of nonstandard features of GNU C or C++. Many
1969 warnings are issued only if you ask for them, with one of the @option{-W}
1970 options (for instance, @option{-Wall} requests a variety of useful
1974 @opindex pedantic-errors
1975 GCC always tries to compile your program if possible; it never
1976 gratuitously rejects a program whose meaning is clear merely because
1977 (for instance) it fails to conform to a standard. In some cases,
1978 however, the C and C++ standards specify that certain extensions are
1979 forbidden, and a diagnostic @emph{must} be issued by a conforming
1980 compiler. The @option{-pedantic} option tells GCC to issue warnings in
1981 such cases; @option{-pedantic-errors} says to make them errors instead.
1982 This does not mean that @emph{all} non-ISO constructs get warnings
1985 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
1986 more detail on these and related command-line options.
1989 @chapter Reporting Bugs
1991 @cindex reporting bugs
1993 Your bug reports play an essential role in making GCC reliable.
1995 When you encounter a problem, the first thing to do is to see if it is
1996 already known. @xref{Trouble}. If it isn't known, then you should
1999 Reporting a bug may help you by bringing a solution to your problem, or
2000 it may not. (If it does not, look in the service directory; see
2001 @ref{Service}.) In any case, the principal function of a bug report is
2002 to help the entire community by making the next version of GCC work
2003 better. Bug reports are your contribution to the maintenance of GCC@.
2005 Since the maintainers are very overloaded, we cannot respond to every
2006 bug report. However, if the bug has not been fixed, we are likely to
2007 send you a patch and ask you to tell us whether it works.
2009 In order for a bug report to serve its purpose, you must include the
2010 information that makes for fixing the bug.
2013 * Criteria: Bug Criteria. Have you really found a bug?
2014 * Where: Bug Lists. Where to send your bug report.
2015 * Reporting: Bug Reporting. How to report a bug effectively.
2016 * GNATS: gccbug. You can use a bug reporting tool.
2017 * Known: Trouble. Known problems.
2018 * Help: Service. Where to ask for help.
2021 @node Bug Criteria,Bug Lists,,Bugs
2022 @section Have You Found a Bug?
2023 @cindex bug criteria
2025 If you are not sure whether you have found a bug, here are some guidelines:
2028 @cindex fatal signal
2031 If the compiler gets a fatal signal, for any input whatever, that is a
2032 compiler bug. Reliable compilers never crash.
2034 @cindex invalid assembly code
2035 @cindex assembly code, invalid
2037 If the compiler produces invalid assembly code, for any input whatever
2038 (except an @code{asm} statement), that is a compiler bug, unless the
2039 compiler reports errors (not just warnings) which would ordinarily
2040 prevent the assembler from being run.
2042 @cindex undefined behavior
2043 @cindex undefined function value
2044 @cindex increment operators
2046 If the compiler produces valid assembly code that does not correctly
2047 execute the input source code, that is a compiler bug.
2049 However, you must double-check to make sure, because you may have run
2050 into an incompatibility between GNU C and traditional C
2051 (@pxref{Incompatibilities}). These incompatibilities might be considered
2052 bugs, but they are inescapable consequences of valuable features.
2054 Or you may have a program whose behavior is undefined, which happened
2055 by chance to give the desired results with another C or C++ compiler.
2057 For example, in many nonoptimizing compilers, you can write @samp{x;}
2058 at the end of a function instead of @samp{return x;}, with the same
2059 results. But the value of the function is undefined if @code{return}
2060 is omitted; it is not a bug when GCC produces different results.
2062 Problems often result from expressions with two increment operators,
2063 as in @code{f (*p++, *p++)}. Your previous compiler might have
2064 interpreted that expression the way you intended; GCC might
2065 interpret it another way. Neither compiler is wrong. The bug is
2068 After you have localized the error to a single source line, it should
2069 be easy to check for these things. If your program is correct and
2070 well defined, you have found a compiler bug.
2073 If the compiler produces an error message for valid input, that is a
2076 @cindex invalid input
2078 If the compiler does not produce an error message for invalid input,
2079 that is a compiler bug. However, you should note that your idea of
2080 ``invalid input'' might be my idea of ``an extension'' or ``support
2081 for traditional practice''.
2084 If you are an experienced user of one of the languages GCC supports, your
2085 suggestions for improvement of GCC are welcome in any case.
2088 @node Bug Lists,Bug Reporting,Bug Criteria,Bugs
2089 @section Where to Report Bugs
2090 @cindex bug report mailing lists
2091 @kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
2092 Send bug reports for the GNU Compiler Collection to
2093 @email{gcc-bugs@@gcc.gnu.org}. In accordance with the GNU-wide
2094 convention, in which bug reports for tool ``foo'' are sent
2095 to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
2096 may also be used; it will forward to the address given above.
2098 Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or
2099 more up-to-date bug reporting instructions before you post a bug report.
2101 @node Bug Reporting,gccbug,Bug Lists,Bugs
2102 @section How to Report Bugs
2103 @cindex compiler bugs, reporting
2105 The fundamental principle of reporting bugs usefully is this:
2106 @strong{report all the facts}. If you are not sure whether to state a
2107 fact or leave it out, state it!
2109 Often people omit facts because they think they know what causes the
2110 problem and they conclude that some details don't matter. Thus, you might
2111 assume that the name of the variable you use in an example does not matter.
2112 Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
2113 stray memory reference which happens to fetch from the location where that
2114 name is stored in memory; perhaps, if the name were different, the contents
2115 of that location would fool the compiler into doing the right thing despite
2116 the bug. Play it safe and give a specific, complete example. That is the
2117 easiest thing for you to do, and the most helpful.
2119 Keep in mind that the purpose of a bug report is to enable someone to
2120 fix the bug if it is not known. It isn't very important what happens if
2121 the bug is already known. Therefore, always write your bug reports on
2122 the assumption that the bug is not known.
2124 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2125 bell?'' This cannot help us fix a bug, so it is basically useless. We
2126 respond by asking for enough details to enable us to investigate.
2127 You might as well expedite matters by sending them to begin with.
2129 Try to make your bug report self-contained. If we have to ask you for
2130 more information, it is best if you include all the previous information
2131 in your response, as well as the information that was missing.
2133 Please report each bug in a separate message. This makes it easier for
2134 us to track which bugs have been fixed and to forward your bugs reports
2135 to the appropriate maintainer.
2137 To enable someone to investigate the bug, you should include all these
2142 The version of GCC@. You can get this by running it with the
2145 Without this, we won't know whether there is any point in looking for
2146 the bug in the current version of GCC@.
2149 A complete input file that will reproduce the bug. If the bug is in the
2150 C preprocessor, send a source file and any header files that it
2151 requires. If the bug is in the compiler proper (@file{cc1}), send the
2152 preprocessor output generated by adding @option{-save-temps} to the
2153 compilation command (@pxref{Debugging Options}). When you do this, use
2154 the same @option{-I}, @option{-D} or @option{-U} options that you used in
2155 actual compilation. Then send the @var{input}.i or @var{input}.ii files
2158 A single statement is not enough of an example. In order to compile it,
2159 it must be embedded in a complete file of compiler input; and the bug
2160 might depend on the details of how this is done.
2162 Without a real example one can compile, all anyone can do about your bug
2163 report is wish you luck. It would be futile to try to guess how to
2164 provoke the bug. For example, bugs in register allocation and reloading
2165 frequently depend on every little detail of the function they happen in.
2167 Even if the input file that fails comes from a GNU program, you should
2168 still send the complete test case. Don't ask the GCC maintainers to
2169 do the extra work of obtaining the program in question---they are all
2170 overworked as it is. Also, the problem may depend on what is in the
2171 header files on your system; it is unreliable for the GCC maintainers
2172 to try the problem with the header files available to them. By sending
2173 CPP output, you can eliminate this source of uncertainty and save us
2174 a certain percentage of wild goose chases.
2177 The command arguments you gave GCC to compile that example
2178 and observe the bug. For example, did you use @option{-O}? To guarantee
2179 you won't omit something important, list all the options.
2181 If we were to try to guess the arguments, we would probably guess wrong
2182 and then we would not encounter the bug.
2185 The type of machine you are using, and the operating system name and
2189 The operands you gave to the @code{configure} command when you installed
2193 A complete list of any modifications you have made to the compiler
2194 source. (We don't promise to investigate the bug unless it happens in
2195 an unmodified compiler. But if you've made modifications and don't tell
2196 us, then you are sending us on a wild goose chase.)
2198 Be precise about these changes. A description in English is not
2199 enough---send a context diff for them.
2201 Adding files of your own (such as a machine description for a machine we
2202 don't support) is a modification of the compiler source.
2205 Details of any other deviations from the standard procedure for installing
2209 A description of what behavior you observe that you believe is
2210 incorrect. For example, ``The compiler gets a fatal signal,'' or,
2211 ``The assembler instruction at line 208 in the output is incorrect.''
2213 Of course, if the bug is that the compiler gets a fatal signal, then one
2214 can't miss it. But if the bug is incorrect output, the maintainer might
2215 not notice unless it is glaringly wrong. None of us has time to study
2216 all the assembler code from a 50-line C program just on the chance that
2217 one instruction might be wrong. We need @emph{you} to do this part!
2219 Even if the problem you experience is a fatal signal, you should still
2220 say so explicitly. Suppose something strange is going on, such as, your
2221 copy of the compiler is out of synch, or you have encountered a bug in
2222 the C library on your system. (This has happened!) Your copy might
2223 crash and the copy here would not. If you @i{said} to expect a crash,
2224 then when the compiler here fails to crash, we would know that the bug
2225 was not happening. If you don't say to expect a crash, then we would
2226 not know whether the bug was happening. We would not be able to draw
2227 any conclusion from our observations.
2229 If the problem is a diagnostic when compiling GCC with some other
2230 compiler, say whether it is a warning or an error.
2232 Often the observed symptom is incorrect output when your program is run.
2233 Sad to say, this is not enough information unless the program is short
2234 and simple. None of us has time to study a large program to figure out
2235 how it would work if compiled correctly, much less which line of it was
2236 compiled wrong. So you will have to do that. Tell us which source line
2237 it is, and what incorrect result happens when that line is executed. A
2238 person who understands the program can find this as easily as finding a
2239 bug in the program itself.
2242 If you send examples of assembler code output from GCC,
2243 please use @option{-g} when you make them. The debugging information
2244 includes source line numbers which are essential for correlating the
2245 output with the input.
2248 If you wish to mention something in the GCC source, refer to it by
2249 context, not by line number.
2251 The line numbers in the development sources don't match those in your
2252 sources. Your line numbers would convey no useful information to the
2256 Additional information from a debugger might enable someone to find a
2257 problem on a machine which he does not have available. However, you
2258 need to think when you collect this information if you want it to have
2259 any chance of being useful.
2261 @cindex backtrace for bug reports
2262 For example, many people send just a backtrace, but that is never
2263 useful by itself. A simple backtrace with arguments conveys little
2264 about GCC because the compiler is largely data-driven; the same
2265 functions are called over and over for different RTL insns, doing
2266 different things depending on the details of the insn.
2268 Most of the arguments listed in the backtrace are useless because they
2269 are pointers to RTL list structure. The numeric values of the
2270 pointers, which the debugger prints in the backtrace, have no
2271 significance whatever; all that matters is the contents of the objects
2272 they point to (and most of the contents are other such pointers).
2274 In addition, most compiler passes consist of one or more loops that
2275 scan the RTL insn sequence. The most vital piece of information about
2276 such a loop---which insn it has reached---is usually in a local variable,
2280 What you need to provide in addition to a backtrace are the values of
2281 the local variables for several stack frames up. When a local
2282 variable or an argument is an RTX, first print its value and then use
2283 the GDB command @code{pr} to print the RTL expression that it points
2284 to. (If GDB doesn't run on your machine, use your debugger to call
2285 the function @code{debug_rtx} with the RTX as an argument.) In
2286 general, whenever a variable is a pointer, its value is no use
2287 without the data it points to.
2290 Here are some things that are not necessary:
2294 A description of the envelope of the bug.
2296 Often people who encounter a bug spend a lot of time investigating
2297 which changes to the input file will make the bug go away and which
2298 changes will not affect it.
2300 This is often time consuming and not very useful, because the way we
2301 will find the bug is by running a single example under the debugger with
2302 breakpoints, not by pure deduction from a series of examples. You might
2303 as well save your time for something else.
2305 Of course, if you can find a simpler example to report @emph{instead} of
2306 the original one, that is a convenience. Errors in the output will be
2307 easier to spot, running under the debugger will take less time, etc.
2308 Most GCC bugs involve just one function, so the most straightforward
2309 way to simplify an example is to delete all the function definitions
2310 except the one where the bug occurs. Those earlier in the file may be
2311 replaced by external declarations if the crucial function depends on
2312 them. (Exception: inline functions may affect compilation of functions
2313 defined later in the file.)
2315 However, simplification is not vital; if you don't want to do this,
2316 report the bug anyway and send the entire test case you used.
2319 In particular, some people insert conditionals @samp{#ifdef BUG} around
2320 a statement which, if removed, makes the bug not happen. These are just
2321 clutter; we won't pay any attention to them anyway. Besides, you should
2322 send us cpp output, and that can't have conditionals.
2325 A patch for the bug.
2327 A patch for the bug is useful if it is a good one. But don't omit the
2328 necessary information, such as the test case, on the assumption that a
2329 patch is all we need. We might see problems with your patch and decide
2330 to fix the problem another way, or we might not understand it at all.
2332 Sometimes with a program as complicated as GCC it is very hard to
2333 construct an example that will make the program follow a certain path
2334 through the code. If you don't send the example, we won't be able to
2335 construct one, so we won't be able to verify that the bug is fixed.
2337 And if we can't understand what bug you are trying to fix, or why your
2338 patch should be an improvement, we won't install it. A test case will
2339 help us to understand.
2341 See @uref{http://gcc.gnu.org/contribute.html}
2342 for guidelines on how to make it easy for us to
2343 understand and install your patches.
2346 A guess about what the bug is or what it depends on.
2348 Such guesses are usually wrong. Even I can't guess right about such
2349 things without first using the debugger to find the facts.
2354 We have no way of examining a core dump for your type of machine
2355 unless we have an identical system---and if we do have one,
2356 we should be able to reproduce the crash ourselves.
2359 @node gccbug,, Bug Reporting, Bugs
2360 @section The gccbug script
2361 @cindex gccbug script
2363 To simplify creation of bug reports, and to allow better tracking of
2364 reports, we use the GNATS bug tracking system. Part of that system is
2365 the @code{gccbug} script. This is a Unix shell script, so you need a
2366 shell to run it. It is normally installed in the same directory where
2367 @code{gcc} is installed.
2369 The gccbug script is derived from send-pr, @pxref{using
2370 send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
2371 invoked, it starts a text editor so you can fill out the various fields
2372 of the report. When the you quit the editor, the report is automatically
2373 send to the bug reporting address.
2375 A number of fields in this bug report form are specific to GCC, and are
2376 explained at @uref{http://gcc.gnu.org/gnats.html}.
2379 @chapter How To Get Help with GCC
2381 If you need help installing, using or changing GCC, there are two
2386 Send a message to a suitable network mailing list. First try
2387 @email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
2388 that brings no response, try @email{gcc@@gcc.gnu.org}. For help
2389 changing GCC, ask @email{gcc@@gcc.gnu.org}. If you think you have found
2390 a bug in GCC, please report it following the instructions at
2391 @pxref{Bug Reporting}.
2394 Look in the service directory for someone who might help you for a fee.
2395 The service directory is found at
2396 @uref{http://www.gnu.org/prep/service.html}.
2399 @c For further information, see
2400 @c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}.
2401 @c FIXME: this URL may be too volatile, this FAQ entry needs to move to
2402 @c the regular web pages before we can uncomment the reference.
2405 @chapter Contributing to GCC Development
2407 If you would like to help pretest GCC releases to assure they work well,
2408 our current development sources are available by CVS (see
2409 @uref{http://gcc.gnu.org/cvs.html}). Source and binary snapshots are
2410 also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
2412 If you would like to work on improvements to GCC, please read the
2413 advice at these URLs:
2416 @uref{http://gcc.gnu.org/contribute.html}
2417 @uref{http://gcc.gnu.org/contributewhy.html}
2421 for information on how to make useful contributions and avoid
2422 duplication of effort. Suggested projects are listed at
2423 @uref{http://gcc.gnu.org/projects/}.
2426 @chapter Using GCC on VMS
2428 @c prevent bad page break with this line
2429 Here is how to use GCC on VMS@.
2432 * Include Files and VMS:: Where the preprocessor looks for the include files.
2433 * Global Declarations:: How to do globaldef, globalref and globalvalue with
2435 * VMS Misc:: Misc information.
2438 @node Include Files and VMS
2439 @section Include Files and VMS
2441 @cindex include files and VMS
2442 @cindex VMS and include files
2443 @cindex header files and VMS
2444 Due to the differences between the filesystems of Unix and VMS, GCC
2445 attempts to translate file names in @samp{#include} into names that VMS
2446 will understand. The basic strategy is to prepend a prefix to the
2447 specification of the include file, convert the whole filename to a VMS
2448 filename, and then try to open the file. GCC tries various prefixes
2449 one by one until one of them succeeds:
2453 The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
2454 where GNU C header files are traditionally stored. If you wish to store
2455 header files in non-standard locations, then you can assign the logical
2456 @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
2457 list is suitable for use with a rooted logical.
2460 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where
2461 VAX-C header files are traditionally stored.
2464 If the include file specification by itself is a valid VMS filename, the
2465 preprocessor then uses this name with no prefix in an attempt to open
2469 If the file specification is not a valid VMS filename (i.e.@: does not
2470 contain a device or a directory specifier, and contains a @samp{/}
2471 character), the preprocessor tries to convert it from Unix syntax to
2474 Conversion works like this: the first directory name becomes a device,
2475 and the rest of the directories are converted into VMS-format directory
2476 names. For example, the name @file{X11/foobar.h} is
2477 translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
2478 whichever one can be opened. This strategy allows you to assign a
2479 logical name to point to the actual location of the header files.
2482 If none of these strategies succeeds, the @samp{#include} fails.
2485 Include directives of the form:
2492 are a common source of incompatibility between VAX-C and GCC@. VAX-C
2493 treats this much like a standard @code{#include <foobar.h>} directive.
2494 That is incompatible with the ISO C behavior implemented by GCC: to
2495 expand the name @code{foobar} as a macro. Macro expansion should
2496 eventually yield one of the two standard formats for @code{#include}:
2499 #include "@var{file}"
2500 #include <@var{file}>
2503 If you have this problem, the best solution is to modify the source to
2504 convert the @code{#include} directives to one of the two standard forms.
2505 That will work with either compiler. If you want a quick and dirty fix,
2506 define the file names as macros with the proper expansion, like this:
2509 #define stdio <stdio.h>
2513 This will work, as long as the name doesn't conflict with anything else
2516 Another source of incompatibility is that VAX-C assumes that:
2523 is actually asking for the file @file{foobar.h}. GCC does not
2524 make this assumption, and instead takes what you ask for literally;
2525 it tries to read the file @file{foobar}. The best way to avoid this
2526 problem is to always specify the desired file extension in your include
2529 GCC for VMS is distributed with a set of include files that is
2530 sufficient to compile most general purpose programs. Even though the
2531 GCC distribution does not contain header files to define constants
2532 and structures for some VMS system-specific functions, there is no
2533 reason why you cannot use GCC with any of these functions. You first
2534 may have to generate or create header files, either by using the public
2535 domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
2536 extracting the relevant modules from one of the system macro libraries,
2537 and using an editor to construct a C header file.
2539 A @code{#include} file name cannot contain a DECNET node name. The
2540 preprocessor reports an I/O error if you attempt to use a node name,
2541 whether explicitly, or implicitly via a logical name.
2543 @node Global Declarations
2544 @section Global Declarations and VMS
2548 @findex GLOBALVALUEDEF
2549 @findex GLOBALVALUEREF
2550 GCC does not provide the @code{globalref}, @code{globaldef} and
2551 @code{globalvalue} keywords of VAX-C@. You can get the same effect with
2552 an obscure feature of GAS, the GNU assembler. (This requires GAS
2553 version 1.39 or later.) The following macros allow you to use this
2554 feature in a fairly natural way:
2558 #define GLOBALREF(TYPE,NAME) \
2560 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
2561 #define GLOBALDEF(TYPE,NAME,VALUE) \
2563 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
2565 #define GLOBALVALUEREF(TYPE,NAME) \
2566 const TYPE NAME[1] \
2567 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
2568 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2569 const TYPE NAME[1] \
2570 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \
2573 #define GLOBALREF(TYPE,NAME) \
2575 #define GLOBALDEF(TYPE,NAME,VALUE) \
2576 globaldef TYPE NAME = VALUE
2577 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2578 globalvalue TYPE NAME = VALUE
2579 #define GLOBALVALUEREF(TYPE,NAME) \
2580 globalvalue TYPE NAME
2585 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
2586 name is removed by the assembler, after it has modified the attributes
2587 of the symbol). These macros are provided in the VMS binaries
2588 distribution in a header file @file{GNU_HACKS.H}. An example of the
2592 GLOBALREF (int, ijk);
2593 GLOBALDEF (int, jkl, 0);
2596 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
2597 straightforwardly for arrays, since there is no way to insert the array
2598 dimension into the declaration at the right place. However, you can
2599 declare an array with these macros if you first define a typedef for the
2600 array type, like this:
2603 typedef int intvector[10];
2604 GLOBALREF (intvector, foo);
2607 Array and structure initializers will also break the macros; you can
2608 define the initializer to be a macro of its own, or you can expand the
2609 @code{GLOBALDEF} macro by hand. You may find a case where you wish to
2610 use the @code{GLOBALDEF} macro with a large array, but you are not
2611 interested in explicitly initializing each element of the array. In
2612 such cases you can use an initializer like: @code{@{0,@}}, which will
2613 initialize the entire array to @code{0}.
2615 A shortcoming of this implementation is that a variable declared with
2616 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For
2617 example, the declaration:
2620 GLOBALVALUEREF(int, ijk);
2624 declares the variable @code{ijk} as an array of type @code{int [1]}.
2625 This is done because a globalvalue is actually a constant; its ``value''
2626 is what the linker would normally consider an address. That is not how
2627 an integer value works in C, but it is how an array works. So treating
2628 the symbol as an array name gives consistent results---with the
2629 exception that the value seems to have the wrong type. @strong{Don't
2630 try to access an element of the array.} It doesn't have any elements.
2631 The array ``address'' may not be the address of actual storage.
2633 The fact that the symbol is an array may lead to warnings where the
2634 variable is used. Insert type casts to avoid the warnings. Here is an
2635 example; it takes advantage of the ISO C feature allowing macros that
2636 expand to use the same name as the macro itself.
2639 GLOBALVALUEREF (int, ss$_normal);
2640 GLOBALVALUEDEF (int, xyzzy,123);
2642 #define ss$_normal ((int) ss$_normal)
2643 #define xyzzy ((int) xyzzy)
2647 Don't use @code{globaldef} or @code{globalref} with a variable whose
2648 type is an enumeration type; this is not implemented. Instead, make the
2649 variable an integer, and use a @code{globalvaluedef} for each of the
2650 enumeration values. An example of this would be:
2654 GLOBALDEF (int, color, 0);
2655 GLOBALVALUEDEF (int, RED, 0);
2656 GLOBALVALUEDEF (int, BLUE, 1);
2657 GLOBALVALUEDEF (int, GREEN, 3);
2659 enum globaldef color @{RED, BLUE, GREEN = 3@};
2664 @section Other VMS Issues
2666 @cindex exit status and VMS
2667 @cindex return value of @code{main}
2668 @cindex @code{main} and the exit status
2669 GCC automatically arranges for @code{main} to return 1 by default if
2670 you fail to specify an explicit return value. This will be interpreted
2671 by VMS as a status code indicating a normal successful completion.
2672 Version 1 of GCC did not provide this default.
2674 GCC on VMS works only with the GNU assembler, GAS@. You need version
2675 1.37 or later of GAS in order to produce value debugging information for
2676 the VMS debugger. Use the ordinary VMS linker with the object files
2679 @cindex shared VMS run time system
2680 @cindex @file{VAXCRTL}
2681 Under previous versions of GCC, the generated code would occasionally
2682 give strange results when linked to the sharable @file{VAXCRTL} library.
2683 Now this should work.
2685 A caveat for use of @code{const} global variables: the @code{const}
2686 modifier must be specified in every external declaration of the variable
2687 in all of the source files that use that variable. Otherwise the linker
2688 will issue warnings about conflicting attributes for the variable. Your
2689 program will still work despite the warnings, but the variable will be
2690 placed in writable storage.
2692 @cindex name augmentation
2693 @cindex case sensitivity and VMS
2694 @cindex VMS and case sensitivity
2695 Although the VMS linker does distinguish between upper and lower case
2696 letters in global symbols, most VMS compilers convert all such symbols
2697 into upper case and most run-time library routines also have upper case
2698 names. To be able to reliably call such routines, GCC (by means of
2699 the assembler GAS) converts global symbols into upper case like other
2700 VMS compilers. However, since the usual practice in C is to distinguish
2701 case, GCC (via GAS) tries to preserve usual C behavior by augmenting
2702 each name that is not all lower case. This means truncating the name
2703 to at most 23 characters and then adding more characters at the end
2704 which encode the case pattern of those 23. Names which contain at
2705 least one dollar sign are an exception; they are converted directly into
2706 upper case without augmentation.
2708 Name augmentation yields bad results for programs that use precompiled
2709 libraries (such as Xlib) which were generated by another compiler. You
2710 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
2711 it makes external C functions and variables case-independent as is usual
2712 on VMS@. Alternatively, you could write all references to the functions
2713 and variables in such libraries using lower case; this will work on VMS,
2714 but is not portable to other systems. The compiler option @samp{/NAMES}
2715 also provides control over global name handling.
2717 Function and variable names are handled somewhat differently with G++.
2718 The GNU C++ compiler performs @dfn{name mangling} on function
2719 names, which means that it adds information to the function name to
2720 describe the data types of the arguments that the function takes. One
2721 result of this is that the name of a function can become very long.
2722 Since the VMS linker only recognizes the first 31 characters in a name,
2723 special action is taken to ensure that each function and variable has a
2724 unique name that can be represented in 31 characters.
2726 If the name (plus a name augmentation, if required) is less than 32
2727 characters in length, then no special action is performed. If the name
2728 is longer than 31 characters, the assembler (GAS) will generate a
2729 hash string based upon the function name, truncate the function name to
2730 23 characters, and append the hash string to the truncated name. If the
2731 @samp{/VERBOSE} compiler option is used, the assembler will print both
2732 the full and truncated names of each symbol that is truncated.
2734 The @samp{/NOCASE_HACK} compiler option should not be used when you are
2735 compiling programs that use libg++. libg++ has several instances of
2736 objects (i.e. @code{Filebuf} and @code{filebuf}) which become
2737 indistinguishable in a case-insensitive environment. This leads to
2738 cases where you need to inhibit augmentation selectively (if you were
2739 using libg++ and Xlib in the same program, for example). There is no
2740 special feature for doing this, but you can get the result by defining a
2741 macro for each mixed case symbol for which you wish to inhibit
2742 augmentation. The macro should expand into the lower case equivalent of
2743 itself. For example:
2746 #define StuDlyCapS studlycaps
2749 These macro definitions can be placed in a header file to minimize the
2750 number of changes to your source code.
2753 @chapter Additional Makefile and configure information.
2755 @section Makefile Targets
2756 @cindex makefile targets
2757 @cindex targets, makefile
2761 This is the default target. Depending on what your build/host/target
2762 configuration is, it coordinates all the things that need to be built.
2765 Produce info-formatted documentation. Also, @code{make dvi} is
2766 available for DVI-formatted documentation, and @code{make
2767 generated-manpages} to generate man pages.
2770 Delete the files made while building the compiler.
2773 That, and all the other files built by @code{make all}.
2776 That, and all the files created by @code{configure}.
2779 That, and any temporary or intermediate files, like emacs backup files.
2781 @item maintainer-clean
2782 Distclean plus any file that can be generated from other files. Note
2783 that additional tools may be required beyond what is normally needed to
2790 Deletes installed files.
2793 Run the testsuite. This creates a @file{testsuite} subdirectory that
2794 has various @file{.sum} and @file{.log} files containing the results of
2795 the testing. You can run subsets with, for example, @code{make check-gcc}.
2796 You can specify specific tests by setting RUNTESTFLAGS to be the name
2797 of the @file{.exp} file, optionally followed by (for some tests) an equals
2798 and a file wildcard, like:
2801 make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
2804 Note that running the testsuite may require additional tools be
2805 installed, such as TCL or dejagnu.
2808 Builds gcc three times---once with the native compiler, once with the
2809 native-built compiler it just built, and once with the compiler it built
2810 the second time. In theory, the last two should produce the same
2811 results, which @code{make compare} can check. Each step of this process
2812 is called a ``stage'', and the results of each stage @var{N}
2813 (@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}.
2815 @item bootstrap-lean
2816 Like @code{bootstrap}, except that the various stages are removed once
2817 they're no longer needed. This saves disk space.
2820 Once bootstrapped, this incrementally rebuilds each of the three stages,
2821 one at a time. It does this by ``bubbling'' the stages up from their
2822 subdirectories, rebuilding them, and copying them back to their
2823 subdirectories. This will allow you to, for example, quickly rebuild a
2824 bootstrapped compiler after changing the sources, without having to do a
2828 Rebuilds the most recently built stage. Since each stage requires
2829 special invocation, using this target means you don't have to keep track
2830 of which stage you're on or what invocation that stage needs.
2833 Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}).
2835 @item stage@var{N} (@var{N} = 1@dots{}4)
2836 For each stage, moves the appropriate files to the @file{stage@var{N}}
2839 @item unstage@var{N} (@var{N} = 1@dots{}4)
2840 Undoes the corresponding @code{stage@var{N}}.
2842 @item restage@var{N} (@var{N} = 1@dots{}4)
2843 Undoes the corresponding @code{stage@var{N}} and rebuilds it with the
2847 Compares the results of stages 2 and 3. This ensures that the compiler
2848 is running properly, since it should produce the same object files
2849 regardless of how it itself was compiled.
2853 @section Configure Terms and History
2854 @cindex configure terms
2857 This section is not instructions for building GCC. If you are trying to
2858 do a build, you should first read @uref{http://gcc.gnu.org/install/} or
2859 whatever installation instructions came with your source package.
2861 The configure and build process has a long and colorful history, and can
2862 be confusing to anyone who doesn't know why things are the way they are.
2863 While there are other documents which describe the configuration process
2864 in detail, here are a few things that everyone working on GCC should
2867 There are three system names that the build knows about: the machine you
2868 are building on (@dfn{build}), the machine that you are building for
2869 (@dfn{host}), and the machine that GCC will produce code for
2870 (@dfn{target}). When you configure GCC, you specify these with
2871 @option{--build=}, @option{--host=}, and @option{--target=}.
2873 Specifying the host without specifying the build should be avoided, as
2874 @command{configure} may (and once did) assume that the host you specify
2875 is also the build, which may not be true.
2877 If build, host, and target are all the same, this is called a
2878 @dfn{native}. If build and host are the same but target is different,
2879 this is called a @dfn{cross}. If build, host, and target are all
2880 different this is called a @dfn{canadian} (for obscure reasons dealing
2881 with Canada's political party and the background of the person working
2882 on the build at that time). If host and target are the same, but build
2883 is different, you are using a cross-compiler to build a native for a
2884 different system. Some people call this a @dfn{host-x-host},
2885 @dfn{crossed native}, or @dfn{cross-built native}. If build and target
2886 are the same, but host is different, you are using a cross compiler to
2887 build a cross compiler that produces code for the machine you're
2888 building on. This is rare, so there is no common say of describing it
2889 (although I propose calling it a @dfn{crossback}).
2891 If build and host are the same, the GCC you are building will also be
2892 used to build the target libraries (like @code{libstdc++}). If build and host
2893 are different, you must have already build and installed a cross
2894 compiler that will be used to build the target libraries (if you
2895 configured with @option{--target=foo-bar}, this compiler will be called
2896 @command{foo-bar-gcc}).
2898 In the case of target libraries, the machine you're building for is the
2899 machine you specified with @option{--target}. So, build is the machine
2900 you're building on (no change there), host is the machine you're
2901 building for (the target libraries are built for the target, so host is
2902 the target you specified), and target doesn't apply (because you're not
2903 building a compiler, you're building libraries). The configure/make
2904 process will adjust these variables as needed. It also sets
2905 @code{$with_cross_host} to the original @option{--host} value in case you
2908 Libiberty, for example, is built twice. The first time, host comes from
2909 @option{--host} and the second time host comes from @option{--target}.
2910 Historically, libiberty has not been built for the build machine,
2911 though, which causes some interesting issues with programs used to
2912 generate sources for the build. Fixing this, so that libiberty is built
2913 three times, has long been on the to-do list.
2919 @chapter GCC and Portability
2921 @cindex GCC and portability
2923 The main goal of GCC was to make a good, fast compiler for machines in
2924 the class that the GNU system aims to run on: 32-bit machines that address
2925 8-bit bytes and have several general registers. Elegance, theoretical
2926 power and simplicity are only secondary.
2928 GCC gets most of the information about the target machine from a machine
2929 description which gives an algebraic formula for each of the machine's
2930 instructions. This is a very clean way to describe the target. But when
2931 the compiler needs information that is difficult to express in this
2932 fashion, I have not hesitated to define an ad-hoc parameter to the machine
2933 description. The purpose of portability is to reduce the total work needed
2934 on the compiler; it was not of interest for its own sake.
2937 @cindex autoincrement addressing, availability
2939 GCC does not contain machine dependent code, but it does contain code
2940 that depends on machine parameters such as endianness (whether the most
2941 significant byte has the highest or lowest address of the bytes in a word)
2942 and the availability of autoincrement addressing. In the RTL-generation
2943 pass, it is often necessary to have multiple strategies for generating code
2944 for a particular kind of syntax tree, strategies that are usable for different
2945 combinations of parameters. Often I have not tried to address all possible
2946 cases, but only the common ones or only the ones that I have encountered.
2947 As a result, a new target may require additional strategies. You will know
2948 if this happens because the compiler will call @code{abort}. Fortunately,
2949 the new strategies can be added in a machine-independent fashion, and will
2950 affect only the target machines that need them.
2955 @chapter Interfacing to GCC Output
2956 @cindex interfacing to GCC output
2957 @cindex run-time conventions
2958 @cindex function call conventions
2959 @cindex conventions, run-time
2961 GCC is normally configured to use the same function calling convention
2962 normally in use on the target system. This is done with the
2963 machine-description macros described (@pxref{Target Macros}).
2965 @cindex unions, returning
2966 @cindex structures, returning
2967 @cindex returning structures and unions
2968 However, returning of structure and union values is done differently on
2969 some target machines. As a result, functions compiled with PCC
2970 returning such types cannot be called from code compiled with GCC,
2971 and vice versa. This does not cause trouble often because few Unix
2972 library routines return structures or unions.
2974 GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
2975 long in the same registers used for @code{int} or @code{double} return
2976 values. (GCC typically allocates variables of such types in
2977 registers also.) Structures and unions of other sizes are returned by
2978 storing them into an address passed by the caller (usually in a
2979 register). The machine-description macros @code{STRUCT_VALUE} and
2980 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
2982 By contrast, PCC on most target machines returns structures and unions
2983 of any size by copying the data into an area of static storage, and then
2984 returning the address of that storage as if it were a pointer value.
2985 The caller must copy the data from that memory area to the place where
2986 the value is wanted. This is slower than the method used by GCC, and
2987 fails to be reentrant.
2989 On some target machines, such as RISC machines and the 80386, the
2990 standard system convention is to pass to the subroutine the address of
2991 where to return the value. On these machines, GCC has been
2992 configured to be compatible with the standard compiler, when this method
2993 is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
2995 @cindex argument passing
2996 @cindex passing arguments
2997 GCC uses the system's standard convention for passing arguments. On
2998 some machines, the first few arguments are passed in registers; in
2999 others, all are passed on the stack. It would be possible to use
3000 registers for argument passing on any machine, and this would probably
3001 result in a significant speedup. But the result would be complete
3002 incompatibility with code that follows the standard convention. So this
3003 change is practical only if you are switching to GCC as the sole C
3004 compiler for the system. We may implement register argument passing on
3005 certain machines once we have a complete GNU system so that we can
3006 compile the libraries with GCC@.
3008 On some machines (particularly the Sparc), certain types of arguments
3009 are passed ``by invisible reference''. This means that the value is
3010 stored in memory, and the address of the memory location is passed to
3013 @cindex @code{longjmp} and automatic variables
3014 If you use @code{longjmp}, beware of automatic variables. ISO C says that
3015 automatic variables that are not declared @code{volatile} have undefined
3016 values after a @code{longjmp}. And this is all GCC promises to do,
3017 because it is very difficult to restore register variables correctly, and
3018 one of GCC's features is that it can put variables in registers without
3021 If you want a variable to be unaltered by @code{longjmp}, and you don't
3022 want to write @code{volatile} because old C compilers don't accept it,
3023 just take the address of the variable. If a variable's address is ever
3024 taken, even if just to compute it and ignore it, then the variable cannot
3035 @cindex arithmetic libraries
3036 @cindex math libraries
3037 @opindex msoft-float
3038 Code compiled with GCC may call certain library routines. Most of
3039 them handle arithmetic for which there are no instructions. This
3040 includes multiply and divide on some machines, and floating point
3041 operations on any machine for which floating point support is disabled
3042 with @option{-msoft-float}. Some standard parts of the C library, such as
3043 @code{bcopy} or @code{memcpy}, are also called automatically. The usual
3044 function call interface is used for calling the library routines.
3046 Some of these routines can be defined in mostly machine-independent C;
3047 they appear in @file{libgcc2.c}. Others must be hand-written in
3048 assembly language for each processor. Wherever they are defined, they
3049 are compiled into the support library, @file{libgcc.a}, which is
3050 automatically searched when you link programs with GCC@.
3055 @chapter Passes and Files of the Compiler
3056 @cindex passes and files of the compiler
3057 @cindex files and passes of the compiler
3058 @cindex compiler passes and files
3060 @cindex top level of compiler
3061 The overall control structure of the compiler is in @file{toplev.c}. This
3062 file is responsible for initialization, decoding arguments, opening and
3063 closing files, and sequencing the passes.
3065 @cindex parsing pass
3066 The parsing pass is invoked only once, to parse the entire input. A
3067 high level tree representation is then generated from the input,
3068 one function at a time. This tree code is then transformed into RTL
3069 intermediate code, and processed. The files involved in transforming
3070 the trees into RTL are @file{expr.c}, @file{expmed.c}, and
3072 @c Note, the above files aren't strictly the only files involved. It's
3073 @c all over the place (function.c, final.c,etc). However, those are
3074 @c the files that are supposed to be directly involved, and have
3075 @c their purpose listed as such, so i've only listed them.
3076 The order of trees that are processed, is not
3077 necessarily the same order they are generated from
3078 the input, due to deferred inlining, and other considerations.
3080 @findex rest_of_compilation
3081 @findex rest_of_decl_compilation
3082 Each time the parsing pass reads a complete function definition or
3083 top-level declaration, it calls either the function
3084 @code{rest_of_compilation}, or the function
3085 @code{rest_of_decl_compilation} in @file{toplev.c}, which are
3086 responsible for all further processing necessary, ending with output of
3087 the assembler language. All other compiler passes run, in sequence,
3088 within @code{rest_of_compilation}. When that function returns from
3089 compiling a function definition, the storage used for that function
3090 definition's compilation is entirely freed, unless it is an inline
3091 function, or was deferred for some reason (this can occur in
3092 templates, for example).
3094 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3097 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3100 Here is a list of all the passes of the compiler and their source files.
3101 Also included is a description of where debugging dumps can be requested
3102 with @option{-d} options.
3106 Parsing. This pass reads the entire text of a function definition,
3107 constructing a high level tree representation. (Because of the semantic
3108 analysis that takes place during this pass, it does more than is
3109 formally considered to be parsing.)
3111 The tree representation does not entirely follow C syntax, because it is
3112 intended to support other languages as well.
3114 Language-specific data type analysis is also done in this pass, and every
3115 tree node that represents an expression has a data type attached.
3116 Variables are represented as declaration nodes.
3118 The language-independent source files for parsing are
3119 @file{tree.c}, @file{fold-const.c}, and @file{stor-layout.c}.
3120 There are also header files @file{tree.h} and @file{tree.def}
3121 which define the format of the tree representation.
3123 C preprocessing, for language front ends, that want or require it, is
3124 performed by cpplib, which is covered in separate documentation. In
3125 particular, the internals are covered in @xref{Top, ,Cpplib internals,
3126 cppinternals, Cpplib Internals}.
3128 @c Avoiding overfull is tricky here.
3129 The source files to parse C are
3135 @file{c-aux-info.c},
3138 along with a header file
3140 and some files shared with Objective-C and C++.
3142 The source files for parsing C++ are in @file{cp/}.
3143 They are @file{parse.y},
3145 @file{cvt.c}, @file{decl.c}, @file{decl2.c},
3147 @file{expr.c}, @file{init.c}, @file{lex.c},
3148 @file{method.c}, @file{ptree.c},
3149 @file{search.c}, @file{spew.c},
3150 @file{semantics.c}, @file{tree.c},
3151 @file{typeck2.c}, and
3152 @file{typeck.c}, along with header files @file{cp-tree.def},
3153 @file{cp-tree.h}, and @file{decl.h}.
3155 The special source files for parsing Objective-C are in @file{objc/}.
3156 They are @file{objc-act.c}, @file{objc-tree.def}, and @file{objc-act.h}.
3157 Certain C-specific files are used for this as well.
3161 @file{c-common.def},
3165 @file{c-semantics.c},
3168 along with header files
3174 are also used for all of the above languages.
3177 @cindex Tree optimization
3179 Tree optimization. This is the optimization of the tree
3180 representation, before converting into RTL code.
3182 @cindex inline on trees, automatic
3183 Currently, the main optimization performed here is tree-based
3185 This is implemented for C++ in @file{cp/optimize.c}. Note that
3186 tree based inlining turns off rtx based inlining (since it's more
3187 powerful, it would be a waste of time to do rtx based inlining in
3189 The C front end currently does not perform tree based inlining.
3191 @cindex constant folding
3192 @cindex arithmetic simplifications
3193 @cindex simplifications, arithmetic
3194 Constant folding and some arithmetic simplifications are also done
3195 during this pass, on the tree representation.
3196 The routines that perform these tasks are located in @file{fold-const.c}.
3198 @cindex RTL generation
3200 RTL generation. This is the conversion of syntax tree into RTL code.
3202 @cindex target-parameter-dependent code
3203 This is where the bulk of target-parameter-dependent code is found,
3204 since often it is necessary for strategies to apply only when certain
3205 standard kinds of instructions are available. The purpose of named
3206 instruction patterns is to provide this information to the RTL
3209 @cindex tail recursion optimization
3210 Optimization is done in this pass for @code{if}-conditions that are
3211 comparisons, boolean operations or conditional expressions. Tail
3212 recursion is detected at this time also. Decisions are made about how
3213 best to arrange loops and how to output @code{switch} statements.
3215 @c Avoiding overfull is tricky here.
3216 The source files for RTL generation include
3224 and @file{emit-rtl.c}.
3226 @file{insn-emit.c}, generated from the machine description by the
3227 program @code{genemit}, is used in this pass. The header file
3228 @file{expr.h} is used for communication within this pass.
3232 The header files @file{insn-flags.h} and @file{insn-codes.h},
3233 generated from the machine description by the programs @code{genflags}
3234 and @code{gencodes}, tell this pass which standard names are available
3235 for use and which patterns correspond to them.
3237 Aside from debugging information output, none of the following passes
3238 refers to the tree structure representation of the function (only
3239 part of which is saved).
3241 @cindex inline on rtx, automatic
3242 The decision of whether the function can and should be expanded inline
3243 in its subsequent callers is made at the end of rtl generation. The
3244 function must meet certain criteria, currently related to the size of
3245 the function and the types and number of parameters it has. Note that
3246 this function may contain loops, recursive calls to itself
3247 (tail-recursive functions can be inlined!), gotos, in short, all
3248 constructs supported by GCC@. The file @file{integrate.c} contains
3249 the code to save a function's rtl for later inlining and to inline that
3250 rtl when the function is called. The header file @file{integrate.h}
3251 is also used for this purpose.
3254 The option @option{-dr} causes a debugging dump of the RTL code after
3255 this pass. This dump file's name is made by appending @samp{.rtl} to
3256 the input file name.
3258 @c Should the exception handling pass be talked about here?
3260 @cindex sibling call optimization
3262 Sibiling call optimization. This pass performs tail recursion
3263 elimination, and tail and sibling call optimizations. The purpose of
3264 these optimizations is to reduce the overhead of function calls,
3267 The source file of this pass is @file{sibcall.c}
3270 The option @option{-di} causes a debugging dump of the RTL code after
3271 this pass is run. This dump file's name is made by appending
3272 @samp{.sibling} to the input file name.
3274 @cindex jump optimization
3275 @cindex unreachable code
3278 Jump optimization. This pass simplifies jumps to the following
3279 instruction, jumps across jumps, and jumps to jumps. It deletes
3280 unreferenced labels and unreachable code, except that unreachable code
3281 that contains a loop is not recognized as unreachable in this pass.
3282 (Such loops are deleted later in the basic block analysis.) It also
3283 converts some code originally written with jumps into sequences of
3284 instructions that directly set values from the results of comparisons,
3285 if the machine has such instructions.
3287 Jump optimization is performed two or three times. The first time is
3288 immediately following RTL generation. The second time is after CSE,
3289 but only if CSE says repeated jump optimization is needed. The
3290 last time is right before the final pass. That time, cross-jumping
3291 and deletion of no-op move instructions are done together with the
3292 optimizations described above.
3294 The source file of this pass is @file{jump.c}.
3297 The option @option{-dj} causes a debugging dump of the RTL code after
3298 this pass is run for the first time. This dump file's name is made by
3299 appending @samp{.jump} to the input file name.
3302 @cindex register use analysis
3304 Register scan. This pass finds the first and last use of each
3305 register, as a guide for common subexpression elimination. Its source
3306 is in @file{regclass.c}.
3308 @cindex jump threading
3310 @opindex fthread-jumps
3311 Jump threading. This pass detects a condition jump that branches to an
3312 identical or inverse test. Such jumps can be @samp{threaded} through
3313 the second conditional test. The source code for this pass is in
3314 @file{jump.c}. This optimization is only performed if
3315 @option{-fthread-jumps} is enabled.
3317 @cindex SSA optimizations
3318 @cindex Single Static Assignment optimizations
3321 Static Single Assignment (SSA) based optimization passes. The
3322 SSA conversion passes (to/from) are turned on by the @option{-fssa}
3323 option (it is also done automatically if you enable an SSA optimization pass).
3324 These passes utilize a form called Static Single Assignment. In SSA form,
3325 each variable (pseudo register) is only set once, giving you def-use
3326 and use-def chains for free, and enabling a lot more optimization
3327 passes to be run in linear time.
3328 Conversion to and from SSA form is handled by functions in
3332 The option @option{-de} causes a debugging dump of the RTL code after
3333 this pass. This dump file's name is made by appending @samp{.ssa} to
3334 the input file name.
3336 @cindex SSA Conditional Constant Propagation
3337 @cindex Conditional Constant Propagation, SSA based
3338 @cindex conditional constant propagation
3341 SSA Conditional Constant Propagation. Turned on by the @option{-fssa-ccp}
3342 SSA Aggressive Dead Code Elimination. Turned on by the @option{-fssa-dce}
3343 option. This pass performs conditional constant propagation to simplify
3344 instructions including conditional branches. This pass is more aggressive
3345 than the constant propgation done by the CSE and GCSE pases, but operates
3349 The option @option{-dW} causes a debugging dump of the RTL code after
3350 this pass. This dump file's name is made by appending @samp{.ssaccp} to
3351 the input file name.
3354 @cindex DCE, SSA based
3355 @cindex dead code elimination
3358 SSA Aggressive Dead Code Elimination. Turned on by the @option{-fssa-dce}
3359 option. This pass performs elimination of code considered unnecessary because
3360 it has no externally visible effects on the program. It operates in
3364 The option @option{-dX} causes a debugging dump of the RTL code after
3365 this pass. This dump file's name is made by appending @samp{.ssadce} to
3366 the input file name.
3369 @cindex common subexpression elimination
3370 @cindex constant propagation
3372 Common subexpression elimination. This pass also does constant
3373 propagation. Its source files are @file{cse.c}, and @file{cselib.c}.
3374 If constant propagation causes conditional jumps to become
3375 unconditional or to become no-ops, jump optimization is run again when
3379 The option @option{-ds} causes a debugging dump of the RTL code after
3380 this pass. This dump file's name is made by appending @samp{.cse} to
3381 the input file name.
3383 @cindex global common subexpression elimination
3384 @cindex constant propagation
3385 @cindex copy propagation
3387 Global common subexpression elimination. This pass performs two
3388 different types of GCSE depending on whether you are optimizing for
3389 size or not (LCM based GCSE tends to increase code size for a gain in
3390 speed, while Morel-Renvoise based GCSE does not).
3391 When optimizing for size, GCSE is done using Morel-Renvoise Partial
3392 Redundancy Elimination, with the exception that it does not try to move
3393 invariants out of loops---that is left to the loop optimization pass.
3394 If MR PRE GCSE is done, code hoisting (aka unification) is also done, as
3395 well as load motion.
3396 If you are optimizing for speed, LCM (lazy code motion) based GCSE is
3397 done. LCM is based on the work of Knoop, Ruthing, and Steffen. LCM
3398 based GCSE also does loop invariant code motion. We also perform load
3399 and store motion when optimizing for speed.
3400 Regardless of which type of GCSE is used, the GCSE pass also performs
3401 global constant and copy propagation.
3403 The source file for this pass is @file{gcse.c}, and the LCM routines
3404 are in @file{lcm.c}.
3407 The option @option{-dG} causes a debugging dump of the RTL code after
3408 this pass. This dump file's name is made by appending @samp{.gcse} to
3409 the input file name.
3411 @cindex loop optimization
3413 @cindex strength-reduction
3415 Loop optimization. This pass moves constant expressions out of loops,
3416 and optionally does strength-reduction and loop unrolling as well.
3417 Its source files are @file{loop.c} and @file{unroll.c}, plus the header
3418 @file{loop.h} used for communication between them. Loop unrolling uses
3419 some functions in @file{integrate.c} and the header @file{integrate.h}.
3420 Loop dependency analysis routines are contained in @file{dependence.c}.
3423 The option @option{-dL} causes a debugging dump of the RTL code after
3424 this pass. This dump file's name is made by appending @samp{.loop} to
3425 the input file name.
3428 @opindex frerun-cse-after-loop
3429 If @option{-frerun-cse-after-loop} was enabled, a second common
3430 subexpression elimination pass is performed after the loop optimization
3431 pass. Jump threading is also done again at this time if it was specified.
3434 The option @option{-dt} causes a debugging dump of the RTL code after
3435 this pass. This dump file's name is made by appending @samp{.cse2} to
3436 the input file name.
3438 @cindex data flow analysis
3439 @cindex analysis, data flow
3440 @cindex basic blocks
3442 Data flow analysis (@file{flow.c}). This pass divides the program
3443 into basic blocks (and in the process deletes unreachable loops); then
3444 it computes which pseudo-registers are live at each point in the
3445 program, and makes the first instruction that uses a value point at
3446 the instruction that computed the value.
3448 @cindex autoincrement/decrement analysis
3449 This pass also deletes computations whose results are never used, and
3450 combines memory references with add or subtract instructions to make
3451 autoincrement or autodecrement addressing.
3454 The option @option{-df} causes a debugging dump of the RTL code after
3455 this pass. This dump file's name is made by appending @samp{.flow} to
3456 the input file name. If stupid register allocation is in use, this
3457 dump file reflects the full results of such allocation.
3459 @cindex instruction combination
3461 Instruction combination (@file{combine.c}). This pass attempts to
3462 combine groups of two or three instructions that are related by data
3463 flow into single instructions. It combines the RTL expressions for
3464 the instructions by substitution, simplifies the result using algebra,
3465 and then attempts to match the result against the machine description.
3468 The option @option{-dc} causes a debugging dump of the RTL code after
3469 this pass. This dump file's name is made by appending @samp{.combine}
3470 to the input file name.
3472 @cindex if conversion
3474 If-conversion is a transformation that transforms control dependencies
3475 into data dependencies (IE it transforms conditional code into a
3476 single control stream).
3477 It is implemented in the file @file{ifcvt.c}.
3480 The option @option{-dE} causes a debugging dump of the RTL code after
3481 this pass. This dump file's name is made by appending @samp{.ce} to
3482 the input file name.
3484 @cindex register movement
3486 Register movement (@file{regmove.c}). This pass looks for cases where
3487 matching constraints would force an instruction to need a reload, and
3488 this reload would be a register to register move. It then attempts
3489 to change the registers used by the instruction to avoid the move
3493 The option @option{-dN} causes a debugging dump of the RTL code after
3494 this pass. This dump file's name is made by appending @samp{.regmove}
3495 to the input file name.
3497 @cindex instruction scheduling
3498 @cindex scheduling, instruction
3500 Instruction scheduling (@file{sched.c}). This pass looks for
3501 instructions whose output will not be available by the time that it is
3502 used in subsequent instructions. (Memory loads and floating point
3503 instructions often have this behavior on RISC machines). It re-orders
3504 instructions within a basic block to try to separate the definition and
3505 use of items that otherwise would cause pipeline stalls.
3507 Instruction scheduling is performed twice. The first time is immediately
3508 after instruction combination and the second is immediately after reload.
3511 The option @option{-dS} causes a debugging dump of the RTL code after this
3512 pass is run for the first time. The dump file's name is made by
3513 appending @samp{.sched} to the input file name.
3515 @cindex register class preference pass
3517 Register class preferencing. The RTL code is scanned to find out
3518 which register class is best for each pseudo register. The source
3519 file is @file{regclass.c}.
3521 @cindex register allocation
3522 @cindex local register allocation
3524 Local register allocation (@file{local-alloc.c}). This pass allocates
3525 hard registers to pseudo registers that are used only within one basic
3526 block. Because the basic block is linear, it can use fast and
3527 powerful techniques to do a very good job.
3530 The option @option{-dl} causes a debugging dump of the RTL code after
3531 this pass. This dump file's name is made by appending @samp{.lreg} to
3532 the input file name.
3534 @cindex global register allocation
3536 Global register allocation (@file{global.c}). This pass
3537 allocates hard registers for the remaining pseudo registers (those
3538 whose life spans are not contained in one basic block).
3542 Reloading. This pass renumbers pseudo registers with the hardware
3543 registers numbers they were allocated. Pseudo registers that did not
3544 get hard registers are replaced with stack slots. Then it finds
3545 instructions that are invalid because a value has failed to end up in
3546 a register, or has ended up in a register of the wrong kind. It fixes
3547 up these instructions by reloading the problematical values
3548 temporarily into registers. Additional instructions are generated to
3551 The reload pass also optionally eliminates the frame pointer and inserts
3552 instructions to save and restore call-clobbered registers around calls.
3554 Source files are @file{reload.c} and @file{reload1.c}, plus the header
3555 @file{reload.h} used for communication between them.
3558 The option @option{-dg} causes a debugging dump of the RTL code after
3559 this pass. This dump file's name is made by appending @samp{.greg} to
3560 the input file name.
3562 @cindex instruction scheduling
3563 @cindex scheduling, instruction
3565 Instruction scheduling is repeated here to try to avoid pipeline stalls
3566 due to memory loads generated for spilled pseudo registers.
3569 The option @option{-dR} causes a debugging dump of the RTL code after
3570 this pass. This dump file's name is made by appending @samp{.sched2}
3571 to the input file name.
3573 @cindex basic block reordering
3574 @cindex reordering, block
3576 Basic block reordering. This pass implements profile guided code
3577 positioning. If profile information is not available, various types of
3578 static analysis are performed to make the predictions normally coming
3579 from the profile feedback (IE execution frequency, branch probability,
3580 etc). It is implemented in the file @file{bb-reorder.c}, and the
3581 various prediction routines are in @file{predict.c}.
3584 The option @option{-dB} causes a debugging dump of the RTL code after
3585 this pass. This dump file's name is made by appending @samp{.bbro} to
3586 the input file name.
3588 @cindex cross-jumping
3589 @cindex no-op move instructions
3591 Jump optimization is repeated, this time including cross-jumping
3592 and deletion of no-op move instructions.
3595 The option @option{-dJ} causes a debugging dump of the RTL code after
3596 this pass. This dump file's name is made by appending @samp{.jump2}
3597 to the input file name.
3599 @cindex delayed branch scheduling
3600 @cindex scheduling, delayed branch
3602 Delayed branch scheduling. This optional pass attempts to find
3603 instructions that can go into the delay slots of other instructions,
3604 usually jumps and calls. The source file name is @file{reorg.c}.
3607 The option @option{-dd} causes a debugging dump of the RTL code after
3608 this pass. This dump file's name is made by appending @samp{.dbr}
3609 to the input file name.
3611 @cindex branch shortening
3613 Branch shortening. On many RISC machines, branch instructions have a
3614 limited range. Thus, longer sequences of instructions must be used for
3615 long branches. In this pass, the compiler figures out what how far each
3616 instruction will be from each other instruction, and therefore whether
3617 the usual instructions, or the longer sequences, must be used for each
3620 @cindex register-to-stack conversion
3622 Conversion from usage of some hard registers to usage of a register
3623 stack may be done at this point. Currently, this is supported only
3624 for the floating-point registers of the Intel 80387 coprocessor. The
3625 source file name is @file{reg-stack.c}.
3628 The options @option{-dk} causes a debugging dump of the RTL code after
3629 this pass. This dump file's name is made by appending @samp{.stack}
3630 to the input file name.
3633 @cindex peephole optimization
3635 Final. This pass outputs the assembler code for the function. It is
3636 also responsible for identifying spurious test and compare
3637 instructions. Machine-specific peephole optimizations are performed
3638 at the same time. The function entry and exit sequences are generated
3639 directly as assembler code in this pass; they never exist as RTL@.
3641 The source files are @file{final.c} plus @file{insn-output.c}; the
3642 latter is generated automatically from the machine description by the
3643 tool @file{genoutput}. The header file @file{conditions.h} is used
3644 for communication between these files.
3646 @cindex debugging information generation
3648 Debugging information output. This is run after final because it must
3649 output the stack slot offsets for pseudo registers that did not get
3650 hard registers. Source files are @file{dbxout.c} for DBX symbol table
3651 format, @file{sdbout.c} for SDB symbol table format, @file{dwarfout.c}
3652 for DWARF symbol table format, and the files @file{dwarf2out.c} and
3653 @file{dwarf2asm.c} for DWARF2 symbol table format.
3656 Some additional files are used by all or many passes:
3660 Every pass uses @file{machmode.def} and @file{machmode.h} which define
3664 Several passes use @file{real.h}, which defines the default
3665 representation of floating point constants and how to operate on them.
3668 All the passes that work with RTL use the header files @file{rtl.h}
3669 and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
3670 @code{gen*} also use these files to read and work with the machine
3674 All the tools that read the machine description use support routines
3675 found in @file{gensupport.c}, @file{errors.c}, and @file{read-rtl.c}.
3679 Several passes refer to the header file @file{insn-config.h} which
3680 contains a few parameters (C macro definitions) generated
3681 automatically from the machine description RTL by the tool
3684 @cindex instruction recognizer
3686 Several passes use the instruction recognizer, which consists of
3687 @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
3688 and @file{insn-extract.c} that are generated automatically from the
3689 machine description by the tools @file{genrecog} and
3693 Several passes use the header files @file{regs.h} which defines the
3694 information recorded about pseudo register usage, and @file{basic-block.h}
3695 which defines the information recorded about basic blocks.
3698 @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
3699 with a bit for each hard register, and some macros to manipulate it.
3700 This type is just @code{int} if the machine has few enough hard registers;
3701 otherwise it is an array of @code{int} and some of the macros expand
3705 Several passes use instruction attributes. A definition of the
3706 attributes defined for a particular machine is in file
3707 @file{insn-attr.h}, which is generated from the machine description by
3708 the program @file{genattr}. The file @file{insn-attrtab.c} contains
3709 subroutines to obtain the attribute values for insns. It is generated
3710 from the machine description by the program @file{genattrtab}.
3715 @include c-tree.texi
3723 @chapter The Configuration File
3724 @cindex configuration file
3725 @cindex @file{xm-@var{machine}.h}
3727 The configuration file @file{xm-@var{machine}.h} contains macro
3728 definitions that describe the machine and system on which the compiler
3729 is running, unlike the definitions in @file{@var{machine}.h}, which
3730 describe the machine for which the compiler is producing output. Most
3731 of the values in @file{xm-@var{machine}.h} are actually the same on all
3732 machines that GCC runs on, so large parts of all configuration files
3733 are identical. But there are some macros that vary:
3738 Define this macro if the host system is System V@.
3742 Define this macro if the host system is VMS@.
3744 @findex FATAL_EXIT_CODE
3745 @item FATAL_EXIT_CODE
3746 A C expression for the status code to be returned when the compiler
3747 exits after serious errors. The default is the system-provided macro
3748 @samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
3749 macro. Define this macro only if these defaults are incorrect.
3751 @findex SUCCESS_EXIT_CODE
3752 @item SUCCESS_EXIT_CODE
3753 A C expression for the status code to be returned when the compiler
3754 exits without serious errors. (Warnings are not serious errors.) The
3755 default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
3756 the system doesn't define that macro. Define this macro only if these
3757 defaults are incorrect.
3759 @findex HOST_WORDS_BIG_ENDIAN
3760 @item HOST_WORDS_BIG_ENDIAN
3761 Defined if the host machine stores words of multi-word values in
3762 big-endian order. (GCC does not depend on the host byte ordering
3765 @findex HOST_FLOAT_WORDS_BIG_ENDIAN
3766 @item HOST_FLOAT_WORDS_BIG_ENDIAN
3767 Define this macro to be 1 if the host machine stores @code{DFmode},
3768 @code{XFmode} or @code{TFmode} floating point numbers in memory with the
3769 word containing the sign bit at the lowest address; otherwise, define it
3772 This macro need not be defined if the ordering is the same as for
3773 multi-word integers.
3775 @findex HOST_FLOAT_FORMAT
3776 @item HOST_FLOAT_FORMAT
3777 A numeric code distinguishing the floating point format for the host
3778 machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
3779 alternatives and default.
3781 @findex HOST_BITS_PER_CHAR
3782 @item HOST_BITS_PER_CHAR
3783 A C expression for the number of bits in @code{char} on the host
3786 @findex HOST_BITS_PER_SHORT
3787 @item HOST_BITS_PER_SHORT
3788 A C expression for the number of bits in @code{short} on the host
3791 @findex HOST_BITS_PER_INT
3792 @item HOST_BITS_PER_INT
3793 A C expression for the number of bits in @code{int} on the host
3796 @findex HOST_BITS_PER_LONG
3797 @item HOST_BITS_PER_LONG
3798 A C expression for the number of bits in @code{long} on the host
3801 @findex HOST_BITS_PER_LONGLONG
3802 @item HOST_BITS_PER_LONGLONG
3803 A C expression for the number of bits in @code{long long} on the host
3806 @findex ONLY_INT_FIELDS
3807 @item ONLY_INT_FIELDS
3808 Define this macro to indicate that the host compiler only supports
3809 @code{int} bit-fields, rather than other integral types, including
3810 @code{enum}, as do most C compilers.
3812 @findex OBSTACK_CHUNK_SIZE
3813 @item OBSTACK_CHUNK_SIZE
3814 A C expression for the size of ordinary obstack chunks.
3815 If you don't define this, a usually-reasonable default is used.
3817 @findex OBSTACK_CHUNK_ALLOC
3818 @item OBSTACK_CHUNK_ALLOC
3819 The function used to allocate obstack chunks.
3820 If you don't define this, @code{xmalloc} is used.
3822 @findex OBSTACK_CHUNK_FREE
3823 @item OBSTACK_CHUNK_FREE
3824 The function used to free obstack chunks.
3825 If you don't define this, @code{free} is used.
3827 @findex USE_C_ALLOCA
3829 Define this macro to indicate that the compiler is running with the
3830 @code{alloca} implemented in C@. This version of @code{alloca} can be
3831 found in the file @file{alloca.c}; to use it, you must also alter the
3832 @file{Makefile} variable @code{ALLOCA}. (This is done automatically
3833 for the systems on which we know it is needed.)
3835 If you do define this macro, you should probably do it as follows:
3839 #define USE_C_ALLOCA
3841 #define alloca __builtin_alloca
3846 so that when the compiler is compiled with GCC it uses the more
3847 efficient built-in @code{alloca} function.
3849 @item FUNCTION_CONVERSION_BUG
3850 @findex FUNCTION_CONVERSION_BUG
3851 Define this macro to indicate that the host compiler does not properly
3852 handle converting a function value to a pointer-to-function when it is
3853 used in an expression.
3855 @findex MULTIBYTE_CHARS
3856 @item MULTIBYTE_CHARS
3857 Define this macro to enable support for multibyte characters in the
3858 input to GCC@. This requires that the host system support the ISO C
3859 library functions for converting multibyte characters to wide
3864 Define this if your system is POSIX.1 compliant.
3866 @findex PATH_SEPARATOR
3867 @item PATH_SEPARATOR
3868 Define this macro to be a C character constant representing the
3869 character used to separate components in paths. The default value is
3872 @findex DIR_SEPARATOR
3874 If your system uses some character other than slash to separate
3875 directory names within a file specification, define this macro to be a C
3876 character constant specifying that character. When GCC displays file
3877 names, the character you specify will be used. GCC will test for
3878 both slash and the character you specify when parsing filenames.
3880 @findex DIR_SEPARATOR_2
3881 @item DIR_SEPARATOR_2
3882 If your system uses an alternative character other than
3883 @samp{DIR_SEPARATOR} to separate directory names within a file
3884 specification, define this macro to be a C character constant specifying
3885 that character. If you define this macro, GCC will test for slash,
3886 @samp{DIR_SEPARATOR}, and @samp{DIR_SEPARATOR_2} when parsing filenames.
3888 @findex TARGET_OBJECT_SUFFIX
3889 @item TARGET_OBJECT_SUFFIX
3890 Define this macro to be a C string representing the suffix for object
3891 files on your target machine. If you do not define this macro, GCC will
3892 use @samp{.o} as the suffix for object files.
3894 @findex TARGET_EXECUTABLE_SUFFIX
3895 @item TARGET_EXECUTABLE_SUFFIX
3896 Define this macro to be a C string representing the suffix to be
3897 automatically added to executable files on your target machine. If you
3898 do not define this macro, GCC will use the null string as the suffix for
3901 @findex HOST_OBJECT_SUFFIX
3902 @item HOST_OBJECT_SUFFIX
3903 Define this macro to be a C string representing the suffix for object
3904 files on your host machine (@samp{xm-*.h}). If you do not define this
3905 macro, GCC will use @samp{.o} as the suffix for object files.
3907 @findex HOST_EXECUTABLE_SUFFIX
3908 @item HOST_EXECUTABLE_SUFFIX
3909 Define this macro to be a C string representing the suffix for
3910 executable files on your host machine (@samp{xm-*.h}). If you do not
3911 define this macro, GCC will use the null string as the suffix for
3914 @findex HOST_BIT_BUCKET
3915 @item HOST_BIT_BUCKET
3916 The name of a file or file-like object on the host system which acts as
3917 a ``bit bucket''. If you do not define this macro, GCC will use
3918 @samp{/dev/null} as the bit bucket. If the target does not support a
3919 bit bucket, this should be defined to the null string, or some other
3920 invalid filename. If the bit bucket is not writable, GCC will use a
3921 temporary file instead.
3923 @findex COLLECT_EXPORT_LIST
3924 @item COLLECT_EXPORT_LIST
3925 If defined, @code{collect2} will scan the individual object files
3926 specified on its command line and create an export list for the linker.
3927 Define this macro for systems like AIX, where the linker discards
3928 object files that are not referenced from @code{main} and uses export
3931 @findex COLLECT2_HOST_INITIALIZATION
3932 @item COLLECT2_HOST_INITIALIZATION
3933 If defined, a C statement (sans semicolon) that performs host-dependent
3934 initialization when @code{collect2} is being initialized.
3936 @findex GCC_DRIVER_HOST_INITIALIZATION
3937 @item GCC_DRIVER_HOST_INITIALIZATION
3938 If defined, a C statement (sans semicolon) that performs host-dependent
3939 initialization when a compilation driver is being initialized.
3941 @findex UPDATE_PATH_HOST_CANONICALIZE
3942 @item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
3943 If defined, a C statement (sans semicolon) that performs host-dependent
3944 canonicalization when a path used in a compilation driver or
3945 preprocessor is canonicalized. @var{path} is a malloc-ed path to be
3946 canonicalized. If the C statement does canonicalize @var{path} into a
3947 different buffer, the old path should be freed and the new buffer should
3948 have been allocated with malloc.
3953 In addition, configuration files for system V define @code{bcopy},
3954 @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
3955 as a macro when compiled with GCC, in order to take advantage of the
3956 benefit of GCC's built-in @code{alloca}.
3959 @chapter Makefile Fragments
3960 @cindex makefile fragment
3962 When you configure GCC using the @file{configure} script
3963 (@pxref{Installation}), it will construct the file @file{Makefile} from
3964 the template file @file{Makefile.in}. When it does this, it will
3965 incorporate makefile fragment files from the @file{config} directory,
3966 named @file{t-@var{target}} and @file{x-@var{host}}. If these files do
3967 not exist, it means nothing needs to be added for a given target or
3971 * Target Fragment:: Writing the @file{t-@var{target}} file.
3972 * Host Fragment:: Writing the @file{x-@var{host}} file.
3975 @node Target Fragment
3976 @section The Target Makefile Fragment
3977 @cindex target makefile fragment
3978 @cindex @file{t-@var{target}}
3980 The target makefile fragment, @file{t-@var{target}}, defines special
3981 target dependent variables and targets used in the @file{Makefile}:
3984 @findex LIBGCC2_CFLAGS
3985 @item LIBGCC2_CFLAGS
3986 Compiler flags to use when compiling @file{libgcc2.c}.
3988 @findex LIB2FUNCS_EXTRA
3989 @item LIB2FUNCS_EXTRA
3990 A list of source file names to be compiled or assembled and inserted
3991 into @file{libgcc.a}.
3993 @findex Floating Point Emulation
3994 @item Floating Point Emulation
3995 To have GCC include software floating point libraries in @file{libgcc.a}
3996 define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
3998 # We want fine grained libraries, so use the new code
3999 # to build the floating point emulation libraries.
4004 fp-bit.c: $(srcdir)/config/fp-bit.c
4005 echo '#define FLOAT' > fp-bit.c
4006 cat $(srcdir)/config/fp-bit.c >> fp-bit.c
4008 dp-bit.c: $(srcdir)/config/fp-bit.c
4009 cat $(srcdir)/config/fp-bit.c > dp-bit.c
4012 You may need to provide additional #defines at the beginning of @file{fp-bit.c}
4013 and @file{dp-bit.c} to control target endianness and other options.
4016 @findex CRTSTUFF_T_CFLAGS
4017 @item CRTSTUFF_T_CFLAGS
4018 Special flags used when compiling @file{crtstuff.c}.
4019 @xref{Initialization}.
4021 @findex CRTSTUFF_T_CFLAGS_S
4022 @item CRTSTUFF_T_CFLAGS_S
4023 Special flags used when compiling @file{crtstuff.c} for shared
4024 linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
4025 in @code{EXTRA-PARTS}.
4026 @xref{Initialization}.
4028 @findex MULTILIB_OPTIONS
4029 @item MULTILIB_OPTIONS
4030 For some targets, invoking GCC in different ways produces objects
4031 that can not be linked together. For example, for some targets GCC
4032 produces both big and little endian code. For these targets, you must
4033 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
4034 each set of incompatible options. When GCC invokes the linker, it
4035 arranges to link in the right version of @file{libgcc.a}, based on
4036 the command line options used.
4038 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
4039 special versions of @file{libgcc.a} must be built. Write options that
4040 are mutually incompatible side by side, separated by a slash. Write
4041 options that may be used together separated by a space. The build
4042 procedure will build all combinations of compatible options.
4044 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
4045 msoft-float}, @file{Makefile} will build special versions of
4046 @file{libgcc.a} using the following sets of options: @option{-m68000},
4047 @option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
4048 @samp{-m68020 -msoft-float}.
4050 @findex MULTILIB_DIRNAMES
4051 @item MULTILIB_DIRNAMES
4052 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
4053 directory names that should be used to hold the various libraries.
4054 Write one element in @code{MULTILIB_DIRNAMES} for each element in
4055 @code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
4056 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
4059 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
4060 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
4061 @samp{m68000 m68020 msoft-float}. You may specify a different value if
4062 you desire a different set of directory names.
4064 @findex MULTILIB_MATCHES
4065 @item MULTILIB_MATCHES
4066 Sometimes the same option may be written in two different ways. If an
4067 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
4068 any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
4069 items of the form @samp{option=option} to describe all relevant
4070 synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
4072 @findex MULTILIB_EXCEPTIONS
4073 @item MULTILIB_EXCEPTIONS
4074 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
4075 specified, there are combinations that should not be built. In that
4076 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
4077 in shell case syntax that should not be built.
4079 For example, in the PowerPC embedded ABI support, it is not desirable
4080 to build libraries compiled with the @option{-mcall-aix} option
4081 and either of the @option{-fleading-underscore} or @option{-mlittle} options
4082 at the same time. Therefore @code{MULTILIB_EXCEPTIONS} is set to
4084 *mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*
4087 @findex MULTILIB_EXTRA_OPTS
4088 @item MULTILIB_EXTRA_OPTS
4089 Sometimes it is desirable that when building multiple versions of
4090 @file{libgcc.a} certain options should always be passed on to the
4091 compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
4092 of options to be used for all builds.
4096 @section The Host Makefile Fragment
4097 @cindex host makefile fragment
4098 @cindex @file{x-@var{host}}
4100 The host makefile fragment, @file{x-@var{host}}, defines special host
4101 dependent variables and targets used in the @file{Makefile}:
4106 The compiler to use when building the first stage.
4110 The install program to use.
4114 @include funding.texi
4117 @unnumbered Linux and the GNU Project
4119 Many computer users run a modified version of the GNU system every
4120 day, without realizing it. Through a peculiar turn of events, the
4121 version of GNU which is widely used today is more often known as
4122 ``Linux'', and many users are not aware of the extent of its
4123 connection with the GNU Project.
4125 There really is a Linux; it is a kernel, and these people are using
4126 it. But you can't use a kernel by itself; a kernel is useful only as
4127 part of a whole system. The system in which Linux is typically used
4128 is a modified variant of the GNU system---in other words, a Linux-based
4131 Many users are not fully aware of the distinction between the kernel,
4132 which is Linux, and the whole system, which they also call ``Linux''.
4133 The ambiguous use of the name doesn't promote understanding.
4135 Programmers generally know that Linux is a kernel. But since they
4136 have generally heard the whole system called ``Linux'' as well, they
4137 often envisage a history which fits that name. For example, many
4138 believe that once Linus Torvalds finished writing the kernel, his
4139 friends looked around for other free software, and for no particular
4140 reason most everything necessary to make a Unix-like system was
4143 What they found was no accident---it was the GNU system. The available
4144 free software added up to a complete system because the GNU Project
4145 had been working since 1984 to make one. The GNU Manifesto
4146 had set forth the goal of developing a free Unix-like system, called
4147 GNU@. By the time Linux was written, the system was almost finished.
4149 Most free software projects have the goal of developing a particular
4150 program for a particular job. For example, Linus Torvalds set out to
4151 write a Unix-like kernel (Linux); Donald Knuth set out to write a text
4152 formatter (TeX); Bob Scheifler set out to develop a window system (X
4153 Windows). It's natural to measure the contribution of this kind of
4154 project by specific programs that came from the project.
4156 If we tried to measure the GNU Project's contribution in this way,
4157 what would we conclude? One CD-ROM vendor found that in their ``Linux
4158 distribution'', GNU software was the largest single contingent, around
4159 28% of the total source code, and this included some of the essential
4160 major components without which there could be no system. Linux itself
4161 was about 3%. So if you were going to pick a name for the system
4162 based on who wrote the programs in the system, the most appropriate
4163 single choice would be ``GNU''@.
4165 But we don't think that is the right way to consider the question.
4166 The GNU Project was not, is not, a project to develop specific
4167 software packages. It was not a project to develop a C compiler,
4168 although we did. It was not a project to develop a text editor,
4169 although we developed one. The GNU Project's aim was to develop
4170 @emph{a complete free Unix-like system}.
4172 Many people have made major contributions to the free software in the
4173 system, and they all deserve credit. But the reason it is @emph{a
4174 system}---and not just a collection of useful programs---is because the
4175 GNU Project set out to make it one. We wrote the programs that were
4176 needed to make a @emph{complete} free system. We wrote essential but
4177 unexciting major components, such as the assembler and linker, because
4178 you can't have a system without them. A complete system needs more
4179 than just programming tools, so we wrote other components as well,
4180 such as the Bourne Again SHell, the PostScript interpreter
4181 Ghostscript, and the GNU C library.
4183 By the early 90s we had put together the whole system aside from the
4184 kernel (and we were also working on a kernel, the GNU Hurd, which runs
4185 on top of Mach). Developing this kernel has been a lot harder than we
4186 expected, and we are still working on finishing it.
4188 Fortunately, you don't have to wait for it, because Linux is working
4189 now. When Linus Torvalds wrote Linux, he filled the last major gap.
4190 People could then put Linux together with the GNU system to make a
4191 complete free system: a Linux-based GNU system (or GNU/Linux system,
4194 Putting them together sounds simple, but it was not a trivial job.
4195 The GNU C library (called glibc for short) needed substantial changes.
4196 Integrating a complete system as a distribution that would work ``out
4197 of the box'' was a big job, too. It required addressing the issue of
4198 how to install and boot the system---a problem we had not tackled,
4199 because we hadn't yet reached that point. The people who developed
4200 the various system distributions made a substantial contribution.
4202 The GNU Project supports GNU/Linux systems as well as @emph{the}
4203 GNU system---even with funds. We funded the rewriting of the
4204 Linux-related extensions to the GNU C library, so that now they are
4205 well integrated, and the newest GNU/Linux systems use the current
4206 library release with no changes. We also funded an early stage of the
4207 development of Debian GNU/Linux.
4209 We use Linux-based GNU systems today for most of our work, and we hope
4210 you use them too. But please don't confuse the public by using the
4211 name ``Linux'' ambiguously. Linux is the kernel, one of the essential
4212 major components of the system. The system as a whole is more or less
4217 @c ---------------------------------------------------------------------
4219 @c ---------------------------------------------------------------------
4224 @unnumbered Contributors to GCC
4225 @cindex contributors
4226 @include contrib.texi
4228 @c ---------------------------------------------------------------------
4230 @c ---------------------------------------------------------------------
4233 @unnumbered Option Index
4235 GCC's command line options are indexed here without any initial @samp{-}
4236 or @samp{--}. Where an option has both positive and negative forms
4237 (such as @option{-f@var{option}} and @option{-fno-@var{option}}),
4238 relevant entries in the manual are indexed under the most appropriate
4239 form; it may sometimes be useful to look up both forms.
4248 @c ---------------------------------------------------------------------
4250 @c ---------------------------------------------------------------------