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 @c For consistency, use the following:
45 @c - "32-bit" rather than "32 bit" as an adjective.
46 @c - "back end" as a noun, "back-end" as an adjective.
47 @c - "bit-field" not "bitfield" or "bit field" (following the C and C++
49 @c - "built-in" as an adjective ("built-in function"), or sometimes
50 @c "built in", not "builtin" (which isn't a word).
51 @c - "front end" as a noun, "front-end" as an adjective.
52 @c - "GCC" for the GNU Compiler Collection, both generally
53 @c and as the GNU C Compiler in the context of compiling C;
54 @c "G++" for the C++ compiler; "gcc" and "g++" (lowercase),
55 @c marked up with @command, for the commands for compilation when the
56 @c emphasis is on those; "GNU C" and "GNU C++" for language dialects;
57 @c and try to avoid the older term "GNU CC".
58 @c - "nonzero" rather than "non-zero".
59 @c - "@code{NULL}" rather than "NULL".
60 @c - "Objective-C" rather than "Objective C".
62 @macro gcctabopt{body}
65 @macro gccoptlist{body}
70 @c Makeinfo handles the above macro OK, TeX needs manual line breaks;
71 @c they get lost at some point in handling the macro. But if @macro is
72 @c used here rather than @alias, it produces double line breaks.
83 @settitle Using and Porting the GNU Compiler Collection (GCC)
86 @c seems reasonable to assume at least one of INTERNALS or USING is set...
88 @settitle Using the GNU Compiler Collection
91 @settitle Porting the GNU Compiler Collection
94 @c Create a separate index for command line options.
96 @c Merge the standard indexes into a single one.
105 @c Use with @@smallbook.
107 @c Cause even numbered pages to be printed on the left hand side of
108 @c the page and odd numbered pages to be printed on the right hand
109 @c side of the page. Using this, you can print on both sides of a
110 @c sheet of paper and have the text on the same part of the sheet.
112 @c The text on right hand pages is pushed towards the right hand
113 @c margin and the text on left hand pages is pushed toward the left
115 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
118 @c \global\bindingoffset=0.75in
119 @c \global\normaloffset =0.75in
122 @c Change the font used for @def... commands, since the default
123 @c proportional one used is bad for names starting __.
125 \global\setfont\defbf\ttbshape{10}{\magstep1}
129 @dircategory Programming
131 * gcc: (gcc). The GNU Compiler Collection.
135 This file documents the use and the internals of the GNU compiler.
139 This file documents the internals of the GNU compiler.
142 This file documents the use of the GNU compiler.
145 Published by the Free Software Foundation@*
146 59 Temple Place - Suite 330@*
147 Boston, MA 02111-1307 USA
149 @c When you update the list of years below, search for copyright{} and
150 @c update the other copy too.
151 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
152 1999, 2000, 2001 Free Software Foundation, Inc.
154 Permission is granted to copy, distribute and/or modify this document
155 under the terms of the GNU Free Documentation License, Version 1.1 or
156 any later version published by the Free Software Foundation; with the
157 Invariant Sections being ``GNU General Public License'' and ``Funding
158 Free Software'', the Front-Cover texts being (a) (see below), and with
159 the Back-Cover Texts being (b) (see below). A copy of the license is
160 included in the section entitled ``GNU Free Documentation License''.
162 (a) The FSF's Front-Cover Text is:
166 (b) The FSF's Back-Cover Text is:
168 You have freedom to copy and modify this GNU Manual, like GNU
169 software. Copies published by the Free Software Foundation raise
170 funds for GNU development.
173 @setchapternewpage odd
178 @center @titlefont{Using and Porting the GNU Compiler Collection}
183 @title Using the GNU Compiler Collection
186 @title Porting the GNU Compiler Collection
189 @center Richard M. Stallman
191 @center Last updated 22 June 2001
193 @c The version number appears five times more in this file.
197 @vskip 0pt plus 1filll
198 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
199 1999, 2000, 2001 Free Software Foundation, Inc.
201 For GCC Version 3.1@*
203 Published by the Free Software Foundation @*
204 59 Temple Place---Suite 330@*
205 Boston, MA 02111-1307, USA@*
206 Last printed April, 1998.@*
207 Printed copies are available for $50 each.@*
210 Permission is granted to copy, distribute and/or modify this document
211 under the terms of the GNU Free Documentation License, Version 1.1 or
212 any later version published by the Free Software Foundation; with the
213 Invariant Sections being ``GNU General Public License'', the Front-Cover
214 texts being (a) (see below), and with the Back-Cover Texts being (b)
215 (see below). A copy of the license is included in the section entitled
216 ``GNU Free Documentation License''.
218 (a) The FSF's Front-Cover Text is:
222 (b) The FSF's Back-Cover Text is:
224 You have freedom to copy and modify this GNU Manual, like GNU
225 software. Copies published by the Free Software Foundation raise
226 funds for GNU development.
232 @node Top, G++ and GCC,, (DIR)
238 This manual documents how to run, install and port the GNU
239 compiler, as well as its new features and incompatibilities, and how to
240 report bugs. It corresponds to GCC version 3.1.
245 This manual documents how to run and install the GNU compiler,
246 as well as its new features and incompatibilities, and how to report
247 bugs. It corresponds to GCC version 3.1.
250 This manual documents how to port the GNU compiler,
251 as well as its new features and incompatibilities, and how to report
252 bugs. It corresponds to GCC version 3.1.
257 * G++ and GCC:: You can compile C or C++ programs.
258 * Standards:: Language standards supported by GCC.
259 * Invoking GCC:: Command options supported by @samp{gcc}.
260 * Installation:: How to configure, compile and install GCC.
261 * C Implementation:: How GCC implements the ISO C specification.
262 * C Extensions:: GNU extensions to the C language family.
263 * C++ Extensions:: GNU extensions to the C++ language.
264 * Objective-C:: GNU Objective-C runtime features.
265 * Gcov:: gcov: a GCC test coverage program.
266 * Trouble:: If you have trouble installing GCC.
267 * Bugs:: How, why and where to report bugs.
268 * Service:: How to find suppliers of support for GCC.
269 * Contributing:: How to contribute to testing and developing GCC.
270 * VMS:: Using GCC on VMS.
271 * Makefile:: Additional Makefile and configure information.
274 * Portability:: Goals of GCC's portability features.
275 * Interface:: Function-call interface of GCC output.
276 * Passes:: Order of passes, what they do, and what each file is for.
277 * Trees:: The source representation used by the C and C++ front ends.
278 * RTL:: The intermediate representation that most passes work on.
279 * Machine Desc:: How to write machine description instruction patterns.
280 * Target Macros:: How to write the machine description C macros and functions.
281 * Config:: Writing the @file{xm-@var{machine}.h} file.
282 * Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
285 * Funding:: How to help assure funding for free software.
286 * GNU/Linux:: Linux and the GNU Project
288 * Copying:: GNU General Public License says
289 how you can copy and share GCC.
290 * GNU Free Documentation License:: How you can copy and share this manual.
291 * Contributors:: People who have contributed to GCC.
293 * Option Index:: Index to command line options.
294 * Index:: Index of concepts and symbol names.
299 @chapter Compile C, C++, Objective-C, Fortran, Java or CHILL
305 Several versions of the compiler (C, C++, Objective-C, Fortran, Java
306 and CHILL) are integrated; this is why we use the name
307 ``GNU Compiler Collection''. GCC can compile programs written in any of these
308 languages. The Fortran, CHILL, and Java compilers are described in
312 ``GCC'' is a common shorthand term for the GNU Compiler Collection. This is both
313 the most general name for the compiler, and the name used when the
314 emphasis is on compiling C programs (as the abbreviation formerly
315 stood for ``GNU C Compiler'').
319 When referring to C++ compilation, it is usual to call the compiler
320 ``G++''. Since there is only one compiler, it is also accurate to call
321 it ``GCC'' no matter what the language context; however, the term
322 ``G++'' is more useful when the emphasis is on compiling C++ programs.
324 We use the name ``GCC'' to refer to the compilation system as a
325 whole, and more specifically to the language-independent part of the
326 compiler. For example, we refer to the optimization options as
327 affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
329 Front ends for other languages, such as Ada 95 and Pascal exist but
330 have not yet been integrated into GCC@. These front ends, like that for C++,
331 are built in subdirectories of GCC and link to it. The result is an
332 integrated compiler that can compile programs written in C, C++,
333 Objective-C, or any of the languages for which you have installed front
336 In this manual, we only discuss the options for the C, Objective-C, and
337 C++ compilers and those of the GCC core. Consult the documentation
338 of the other front ends for the options to use when compiling programs
339 written in other languages.
341 @cindex compiler compared to C++ preprocessor
342 @cindex intermediate C version, nonexistent
343 @cindex C intermediate output, nonexistent
344 G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object
345 code directly from your C++ program source. There is no intermediate C
346 version of the program. (By contrast, for example, some other
347 implementations use a program that generates a C program from your C++
348 source.) Avoiding an intermediate C representation of the program means
349 that you get better object code, and better debugging information. The
350 GNU debugger, GDB, works with this information in the object code to
351 give you comprehensive C++ source-level editing capabilities
352 (@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
354 @c FIXME! Someone who knows something about Objective-C ought to put in
355 @c a paragraph or two about it here, and move the index entry down when
356 @c there is more to point to than the general mention in the 1st par.
359 @chapter Language Standards Supported by GCC
362 @cindex ANSI C standard
366 @cindex ANSI X3.159-1989
368 @cindex ISO C standard
383 @cindex Technical Corrigenda
385 @cindex Technical Corrigendum 1
387 @cindex Technical Corrigendum 2
389 @cindex freestanding implementation
390 @cindex freestanding environment
391 @cindex hosted implementation
392 @cindex hosted environment
393 @findex __STDC_HOSTED__
395 For each language compiled by GCC for which there is a standard, GCC
396 attempts to follow one or more versions of that standard, possibly
397 with some exceptions, and possibly with some extensions.
399 GCC supports three versions of the C standard, although support for
400 the most recent version is not yet complete.
405 @opindex pedantic-errors
406 The original ANSI C standard (X3.159-1989) was ratified in 1989 and
407 published in 1990. This standard was ratified as an ISO standard
408 (ISO/IEC 9899:1990) later in 1990. There were no technical
409 differences between these publications, although the sections of the
410 ANSI standard were renumbered and became clauses in the ISO standard.
411 This standard, in both its forms, is commonly known as @dfn{C89}, or
412 occasionally as @dfn{C90}, from the dates of ratification. The ANSI
413 standard, but not the ISO standard, also came with a Rationale
414 document. To select this standard in GCC, use one of the options
415 @option{-ansi}, @option{-std=c89} or @option{-std=iso9899:1990}; to obtain
416 all the diagnostics required by the standard, you should also specify
417 @option{-pedantic} (or @option{-pedantic-errors} if you want them to be
418 errors rather than warnings). @xref{C Dialect Options,,Options
419 Controlling C Dialect}.
421 Errors in the 1990 ISO C standard were corrected in two Technical
422 Corrigenda published in 1994 and 1996. GCC does not support the
425 An amendment to the 1990 standard was published in 1995. This
426 amendment added digraphs and @code{__STDC_VERSION__} to the language,
427 but otherwise concerned the library. This amendment is commonly known
428 as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
429 @dfn{C95}. To select this standard in GCC, use the option
430 @option{-std=iso9899:199409} (with, as for other standard versions,
431 @option{-pedantic} to receive all required diagnostics).
433 A new edition of the ISO C standard was published in 1999 as ISO/IEC
434 9899:1999, and is commonly known as @dfn{C99}. GCC has incomplete
435 support for this standard version; see
436 @uref{http://gcc.gnu.org/c99status.html} for details. To select this
437 standard, use @option{-std=c99} or @option{-std=iso9899:1999}. (While in
438 development, drafts of this standard version were referred to as
442 GCC also has some limited support for traditional (pre-ISO) C with the
443 @option{-traditional} option. This support may be of use for compiling
444 some very old programs that have not been updated to ISO C, but should
445 not be used for new programs. It will not work with some modern C
446 libraries such as the GNU C library.
448 By default, GCC provides some extensions to the C language that on
449 rare occasions conflict with the C standard. @xref{C
450 Extensions,,Extensions to the C Language Family}. Use of the
451 @option{-std} options listed above will disable these extensions where
452 they conflict with the C standard version selected. You may also
453 select an extended version of the C language explicitly with
454 @option{-std=gnu89} (for C89 with GNU extensions) or @option{-std=gnu99}
455 (for C99 with GNU extensions). The default, if no C language dialect
456 options are given, is @option{-std=gnu89}; this will change to
457 @option{-std=gnu99} in some future release when the C99 support is
458 complete. Some features that are part of the C99 standard are
459 accepted as extensions in C89 mode.
461 The ISO C standard defines (in clause 4) two classes of conforming
462 implementation. A @dfn{conforming hosted implementation} supports the
463 whole standard including all the library facilities; a @dfn{conforming
464 freestanding implementation} is only required to provide certain
465 library facilities: those in @code{<float.h>}, @code{<limits.h>},
466 @code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
467 @code{<iso646.h>}; and in C99, also those in @code{<stdbool.h>} and
468 @code{<stdint.h>}. In addition, complex types, added in C99, are not
469 required for freestanding implementations. The standard also defines
470 two environments for programs, a @dfn{freestanding environment},
471 required of all implementations and which may not have library
472 facilities beyond those required of freestanding implementations,
473 where the handling of program startup and termination are
474 implementation-defined, and a @dfn{hosted environment}, which is not
475 required, in which all the library facilities are provided and startup
476 is through a function @code{int main (void)} or @code{int main (int,
477 char *[])}. An OS kernel would be a freestanding environment; a
478 program using the facilities of an operating system would normally be
479 in a hosted implementation.
481 @opindex ffreestanding
482 GCC aims towards being usable as a conforming freestanding
483 implementation, or as the compiler for a conforming hosted
484 implementation. By default, it will act as the compiler for a hosted
485 implementation, defining @code{__STDC_HOSTED__} as @code{1} and
486 presuming that when the names of ISO C functions are used, they have
487 the semantics defined in the standard. To make it act as a conforming
488 freestanding implementation for a freestanding environment, use the
489 option @option{-ffreestanding}; it will then define
490 @code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
491 meanings of function names from the standard library. To build an OS
492 kernel, you may well still need to make your own arrangements for
493 linking and startup. @xref{C Dialect Options,,Options Controlling C
496 GCC does not provide the library facilities required only of hosted
497 implementations, nor yet all the facilities required by C99 of
498 freestanding implementations; to use the facilities of a hosted
499 environment, you will need to find them elsewhere (for example, in the
500 GNU C library). @xref{Standard Libraries,,Standard Libraries}.
502 For references to Technical Corrigenda, Rationale documents and
503 information concerning the history of C that is available online, see
504 @uref{http://gcc.gnu.org/readings.html}
506 @c FIXME: details of C++ standard.
508 There is no formal written standard for Objective-C@. The most
509 authoritative manual is ``Object-Oriented Programming and the
510 Objective-C Language'', available at a number of web sites;
511 @uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/} has a
512 recent version, while @uref{http://www.toodarkpark.org/computers/objc/}
513 is an older example. @uref{http://www.gnustep.org} includes useful
516 @xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
517 Fortran}, for details of the Fortran language supported by GCC@.
519 @xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj},
520 for details of compatibility between @code{gcj} and the Java Platform.
522 @xref{References,,Language Definition References, chill, GNU Chill},
523 for details of the CHILL standard.
527 @include install-old.texi
536 @chapter Known Causes of Trouble with GCC
538 @cindex installation trouble
539 @cindex known causes of trouble
541 This section describes known problems that affect users of GCC@. Most
542 of these are not GCC bugs per se---if they were, we would fix them.
543 But the result for a user may be like the result of a bug.
545 Some of these problems are due to bugs in other software, some are
546 missing features that are too much work to add, and some are places
547 where people's opinions differ as to what is best.
550 * Actual Bugs:: Bugs we will fix later.
551 * Cross-Compiler Problems:: Common problems of cross compiling with GCC.
552 * Interoperation:: Problems using GCC with other compilers,
553 and with certain linkers, assemblers and debuggers.
554 * External Bugs:: Problems compiling certain programs.
555 * Incompatibilities:: GCC is incompatible with traditional C.
556 * Fixed Headers:: GCC uses corrected versions of system header files.
557 This is necessary, but doesn't always work smoothly.
558 * Standard Libraries:: GCC uses the system C library, which might not be
559 compliant with the ISO C standard.
560 * Disappointments:: Regrettable things we can't change, but not quite bugs.
561 * C++ Misunderstandings:: Common misunderstandings with GNU C++.
562 * Protoize Caveats:: Things to watch out for when using @code{protoize}.
563 * Non-bugs:: Things we think are right, but some others disagree.
564 * Warnings and Errors:: Which problems in your code get warnings,
565 and which get errors.
569 @section Actual Bugs We Haven't Fixed Yet
573 The @code{fixincludes} script interacts badly with automounters; if the
574 directory of system header files is automounted, it tends to be
575 unmounted while @code{fixincludes} is running. This would seem to be a
576 bug in the automounter. We don't know any good way to work around it.
579 The @code{fixproto} script will sometimes add prototypes for the
580 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
581 @code{jmp_buf} type before that type is defined. To work around this,
582 edit the offending file and place the typedef in front of the
586 @opindex pedantic-errors
587 When @option{-pedantic-errors} is specified, GCC will incorrectly give
588 an error message when a function name is specified in an expression
589 involving the comma operator.
592 @node Cross-Compiler Problems
593 @section Cross-Compiler Problems
595 You may run into problems with cross compilation on certain machines,
600 Cross compilation can run into trouble for certain machines because
601 some target machines' assemblers require floating point numbers to be
602 written as @emph{integer} constants in certain contexts.
604 The compiler writes these integer constants by examining the floating
605 point value as an integer and printing that integer, because this is
606 simple to write and independent of the details of the floating point
607 representation. But this does not work if the compiler is running on
608 a different machine with an incompatible floating point format, or
609 even a different byte-ordering.
611 In addition, correct constant folding of floating point values
612 requires representing them in the target machine's format.
613 (The C standard does not quite require this, but in practice
614 it is the only way to win.)
616 It is now possible to overcome these problems by defining macros such
617 as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
618 work for each target machine.
620 @xref{Cross-compilation}.
623 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
624 gcc.info, Using and Porting GCC}.
628 At present, the program @file{mips-tfile} which adds debug
629 support to object files on MIPS systems does not work in a cross
634 @section Interoperation
636 This section lists various difficulties encountered in using GCC
637 together with other compilers or with the assemblers, linkers,
638 libraries and debuggers on certain systems.
642 Objective-C does not work on the RS/6000.
645 G++ does not do name mangling in the same way as other C++
646 compilers. This means that object files compiled with one compiler
647 cannot be used with another.
649 This effect is intentional, to protect you from more subtle problems.
650 Compilers differ as to many internal details of C++ implementation,
651 including: how class instances are laid out, how multiple inheritance is
652 implemented, and how virtual function calls are handled. If the name
653 encoding were made the same, your programs would link against libraries
654 provided from other compilers---but the programs would then crash when
655 run. Incompatible libraries are then detected at link time, rather than
659 Older GDB versions sometimes fail to read the output of GCC version
660 2. If you have trouble, get GDB version 4.4 or later.
664 DBX rejects some files produced by GCC, though it accepts similar
665 constructs in output from PCC@. Until someone can supply a coherent
666 description of what is valid DBX input and what is not, there is
667 nothing I can do about these problems. You are on your own.
670 The GNU assembler (GAS) does not support PIC@. To generate PIC code, you
671 must use some other assembler, such as @file{/bin/as}.
674 On some BSD systems, including some versions of Ultrix, use of profiling
675 causes static variable destructors (currently used only in C++) not to
679 @cindex @code{vfork}, for the Sun-4
681 There is a bug in @code{vfork} on the Sun-4 which causes the registers
682 of the child process to clobber those of the parent. Because of this,
683 programs that call @code{vfork} are likely to lose when compiled
684 optimized with GCC when the child code alters registers which contain
685 C variables in the parent. This affects variables which are live in the
686 parent across the call to @code{vfork}.
688 If you encounter this, you can work around the problem by declaring
689 variables @code{volatile} in the function that calls @code{vfork}, until
690 the problem goes away, or by not declaring them @code{register} and not
691 using @option{-O} for those source files.
695 On some SGI systems, when you use @option{-lgl_s} as an option,
696 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
697 Naturally, this does not happen when you use GCC@.
698 You must specify all three options explicitly.
701 On a Sparc, GCC aligns all values of type @code{double} on an 8-byte
702 boundary, and it expects every @code{double} to be so aligned. The Sun
703 compiler usually gives @code{double} values 8-byte alignment, with one
704 exception: function arguments of type @code{double} may not be aligned.
706 As a result, if a function compiled with Sun CC takes the address of an
707 argument of type @code{double} and passes this pointer of type
708 @code{double *} to a function compiled with GCC, dereferencing the
709 pointer may cause a fatal signal.
711 One way to solve this problem is to compile your entire program with GCC@.
712 Another solution is to modify the function that is compiled with
713 Sun CC to copy the argument into a local variable; local variables
714 are always properly aligned. A third solution is to modify the function
715 that uses the pointer to dereference it via the following function
716 @code{access_double} instead of directly with @samp{*}:
720 access_double (double *unaligned_ptr)
722 union d2i @{ double d; int i[2]; @};
724 union d2i *p = (union d2i *) unaligned_ptr;
735 Storing into the pointer can be done likewise with the same union.
738 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
739 may allocate memory that is only 4 byte aligned. Since GCC on the
740 Sparc assumes that doubles are 8 byte aligned, this may result in a
741 fatal signal if doubles are stored in memory allocated by the
742 @file{libmalloc.a} library.
744 The solution is to not use the @file{libmalloc.a} library. Use instead
745 @code{malloc} and related functions from @file{libc.a}; they do not have
749 Sun forgot to include a static version of @file{libdl.a} with some
750 versions of SunOS (mainly 4.1). This results in undefined symbols when
751 linking static binaries (that is, if you use @option{-static}). If you
752 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
753 when linking, compile and link against the file
754 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
757 The 128-bit long double format that the Sparc port supports currently
758 works by using the architecturally defined quad-word floating point
759 instructions. Since there is no hardware that supports these
760 instructions they must be emulated by the operating system. Long
761 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
762 kernel emulator uses an obsolete and incompatible format. Long doubles
763 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
764 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
765 does not enable them by default. Long doubles appear to work in Sun OS
769 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
770 compile GCC correctly. We do not yet know why. However, GCC
771 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
772 compile itself properly on 9.01.
775 On the HP PA machine, ADB sometimes fails to work on functions compiled
776 with GCC@. Specifically, it fails to work on functions that use
777 @code{alloca} or variable-size arrays. This is because GCC doesn't
778 generate HP-UX unwind descriptors for such functions. It may even be
779 impossible to generate them.
782 Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
783 the preliminary GNU tools (@pxref{Installation}).
786 Taking the address of a label may generate errors from the HP-UX
787 PA assembler. GAS for the PA does not have this problem.
790 Using floating point parameters for indirect calls to static functions
791 will not work when using the HP assembler. There simply is no way for GCC
792 to specify what registers hold arguments for static functions when using
793 the HP assembler. GAS for the PA does not have this problem.
796 In extremely rare cases involving some very large functions you may
797 receive errors from the HP linker complaining about an out of bounds
798 unconditional branch offset. This used to occur more often in previous
799 versions of GCC, but is now exceptionally rare. If you should run
800 into it, you can work around by making your function smaller.
803 GCC compiled code sometimes emits warnings from the HP-UX assembler of
807 (warning) Use of GR3 when
808 frame >= 8192 may cause conflict.
811 These warnings are harmless and can be safely ignored.
814 The current version of the assembler (@file{/bin/as}) for the RS/6000
815 has certain problems that prevent the @option{-g} option in GCC from
816 working. Note that @file{Makefile.in} uses @option{-g} by default when
817 compiling @file{libgcc2.c}.
819 IBM has produced a fixed version of the assembler. The upgraded
820 assembler unfortunately was not included in any of the AIX 3.2 update
821 PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request
822 PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
823 See the file @file{README.RS6000} for more details on these updates.
825 You can test for the presence of a fixed assembler by using the
833 If the command exits normally, the assembler fix already is installed.
834 If the assembler complains that @option{-u} is an unknown flag, you need to
838 On the IBM RS/6000, compiling code of the form
849 will cause the linker to report an undefined symbol @code{foo}.
850 Although this behavior differs from most other systems, it is not a
851 bug because redefining an @code{extern} variable as @code{static}
852 is undefined in ISO C@.
855 AIX on the RS/6000 provides support (NLS) for environments outside of
856 the United States. Compilers and assemblers use NLS to support
857 locale-specific representations of various objects including
858 floating-point numbers (@samp{.} vs @samp{,} for separating decimal fractions).
859 There have been problems reported where the library linked with GCC does
860 not produce the same floating-point formats that the assembler accepts.
861 If you have this problem, set the @env{LANG} environment variable to
862 @samp{C} or @samp{En_US}.
865 @opindex fdollars-in-identifiers
866 Even if you specify @option{-fdollars-in-identifiers},
867 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
868 to a restriction in the IBM assembler. GAS supports these
872 On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC
873 version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2
874 by requesting PTF 421749 from IBM@.
877 @opindex mno-serialize-volatile
878 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
879 occurs when the @samp{fldcr} instruction is used. GCC uses
880 @samp{fldcr} on the 88100 to serialize volatile memory references. Use
881 the option @option{-mno-serialize-volatile} if your version of the
882 assembler has this bug.
885 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
886 messages from the linker. These warning messages complain of mismatched
887 psect attributes. You can ignore them. @xref{VMS Install}.
890 On NewsOS version 3, if you include both of the files @file{stddef.h}
891 and @file{sys/types.h}, you get an error because there are two typedefs
892 of @code{size_t}. You should change @file{sys/types.h} by adding these
893 lines around the definition of @code{size_t}:
898 @var{actual-typedef-here}
904 On the Alliant, the system's own convention for returning structures
905 and unions is unusual, and is not compatible with GCC no matter
906 what options are used.
911 @opindex mhc-struct-return
912 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
913 convention for structure and union returning. Use the option
914 @option{-mhc-struct-return} to tell GCC to use a convention compatible
917 @cindex VAX calling convention
918 @cindex Ultrix calling convention
921 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
922 by function calls. However, the C compiler uses conventions compatible
923 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
925 GCC uses the same convention as the Ultrix C compiler. You can use
926 these options to produce code compatible with the Fortran compiler:
929 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
933 On the WE32k, you may find that programs compiled with GCC do not
934 work with the standard shared C library. You may need to link with
935 the ordinary C compiler. If you do so, you must specify the following
939 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
942 The first specifies where to find the library @file{libgcc.a}
943 specified with the @option{-lgcc} option.
945 GCC does linking by invoking @command{ld}, just as @command{cc} does, and
946 there is no reason why it @emph{should} matter which compilation program
947 you use to invoke @command{ld}. If someone tracks this problem down,
948 it can probably be fixed easily.
951 On the Alpha, you may get assembler errors about invalid syntax as a
952 result of floating point constants. This is due to a bug in the C
953 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid
954 floating point numbers, they sometimes print @samp{NaN}.
957 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
958 sometimes reorders instructions incorrectly when optimization is turned
959 on. If you think this may be happening to you, try using the GNU
960 assembler; GAS version 2.1 supports ECOFF on Irix.
963 Or use the @option{-noasmopt} option when you compile GCC with itself,
964 and then again when you compile your program. (This is a temporary
965 kludge to turn off assembler optimization on Irix.) If this proves to
966 be what you need, edit the assembler spec in the file @file{specs} so
967 that it unconditionally passes @option{-O0} to the assembler, and never
968 passes @option{-O2} or @option{-O3}.
972 @section Problems Compiling Certain Programs
974 @c prevent bad page break with this line
975 Certain programs have problems compiling.
979 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
980 because of problems in DEC's versions of the X11 header files
981 @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
982 @option{-I/usr/include/mit} to use the MIT versions of the header files,
983 using the @option{-traditional} switch to turn off ISO C, or fixing the
984 header files by adding this:
988 #define NeedFunctionPrototypes 0
993 On various 386 Unix systems derived from System V, including SCO, ISC,
994 and ESIX, you may get error messages about running out of virtual memory
995 while compiling certain programs.
997 You can prevent this problem by linking GCC with the GNU malloc
998 (which thus replaces the malloc that comes with the system). GNU malloc
999 is available as a separate package, and also in the file
1000 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
1002 If you have installed GNU malloc as a separate library package, use this
1003 option when you relink GCC:
1006 MALLOC=/usr/local/lib/libgmalloc.a
1009 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
1010 the object file to @file{gmalloc.o} and use this option when you relink
1018 @node Incompatibilities
1019 @section Incompatibilities of GCC
1020 @cindex incompatibilities of GCC
1021 @opindex traditional
1023 There are several noteworthy incompatibilities between GNU C and K&R
1024 (non-ISO) versions of C@. The @option{-traditional} option
1025 eliminates many of these incompatibilities, @emph{but not all}, by
1026 telling GCC to behave like a K&R C compiler.
1029 @cindex string constants
1030 @cindex read-only strings
1031 @cindex shared strings
1033 GCC normally makes string constants read-only. If several
1034 identical-looking string constants are used, GCC stores only one
1037 @cindex @code{mktemp}, and constant strings
1038 One consequence is that you cannot call @code{mktemp} with a string
1039 constant argument. The function @code{mktemp} always alters the
1040 string its argument points to.
1042 @cindex @code{sscanf}, and constant strings
1043 @cindex @code{fscanf}, and constant strings
1044 @cindex @code{scanf}, and constant strings
1045 Another consequence is that @code{sscanf} does not work on some systems
1046 when passed a string constant as its format control string or input.
1047 This is because @code{sscanf} incorrectly tries to write into the string
1048 constant. Likewise @code{fscanf} and @code{scanf}.
1050 @opindex fwritable-strings
1051 The best solution to these problems is to change the program to use
1052 @code{char}-array variables with initialization strings for these
1053 purposes instead of string constants. But if this is not possible,
1054 you can use the @option{-fwritable-strings} flag, which directs GCC
1055 to handle string constants the same way most C compilers do.
1056 @option{-traditional} also has this effect, among others.
1059 @code{-2147483648} is positive.
1061 This is because 2147483648 cannot fit in the type @code{int}, so
1062 (following the ISO C rules) its data type is @code{unsigned long int}.
1063 Negating this value yields 2147483648 again.
1066 GCC does not substitute macro arguments when they appear inside of
1067 string constants. For example, the following macro in GCC
1074 will produce output @code{"a"} regardless of what the argument @var{a} is.
1076 The @option{-traditional} option directs GCC to handle such cases
1077 (among others) in the old-fashioned (non-ISO) fashion.
1079 @cindex @code{setjmp} incompatibilities
1080 @cindex @code{longjmp} incompatibilities
1082 When you use @code{setjmp} and @code{longjmp}, the only automatic
1083 variables guaranteed to remain valid are those declared
1084 @code{volatile}. This is a consequence of automatic register
1085 allocation. Consider this function:
1099 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
1104 Here @code{a} may or may not be restored to its first value when the
1105 @code{longjmp} occurs. If @code{a} is allocated in a register, then
1106 its first value is restored; otherwise, it keeps the last value stored
1110 If you use the @option{-W} option with the @option{-O} option, you will
1111 get a warning when GCC thinks such a problem might be possible.
1113 The @option{-traditional} option directs GCC to put variables in
1114 the stack by default, rather than in registers, in functions that
1115 call @code{setjmp}. This results in the behavior found in
1116 traditional C compilers.
1119 Programs that use preprocessing directives in the middle of macro
1120 arguments do not work with GCC@. For example, a program like this
1131 ISO C does not permit such a construct. It would make sense to support
1132 it when @option{-traditional} is used, but it is too much work to
1136 K&R compilers allow comments to cross over an inclusion boundary
1137 (i.e.@: started in an include file and ended in the including file). I think
1138 this would be quite ugly and can't imagine it could be needed.
1140 @cindex external declaration scope
1141 @cindex scope of external declarations
1142 @cindex declaration scope
1144 Declarations of external variables and functions within a block apply
1145 only to the block containing the declaration. In other words, they
1146 have the same scope as any other declaration in the same place.
1148 In some other C compilers, a @code{extern} declaration affects all the
1149 rest of the file even if it happens within a block.
1151 The @option{-traditional} option directs GCC to treat all @code{extern}
1152 declarations as global, like traditional compilers.
1155 In traditional C, you can combine @code{long}, etc., with a typedef name,
1160 typedef long foo bar;
1163 In ISO C, this is not allowed: @code{long} and other type modifiers
1164 require an explicit @code{int}. Because this criterion is expressed
1165 by Bison grammar rules rather than C code, the @option{-traditional}
1166 flag cannot alter it.
1168 @cindex typedef names as function parameters
1170 PCC allows typedef names to be used as function parameters. The
1171 difficulty described immediately above applies here too.
1174 When in @option{-traditional} mode, GCC allows the following erroneous
1175 pair of declarations to appear together in a given scope:
1183 GCC treats all characters of identifiers as significant, even when in
1184 @option{-traditional} mode. According to K&R-1 (2.2), ``No more than the
1185 first eight characters are significant, although more may be used.''.
1186 Also according to K&R-1 (2.2), ``An identifier is a sequence of letters
1187 and digits; the first character must be a letter. The underscore _
1188 counts as a letter.'', but GCC also allows dollar signs in identifiers.
1192 PCC allows whitespace in the middle of compound assignment operators
1193 such as @samp{+=}. GCC, following the ISO standard, does not
1194 allow this. The difficulty described immediately above applies here
1200 GCC complains about unterminated character constants inside of
1201 preprocessing conditionals that fail. Some programs have English
1202 comments enclosed in conditionals that are guaranteed to fail; if these
1203 comments contain apostrophes, GCC will probably report an error. For
1204 example, this code would produce an error:
1208 You can't expect this to work.
1212 The best solution to such a problem is to put the text into an actual
1213 C comment delimited by @samp{/*@dots{}*/}. However,
1214 @option{-traditional} suppresses these error messages.
1217 Many user programs contain the declaration @samp{long time ();}. In the
1218 past, the system header files on many systems did not actually declare
1219 @code{time}, so it did not matter what type your program declared it to
1220 return. But in systems with ISO C headers, @code{time} is declared to
1221 return @code{time_t}, and if that is not the same as @code{long}, then
1222 @samp{long time ();} is erroneous.
1224 The solution is to change your program to use appropriate system headers
1225 (@code{<time.h>} on systems with ISO C headers) and not to declare
1226 @code{time} if the system header files declare it, or failing that to
1227 use @code{time_t} as the return type of @code{time}.
1229 @cindex @code{float} as function value type
1231 When compiling functions that return @code{float}, PCC converts it to
1232 a double. GCC actually returns a @code{float}. If you are concerned
1233 with PCC compatibility, you should declare your functions to return
1234 @code{double}; you might as well say what you mean.
1239 When compiling functions that return structures or unions, GCC
1240 output code normally uses a method different from that used on most
1241 versions of Unix. As a result, code compiled with GCC cannot call
1242 a structure-returning function compiled with PCC, and vice versa.
1244 The method used by GCC is as follows: a structure or union which is
1245 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
1246 with any other size is stored into an address supplied by the caller
1247 (usually in a special, fixed register, but on some machines it is passed
1248 on the stack). The machine-description macros @code{STRUCT_VALUE} and
1249 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
1251 By contrast, PCC on most target machines returns structures and unions
1252 of any size by copying the data into an area of static storage, and then
1253 returning the address of that storage as if it were a pointer value.
1254 The caller must copy the data from that memory area to the place where
1255 the value is wanted. GCC does not use this method because it is
1256 slower and nonreentrant.
1258 On some newer machines, PCC uses a reentrant convention for all
1259 structure and union returning. GCC on most of these machines uses a
1260 compatible convention when returning structures and unions in memory,
1261 but still returns small structures and unions in registers.
1263 @opindex fpcc-struct-return
1264 You can tell GCC to use a compatible convention for all structure and
1265 union returning with the option @option{-fpcc-struct-return}.
1267 @cindex preprocessing tokens
1268 @cindex preprocessing numbers
1270 GCC complains about program fragments such as @samp{0x74ae-0x4000}
1271 which appear to be two hexadecimal constants separated by the minus
1272 operator. Actually, this string is a single @dfn{preprocessing token}.
1273 Each such token must correspond to one token in C@. Since this does not,
1274 GCC prints an error message. Although it may appear obvious that what
1275 is meant is an operator and two values, the ISO C standard specifically
1276 requires that this be treated as erroneous.
1278 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
1279 begins with a digit and is followed by letters, underscores, digits,
1280 periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
1281 @samp{p-}, @samp{P+}, or @samp{P-} character sequences. (In strict C89
1282 mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
1283 appear in preprocessing numbers.)
1285 To make the above program fragment valid, place whitespace in front of
1286 the minus sign. This whitespace will end the preprocessing number.
1290 @section Fixed Header Files
1292 GCC needs to install corrected versions of some system header files.
1293 This is because most target systems have some header files that won't
1294 work with GCC unless they are changed. Some have bugs, some are
1295 incompatible with ISO C, and some depend on special features of other
1298 Installing GCC automatically creates and installs the fixed header
1299 files, by running a program called @code{fixincludes} (or for certain
1300 targets an alternative such as @code{fixinc.svr4}). Normally, you
1301 don't need to pay attention to this. But there are cases where it
1302 doesn't do the right thing automatically.
1306 If you update the system's header files, such as by installing a new
1307 system version, the fixed header files of GCC are not automatically
1308 updated. The easiest way to update them is to reinstall GCC@. (If
1309 you want to be clever, look in the makefile and you can find a
1313 On some systems, in particular SunOS 4, header file directories contain
1314 machine-specific symbolic links in certain places. This makes it
1315 possible to share most of the header files among hosts running the
1316 same version of SunOS 4 on different machine models.
1318 The programs that fix the header files do not understand this special
1319 way of using symbolic links; therefore, the directory of fixed header
1320 files is good only for the machine model used to build it.
1322 In SunOS 4, only programs that look inside the kernel will notice the
1323 difference between machine models. Therefore, for most purposes, you
1324 need not be concerned about this.
1326 It is possible to make separate sets of fixed header files for the
1327 different machine models, and arrange a structure of symbolic links so
1328 as to use the proper set, but you'll have to do this by hand.
1331 On Lynxos, GCC by default does not fix the header files. This is
1332 because bugs in the shell cause the @code{fixincludes} script to fail.
1334 This means you will encounter problems due to bugs in the system header
1335 files. It may be no comfort that they aren't GCC's fault, but it
1336 does mean that there's nothing for us to do about them.
1339 @node Standard Libraries
1340 @section Standard Libraries
1343 GCC by itself attempts to be a conforming freestanding implementation.
1344 @xref{Standards,,Language Standards Supported by GCC}, for details of
1345 what this means. Beyond the library facilities required of such an
1346 implementation, the rest of the C library is supplied by the vendor of
1347 the operating system. If that C library doesn't conform to the C
1348 standards, then your programs might get warnings (especially when using
1349 @option{-Wall}) that you don't expect.
1351 For example, the @code{sprintf} function on SunOS 4.1.3 returns
1352 @code{char *} while the C standard says that @code{sprintf} returns an
1353 @code{int}. The @code{fixincludes} program could make the prototype for
1354 this function match the Standard, but that would be wrong, since the
1355 function will still return @code{char *}.
1357 If you need a Standard compliant library, then you need to find one, as
1358 GCC does not provide one. The GNU C library (called @code{glibc})
1359 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
1360 GNU/Linux and HURD-based GNU systems; no recent version of it supports
1361 other systems, though some very old versions did. Version 2.2 of the
1362 GNU C library includes nearly complete C99 support. You could also ask
1363 your operating system vendor if newer libraries are available.
1365 @node Disappointments
1366 @section Disappointments and Misunderstandings
1368 These problems are perhaps regrettable, but we don't know any practical
1373 Certain local variables aren't recognized by debuggers when you compile
1376 This occurs because sometimes GCC optimizes the variable out of
1377 existence. There is no way to tell the debugger how to compute the
1378 value such a variable ``would have had'', and it is not clear that would
1379 be desirable anyway. So GCC simply does not mention the eliminated
1380 variable when it writes debugging information.
1382 You have to expect a certain amount of disagreement between the
1383 executable and your source code, when you use optimization.
1385 @cindex conflicting types
1386 @cindex scope of declaration
1388 Users often think it is a bug when GCC reports an error for code
1392 int foo (struct mumble *);
1394 struct mumble @{ @dots{} @};
1396 int foo (struct mumble *x)
1400 This code really is erroneous, because the scope of @code{struct
1401 mumble} in the prototype is limited to the argument list containing it.
1402 It does not refer to the @code{struct mumble} defined with file scope
1403 immediately below---they are two unrelated types with similar names in
1406 But in the definition of @code{foo}, the file-scope type is used
1407 because that is available to be inherited. Thus, the definition and
1408 the prototype do not match, and you get an error.
1410 This behavior may seem silly, but it's what the ISO standard specifies.
1411 It is easy enough for you to make your code work by moving the
1412 definition of @code{struct mumble} above the prototype. It's not worth
1413 being incompatible with ISO C just to avoid an error for the example
1417 Accesses to bit-fields even in volatile objects works by accessing larger
1418 objects, such as a byte or a word. You cannot rely on what size of
1419 object is accessed in order to read or write the bit-field; it may even
1420 vary for a given bit-field according to the precise usage.
1422 If you care about controlling the amount of memory that is accessed, use
1423 volatile but do not use bit-fields.
1426 GCC comes with shell scripts to fix certain known problems in system
1427 header files. They install corrected copies of various header files in
1428 a special directory where only GCC will normally look for them. The
1429 scripts adapt to various systems by searching all the system header
1430 files for the problem cases that we know about.
1432 If new system header files are installed, nothing automatically arranges
1433 to update the corrected header files. You will have to reinstall GCC
1434 to fix the new header files. More specifically, go to the build
1435 directory and delete the files @file{stmp-fixinc} and
1436 @file{stmp-headers}, and the subdirectory @code{include}; then do
1437 @samp{make install} again.
1440 @cindex floating point precision
1441 On 68000 and x86 systems, for instance, you can get paradoxical results
1442 if you test the precise values of floating point numbers. For example,
1443 you can find that a floating point value which is not a NaN is not equal
1444 to itself. This results from the fact that the floating point registers
1445 hold a few more bits of precision than fit in a @code{double} in memory.
1446 Compiled code moves values between memory and floating point registers
1447 at its convenience, and moving them into memory truncates them.
1449 @opindex ffloat-store
1450 You can partially avoid this problem by using the @option{-ffloat-store}
1451 option (@pxref{Optimize Options}).
1454 On the MIPS, variable argument functions using @file{varargs.h}
1455 cannot have a floating point value for the first argument. The
1456 reason for this is that in the absence of a prototype in scope,
1457 if the first argument is a floating point, it is passed in a
1458 floating point register, rather than an integer register.
1460 If the code is rewritten to use the ISO standard @file{stdarg.h}
1461 method of variable arguments, and the prototype is in scope at
1462 the time of the call, everything will work fine.
1465 On the H8/300 and H8/300H, variable argument functions must be
1466 implemented using the ISO standard @file{stdarg.h} method of
1467 variable arguments. Furthermore, calls to functions using @file{stdarg.h}
1468 variable arguments must have a prototype for the called function
1469 in scope at the time of the call.
1472 @node C++ Misunderstandings
1473 @section Common Misunderstandings with GNU C++
1475 @cindex misunderstandings in C++
1476 @cindex surprises in C++
1477 @cindex C++ misunderstandings
1478 C++ is a complex language and an evolving one, and its standard
1479 definition (the ISO C++ standard) was only recently completed. As a
1480 result, your C++ compiler may occasionally surprise you, even when its
1481 behavior is correct. This section discusses some areas that frequently
1482 give rise to questions of this sort.
1485 * Static Definitions:: Static member declarations are not definitions
1486 * Temporaries:: Temporaries may vanish before you expect
1487 * Copy Assignment:: Copy Assignment operators copy virtual bases twice
1490 @node Static Definitions
1491 @subsection Declare @emph{and} Define Static Members
1493 @cindex C++ static data, declaring and defining
1494 @cindex static data in C++, declaring and defining
1495 @cindex declaring static data in C++
1496 @cindex defining static data in C++
1497 When a class has static data members, it is not enough to @emph{declare}
1498 the static member; you must also @emph{define} it. For example:
1509 This declaration only establishes that the class @code{Foo} has an
1510 @code{int} named @code{Foo::bar}, and a member function named
1511 @code{Foo::method}. But you still need to define @emph{both}
1512 @code{method} and @code{bar} elsewhere. According to the ISO
1513 standard, you must supply an initializer in one (and only one) source
1520 Other C++ compilers may not correctly implement the standard behavior.
1521 As a result, when you switch to @code{g++} from one of these compilers,
1522 you may discover that a program that appeared to work correctly in fact
1523 does not conform to the standard: @code{g++} reports as undefined
1524 symbols any static data members that lack definitions.
1527 @subsection Temporaries May Vanish Before You Expect
1529 @cindex temporaries, lifetime of
1530 @cindex portions of temporary objects, pointers to
1531 It is dangerous to use pointers or references to @emph{portions} of a
1532 temporary object. The compiler may very well delete the object before
1533 you expect it to, leaving a pointer to garbage. The most common place
1534 where this problem crops up is in classes like string classes,
1535 especially ones that define a conversion function to type @code{char *}
1536 or @code{const char *}---which is one reason why the standard
1537 @code{string} class requires you to call the @code{c_str} member
1538 function. However, any class that returns a pointer to some internal
1539 structure is potentially subject to this problem.
1541 For example, a program may use a function @code{strfunc} that returns
1542 @code{string} objects, and another function @code{charfunc} that
1543 operates on pointers to @code{char}:
1547 void charfunc (const char *);
1552 const char *p = strfunc().c_str();
1561 In this situation, it may seem reasonable to save a pointer to the C
1562 string returned by the @code{c_str} member function and use that rather
1563 than call @code{c_str} repeatedly. However, the temporary string
1564 created by the call to @code{strfunc} is destroyed after @code{p} is
1565 initialized, at which point @code{p} is left pointing to freed memory.
1567 Code like this may run successfully under some other compilers,
1568 particularly obsolete cfront-based compilers that delete temporaries
1569 along with normal local variables. However, the GNU C++ behavior is
1570 standard-conforming, so if your program depends on late destruction of
1571 temporaries it is not portable.
1573 The safe way to write such code is to give the temporary a name, which
1574 forces it to remain until the end of the scope of the name. For
1578 string& tmp = strfunc ();
1579 charfunc (tmp.c_str ());
1582 @node Copy Assignment
1583 @subsection Implicit Copy-Assignment for Virtual Bases
1585 When a base class is virtual, only one subobject of the base class
1586 belongs to each full object. Also, the constructors and destructors are
1587 invoked only once, and called from the most-derived class. However, such
1588 objects behave unspecified when being assigned. For example:
1593 Base(char *n) : name(strdup(n))@{@}
1594 Base& operator= (const Base& other)@{
1596 name = strdup (other.name);
1600 struct A:virtual Base@{
1605 struct B:virtual Base@{
1610 struct Derived:public A, public B@{
1611 Derived():Base("Derived")@{@}
1614 void func(Derived &d1, Derived &d2)
1620 The C++ standard specifies that @samp{Base::Base} is only called once
1621 when constructing or copy-constructing a Derived object. It is
1622 unspecified whether @samp{Base::operator=} is called more than once when
1623 the implicit copy-assignment for Derived objects is invoked (as it is
1624 inside @samp{func} in the example).
1626 g++ implements the ``intuitive'' algorithm for copy-assignment: assign all
1627 direct bases, then assign all members. In that algorithm, the virtual
1628 base subobject can be encountered many times. In the example, copying
1629 proceeds in the following order: @samp{val}, @samp{name} (via
1630 @code{strdup}), @samp{bval}, and @samp{name} again.
1632 If application code relies on copy-assignment, a user-defined
1633 copy-assignment operator removes any uncertainties. With such an
1634 operator, the application can define whether and how the virtual base
1635 subobject is assigned.
1637 @node Protoize Caveats
1638 @section Caveats of using @command{protoize}
1640 The conversion programs @command{protoize} and @command{unprotoize} can
1641 sometimes change a source file in a way that won't work unless you
1646 @command{protoize} can insert references to a type name or type tag before
1647 the definition, or in a file where they are not defined.
1649 If this happens, compiler error messages should show you where the new
1650 references are, so fixing the file by hand is straightforward.
1653 There are some C constructs which @command{protoize} cannot figure out.
1654 For example, it can't determine argument types for declaring a
1655 pointer-to-function variable; this you must do by hand. @command{protoize}
1656 inserts a comment containing @samp{???} each time it finds such a
1657 variable; so you can find all such variables by searching for this
1658 string. ISO C does not require declaring the argument types of
1659 pointer-to-function types.
1662 Using @command{unprotoize} can easily introduce bugs. If the program
1663 relied on prototypes to bring about conversion of arguments, these
1664 conversions will not take place in the program without prototypes.
1665 One case in which you can be sure @command{unprotoize} is safe is when
1666 you are removing prototypes that were made with @command{protoize}; if
1667 the program worked before without any prototypes, it will work again
1670 @opindex Wconversion
1671 You can find all the places where this problem might occur by compiling
1672 the program with the @option{-Wconversion} option. It prints a warning
1673 whenever an argument is converted.
1676 Both conversion programs can be confused if there are macro calls in and
1677 around the text to be converted. In other words, the standard syntax
1678 for a declaration or definition must not result from expanding a macro.
1679 This problem is inherent in the design of C and cannot be fixed. If
1680 only a few functions have confusing macro calls, you can easily convert
1684 @command{protoize} cannot get the argument types for a function whose
1685 definition was not actually compiled due to preprocessing conditionals.
1686 When this happens, @command{protoize} changes nothing in regard to such
1687 a function. @command{protoize} tries to detect such instances and warn
1690 You can generally work around this problem by using @command{protoize} step
1691 by step, each time specifying a different set of @option{-D} options for
1692 compilation, until all of the functions have been converted. There is
1693 no automatic way to verify that you have got them all, however.
1696 Confusion may result if there is an occasion to convert a function
1697 declaration or definition in a region of source code where there is more
1698 than one formal parameter list present. Thus, attempts to convert code
1699 containing multiple (conditionally compiled) versions of a single
1700 function header (in the same vicinity) may not produce the desired (or
1703 If you plan on converting source files which contain such code, it is
1704 recommended that you first make sure that each conditionally compiled
1705 region of source code which contains an alternative function header also
1706 contains at least one additional follower token (past the final right
1707 parenthesis of the function header). This should circumvent the
1711 @command{unprotoize} can become confused when trying to convert a function
1712 definition or declaration which contains a declaration for a
1713 pointer-to-function formal argument which has the same name as the
1714 function being defined or declared. We recommend you avoid such choices
1715 of formal parameter names.
1718 You might also want to correct some of the indentation by hand and break
1719 long lines. (The conversion programs don't write lines longer than
1720 eighty characters in any case.)
1724 @section Certain Changes We Don't Want to Make
1726 This section lists changes that people frequently request, but which
1727 we do not make because we think GCC is better without them.
1731 Checking the number and type of arguments to a function which has an
1732 old-fashioned definition and no prototype.
1734 Such a feature would work only occasionally---only for calls that appear
1735 in the same file as the called function, following the definition. The
1736 only way to check all calls reliably is to add a prototype for the
1737 function. But adding a prototype eliminates the motivation for this
1738 feature. So the feature is not worthwhile.
1741 Warning about using an expression whose type is signed as a shift count.
1743 Shift count operands are probably signed more often than unsigned.
1744 Warning about this would cause far more annoyance than good.
1747 Warning about assigning a signed value to an unsigned variable.
1749 Such assignments must be very common; warning about them would cause
1750 more annoyance than good.
1753 Warning when a non-void function value is ignored.
1755 Coming as I do from a Lisp background, I balk at the idea that there is
1756 something dangerous about discarding a value. There are functions that
1757 return values which some callers may find useful; it makes no sense to
1758 clutter the program with a cast to @code{void} whenever the value isn't
1762 @opindex fshort-enums
1763 Making @option{-fshort-enums} the default.
1765 This would cause storage layout to be incompatible with most other C
1766 compilers. And it doesn't seem very important, given that you can get
1767 the same result in other ways. The case where it matters most is when
1768 the enumeration-valued object is inside a structure, and in that case
1769 you can specify a field width explicitly.
1772 Making bit-fields unsigned by default on particular machines where ``the
1773 ABI standard'' says to do so.
1775 The ISO C standard leaves it up to the implementation whether a bit-field
1776 declared plain @code{int} is signed or not. This in effect creates two
1777 alternative dialects of C@.
1779 @opindex fsigned-bitfields
1780 @opindex funsigned-bitfields
1781 The GNU C compiler supports both dialects; you can specify the signed
1782 dialect with @option{-fsigned-bitfields} and the unsigned dialect with
1783 @option{-funsigned-bitfields}. However, this leaves open the question of
1784 which dialect to use by default.
1786 Currently, the preferred dialect makes plain bit-fields signed, because
1787 this is simplest. Since @code{int} is the same as @code{signed int} in
1788 every other context, it is cleanest for them to be the same in bit-fields
1791 Some computer manufacturers have published Application Binary Interface
1792 standards which specify that plain bit-fields should be unsigned. It is
1793 a mistake, however, to say anything about this issue in an ABI@. This is
1794 because the handling of plain bit-fields distinguishes two dialects of C@.
1795 Both dialects are meaningful on every type of machine. Whether a
1796 particular object file was compiled using signed bit-fields or unsigned
1797 is of no concern to other object files, even if they access the same
1798 bit-fields in the same data structures.
1800 A given program is written in one or the other of these two dialects.
1801 The program stands a chance to work on most any machine if it is
1802 compiled with the proper dialect. It is unlikely to work at all if
1803 compiled with the wrong dialect.
1805 Many users appreciate the GNU C compiler because it provides an
1806 environment that is uniform across machines. These users would be
1807 inconvenienced if the compiler treated plain bit-fields differently on
1810 Occasionally users write programs intended only for a particular machine
1811 type. On these occasions, the users would benefit if the GNU C compiler
1812 were to support by default the same dialect as the other compilers on
1813 that machine. But such applications are rare. And users writing a
1814 program to run on more than one type of machine cannot possibly benefit
1815 from this kind of compatibility.
1817 This is why GCC does and will treat plain bit-fields in the same
1818 fashion on all types of machines (by default).
1820 There are some arguments for making bit-fields unsigned by default on all
1821 machines. If, for example, this becomes a universal de facto standard,
1822 it would make sense for GCC to go along with it. This is something
1823 to be considered in the future.
1825 (Of course, users strongly concerned about portability should indicate
1826 explicitly in each bit-field whether it is signed or not. In this way,
1827 they write programs which have the same meaning in both C dialects.)
1831 @opindex traditional
1833 Undefining @code{__STDC__} when @option{-ansi} is not used.
1835 Currently, GCC defines @code{__STDC__} as long as you don't use
1836 @option{-traditional}. This provides good results in practice.
1838 Programmers normally use conditionals on @code{__STDC__} to ask whether
1839 it is safe to use certain features of ISO C, such as function
1840 prototypes or ISO token concatenation. Since plain @command{gcc} supports
1841 all the features of ISO C, the correct answer to these questions is
1844 Some users try to use @code{__STDC__} to check for the availability of
1845 certain library facilities. This is actually incorrect usage in an ISO
1846 C program, because the ISO C standard says that a conforming
1847 freestanding implementation should define @code{__STDC__} even though it
1848 does not have the library facilities. @samp{gcc -ansi -pedantic} is a
1849 conforming freestanding implementation, and it is therefore required to
1850 define @code{__STDC__}, even though it does not come with an ISO C
1853 Sometimes people say that defining @code{__STDC__} in a compiler that
1854 does not completely conform to the ISO C standard somehow violates the
1855 standard. This is illogical. The standard is a standard for compilers
1856 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
1857 compilers such as plain @command{gcc}. Whatever the ISO C standard says
1858 is relevant to the design of plain @command{gcc} without @option{-ansi} only
1859 for pragmatic reasons, not as a requirement.
1861 GCC normally defines @code{__STDC__} to be 1, and in addition
1862 defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
1863 or a @option{-std} option for strict conformance to some version of ISO C@.
1864 On some hosts, system include files use a different convention, where
1865 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
1866 conformance to the C Standard. GCC follows the host convention when
1867 processing system include files, but when processing user files it follows
1868 the usual GNU C convention.
1871 Undefining @code{__STDC__} in C++.
1873 Programs written to compile with C++-to-C translators get the
1874 value of @code{__STDC__} that goes with the C compiler that is
1875 subsequently used. These programs must test @code{__STDC__}
1876 to determine what kind of C preprocessor that compiler uses:
1877 whether they should concatenate tokens in the ISO C fashion
1878 or in the traditional fashion.
1880 These programs work properly with GNU C++ if @code{__STDC__} is defined.
1881 They would not work otherwise.
1883 In addition, many header files are written to provide prototypes in ISO
1884 C but not in traditional C@. Many of these header files can work without
1885 change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
1886 is not defined, they will all fail, and will all need to be changed to
1887 test explicitly for C++ as well.
1890 Deleting ``empty'' loops.
1892 Historically, GCC has not deleted ``empty'' loops under the
1893 assumption that the most likely reason you would put one in a program is
1894 to have a delay, so deleting them will not make real programs run any
1897 However, the rationale here is that optimization of a nonempty loop
1898 cannot produce an empty one, which holds for C but is not always the
1901 @opindex funroll-loops
1902 Moreover, with @option{-funroll-loops} small ``empty'' loops are already
1903 removed, so the current behavior is both sub-optimal and inconsistent
1904 and will change in the future.
1907 Making side effects happen in the same order as in some other compiler.
1909 @cindex side effects, order of evaluation
1910 @cindex order of evaluation, side effects
1911 It is never safe to depend on the order of evaluation of side effects.
1912 For example, a function call like this may very well behave differently
1913 from one compiler to another:
1916 void func (int, int);
1922 There is no guarantee (in either the C or the C++ standard language
1923 definitions) that the increments will be evaluated in any particular
1924 order. Either increment might happen first. @code{func} might get the
1925 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
1928 Not allowing structures with volatile fields in registers.
1930 Strictly speaking, there is no prohibition in the ISO C standard
1931 against allowing structures with volatile fields in registers, but
1932 it does not seem to make any sense and is probably not what you wanted
1933 to do. So the compiler will give an error message in this case.
1936 Making certain warnings into errors by default.
1938 Some ISO C testsuites report failure when the compiler does not produce
1939 an error message for a certain program.
1941 @opindex pedantic-errors
1942 ISO C requires a ``diagnostic'' message for certain kinds of invalid
1943 programs, but a warning is defined by GCC to count as a diagnostic. If
1944 GCC produces a warning but not an error, that is correct ISO C support.
1945 If test suites call this ``failure'', they should be run with the GCC
1946 option @option{-pedantic-errors}, which will turn these warnings into
1951 @node Warnings and Errors
1952 @section Warning Messages and Error Messages
1954 @cindex error messages
1955 @cindex warnings vs errors
1956 @cindex messages, warning and error
1957 The GNU compiler can produce two kinds of diagnostics: errors and
1958 warnings. Each kind has a different purpose:
1962 @dfn{Errors} report problems that make it impossible to compile your
1963 program. GCC reports errors with the source file name and line
1964 number where the problem is apparent.
1967 @dfn{Warnings} report other unusual conditions in your code that
1968 @emph{may} indicate a problem, although compilation can (and does)
1969 proceed. Warning messages also report the source file name and line
1970 number, but include the text @samp{warning:} to distinguish them
1971 from error messages.
1974 Warnings may indicate danger points where you should check to make sure
1975 that your program really does what you intend; or the use of obsolete
1976 features; or the use of nonstandard features of GNU C or C++. Many
1977 warnings are issued only if you ask for them, with one of the @option{-W}
1978 options (for instance, @option{-Wall} requests a variety of useful
1982 @opindex pedantic-errors
1983 GCC always tries to compile your program if possible; it never
1984 gratuitously rejects a program whose meaning is clear merely because
1985 (for instance) it fails to conform to a standard. In some cases,
1986 however, the C and C++ standards specify that certain extensions are
1987 forbidden, and a diagnostic @emph{must} be issued by a conforming
1988 compiler. The @option{-pedantic} option tells GCC to issue warnings in
1989 such cases; @option{-pedantic-errors} says to make them errors instead.
1990 This does not mean that @emph{all} non-ISO constructs get warnings
1993 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
1994 more detail on these and related command-line options.
1997 @chapter Reporting Bugs
1999 @cindex reporting bugs
2001 Your bug reports play an essential role in making GCC reliable.
2003 When you encounter a problem, the first thing to do is to see if it is
2004 already known. @xref{Trouble}. If it isn't known, then you should
2007 Reporting a bug may help you by bringing a solution to your problem, or
2008 it may not. (If it does not, look in the service directory; see
2009 @ref{Service}.) In any case, the principal function of a bug report is
2010 to help the entire community by making the next version of GCC work
2011 better. Bug reports are your contribution to the maintenance of GCC@.
2013 Since the maintainers are very overloaded, we cannot respond to every
2014 bug report. However, if the bug has not been fixed, we are likely to
2015 send you a patch and ask you to tell us whether it works.
2017 In order for a bug report to serve its purpose, you must include the
2018 information that makes for fixing the bug.
2021 * Criteria: Bug Criteria. Have you really found a bug?
2022 * Where: Bug Lists. Where to send your bug report.
2023 * Reporting: Bug Reporting. How to report a bug effectively.
2024 * GNATS: gccbug. You can use a bug reporting tool.
2025 * Known: Trouble. Known problems.
2026 * Help: Service. Where to ask for help.
2029 @node Bug Criteria,Bug Lists,,Bugs
2030 @section Have You Found a Bug?
2031 @cindex bug criteria
2033 If you are not sure whether you have found a bug, here are some guidelines:
2036 @cindex fatal signal
2039 If the compiler gets a fatal signal, for any input whatever, that is a
2040 compiler bug. Reliable compilers never crash.
2042 @cindex invalid assembly code
2043 @cindex assembly code, invalid
2045 If the compiler produces invalid assembly code, for any input whatever
2046 (except an @code{asm} statement), that is a compiler bug, unless the
2047 compiler reports errors (not just warnings) which would ordinarily
2048 prevent the assembler from being run.
2050 @cindex undefined behavior
2051 @cindex undefined function value
2052 @cindex increment operators
2054 If the compiler produces valid assembly code that does not correctly
2055 execute the input source code, that is a compiler bug.
2057 However, you must double-check to make sure, because you may have run
2058 into an incompatibility between GNU C and traditional C
2059 (@pxref{Incompatibilities}). These incompatibilities might be considered
2060 bugs, but they are inescapable consequences of valuable features.
2062 Or you may have a program whose behavior is undefined, which happened
2063 by chance to give the desired results with another C or C++ compiler.
2065 For example, in many nonoptimizing compilers, you can write @samp{x;}
2066 at the end of a function instead of @samp{return x;}, with the same
2067 results. But the value of the function is undefined if @code{return}
2068 is omitted; it is not a bug when GCC produces different results.
2070 Problems often result from expressions with two increment operators,
2071 as in @code{f (*p++, *p++)}. Your previous compiler might have
2072 interpreted that expression the way you intended; GCC might
2073 interpret it another way. Neither compiler is wrong. The bug is
2076 After you have localized the error to a single source line, it should
2077 be easy to check for these things. If your program is correct and
2078 well defined, you have found a compiler bug.
2081 If the compiler produces an error message for valid input, that is a
2084 @cindex invalid input
2086 If the compiler does not produce an error message for invalid input,
2087 that is a compiler bug. However, you should note that your idea of
2088 ``invalid input'' might be my idea of ``an extension'' or ``support
2089 for traditional practice''.
2092 If you are an experienced user of one of the languages GCC supports, your
2093 suggestions for improvement of GCC are welcome in any case.
2096 @node Bug Lists,Bug Reporting,Bug Criteria,Bugs
2097 @section Where to Report Bugs
2098 @cindex bug report mailing lists
2099 @kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
2100 Send bug reports for the GNU Compiler Collection to
2101 @email{gcc-bugs@@gcc.gnu.org}. In accordance with the GNU-wide
2102 convention, in which bug reports for tool ``foo'' are sent
2103 to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
2104 may also be used; it will forward to the address given above.
2106 Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or
2107 more up-to-date bug reporting instructions before you post a bug report.
2109 @node Bug Reporting,gccbug,Bug Lists,Bugs
2110 @section How to Report Bugs
2111 @cindex compiler bugs, reporting
2113 The fundamental principle of reporting bugs usefully is this:
2114 @strong{report all the facts}. If you are not sure whether to state a
2115 fact or leave it out, state it!
2117 Often people omit facts because they think they know what causes the
2118 problem and they conclude that some details don't matter. Thus, you might
2119 assume that the name of the variable you use in an example does not matter.
2120 Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
2121 stray memory reference which happens to fetch from the location where that
2122 name is stored in memory; perhaps, if the name were different, the contents
2123 of that location would fool the compiler into doing the right thing despite
2124 the bug. Play it safe and give a specific, complete example. That is the
2125 easiest thing for you to do, and the most helpful.
2127 Keep in mind that the purpose of a bug report is to enable someone to
2128 fix the bug if it is not known. It isn't very important what happens if
2129 the bug is already known. Therefore, always write your bug reports on
2130 the assumption that the bug is not known.
2132 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2133 bell?'' This cannot help us fix a bug, so it is basically useless. We
2134 respond by asking for enough details to enable us to investigate.
2135 You might as well expedite matters by sending them to begin with.
2137 Try to make your bug report self-contained. If we have to ask you for
2138 more information, it is best if you include all the previous information
2139 in your response, as well as the information that was missing.
2141 Please report each bug in a separate message. This makes it easier for
2142 us to track which bugs have been fixed and to forward your bugs reports
2143 to the appropriate maintainer.
2145 To enable someone to investigate the bug, you should include all these
2150 The version of GCC@. You can get this by running it with the
2153 Without this, we won't know whether there is any point in looking for
2154 the bug in the current version of GCC@.
2157 A complete input file that will reproduce the bug. If the bug is in the
2158 C preprocessor, send a source file and any header files that it
2159 requires. If the bug is in the compiler proper (@file{cc1}), send the
2160 preprocessor output generated by adding @option{-save-temps} to the
2161 compilation command (@pxref{Debugging Options}). When you do this, use
2162 the same @option{-I}, @option{-D} or @option{-U} options that you used in
2163 actual compilation. Then send the @var{input}.i or @var{input}.ii files
2166 A single statement is not enough of an example. In order to compile it,
2167 it must be embedded in a complete file of compiler input; and the bug
2168 might depend on the details of how this is done.
2170 Without a real example one can compile, all anyone can do about your bug
2171 report is wish you luck. It would be futile to try to guess how to
2172 provoke the bug. For example, bugs in register allocation and reloading
2173 frequently depend on every little detail of the function they happen in.
2175 Even if the input file that fails comes from a GNU program, you should
2176 still send the complete test case. Don't ask the GCC maintainers to
2177 do the extra work of obtaining the program in question---they are all
2178 overworked as it is. Also, the problem may depend on what is in the
2179 header files on your system; it is unreliable for the GCC maintainers
2180 to try the problem with the header files available to them. By sending
2181 CPP output, you can eliminate this source of uncertainty and save us
2182 a certain percentage of wild goose chases.
2185 The command arguments you gave GCC to compile that example
2186 and observe the bug. For example, did you use @option{-O}? To guarantee
2187 you won't omit something important, list all the options.
2189 If we were to try to guess the arguments, we would probably guess wrong
2190 and then we would not encounter the bug.
2193 The type of machine you are using, and the operating system name and
2197 The operands you gave to the @code{configure} command when you installed
2201 A complete list of any modifications you have made to the compiler
2202 source. (We don't promise to investigate the bug unless it happens in
2203 an unmodified compiler. But if you've made modifications and don't tell
2204 us, then you are sending us on a wild goose chase.)
2206 Be precise about these changes. A description in English is not
2207 enough---send a context diff for them.
2209 Adding files of your own (such as a machine description for a machine we
2210 don't support) is a modification of the compiler source.
2213 Details of any other deviations from the standard procedure for installing
2217 A description of what behavior you observe that you believe is
2218 incorrect. For example, ``The compiler gets a fatal signal,'' or,
2219 ``The assembler instruction at line 208 in the output is incorrect.''
2221 Of course, if the bug is that the compiler gets a fatal signal, then one
2222 can't miss it. But if the bug is incorrect output, the maintainer might
2223 not notice unless it is glaringly wrong. None of us has time to study
2224 all the assembler code from a 50-line C program just on the chance that
2225 one instruction might be wrong. We need @emph{you} to do this part!
2227 Even if the problem you experience is a fatal signal, you should still
2228 say so explicitly. Suppose something strange is going on, such as, your
2229 copy of the compiler is out of synch, or you have encountered a bug in
2230 the C library on your system. (This has happened!) Your copy might
2231 crash and the copy here would not. If you @i{said} to expect a crash,
2232 then when the compiler here fails to crash, we would know that the bug
2233 was not happening. If you don't say to expect a crash, then we would
2234 not know whether the bug was happening. We would not be able to draw
2235 any conclusion from our observations.
2237 If the problem is a diagnostic when compiling GCC with some other
2238 compiler, say whether it is a warning or an error.
2240 Often the observed symptom is incorrect output when your program is run.
2241 Sad to say, this is not enough information unless the program is short
2242 and simple. None of us has time to study a large program to figure out
2243 how it would work if compiled correctly, much less which line of it was
2244 compiled wrong. So you will have to do that. Tell us which source line
2245 it is, and what incorrect result happens when that line is executed. A
2246 person who understands the program can find this as easily as finding a
2247 bug in the program itself.
2250 If you send examples of assembler code output from GCC,
2251 please use @option{-g} when you make them. The debugging information
2252 includes source line numbers which are essential for correlating the
2253 output with the input.
2256 If you wish to mention something in the GCC source, refer to it by
2257 context, not by line number.
2259 The line numbers in the development sources don't match those in your
2260 sources. Your line numbers would convey no useful information to the
2264 Additional information from a debugger might enable someone to find a
2265 problem on a machine which he does not have available. However, you
2266 need to think when you collect this information if you want it to have
2267 any chance of being useful.
2269 @cindex backtrace for bug reports
2270 For example, many people send just a backtrace, but that is never
2271 useful by itself. A simple backtrace with arguments conveys little
2272 about GCC because the compiler is largely data-driven; the same
2273 functions are called over and over for different RTL insns, doing
2274 different things depending on the details of the insn.
2276 Most of the arguments listed in the backtrace are useless because they
2277 are pointers to RTL list structure. The numeric values of the
2278 pointers, which the debugger prints in the backtrace, have no
2279 significance whatever; all that matters is the contents of the objects
2280 they point to (and most of the contents are other such pointers).
2282 In addition, most compiler passes consist of one or more loops that
2283 scan the RTL insn sequence. The most vital piece of information about
2284 such a loop---which insn it has reached---is usually in a local variable,
2288 What you need to provide in addition to a backtrace are the values of
2289 the local variables for several stack frames up. When a local
2290 variable or an argument is an RTX, first print its value and then use
2291 the GDB command @code{pr} to print the RTL expression that it points
2292 to. (If GDB doesn't run on your machine, use your debugger to call
2293 the function @code{debug_rtx} with the RTX as an argument.) In
2294 general, whenever a variable is a pointer, its value is no use
2295 without the data it points to.
2298 Here are some things that are not necessary:
2302 A description of the envelope of the bug.
2304 Often people who encounter a bug spend a lot of time investigating
2305 which changes to the input file will make the bug go away and which
2306 changes will not affect it.
2308 This is often time consuming and not very useful, because the way we
2309 will find the bug is by running a single example under the debugger with
2310 breakpoints, not by pure deduction from a series of examples. You might
2311 as well save your time for something else.
2313 Of course, if you can find a simpler example to report @emph{instead} of
2314 the original one, that is a convenience. Errors in the output will be
2315 easier to spot, running under the debugger will take less time, etc.
2316 Most GCC bugs involve just one function, so the most straightforward
2317 way to simplify an example is to delete all the function definitions
2318 except the one where the bug occurs. Those earlier in the file may be
2319 replaced by external declarations if the crucial function depends on
2320 them. (Exception: inline functions may affect compilation of functions
2321 defined later in the file.)
2323 However, simplification is not vital; if you don't want to do this,
2324 report the bug anyway and send the entire test case you used.
2327 In particular, some people insert conditionals @samp{#ifdef BUG} around
2328 a statement which, if removed, makes the bug not happen. These are just
2329 clutter; we won't pay any attention to them anyway. Besides, you should
2330 send us cpp output, and that can't have conditionals.
2333 A patch for the bug.
2335 A patch for the bug is useful if it is a good one. But don't omit the
2336 necessary information, such as the test case, on the assumption that a
2337 patch is all we need. We might see problems with your patch and decide
2338 to fix the problem another way, or we might not understand it at all.
2340 Sometimes with a program as complicated as GCC it is very hard to
2341 construct an example that will make the program follow a certain path
2342 through the code. If you don't send the example, we won't be able to
2343 construct one, so we won't be able to verify that the bug is fixed.
2345 And if we can't understand what bug you are trying to fix, or why your
2346 patch should be an improvement, we won't install it. A test case will
2347 help us to understand.
2349 See @uref{http://gcc.gnu.org/contribute.html}
2350 for guidelines on how to make it easy for us to
2351 understand and install your patches.
2354 A guess about what the bug is or what it depends on.
2356 Such guesses are usually wrong. Even I can't guess right about such
2357 things without first using the debugger to find the facts.
2362 We have no way of examining a core dump for your type of machine
2363 unless we have an identical system---and if we do have one,
2364 we should be able to reproduce the crash ourselves.
2367 @node gccbug,, Bug Reporting, Bugs
2368 @section The gccbug script
2369 @cindex gccbug script
2371 To simplify creation of bug reports, and to allow better tracking of
2372 reports, we use the GNATS bug tracking system. Part of that system is
2373 the @code{gccbug} script. This is a Unix shell script, so you need a
2374 shell to run it. It is normally installed in the same directory where
2375 @code{gcc} is installed.
2377 The gccbug script is derived from send-pr, @pxref{using
2378 send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
2379 invoked, it starts a text editor so you can fill out the various fields
2380 of the report. When the you quit the editor, the report is automatically
2381 send to the bug reporting address.
2383 A number of fields in this bug report form are specific to GCC, and are
2384 explained at @uref{http://gcc.gnu.org/gnats.html}.
2387 @chapter How To Get Help with GCC
2389 If you need help installing, using or changing GCC, there are two
2394 Send a message to a suitable network mailing list. First try
2395 @email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
2396 that brings no response, try @email{gcc@@gcc.gnu.org}. For help
2397 changing GCC, ask @email{gcc@@gcc.gnu.org}. If you think you have found
2398 a bug in GCC, please report it following the instructions at
2399 @pxref{Bug Reporting}.
2402 Look in the service directory for someone who might help you for a fee.
2403 The service directory is found at
2404 @uref{http://www.gnu.org/prep/service.html}.
2407 @c For further information, see
2408 @c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}.
2409 @c FIXME: this URL may be too volatile, this FAQ entry needs to move to
2410 @c the regular web pages before we can uncomment the reference.
2413 @chapter Contributing to GCC Development
2415 If you would like to help pretest GCC releases to assure they work well,
2416 our current development sources are available by CVS (see
2417 @uref{http://gcc.gnu.org/cvs.html}). Source and binary snapshots are
2418 also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
2420 If you would like to work on improvements to GCC, please read the
2421 advice at these URLs:
2424 @uref{http://gcc.gnu.org/contribute.html}
2425 @uref{http://gcc.gnu.org/contributewhy.html}
2429 for information on how to make useful contributions and avoid
2430 duplication of effort. Suggested projects are listed at
2431 @uref{http://gcc.gnu.org/projects/}.
2434 @chapter Using GCC on VMS
2436 @c prevent bad page break with this line
2437 Here is how to use GCC on VMS@.
2440 * Include Files and VMS:: Where the preprocessor looks for the include files.
2441 * Global Declarations:: How to do globaldef, globalref and globalvalue with
2443 * VMS Misc:: Misc information.
2446 @node Include Files and VMS
2447 @section Include Files and VMS
2449 @cindex include files and VMS
2450 @cindex VMS and include files
2451 @cindex header files and VMS
2452 Due to the differences between the filesystems of Unix and VMS, GCC
2453 attempts to translate file names in @samp{#include} into names that VMS
2454 will understand. The basic strategy is to prepend a prefix to the
2455 specification of the include file, convert the whole filename to a VMS
2456 filename, and then try to open the file. GCC tries various prefixes
2457 one by one until one of them succeeds:
2461 The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
2462 where GNU C header files are traditionally stored. If you wish to store
2463 header files in non-standard locations, then you can assign the logical
2464 @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
2465 list is suitable for use with a rooted logical.
2468 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where
2469 VAX-C header files are traditionally stored.
2472 If the include file specification by itself is a valid VMS filename, the
2473 preprocessor then uses this name with no prefix in an attempt to open
2477 If the file specification is not a valid VMS filename (i.e.@: does not
2478 contain a device or a directory specifier, and contains a @samp{/}
2479 character), the preprocessor tries to convert it from Unix syntax to
2482 Conversion works like this: the first directory name becomes a device,
2483 and the rest of the directories are converted into VMS-format directory
2484 names. For example, the name @file{X11/foobar.h} is
2485 translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
2486 whichever one can be opened. This strategy allows you to assign a
2487 logical name to point to the actual location of the header files.
2490 If none of these strategies succeeds, the @samp{#include} fails.
2493 Include directives of the form:
2500 are a common source of incompatibility between VAX-C and GCC@. VAX-C
2501 treats this much like a standard @code{#include <foobar.h>} directive.
2502 That is incompatible with the ISO C behavior implemented by GCC: to
2503 expand the name @code{foobar} as a macro. Macro expansion should
2504 eventually yield one of the two standard formats for @code{#include}:
2507 #include "@var{file}"
2508 #include <@var{file}>
2511 If you have this problem, the best solution is to modify the source to
2512 convert the @code{#include} directives to one of the two standard forms.
2513 That will work with either compiler. If you want a quick and dirty fix,
2514 define the file names as macros with the proper expansion, like this:
2517 #define stdio <stdio.h>
2521 This will work, as long as the name doesn't conflict with anything else
2524 Another source of incompatibility is that VAX-C assumes that:
2531 is actually asking for the file @file{foobar.h}. GCC does not
2532 make this assumption, and instead takes what you ask for literally;
2533 it tries to read the file @file{foobar}. The best way to avoid this
2534 problem is to always specify the desired file extension in your include
2537 GCC for VMS is distributed with a set of include files that is
2538 sufficient to compile most general purpose programs. Even though the
2539 GCC distribution does not contain header files to define constants
2540 and structures for some VMS system-specific functions, there is no
2541 reason why you cannot use GCC with any of these functions. You first
2542 may have to generate or create header files, either by using the public
2543 domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
2544 extracting the relevant modules from one of the system macro libraries,
2545 and using an editor to construct a C header file.
2547 A @code{#include} file name cannot contain a DECNET node name. The
2548 preprocessor reports an I/O error if you attempt to use a node name,
2549 whether explicitly, or implicitly via a logical name.
2551 @node Global Declarations
2552 @section Global Declarations and VMS
2556 @findex GLOBALVALUEDEF
2557 @findex GLOBALVALUEREF
2558 GCC does not provide the @code{globalref}, @code{globaldef} and
2559 @code{globalvalue} keywords of VAX-C@. You can get the same effect with
2560 an obscure feature of GAS, the GNU assembler. (This requires GAS
2561 version 1.39 or later.) The following macros allow you to use this
2562 feature in a fairly natural way:
2566 #define GLOBALREF(TYPE,NAME) \
2568 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
2569 #define GLOBALDEF(TYPE,NAME,VALUE) \
2571 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
2573 #define GLOBALVALUEREF(TYPE,NAME) \
2574 const TYPE NAME[1] \
2575 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
2576 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2577 const TYPE NAME[1] \
2578 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \
2581 #define GLOBALREF(TYPE,NAME) \
2583 #define GLOBALDEF(TYPE,NAME,VALUE) \
2584 globaldef TYPE NAME = VALUE
2585 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2586 globalvalue TYPE NAME = VALUE
2587 #define GLOBALVALUEREF(TYPE,NAME) \
2588 globalvalue TYPE NAME
2593 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
2594 name is removed by the assembler, after it has modified the attributes
2595 of the symbol). These macros are provided in the VMS binaries
2596 distribution in a header file @file{GNU_HACKS.H}. An example of the
2600 GLOBALREF (int, ijk);
2601 GLOBALDEF (int, jkl, 0);
2604 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
2605 straightforwardly for arrays, since there is no way to insert the array
2606 dimension into the declaration at the right place. However, you can
2607 declare an array with these macros if you first define a typedef for the
2608 array type, like this:
2611 typedef int intvector[10];
2612 GLOBALREF (intvector, foo);
2615 Array and structure initializers will also break the macros; you can
2616 define the initializer to be a macro of its own, or you can expand the
2617 @code{GLOBALDEF} macro by hand. You may find a case where you wish to
2618 use the @code{GLOBALDEF} macro with a large array, but you are not
2619 interested in explicitly initializing each element of the array. In
2620 such cases you can use an initializer like: @code{@{0,@}}, which will
2621 initialize the entire array to @code{0}.
2623 A shortcoming of this implementation is that a variable declared with
2624 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For
2625 example, the declaration:
2628 GLOBALVALUEREF(int, ijk);
2632 declares the variable @code{ijk} as an array of type @code{int [1]}.
2633 This is done because a globalvalue is actually a constant; its ``value''
2634 is what the linker would normally consider an address. That is not how
2635 an integer value works in C, but it is how an array works. So treating
2636 the symbol as an array name gives consistent results---with the
2637 exception that the value seems to have the wrong type. @strong{Don't
2638 try to access an element of the array.} It doesn't have any elements.
2639 The array ``address'' may not be the address of actual storage.
2641 The fact that the symbol is an array may lead to warnings where the
2642 variable is used. Insert type casts to avoid the warnings. Here is an
2643 example; it takes advantage of the ISO C feature allowing macros that
2644 expand to use the same name as the macro itself.
2647 GLOBALVALUEREF (int, ss$_normal);
2648 GLOBALVALUEDEF (int, xyzzy,123);
2650 #define ss$_normal ((int) ss$_normal)
2651 #define xyzzy ((int) xyzzy)
2655 Don't use @code{globaldef} or @code{globalref} with a variable whose
2656 type is an enumeration type; this is not implemented. Instead, make the
2657 variable an integer, and use a @code{globalvaluedef} for each of the
2658 enumeration values. An example of this would be:
2662 GLOBALDEF (int, color, 0);
2663 GLOBALVALUEDEF (int, RED, 0);
2664 GLOBALVALUEDEF (int, BLUE, 1);
2665 GLOBALVALUEDEF (int, GREEN, 3);
2667 enum globaldef color @{RED, BLUE, GREEN = 3@};
2672 @section Other VMS Issues
2674 @cindex exit status and VMS
2675 @cindex return value of @code{main}
2676 @cindex @code{main} and the exit status
2677 GCC automatically arranges for @code{main} to return 1 by default if
2678 you fail to specify an explicit return value. This will be interpreted
2679 by VMS as a status code indicating a normal successful completion.
2680 Version 1 of GCC did not provide this default.
2682 GCC on VMS works only with the GNU assembler, GAS@. You need version
2683 1.37 or later of GAS in order to produce value debugging information for
2684 the VMS debugger. Use the ordinary VMS linker with the object files
2687 @cindex shared VMS run time system
2688 @cindex @file{VAXCRTL}
2689 Under previous versions of GCC, the generated code would occasionally
2690 give strange results when linked to the sharable @file{VAXCRTL} library.
2691 Now this should work.
2693 A caveat for use of @code{const} global variables: the @code{const}
2694 modifier must be specified in every external declaration of the variable
2695 in all of the source files that use that variable. Otherwise the linker
2696 will issue warnings about conflicting attributes for the variable. Your
2697 program will still work despite the warnings, but the variable will be
2698 placed in writable storage.
2700 @cindex name augmentation
2701 @cindex case sensitivity and VMS
2702 @cindex VMS and case sensitivity
2703 Although the VMS linker does distinguish between upper and lower case
2704 letters in global symbols, most VMS compilers convert all such symbols
2705 into upper case and most run-time library routines also have upper case
2706 names. To be able to reliably call such routines, GCC (by means of
2707 the assembler GAS) converts global symbols into upper case like other
2708 VMS compilers. However, since the usual practice in C is to distinguish
2709 case, GCC (via GAS) tries to preserve usual C behavior by augmenting
2710 each name that is not all lower case. This means truncating the name
2711 to at most 23 characters and then adding more characters at the end
2712 which encode the case pattern of those 23. Names which contain at
2713 least one dollar sign are an exception; they are converted directly into
2714 upper case without augmentation.
2716 Name augmentation yields bad results for programs that use precompiled
2717 libraries (such as Xlib) which were generated by another compiler. You
2718 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
2719 it makes external C functions and variables case-independent as is usual
2720 on VMS@. Alternatively, you could write all references to the functions
2721 and variables in such libraries using lower case; this will work on VMS,
2722 but is not portable to other systems. The compiler option @samp{/NAMES}
2723 also provides control over global name handling.
2725 Function and variable names are handled somewhat differently with G++.
2726 The GNU C++ compiler performs @dfn{name mangling} on function
2727 names, which means that it adds information to the function name to
2728 describe the data types of the arguments that the function takes. One
2729 result of this is that the name of a function can become very long.
2730 Since the VMS linker only recognizes the first 31 characters in a name,
2731 special action is taken to ensure that each function and variable has a
2732 unique name that can be represented in 31 characters.
2734 If the name (plus a name augmentation, if required) is less than 32
2735 characters in length, then no special action is performed. If the name
2736 is longer than 31 characters, the assembler (GAS) will generate a
2737 hash string based upon the function name, truncate the function name to
2738 23 characters, and append the hash string to the truncated name. If the
2739 @samp{/VERBOSE} compiler option is used, the assembler will print both
2740 the full and truncated names of each symbol that is truncated.
2742 The @samp{/NOCASE_HACK} compiler option should not be used when you are
2743 compiling programs that use libg++. libg++ has several instances of
2744 objects (i.e. @code{Filebuf} and @code{filebuf}) which become
2745 indistinguishable in a case-insensitive environment. This leads to
2746 cases where you need to inhibit augmentation selectively (if you were
2747 using libg++ and Xlib in the same program, for example). There is no
2748 special feature for doing this, but you can get the result by defining a
2749 macro for each mixed case symbol for which you wish to inhibit
2750 augmentation. The macro should expand into the lower case equivalent of
2751 itself. For example:
2754 #define StuDlyCapS studlycaps
2757 These macro definitions can be placed in a header file to minimize the
2758 number of changes to your source code.
2761 @chapter Additional Makefile and configure information.
2763 @section Makefile Targets
2764 @cindex makefile targets
2765 @cindex targets, makefile
2769 This is the default target. Depending on what your build/host/target
2770 configuration is, it coordinates all the things that need to be built.
2773 Produce info-formatted documentation. Also, @code{make dvi} is
2774 available for DVI-formatted documentation, and @code{make
2775 generated-manpages} to generate man pages.
2778 Delete the files made while building the compiler.
2781 That, and all the other files built by @code{make all}.
2784 That, and all the files created by @code{configure}.
2787 That, and any temporary or intermediate files, like emacs backup files.
2789 @item maintainer-clean
2790 Distclean plus any file that can be generated from other files. Note
2791 that additional tools may be required beyond what is normally needed to
2798 Deletes installed files.
2801 Run the testsuite. This creates a @file{testsuite} subdirectory that
2802 has various @file{.sum} and @file{.log} files containing the results of
2803 the testing. You can run subsets with, for example, @code{make check-gcc}.
2804 You can specify specific tests by setting RUNTESTFLAGS to be the name
2805 of the @file{.exp} file, optionally followed by (for some tests) an equals
2806 and a file wildcard, like:
2809 make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
2812 Note that running the testsuite may require additional tools be
2813 installed, such as TCL or dejagnu.
2816 Builds gcc three times---once with the native compiler, once with the
2817 native-built compiler it just built, and once with the compiler it built
2818 the second time. In theory, the last two should produce the same
2819 results, which @code{make compare} can check. Each step of this process
2820 is called a ``stage'', and the results of each stage @var{N}
2821 (@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}.
2823 @item bootstrap-lean
2824 Like @code{bootstrap}, except that the various stages are removed once
2825 they're no longer needed. This saves disk space.
2828 Once bootstrapped, this incrementally rebuilds each of the three stages,
2829 one at a time. It does this by ``bubbling'' the stages up from their
2830 subdirectories, rebuilding them, and copying them back to their
2831 subdirectories. This will allow you to, for example, quickly rebuild a
2832 bootstrapped compiler after changing the sources, without having to do a
2836 Rebuilds the most recently built stage. Since each stage requires
2837 special invocation, using this target means you don't have to keep track
2838 of which stage you're on or what invocation that stage needs.
2841 Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}).
2843 @item stage@var{N} (@var{N} = 1@dots{}4)
2844 For each stage, moves the appropriate files to the @file{stage@var{N}}
2847 @item unstage@var{N} (@var{N} = 1@dots{}4)
2848 Undoes the corresponding @code{stage@var{N}}.
2850 @item restage@var{N} (@var{N} = 1@dots{}4)
2851 Undoes the corresponding @code{stage@var{N}} and rebuilds it with the
2855 Compares the results of stages 2 and 3. This ensures that the compiler
2856 is running properly, since it should produce the same object files
2857 regardless of how it itself was compiled.
2861 @section Configure Terms and History
2862 @cindex configure terms
2865 This section is not instructions for building GCC. If you are trying to
2866 do a build, you should first read @uref{http://gcc.gnu.org/install/} or
2867 whatever installation instructions came with your source package.
2869 The configure and build process has a long and colorful history, and can
2870 be confusing to anyone who doesn't know why things are the way they are.
2871 While there are other documents which describe the configuration process
2872 in detail, here are a few things that everyone working on GCC should
2875 There are three system names that the build knows about: the machine you
2876 are building on (@dfn{build}), the machine that you are building for
2877 (@dfn{host}), and the machine that GCC will produce code for
2878 (@dfn{target}). When you configure GCC, you specify these with
2879 @option{--build=}, @option{--host=}, and @option{--target=}.
2881 Specifying the host without specifying the build should be avoided, as
2882 @command{configure} may (and once did) assume that the host you specify
2883 is also the build, which may not be true.
2885 If build, host, and target are all the same, this is called a
2886 @dfn{native}. If build and host are the same but target is different,
2887 this is called a @dfn{cross}. If build, host, and target are all
2888 different this is called a @dfn{canadian} (for obscure reasons dealing
2889 with Canada's political party and the background of the person working
2890 on the build at that time). If host and target are the same, but build
2891 is different, you are using a cross-compiler to build a native for a
2892 different system. Some people call this a @dfn{host-x-host},
2893 @dfn{crossed native}, or @dfn{cross-built native}. If build and target
2894 are the same, but host is different, you are using a cross compiler to
2895 build a cross compiler that produces code for the machine you're
2896 building on. This is rare, so there is no common say of describing it
2897 (although I propose calling it a @dfn{crossback}).
2899 If build and host are the same, the GCC you are building will also be
2900 used to build the target libraries (like @code{libstdc++}). If build and host
2901 are different, you must have already build and installed a cross
2902 compiler that will be used to build the target libraries (if you
2903 configured with @option{--target=foo-bar}, this compiler will be called
2904 @command{foo-bar-gcc}).
2906 In the case of target libraries, the machine you're building for is the
2907 machine you specified with @option{--target}. So, build is the machine
2908 you're building on (no change there), host is the machine you're
2909 building for (the target libraries are built for the target, so host is
2910 the target you specified), and target doesn't apply (because you're not
2911 building a compiler, you're building libraries). The configure/make
2912 process will adjust these variables as needed. It also sets
2913 @code{$with_cross_host} to the original @option{--host} value in case you
2916 Libiberty, for example, is built twice. The first time, host comes from
2917 @option{--host} and the second time host comes from @option{--target}.
2918 Historically, libiberty has not been built for the build machine,
2919 though, which causes some interesting issues with programs used to
2920 generate sources for the build. Fixing this, so that libiberty is built
2921 three times, has long been on the to-do list.
2927 @chapter GCC and Portability
2929 @cindex GCC and portability
2931 The main goal of GCC was to make a good, fast compiler for machines in
2932 the class that the GNU system aims to run on: 32-bit machines that address
2933 8-bit bytes and have several general registers. Elegance, theoretical
2934 power and simplicity are only secondary.
2936 GCC gets most of the information about the target machine from a machine
2937 description which gives an algebraic formula for each of the machine's
2938 instructions. This is a very clean way to describe the target. But when
2939 the compiler needs information that is difficult to express in this
2940 fashion, I have not hesitated to define an ad-hoc parameter to the machine
2941 description. The purpose of portability is to reduce the total work needed
2942 on the compiler; it was not of interest for its own sake.
2945 @cindex autoincrement addressing, availability
2947 GCC does not contain machine dependent code, but it does contain code
2948 that depends on machine parameters such as endianness (whether the most
2949 significant byte has the highest or lowest address of the bytes in a word)
2950 and the availability of autoincrement addressing. In the RTL-generation
2951 pass, it is often necessary to have multiple strategies for generating code
2952 for a particular kind of syntax tree, strategies that are usable for different
2953 combinations of parameters. Often I have not tried to address all possible
2954 cases, but only the common ones or only the ones that I have encountered.
2955 As a result, a new target may require additional strategies. You will know
2956 if this happens because the compiler will call @code{abort}. Fortunately,
2957 the new strategies can be added in a machine-independent fashion, and will
2958 affect only the target machines that need them.
2963 @chapter Interfacing to GCC Output
2964 @cindex interfacing to GCC output
2965 @cindex run-time conventions
2966 @cindex function call conventions
2967 @cindex conventions, run-time
2969 GCC is normally configured to use the same function calling convention
2970 normally in use on the target system. This is done with the
2971 machine-description macros described (@pxref{Target Macros}).
2973 @cindex unions, returning
2974 @cindex structures, returning
2975 @cindex returning structures and unions
2976 However, returning of structure and union values is done differently on
2977 some target machines. As a result, functions compiled with PCC
2978 returning such types cannot be called from code compiled with GCC,
2979 and vice versa. This does not cause trouble often because few Unix
2980 library routines return structures or unions.
2982 GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
2983 long in the same registers used for @code{int} or @code{double} return
2984 values. (GCC typically allocates variables of such types in
2985 registers also.) Structures and unions of other sizes are returned by
2986 storing them into an address passed by the caller (usually in a
2987 register). The machine-description macros @code{STRUCT_VALUE} and
2988 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
2990 By contrast, PCC on most target machines returns structures and unions
2991 of any size by copying the data into an area of static storage, and then
2992 returning the address of that storage as if it were a pointer value.
2993 The caller must copy the data from that memory area to the place where
2994 the value is wanted. This is slower than the method used by GCC, and
2995 fails to be reentrant.
2997 On some target machines, such as RISC machines and the 80386, the
2998 standard system convention is to pass to the subroutine the address of
2999 where to return the value. On these machines, GCC has been
3000 configured to be compatible with the standard compiler, when this method
3001 is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3003 @cindex argument passing
3004 @cindex passing arguments
3005 GCC uses the system's standard convention for passing arguments. On
3006 some machines, the first few arguments are passed in registers; in
3007 others, all are passed on the stack. It would be possible to use
3008 registers for argument passing on any machine, and this would probably
3009 result in a significant speedup. But the result would be complete
3010 incompatibility with code that follows the standard convention. So this
3011 change is practical only if you are switching to GCC as the sole C
3012 compiler for the system. We may implement register argument passing on
3013 certain machines once we have a complete GNU system so that we can
3014 compile the libraries with GCC@.
3016 On some machines (particularly the Sparc), certain types of arguments
3017 are passed ``by invisible reference''. This means that the value is
3018 stored in memory, and the address of the memory location is passed to
3021 @cindex @code{longjmp} and automatic variables
3022 If you use @code{longjmp}, beware of automatic variables. ISO C says that
3023 automatic variables that are not declared @code{volatile} have undefined
3024 values after a @code{longjmp}. And this is all GCC promises to do,
3025 because it is very difficult to restore register variables correctly, and
3026 one of GCC's features is that it can put variables in registers without
3029 If you want a variable to be unaltered by @code{longjmp}, and you don't
3030 want to write @code{volatile} because old C compilers don't accept it,
3031 just take the address of the variable. If a variable's address is ever
3032 taken, even if just to compute it and ignore it, then the variable cannot
3043 @cindex arithmetic libraries
3044 @cindex math libraries
3045 @opindex msoft-float
3046 Code compiled with GCC may call certain library routines. Most of
3047 them handle arithmetic for which there are no instructions. This
3048 includes multiply and divide on some machines, and floating point
3049 operations on any machine for which floating point support is disabled
3050 with @option{-msoft-float}. Some standard parts of the C library, such as
3051 @code{bcopy} or @code{memcpy}, are also called automatically. The usual
3052 function call interface is used for calling the library routines.
3054 Some of these routines can be defined in mostly machine-independent C;
3055 they appear in @file{libgcc2.c}. Others must be hand-written in
3056 assembly language for each processor. Wherever they are defined, they
3057 are compiled into the support library, @file{libgcc.a}, which is
3058 automatically searched when you link programs with GCC@.
3063 @chapter Passes and Files of the Compiler
3064 @cindex passes and files of the compiler
3065 @cindex files and passes of the compiler
3066 @cindex compiler passes and files
3068 @cindex top level of compiler
3069 The overall control structure of the compiler is in @file{toplev.c}. This
3070 file is responsible for initialization, decoding arguments, opening and
3071 closing files, and sequencing the passes.
3073 @cindex parsing pass
3074 The parsing pass is invoked only once, to parse the entire input. A
3075 high level tree representation is then generated from the input,
3076 one function at a time. This tree code is then transformed into RTL
3077 intermediate code, and processed. The files involved in transforming
3078 the trees into RTL are @file{expr.c}, @file{expmed.c}, and
3080 @c Note, the above files aren't strictly the only files involved. It's
3081 @c all over the place (function.c, final.c,etc). However, those are
3082 @c the files that are supposed to be directly involved, and have
3083 @c their purpose listed as such, so i've only listed them.
3084 The order of trees that are processed, is not
3085 necessarily the same order they are generated from
3086 the input, due to deferred inlining, and other considerations.
3088 @findex rest_of_compilation
3089 @findex rest_of_decl_compilation
3090 Each time the parsing pass reads a complete function definition or
3091 top-level declaration, it calls either the function
3092 @code{rest_of_compilation}, or the function
3093 @code{rest_of_decl_compilation} in @file{toplev.c}, which are
3094 responsible for all further processing necessary, ending with output of
3095 the assembler language. All other compiler passes run, in sequence,
3096 within @code{rest_of_compilation}. When that function returns from
3097 compiling a function definition, the storage used for that function
3098 definition's compilation is entirely freed, unless it is an inline
3099 function, or was deferred for some reason (this can occur in
3100 templates, for example).
3102 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3105 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3108 Here is a list of all the passes of the compiler and their source files.
3109 Also included is a description of where debugging dumps can be requested
3110 with @option{-d} options.
3114 Parsing. This pass reads the entire text of a function definition,
3115 constructing a high level tree representation. (Because of the semantic
3116 analysis that takes place during this pass, it does more than is
3117 formally considered to be parsing.)
3119 The tree representation does not entirely follow C syntax, because it is
3120 intended to support other languages as well.
3122 Language-specific data type analysis is also done in this pass, and every
3123 tree node that represents an expression has a data type attached.
3124 Variables are represented as declaration nodes.
3126 The language-independent source files for parsing are
3127 @file{tree.c}, @file{fold-const.c}, and @file{stor-layout.c}.
3128 There are also header files @file{tree.h} and @file{tree.def}
3129 which define the format of the tree representation.
3131 C preprocessing, for language front ends, that want or require it, is
3132 performed by cpplib, which is covered in separate documentation. In
3133 particular, the internals are covered in @xref{Top, ,Cpplib internals,
3134 cppinternals, Cpplib Internals}.
3136 @c Avoiding overfull is tricky here.
3137 The source files to parse C are
3143 @file{c-aux-info.c},
3146 along with a header file
3148 and some files shared with Objective-C and C++.
3150 The source files for parsing C++ are in @file{cp/}.
3151 They are @file{parse.y},
3153 @file{cvt.c}, @file{decl.c}, @file{decl2.c},
3155 @file{expr.c}, @file{init.c}, @file{lex.c},
3156 @file{method.c}, @file{ptree.c},
3157 @file{search.c}, @file{spew.c},
3158 @file{semantics.c}, @file{tree.c},
3159 @file{typeck2.c}, and
3160 @file{typeck.c}, along with header files @file{cp-tree.def},
3161 @file{cp-tree.h}, and @file{decl.h}.
3163 The special source files for parsing Objective-C are in @file{objc/}.
3164 They are @file{objc-act.c}, @file{objc-tree.def}, and @file{objc-act.h}.
3165 Certain C-specific files are used for this as well.
3169 @file{c-common.def},
3173 @file{c-semantics.c},
3176 along with header files
3182 are also used for all of the above languages.
3185 @cindex Tree optimization
3187 Tree optimization. This is the optimization of the tree
3188 representation, before converting into RTL code.
3190 @cindex inline on trees, automatic
3191 Currently, the main optimization performed here is tree-based
3193 This is implemented for C++ in @file{cp/optimize.c}. Note that
3194 tree based inlining turns off rtx based inlining (since it's more
3195 powerful, it would be a waste of time to do rtx based inlining in
3197 The C front end currently does not perform tree based inlining.
3199 @cindex constant folding
3200 @cindex arithmetic simplifications
3201 @cindex simplifications, arithmetic
3202 Constant folding and some arithmetic simplifications are also done
3203 during this pass, on the tree representation.
3204 The routines that perform these tasks are located in @file{fold-const.c}.
3206 @cindex RTL generation
3208 RTL generation. This is the conversion of syntax tree into RTL code.
3210 @cindex target-parameter-dependent code
3211 This is where the bulk of target-parameter-dependent code is found,
3212 since often it is necessary for strategies to apply only when certain
3213 standard kinds of instructions are available. The purpose of named
3214 instruction patterns is to provide this information to the RTL
3217 @cindex tail recursion optimization
3218 Optimization is done in this pass for @code{if}-conditions that are
3219 comparisons, boolean operations or conditional expressions. Tail
3220 recursion is detected at this time also. Decisions are made about how
3221 best to arrange loops and how to output @code{switch} statements.
3223 @c Avoiding overfull is tricky here.
3224 The source files for RTL generation include
3232 and @file{emit-rtl.c}.
3234 @file{insn-emit.c}, generated from the machine description by the
3235 program @code{genemit}, is used in this pass. The header file
3236 @file{expr.h} is used for communication within this pass.
3240 The header files @file{insn-flags.h} and @file{insn-codes.h},
3241 generated from the machine description by the programs @code{genflags}
3242 and @code{gencodes}, tell this pass which standard names are available
3243 for use and which patterns correspond to them.
3245 Aside from debugging information output, none of the following passes
3246 refers to the tree structure representation of the function (only
3247 part of which is saved).
3249 @cindex inline on rtx, automatic
3250 The decision of whether the function can and should be expanded inline
3251 in its subsequent callers is made at the end of rtl generation. The
3252 function must meet certain criteria, currently related to the size of
3253 the function and the types and number of parameters it has. Note that
3254 this function may contain loops, recursive calls to itself
3255 (tail-recursive functions can be inlined!), gotos, in short, all
3256 constructs supported by GCC@. The file @file{integrate.c} contains
3257 the code to save a function's rtl for later inlining and to inline that
3258 rtl when the function is called. The header file @file{integrate.h}
3259 is also used for this purpose.
3262 The option @option{-dr} causes a debugging dump of the RTL code after
3263 this pass. This dump file's name is made by appending @samp{.rtl} to
3264 the input file name.
3266 @c Should the exception handling pass be talked about here?
3268 @cindex sibling call optimization
3270 Sibiling call optimization. This pass performs tail recursion
3271 elimination, and tail and sibling call optimizations. The purpose of
3272 these optimizations is to reduce the overhead of function calls,
3275 The source file of this pass is @file{sibcall.c}
3278 The option @option{-di} causes a debugging dump of the RTL code after
3279 this pass is run. This dump file's name is made by appending
3280 @samp{.sibling} to the input file name.
3282 @cindex jump optimization
3283 @cindex unreachable code
3286 Jump optimization. This pass simplifies jumps to the following
3287 instruction, jumps across jumps, and jumps to jumps. It deletes
3288 unreferenced labels and unreachable code, except that unreachable code
3289 that contains a loop is not recognized as unreachable in this pass.
3290 (Such loops are deleted later in the basic block analysis.) It also
3291 converts some code originally written with jumps into sequences of
3292 instructions that directly set values from the results of comparisons,
3293 if the machine has such instructions.
3295 Jump optimization is performed two or three times. The first time is
3296 immediately following RTL generation. The second time is after CSE,
3297 but only if CSE says repeated jump optimization is needed. The
3298 last time is right before the final pass. That time, cross-jumping
3299 and deletion of no-op move instructions are done together with the
3300 optimizations described above.
3302 The source file of this pass is @file{jump.c}.
3305 The option @option{-dj} causes a debugging dump of the RTL code after
3306 this pass is run for the first time. This dump file's name is made by
3307 appending @samp{.jump} to the input file name.
3310 @cindex register use analysis
3312 Register scan. This pass finds the first and last use of each
3313 register, as a guide for common subexpression elimination. Its source
3314 is in @file{regclass.c}.
3316 @cindex jump threading
3318 @opindex fthread-jumps
3319 Jump threading. This pass detects a condition jump that branches to an
3320 identical or inverse test. Such jumps can be @samp{threaded} through
3321 the second conditional test. The source code for this pass is in
3322 @file{jump.c}. This optimization is only performed if
3323 @option{-fthread-jumps} is enabled.
3325 @cindex SSA optimizations
3326 @cindex Single Static Assignment optimizations
3329 Static Single Assignment (SSA) based optimization passes. The
3330 SSA conversion passes (to/from) are turned on by the @option{-fssa}
3331 option (it is also done automatically if you enable an SSA optimization pass).
3332 These passes utilize a form called Static Single Assignment. In SSA form,
3333 each variable (pseudo register) is only set once, giving you def-use
3334 and use-def chains for free, and enabling a lot more optimization
3335 passes to be run in linear time.
3336 Conversion to and from SSA form is handled by functions in
3340 The option @option{-de} causes a debugging dump of the RTL code after
3341 this pass. This dump file's name is made by appending @samp{.ssa} to
3342 the input file name.
3344 @cindex SSA Conditional Constant Propagation
3345 @cindex Conditional Constant Propagation, SSA based
3346 @cindex conditional constant propagation
3349 SSA Conditional Constant Propagation. Turned on by the @option{-fssa-ccp}
3350 SSA Aggressive Dead Code Elimination. Turned on by the @option{-fssa-dce}
3351 option. This pass performs conditional constant propagation to simplify
3352 instructions including conditional branches. This pass is more aggressive
3353 than the constant propgation done by the CSE and GCSE pases, but operates
3357 The option @option{-dW} causes a debugging dump of the RTL code after
3358 this pass. This dump file's name is made by appending @samp{.ssaccp} to
3359 the input file name.
3362 @cindex DCE, SSA based
3363 @cindex dead code elimination
3366 SSA Aggressive Dead Code Elimination. Turned on by the @option{-fssa-dce}
3367 option. This pass performs elimination of code considered unnecessary because
3368 it has no externally visible effects on the program. It operates in
3372 The option @option{-dX} causes a debugging dump of the RTL code after
3373 this pass. This dump file's name is made by appending @samp{.ssadce} to
3374 the input file name.
3377 @cindex common subexpression elimination
3378 @cindex constant propagation
3380 Common subexpression elimination. This pass also does constant
3381 propagation. Its source files are @file{cse.c}, and @file{cselib.c}.
3382 If constant propagation causes conditional jumps to become
3383 unconditional or to become no-ops, jump optimization is run again when
3387 The option @option{-ds} causes a debugging dump of the RTL code after
3388 this pass. This dump file's name is made by appending @samp{.cse} to
3389 the input file name.
3391 @cindex global common subexpression elimination
3392 @cindex constant propagation
3393 @cindex copy propagation
3395 Global common subexpression elimination. This pass performs two
3396 different types of GCSE depending on whether you are optimizing for
3397 size or not (LCM based GCSE tends to increase code size for a gain in
3398 speed, while Morel-Renvoise based GCSE does not).
3399 When optimizing for size, GCSE is done using Morel-Renvoise Partial
3400 Redundancy Elimination, with the exception that it does not try to move
3401 invariants out of loops---that is left to the loop optimization pass.
3402 If MR PRE GCSE is done, code hoisting (aka unification) is also done, as
3403 well as load motion.
3404 If you are optimizing for speed, LCM (lazy code motion) based GCSE is
3405 done. LCM is based on the work of Knoop, Ruthing, and Steffen. LCM
3406 based GCSE also does loop invariant code motion. We also perform load
3407 and store motion when optimizing for speed.
3408 Regardless of which type of GCSE is used, the GCSE pass also performs
3409 global constant and copy propagation.
3411 The source file for this pass is @file{gcse.c}, and the LCM routines
3412 are in @file{lcm.c}.
3415 The option @option{-dG} causes a debugging dump of the RTL code after
3416 this pass. This dump file's name is made by appending @samp{.gcse} to
3417 the input file name.
3419 @cindex loop optimization
3421 @cindex strength-reduction
3423 Loop optimization. This pass moves constant expressions out of loops,
3424 and optionally does strength-reduction and loop unrolling as well.
3425 Its source files are @file{loop.c} and @file{unroll.c}, plus the header
3426 @file{loop.h} used for communication between them. Loop unrolling uses
3427 some functions in @file{integrate.c} and the header @file{integrate.h}.
3428 Loop dependency analysis routines are contained in @file{dependence.c}.
3431 The option @option{-dL} causes a debugging dump of the RTL code after
3432 this pass. This dump file's name is made by appending @samp{.loop} to
3433 the input file name.
3436 @opindex frerun-cse-after-loop
3437 If @option{-frerun-cse-after-loop} was enabled, a second common
3438 subexpression elimination pass is performed after the loop optimization
3439 pass. Jump threading is also done again at this time if it was specified.
3442 The option @option{-dt} causes a debugging dump of the RTL code after
3443 this pass. This dump file's name is made by appending @samp{.cse2} to
3444 the input file name.
3446 @cindex data flow analysis
3447 @cindex analysis, data flow
3448 @cindex basic blocks
3450 Data flow analysis (@file{flow.c}). This pass divides the program
3451 into basic blocks (and in the process deletes unreachable loops); then
3452 it computes which pseudo-registers are live at each point in the
3453 program, and makes the first instruction that uses a value point at
3454 the instruction that computed the value.
3456 @cindex autoincrement/decrement analysis
3457 This pass also deletes computations whose results are never used, and
3458 combines memory references with add or subtract instructions to make
3459 autoincrement or autodecrement addressing.
3462 The option @option{-df} causes a debugging dump of the RTL code after
3463 this pass. This dump file's name is made by appending @samp{.flow} to
3464 the input file name. If stupid register allocation is in use, this
3465 dump file reflects the full results of such allocation.
3467 @cindex instruction combination
3469 Instruction combination (@file{combine.c}). This pass attempts to
3470 combine groups of two or three instructions that are related by data
3471 flow into single instructions. It combines the RTL expressions for
3472 the instructions by substitution, simplifies the result using algebra,
3473 and then attempts to match the result against the machine description.
3476 The option @option{-dc} causes a debugging dump of the RTL code after
3477 this pass. This dump file's name is made by appending @samp{.combine}
3478 to the input file name.
3480 @cindex if conversion
3482 If-conversion is a transformation that transforms control dependencies
3483 into data dependencies (IE it transforms conditional code into a
3484 single control stream).
3485 It is implemented in the file @file{ifcvt.c}.
3488 The option @option{-dE} causes a debugging dump of the RTL code after
3489 this pass. This dump file's name is made by appending @samp{.ce} to
3490 the input file name.
3492 @cindex register movement
3494 Register movement (@file{regmove.c}). This pass looks for cases where
3495 matching constraints would force an instruction to need a reload, and
3496 this reload would be a register to register move. It then attempts
3497 to change the registers used by the instruction to avoid the move
3501 The option @option{-dN} causes a debugging dump of the RTL code after
3502 this pass. This dump file's name is made by appending @samp{.regmove}
3503 to the input file name.
3505 @cindex instruction scheduling
3506 @cindex scheduling, instruction
3508 Instruction scheduling (@file{sched.c}). This pass looks for
3509 instructions whose output will not be available by the time that it is
3510 used in subsequent instructions. (Memory loads and floating point
3511 instructions often have this behavior on RISC machines). It re-orders
3512 instructions within a basic block to try to separate the definition and
3513 use of items that otherwise would cause pipeline stalls.
3515 Instruction scheduling is performed twice. The first time is immediately
3516 after instruction combination and the second is immediately after reload.
3519 The option @option{-dS} causes a debugging dump of the RTL code after this
3520 pass is run for the first time. The dump file's name is made by
3521 appending @samp{.sched} to the input file name.
3523 @cindex register class preference pass
3525 Register class preferencing. The RTL code is scanned to find out
3526 which register class is best for each pseudo register. The source
3527 file is @file{regclass.c}.
3529 @cindex register allocation
3530 @cindex local register allocation
3532 Local register allocation (@file{local-alloc.c}). This pass allocates
3533 hard registers to pseudo registers that are used only within one basic
3534 block. Because the basic block is linear, it can use fast and
3535 powerful techniques to do a very good job.
3538 The option @option{-dl} causes a debugging dump of the RTL code after
3539 this pass. This dump file's name is made by appending @samp{.lreg} to
3540 the input file name.
3542 @cindex global register allocation
3544 Global register allocation (@file{global.c}). This pass
3545 allocates hard registers for the remaining pseudo registers (those
3546 whose life spans are not contained in one basic block).
3550 Reloading. This pass renumbers pseudo registers with the hardware
3551 registers numbers they were allocated. Pseudo registers that did not
3552 get hard registers are replaced with stack slots. Then it finds
3553 instructions that are invalid because a value has failed to end up in
3554 a register, or has ended up in a register of the wrong kind. It fixes
3555 up these instructions by reloading the problematical values
3556 temporarily into registers. Additional instructions are generated to
3559 The reload pass also optionally eliminates the frame pointer and inserts
3560 instructions to save and restore call-clobbered registers around calls.
3562 Source files are @file{reload.c} and @file{reload1.c}, plus the header
3563 @file{reload.h} used for communication between them.
3566 The option @option{-dg} causes a debugging dump of the RTL code after
3567 this pass. This dump file's name is made by appending @samp{.greg} to
3568 the input file name.
3570 @cindex instruction scheduling
3571 @cindex scheduling, instruction
3573 Instruction scheduling is repeated here to try to avoid pipeline stalls
3574 due to memory loads generated for spilled pseudo registers.
3577 The option @option{-dR} causes a debugging dump of the RTL code after
3578 this pass. This dump file's name is made by appending @samp{.sched2}
3579 to the input file name.
3581 @cindex basic block reordering
3582 @cindex reordering, block
3584 Basic block reordering. This pass implements profile guided code
3585 positioning. If profile information is not available, various types of
3586 static analysis are performed to make the predictions normally coming
3587 from the profile feedback (IE execution frequency, branch probability,
3588 etc). It is implemented in the file @file{bb-reorder.c}, and the
3589 various prediction routines are in @file{predict.c}.
3592 The option @option{-dB} causes a debugging dump of the RTL code after
3593 this pass. This dump file's name is made by appending @samp{.bbro} to
3594 the input file name.
3596 @cindex cross-jumping
3597 @cindex no-op move instructions
3599 Jump optimization is repeated, this time including cross-jumping
3600 and deletion of no-op move instructions.
3603 The option @option{-dJ} causes a debugging dump of the RTL code after
3604 this pass. This dump file's name is made by appending @samp{.jump2}
3605 to the input file name.
3607 @cindex delayed branch scheduling
3608 @cindex scheduling, delayed branch
3610 Delayed branch scheduling. This optional pass attempts to find
3611 instructions that can go into the delay slots of other instructions,
3612 usually jumps and calls. The source file name is @file{reorg.c}.
3615 The option @option{-dd} causes a debugging dump of the RTL code after
3616 this pass. This dump file's name is made by appending @samp{.dbr}
3617 to the input file name.
3619 @cindex branch shortening
3621 Branch shortening. On many RISC machines, branch instructions have a
3622 limited range. Thus, longer sequences of instructions must be used for
3623 long branches. In this pass, the compiler figures out what how far each
3624 instruction will be from each other instruction, and therefore whether
3625 the usual instructions, or the longer sequences, must be used for each
3628 @cindex register-to-stack conversion
3630 Conversion from usage of some hard registers to usage of a register
3631 stack may be done at this point. Currently, this is supported only
3632 for the floating-point registers of the Intel 80387 coprocessor. The
3633 source file name is @file{reg-stack.c}.
3636 The options @option{-dk} causes a debugging dump of the RTL code after
3637 this pass. This dump file's name is made by appending @samp{.stack}
3638 to the input file name.
3641 @cindex peephole optimization
3643 Final. This pass outputs the assembler code for the function. It is
3644 also responsible for identifying spurious test and compare
3645 instructions. Machine-specific peephole optimizations are performed
3646 at the same time. The function entry and exit sequences are generated
3647 directly as assembler code in this pass; they never exist as RTL@.
3649 The source files are @file{final.c} plus @file{insn-output.c}; the
3650 latter is generated automatically from the machine description by the
3651 tool @file{genoutput}. The header file @file{conditions.h} is used
3652 for communication between these files.
3654 @cindex debugging information generation
3656 Debugging information output. This is run after final because it must
3657 output the stack slot offsets for pseudo registers that did not get
3658 hard registers. Source files are @file{dbxout.c} for DBX symbol table
3659 format, @file{sdbout.c} for SDB symbol table format, @file{dwarfout.c}
3660 for DWARF symbol table format, and the files @file{dwarf2out.c} and
3661 @file{dwarf2asm.c} for DWARF2 symbol table format.
3664 Some additional files are used by all or many passes:
3668 Every pass uses @file{machmode.def} and @file{machmode.h} which define
3672 Several passes use @file{real.h}, which defines the default
3673 representation of floating point constants and how to operate on them.
3676 All the passes that work with RTL use the header files @file{rtl.h}
3677 and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
3678 @code{gen*} also use these files to read and work with the machine
3682 All the tools that read the machine description use support routines
3683 found in @file{gensupport.c}, @file{errors.c}, and @file{read-rtl.c}.
3687 Several passes refer to the header file @file{insn-config.h} which
3688 contains a few parameters (C macro definitions) generated
3689 automatically from the machine description RTL by the tool
3692 @cindex instruction recognizer
3694 Several passes use the instruction recognizer, which consists of
3695 @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
3696 and @file{insn-extract.c} that are generated automatically from the
3697 machine description by the tools @file{genrecog} and
3701 Several passes use the header files @file{regs.h} which defines the
3702 information recorded about pseudo register usage, and @file{basic-block.h}
3703 which defines the information recorded about basic blocks.
3706 @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
3707 with a bit for each hard register, and some macros to manipulate it.
3708 This type is just @code{int} if the machine has few enough hard registers;
3709 otherwise it is an array of @code{int} and some of the macros expand
3713 Several passes use instruction attributes. A definition of the
3714 attributes defined for a particular machine is in file
3715 @file{insn-attr.h}, which is generated from the machine description by
3716 the program @file{genattr}. The file @file{insn-attrtab.c} contains
3717 subroutines to obtain the attribute values for insns. It is generated
3718 from the machine description by the program @file{genattrtab}.
3723 @include c-tree.texi
3731 @chapter The Configuration File
3732 @cindex configuration file
3733 @cindex @file{xm-@var{machine}.h}
3735 The configuration file @file{xm-@var{machine}.h} contains macro
3736 definitions that describe the machine and system on which the compiler
3737 is running, unlike the definitions in @file{@var{machine}.h}, which
3738 describe the machine for which the compiler is producing output. Most
3739 of the values in @file{xm-@var{machine}.h} are actually the same on all
3740 machines that GCC runs on, so large parts of all configuration files
3741 are identical. But there are some macros that vary:
3746 Define this macro if the host system is System V@.
3750 Define this macro if the host system is VMS@.
3752 @findex FATAL_EXIT_CODE
3753 @item FATAL_EXIT_CODE
3754 A C expression for the status code to be returned when the compiler
3755 exits after serious errors. The default is the system-provided macro
3756 @samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
3757 macro. Define this macro only if these defaults are incorrect.
3759 @findex SUCCESS_EXIT_CODE
3760 @item SUCCESS_EXIT_CODE
3761 A C expression for the status code to be returned when the compiler
3762 exits without serious errors. (Warnings are not serious errors.) The
3763 default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
3764 the system doesn't define that macro. Define this macro only if these
3765 defaults are incorrect.
3767 @findex HOST_WORDS_BIG_ENDIAN
3768 @item HOST_WORDS_BIG_ENDIAN
3769 Defined if the host machine stores words of multi-word values in
3770 big-endian order. (GCC does not depend on the host byte ordering
3773 @findex HOST_FLOAT_WORDS_BIG_ENDIAN
3774 @item HOST_FLOAT_WORDS_BIG_ENDIAN
3775 Define this macro to be 1 if the host machine stores @code{DFmode},
3776 @code{XFmode} or @code{TFmode} floating point numbers in memory with the
3777 word containing the sign bit at the lowest address; otherwise, define it
3780 This macro need not be defined if the ordering is the same as for
3781 multi-word integers.
3783 @findex HOST_FLOAT_FORMAT
3784 @item HOST_FLOAT_FORMAT
3785 A numeric code distinguishing the floating point format for the host
3786 machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
3787 alternatives and default.
3789 @findex HOST_BITS_PER_CHAR
3790 @item HOST_BITS_PER_CHAR
3791 A C expression for the number of bits in @code{char} on the host
3794 @findex HOST_BITS_PER_SHORT
3795 @item HOST_BITS_PER_SHORT
3796 A C expression for the number of bits in @code{short} on the host
3799 @findex HOST_BITS_PER_INT
3800 @item HOST_BITS_PER_INT
3801 A C expression for the number of bits in @code{int} on the host
3804 @findex HOST_BITS_PER_LONG
3805 @item HOST_BITS_PER_LONG
3806 A C expression for the number of bits in @code{long} on the host
3809 @findex HOST_BITS_PER_LONGLONG
3810 @item HOST_BITS_PER_LONGLONG
3811 A C expression for the number of bits in @code{long long} on the host
3814 @findex ONLY_INT_FIELDS
3815 @item ONLY_INT_FIELDS
3816 Define this macro to indicate that the host compiler only supports
3817 @code{int} bit-fields, rather than other integral types, including
3818 @code{enum}, as do most C compilers.
3820 @findex OBSTACK_CHUNK_SIZE
3821 @item OBSTACK_CHUNK_SIZE
3822 A C expression for the size of ordinary obstack chunks.
3823 If you don't define this, a usually-reasonable default is used.
3825 @findex OBSTACK_CHUNK_ALLOC
3826 @item OBSTACK_CHUNK_ALLOC
3827 The function used to allocate obstack chunks.
3828 If you don't define this, @code{xmalloc} is used.
3830 @findex OBSTACK_CHUNK_FREE
3831 @item OBSTACK_CHUNK_FREE
3832 The function used to free obstack chunks.
3833 If you don't define this, @code{free} is used.
3835 @findex USE_C_ALLOCA
3837 Define this macro to indicate that the compiler is running with the
3838 @code{alloca} implemented in C@. This version of @code{alloca} can be
3839 found in the file @file{alloca.c}; to use it, you must also alter the
3840 @file{Makefile} variable @code{ALLOCA}. (This is done automatically
3841 for the systems on which we know it is needed.)
3843 If you do define this macro, you should probably do it as follows:
3847 #define USE_C_ALLOCA
3849 #define alloca __builtin_alloca
3854 so that when the compiler is compiled with GCC it uses the more
3855 efficient built-in @code{alloca} function.
3857 @item FUNCTION_CONVERSION_BUG
3858 @findex FUNCTION_CONVERSION_BUG
3859 Define this macro to indicate that the host compiler does not properly
3860 handle converting a function value to a pointer-to-function when it is
3861 used in an expression.
3863 @findex MULTIBYTE_CHARS
3864 @item MULTIBYTE_CHARS
3865 Define this macro to enable support for multibyte characters in the
3866 input to GCC@. This requires that the host system support the ISO C
3867 library functions for converting multibyte characters to wide
3872 Define this if your system is POSIX.1 compliant.
3874 @findex PATH_SEPARATOR
3875 @item PATH_SEPARATOR
3876 Define this macro to be a C character constant representing the
3877 character used to separate components in paths. The default value is
3880 @findex DIR_SEPARATOR
3882 If your system uses some character other than slash to separate
3883 directory names within a file specification, define this macro to be a C
3884 character constant specifying that character. When GCC displays file
3885 names, the character you specify will be used. GCC will test for
3886 both slash and the character you specify when parsing filenames.
3888 @findex DIR_SEPARATOR_2
3889 @item DIR_SEPARATOR_2
3890 If your system uses an alternative character other than
3891 @samp{DIR_SEPARATOR} to separate directory names within a file
3892 specification, define this macro to be a C character constant specifying
3893 that character. If you define this macro, GCC will test for slash,
3894 @samp{DIR_SEPARATOR}, and @samp{DIR_SEPARATOR_2} when parsing filenames.
3896 @findex TARGET_OBJECT_SUFFIX
3897 @item TARGET_OBJECT_SUFFIX
3898 Define this macro to be a C string representing the suffix for object
3899 files on your target machine. If you do not define this macro, GCC will
3900 use @samp{.o} as the suffix for object files.
3902 @findex TARGET_EXECUTABLE_SUFFIX
3903 @item TARGET_EXECUTABLE_SUFFIX
3904 Define this macro to be a C string representing the suffix to be
3905 automatically added to executable files on your target machine. If you
3906 do not define this macro, GCC will use the null string as the suffix for
3909 @findex HOST_OBJECT_SUFFIX
3910 @item HOST_OBJECT_SUFFIX
3911 Define this macro to be a C string representing the suffix for object
3912 files on your host machine (@samp{xm-*.h}). If you do not define this
3913 macro, GCC will use @samp{.o} as the suffix for object files.
3915 @findex HOST_EXECUTABLE_SUFFIX
3916 @item HOST_EXECUTABLE_SUFFIX
3917 Define this macro to be a C string representing the suffix for
3918 executable files on your host machine (@samp{xm-*.h}). If you do not
3919 define this macro, GCC will use the null string as the suffix for
3922 @findex HOST_BIT_BUCKET
3923 @item HOST_BIT_BUCKET
3924 The name of a file or file-like object on the host system which acts as
3925 a ``bit bucket''. If you do not define this macro, GCC will use
3926 @samp{/dev/null} as the bit bucket. If the target does not support a
3927 bit bucket, this should be defined to the null string, or some other
3928 illegal filename. If the bit bucket is not writable, GCC will use a
3929 temporary file instead.
3931 @findex COLLECT_EXPORT_LIST
3932 @item COLLECT_EXPORT_LIST
3933 If defined, @code{collect2} will scan the individual object files
3934 specified on its command line and create an export list for the linker.
3935 Define this macro for systems like AIX, where the linker discards
3936 object files that are not referenced from @code{main} and uses export
3939 @findex COLLECT2_HOST_INITIALIZATION
3940 @item COLLECT2_HOST_INITIALIZATION
3941 If defined, a C statement (sans semicolon) that performs host-dependent
3942 initialization when @code{collect2} is being initialized.
3944 @findex GCC_DRIVER_HOST_INITIALIZATION
3945 @item GCC_DRIVER_HOST_INITIALIZATION
3946 If defined, a C statement (sans semicolon) that performs host-dependent
3947 initialization when a compilation driver is being initialized.
3949 @findex UPDATE_PATH_HOST_CANONICALIZE
3950 @item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
3951 If defined, a C statement (sans semicolon) that performs host-dependent
3952 canonicalization when a path used in a compilation driver or
3953 preprocessor is canonicalized. @var{path} is a malloc-ed path to be
3954 canonicalized. If the C statement does canonicalize @var{path} into a
3955 different buffer, the old path should be freed and the new buffer should
3956 have been allocated with malloc.
3961 In addition, configuration files for system V define @code{bcopy},
3962 @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
3963 as a macro when compiled with GCC, in order to take advantage of the
3964 benefit of GCC's built-in @code{alloca}.
3967 @chapter Makefile Fragments
3968 @cindex makefile fragment
3970 When you configure GCC using the @file{configure} script
3971 (@pxref{Installation}), it will construct the file @file{Makefile} from
3972 the template file @file{Makefile.in}. When it does this, it will
3973 incorporate makefile fragment files from the @file{config} directory,
3974 named @file{t-@var{target}} and @file{x-@var{host}}. If these files do
3975 not exist, it means nothing needs to be added for a given target or
3979 * Target Fragment:: Writing the @file{t-@var{target}} file.
3980 * Host Fragment:: Writing the @file{x-@var{host}} file.
3983 @node Target Fragment
3984 @section The Target Makefile Fragment
3985 @cindex target makefile fragment
3986 @cindex @file{t-@var{target}}
3988 The target makefile fragment, @file{t-@var{target}}, defines special
3989 target dependent variables and targets used in the @file{Makefile}:
3992 @findex LIBGCC2_CFLAGS
3993 @item LIBGCC2_CFLAGS
3994 Compiler flags to use when compiling @file{libgcc2.c}.
3996 @findex LIB2FUNCS_EXTRA
3997 @item LIB2FUNCS_EXTRA
3998 A list of source file names to be compiled or assembled and inserted
3999 into @file{libgcc.a}.
4001 @findex Floating Point Emulation
4002 @item Floating Point Emulation
4003 To have GCC include software floating point libraries in @file{libgcc.a}
4004 define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
4006 # We want fine grained libraries, so use the new code
4007 # to build the floating point emulation libraries.
4012 fp-bit.c: $(srcdir)/config/fp-bit.c
4013 echo '#define FLOAT' > fp-bit.c
4014 cat $(srcdir)/config/fp-bit.c >> fp-bit.c
4016 dp-bit.c: $(srcdir)/config/fp-bit.c
4017 cat $(srcdir)/config/fp-bit.c > dp-bit.c
4020 You may need to provide additional #defines at the beginning of @file{fp-bit.c}
4021 and @file{dp-bit.c} to control target endianness and other options.
4024 @findex CRTSTUFF_T_CFLAGS
4025 @item CRTSTUFF_T_CFLAGS
4026 Special flags used when compiling @file{crtstuff.c}.
4027 @xref{Initialization}.
4029 @findex CRTSTUFF_T_CFLAGS_S
4030 @item CRTSTUFF_T_CFLAGS_S
4031 Special flags used when compiling @file{crtstuff.c} for shared
4032 linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
4033 in @code{EXTRA-PARTS}.
4034 @xref{Initialization}.
4036 @findex MULTILIB_OPTIONS
4037 @item MULTILIB_OPTIONS
4038 For some targets, invoking GCC in different ways produces objects
4039 that can not be linked together. For example, for some targets GCC
4040 produces both big and little endian code. For these targets, you must
4041 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
4042 each set of incompatible options. When GCC invokes the linker, it
4043 arranges to link in the right version of @file{libgcc.a}, based on
4044 the command line options used.
4046 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
4047 special versions of @file{libgcc.a} must be built. Write options that
4048 are mutually incompatible side by side, separated by a slash. Write
4049 options that may be used together separated by a space. The build
4050 procedure will build all combinations of compatible options.
4052 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
4053 msoft-float}, @file{Makefile} will build special versions of
4054 @file{libgcc.a} using the following sets of options: @option{-m68000},
4055 @option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
4056 @samp{-m68020 -msoft-float}.
4058 @findex MULTILIB_DIRNAMES
4059 @item MULTILIB_DIRNAMES
4060 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
4061 directory names that should be used to hold the various libraries.
4062 Write one element in @code{MULTILIB_DIRNAMES} for each element in
4063 @code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
4064 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
4067 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
4068 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
4069 @samp{m68000 m68020 msoft-float}. You may specify a different value if
4070 you desire a different set of directory names.
4072 @findex MULTILIB_MATCHES
4073 @item MULTILIB_MATCHES
4074 Sometimes the same option may be written in two different ways. If an
4075 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
4076 any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
4077 items of the form @samp{option=option} to describe all relevant
4078 synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
4080 @findex MULTILIB_EXCEPTIONS
4081 @item MULTILIB_EXCEPTIONS
4082 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
4083 specified, there are combinations that should not be built. In that
4084 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
4085 in shell case syntax that should not be built.
4087 For example, in the PowerPC embedded ABI support, it is not desirable
4088 to build libraries compiled with the @option{-mcall-aix} option
4089 and either of the @option{-fleading-underscore} or @option{-mlittle} options
4090 at the same time. Therefore @code{MULTILIB_EXCEPTIONS} is set to
4092 *mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*
4095 @findex MULTILIB_EXTRA_OPTS
4096 @item MULTILIB_EXTRA_OPTS
4097 Sometimes it is desirable that when building multiple versions of
4098 @file{libgcc.a} certain options should always be passed on to the
4099 compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
4100 of options to be used for all builds.
4104 @section The Host Makefile Fragment
4105 @cindex host makefile fragment
4106 @cindex @file{x-@var{host}}
4108 The host makefile fragment, @file{x-@var{host}}, defines special host
4109 dependent variables and targets used in the @file{Makefile}:
4114 The compiler to use when building the first stage.
4118 The install program to use.
4122 @include funding.texi
4125 @unnumbered Linux and the GNU Project
4127 Many computer users run a modified version of the GNU system every
4128 day, without realizing it. Through a peculiar turn of events, the
4129 version of GNU which is widely used today is more often known as
4130 ``Linux'', and many users are not aware of the extent of its
4131 connection with the GNU Project.
4133 There really is a Linux; it is a kernel, and these people are using
4134 it. But you can't use a kernel by itself; a kernel is useful only as
4135 part of a whole system. The system in which Linux is typically used
4136 is a modified variant of the GNU system---in other words, a Linux-based
4139 Many users are not fully aware of the distinction between the kernel,
4140 which is Linux, and the whole system, which they also call ``Linux''.
4141 The ambiguous use of the name doesn't promote understanding.
4143 Programmers generally know that Linux is a kernel. But since they
4144 have generally heard the whole system called ``Linux'' as well, they
4145 often envisage a history which fits that name. For example, many
4146 believe that once Linus Torvalds finished writing the kernel, his
4147 friends looked around for other free software, and for no particular
4148 reason most everything necessary to make a Unix-like system was
4151 What they found was no accident---it was the GNU system. The available
4152 free software added up to a complete system because the GNU Project
4153 had been working since 1984 to make one. The GNU Manifesto
4154 had set forth the goal of developing a free Unix-like system, called
4155 GNU@. By the time Linux was written, the system was almost finished.
4157 Most free software projects have the goal of developing a particular
4158 program for a particular job. For example, Linus Torvalds set out to
4159 write a Unix-like kernel (Linux); Donald Knuth set out to write a text
4160 formatter (TeX); Bob Scheifler set out to develop a window system (X
4161 Windows). It's natural to measure the contribution of this kind of
4162 project by specific programs that came from the project.
4164 If we tried to measure the GNU Project's contribution in this way,
4165 what would we conclude? One CD-ROM vendor found that in their ``Linux
4166 distribution'', GNU software was the largest single contingent, around
4167 28% of the total source code, and this included some of the essential
4168 major components without which there could be no system. Linux itself
4169 was about 3%. So if you were going to pick a name for the system
4170 based on who wrote the programs in the system, the most appropriate
4171 single choice would be ``GNU''@.
4173 But we don't think that is the right way to consider the question.
4174 The GNU Project was not, is not, a project to develop specific
4175 software packages. It was not a project to develop a C compiler,
4176 although we did. It was not a project to develop a text editor,
4177 although we developed one. The GNU Project's aim was to develop
4178 @emph{a complete free Unix-like system}.
4180 Many people have made major contributions to the free software in the
4181 system, and they all deserve credit. But the reason it is @emph{a
4182 system}---and not just a collection of useful programs---is because the
4183 GNU Project set out to make it one. We wrote the programs that were
4184 needed to make a @emph{complete} free system. We wrote essential but
4185 unexciting major components, such as the assembler and linker, because
4186 you can't have a system without them. A complete system needs more
4187 than just programming tools, so we wrote other components as well,
4188 such as the Bourne Again SHell, the PostScript interpreter
4189 Ghostscript, and the GNU C library.
4191 By the early 90s we had put together the whole system aside from the
4192 kernel (and we were also working on a kernel, the GNU Hurd, which runs
4193 on top of Mach). Developing this kernel has been a lot harder than we
4194 expected, and we are still working on finishing it.
4196 Fortunately, you don't have to wait for it, because Linux is working
4197 now. When Linus Torvalds wrote Linux, he filled the last major gap.
4198 People could then put Linux together with the GNU system to make a
4199 complete free system: a Linux-based GNU system (or GNU/Linux system,
4202 Putting them together sounds simple, but it was not a trivial job.
4203 The GNU C library (called glibc for short) needed substantial changes.
4204 Integrating a complete system as a distribution that would work ``out
4205 of the box'' was a big job, too. It required addressing the issue of
4206 how to install and boot the system---a problem we had not tackled,
4207 because we hadn't yet reached that point. The people who developed
4208 the various system distributions made a substantial contribution.
4210 The GNU Project supports GNU/Linux systems as well as @emph{the}
4211 GNU system---even with funds. We funded the rewriting of the
4212 Linux-related extensions to the GNU C library, so that now they are
4213 well integrated, and the newest GNU/Linux systems use the current
4214 library release with no changes. We also funded an early stage of the
4215 development of Debian GNU/Linux.
4217 We use Linux-based GNU systems today for most of our work, and we hope
4218 you use them too. But please don't confuse the public by using the
4219 name ``Linux'' ambiguously. Linux is the kernel, one of the essential
4220 major components of the system. The system as a whole is more or less
4225 @c ---------------------------------------------------------------------
4227 @c ---------------------------------------------------------------------
4232 @unnumbered Contributors to GCC
4233 @cindex contributors
4234 @include contrib.texi
4236 @c ---------------------------------------------------------------------
4238 @c ---------------------------------------------------------------------
4241 @unnumbered Option Index
4243 GCC's command line options are indexed here without any initial @samp{-}
4244 or @samp{--}. Where an option has both positive and negative forms
4245 (such as @option{-f@var{option}} and @option{-fno-@var{option}}),
4246 relevant entries in the manual are indexed under the most appropriate
4247 form; it may sometimes be useful to look up both forms.
4256 @c ---------------------------------------------------------------------
4258 @c ---------------------------------------------------------------------