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 - "back end" as a noun, "back-end" as an adjective.
46 @c - "bit-field" not "bitfield" or "bit field" (following the C and C++
48 @c - "built-in" as an adjective ("built-in function"), or sometimes
49 @c "built in", not "builtin" (which isn't a word).
50 @c - "front end" as a noun, "front-end" as an adjective.
51 @c - "GCC" for the GNU Compiler Collection, both generally
52 @c and as the GNU C Compiler in the context of compiling C;
53 @c "G++" for the C++ compiler; "gcc" and "g++" (lowercase),
54 @c marked up with @command, for the commands for compilation when the
55 @c emphasis is on those; "GNU C" and "GNU C++" for language dialects;
56 @c and try to avoid the older term "GNU CC".
58 @macro gcctabopt{body}
61 @macro gccoptlist{body}
66 @c Makeinfo handles the above macro OK, TeX needs manual line breaks;
67 @c they get lost at some point in handling the macro. But if @macro is
68 @c used here rather than @alias, it produces double line breaks.
79 @settitle Using and Porting the GNU Compiler Collection (GCC)
82 @c seems reasonable to assume at least one of INTERNALS or USING is set...
84 @settitle Using the GNU Compiler Collection
87 @settitle Porting the GNU Compiler Collection
90 @c Create a separate index for command line options.
92 @c Merge the standard indexes into a single one.
101 @c Use with @@smallbook.
103 @c Cause even numbered pages to be printed on the left hand side of
104 @c the page and odd numbered pages to be printed on the right hand
105 @c side of the page. Using this, you can print on both sides of a
106 @c sheet of paper and have the text on the same part of the sheet.
108 @c The text on right hand pages is pushed towards the right hand
109 @c margin and the text on left hand pages is pushed toward the left
111 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
114 @c \global\bindingoffset=0.75in
115 @c \global\normaloffset =0.75in
118 @c Change the font used for @def... commands, since the default
119 @c proportional one used is bad for names starting __.
121 \global\setfont\defbf\ttbshape{10}{\magstep1}
125 @dircategory Programming
127 * gcc: (gcc). The GNU Compiler Collection.
131 This file documents the use and the internals of the GNU compiler.
135 This file documents the internals of the GNU compiler.
138 This file documents the use of the GNU compiler.
141 Published by the Free Software Foundation@*
142 59 Temple Place - Suite 330@*
143 Boston, MA 02111-1307 USA
145 @c When you update the list of years below, search for copyright{} and
146 @c update the other copy too.
147 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
148 1999, 2000, 2001 Free Software Foundation, Inc.
150 Permission is granted to copy, distribute and/or modify this document
151 under the terms of the GNU Free Documentation License, Version 1.1 or
152 any later version published by the Free Software Foundation; with the
153 Invariant Sections being ``GNU General Public License'' and ``Funding
154 Free Software'', the Front-Cover texts being (a) (see below), and with
155 the Back-Cover Texts being (b) (see below). A copy of the license is
156 included in the section entitled ``GNU Free Documentation License''.
158 (a) The FSF's Front-Cover Text is:
162 (b) The FSF's Back-Cover Text is:
164 You have freedom to copy and modify this GNU Manual, like GNU
165 software. Copies published by the Free Software Foundation raise
166 funds for GNU development.
169 @setchapternewpage odd
174 @center @titlefont{Using and Porting the GNU Compiler Collection}
179 @title Using the GNU Compiler Collection
182 @title Porting the GNU Compiler Collection
185 @center Richard M. Stallman
187 @center Last updated 22 June 2001
189 @c The version number appears five times more in this file.
193 @vskip 0pt plus 1filll
194 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
195 1999, 2000, 2001 Free Software Foundation, Inc.
197 For GCC Version 3.1@*
199 Published by the Free Software Foundation @*
200 59 Temple Place---Suite 330@*
201 Boston, MA 02111-1307, USA@*
202 Last printed April, 1998.@*
203 Printed copies are available for $50 each.@*
206 Permission is granted to copy, distribute and/or modify this document
207 under the terms of the GNU Free Documentation License, Version 1.1 or
208 any later version published by the Free Software Foundation; with the
209 Invariant Sections being ``GNU General Public License'', the Front-Cover
210 texts being (a) (see below), and with the Back-Cover Texts being (b)
211 (see below). A copy of the license is included in the section entitled
212 ``GNU Free Documentation License''.
214 (a) The FSF's Front-Cover Text is:
218 (b) The FSF's Back-Cover Text is:
220 You have freedom to copy and modify this GNU Manual, like GNU
221 software. Copies published by the Free Software Foundation raise
222 funds for GNU development.
228 @node Top, G++ and GCC,, (DIR)
234 This manual documents how to run, install and port the GNU
235 compiler, as well as its new features and incompatibilities, and how to
236 report bugs. It corresponds to GCC version 3.1.
241 This manual documents how to run and install the GNU compiler,
242 as well as its new features and incompatibilities, and how to report
243 bugs. It corresponds to GCC version 3.1.
246 This manual documents how to port the GNU compiler,
247 as well as its new features and incompatibilities, and how to report
248 bugs. It corresponds to GCC version 3.1.
253 * G++ and GCC:: You can compile C or C++ programs.
254 * Standards:: Language standards supported by GCC.
255 * Invoking GCC:: Command options supported by @samp{gcc}.
256 * Installation:: How to configure, compile and install GCC.
257 * C Extensions:: GNU extensions to the C language family.
258 * C++ Extensions:: GNU extensions to the C++ language.
259 * Objective-C:: GNU Objective-C runtime features.
260 * Gcov:: gcov: a GCC test coverage program.
261 * Trouble:: If you have trouble installing GCC.
262 * Bugs:: How, why and where to report bugs.
263 * Service:: How to find suppliers of support for GCC.
264 * Contributing:: How to contribute to testing and developing GCC.
265 * VMS:: Using GCC on VMS.
266 * Makefile:: List of Makefile targets.
269 * Portability:: Goals of GCC's portability features.
270 * Interface:: Function-call interface of GCC output.
271 * Passes:: Order of passes, what they do, and what each file is for.
272 * Trees:: The source representation used by the C and C++ front ends.
273 * RTL:: The intermediate representation that most passes work on.
274 * Machine Desc:: How to write machine description instruction patterns.
275 * Target Macros:: How to write the machine description C macros and functions.
276 * Config:: Writing the @file{xm-@var{machine}.h} file.
277 * Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
280 * Funding:: How to help assure funding for free software.
281 * GNU/Linux:: Linux and the GNU Project
283 * Copying:: GNU General Public License says
284 how you can copy and share GCC.
285 * GNU Free Documentation License:: How you can copy and share this manual.
286 * Contributors:: People who have contributed to GCC.
288 * Option Index:: Index to command line options.
289 * Index:: Index of concepts and symbol names.
294 @chapter Compile C, C++, Objective-C, Fortran, Java or CHILL
300 Several versions of the compiler (C, C++, Objective-C, Fortran, Java
301 and CHILL) are integrated; this is why we use the name
302 ``GNU Compiler Collection''. GCC can compile programs written in any of these
303 languages. The Fortran, CHILL, and Java compilers are described in
307 ``GCC'' is a common shorthand term for the GNU Compiler Collection. This is both
308 the most general name for the compiler, and the name used when the
309 emphasis is on compiling C programs (as the abbreviation formerly
310 stood for ``GNU C Compiler'').
314 When referring to C++ compilation, it is usual to call the compiler
315 ``G++''. Since there is only one compiler, it is also accurate to call
316 it ``GCC'' no matter what the language context; however, the term
317 ``G++'' is more useful when the emphasis is on compiling C++ programs.
319 We use the name ``GCC'' to refer to the compilation system as a
320 whole, and more specifically to the language-independent part of the
321 compiler. For example, we refer to the optimization options as
322 affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
324 Front ends for other languages, such as Ada 95 and Pascal exist but
325 have not yet been integrated into GCC@. These front ends, like that for C++,
326 are built in subdirectories of GCC and link to it. The result is an
327 integrated compiler that can compile programs written in C, C++,
328 Objective-C, or any of the languages for which you have installed front
331 In this manual, we only discuss the options for the C, Objective-C, and
332 C++ compilers and those of the GCC core. Consult the documentation
333 of the other front ends for the options to use when compiling programs
334 written in other languages.
336 @cindex compiler compared to C++ preprocessor
337 @cindex intermediate C version, nonexistent
338 @cindex C intermediate output, nonexistent
339 G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object
340 code directly from your C++ program source. There is no intermediate C
341 version of the program. (By contrast, for example, some other
342 implementations use a program that generates a C program from your C++
343 source.) Avoiding an intermediate C representation of the program means
344 that you get better object code, and better debugging information. The
345 GNU debugger, GDB, works with this information in the object code to
346 give you comprehensive C++ source-level editing capabilities
347 (@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
349 @c FIXME! Someone who knows something about Objective-C ought to put in
350 @c a paragraph or two about it here, and move the index entry down when
351 @c there is more to point to than the general mention in the 1st par.
354 @chapter Language Standards Supported by GCC
357 @cindex ANSI C standard
361 @cindex ANSI X3.159-1989
363 @cindex ISO C standard
378 @cindex Technical Corrigenda
380 @cindex Technical Corrigendum 1
382 @cindex Technical Corrigendum 2
384 @cindex freestanding implementation
385 @cindex freestanding environment
386 @cindex hosted implementation
387 @cindex hosted environment
388 @findex __STDC_HOSTED__
390 For each language compiled by GCC for which there is a standard, GCC
391 attempts to follow one or more versions of that standard, possibly
392 with some exceptions, and possibly with some extensions.
394 GCC supports three versions of the C standard, although support for
395 the most recent version is not yet complete.
400 @opindex pedantic-errors
401 The original ANSI C standard (X3.159-1989) was ratified in 1989 and
402 published in 1990. This standard was ratified as an ISO standard
403 (ISO/IEC 9899:1990) later in 1990. There were no technical
404 differences between these publications, although the sections of the
405 ANSI standard were renumbered and became clauses in the ISO standard.
406 This standard, in both its forms, is commonly known as @dfn{C89}, or
407 occasionally as @dfn{C90}, from the dates of ratification. The ANSI
408 standard, but not the ISO standard, also came with a Rationale
409 document. To select this standard in GCC, use one of the options
410 @option{-ansi}, @option{-std=c89} or @option{-std=iso9899:1990}; to obtain
411 all the diagnostics required by the standard, you should also specify
412 @option{-pedantic} (or @option{-pedantic-errors} if you want them to be
413 errors rather than warnings). @xref{C Dialect Options,,Options
414 Controlling C Dialect}.
416 Errors in the 1990 ISO C standard were corrected in two Technical
417 Corrigenda published in 1994 and 1996. GCC does not support the
420 An amendment to the 1990 standard was published in 1995. This
421 amendment added digraphs and @code{__STDC_VERSION__} to the language,
422 but otherwise concerned the library. This amendment is commonly known
423 as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
424 @dfn{C95}. To select this standard in GCC, use the option
425 @option{-std=iso9899:199409} (with, as for other standard versions,
426 @option{-pedantic} to receive all required diagnostics).
428 A new edition of the ISO C standard was published in 1999 as ISO/IEC
429 9899:1999, and is commonly known as @dfn{C99}. GCC has incomplete
430 support for this standard version; see
431 @uref{http://gcc.gnu.org/c99status.html} for details. To select this
432 standard, use @option{-std=c99} or @option{-std=iso9899:1999}. (While in
433 development, drafts of this standard version were referred to as
437 GCC also has some limited support for traditional (pre-ISO) C with the
438 @option{-traditional} option. This support may be of use for compiling
439 some very old programs that have not been updated to ISO C, but should
440 not be used for new programs. It will not work with some modern C
441 libraries such as the GNU C library.
443 By default, GCC provides some extensions to the C language that on
444 rare occasions conflict with the C standard. @xref{C
445 Extensions,,Extensions to the C Language Family}. Use of the
446 @option{-std} options listed above will disable these extensions where
447 they conflict with the C standard version selected. You may also
448 select an extended version of the C language explicitly with
449 @option{-std=gnu89} (for C89 with GNU extensions) or @option{-std=gnu99}
450 (for C99 with GNU extensions). The default, if no C language dialect
451 options are given, is @option{-std=gnu89}; this will change to
452 @option{-std=gnu99} in some future release when the C99 support is
453 complete. Some features that are part of the C99 standard are
454 accepted as extensions in C89 mode.
456 The ISO C standard defines (in clause 4) two classes of conforming
457 implementation. A @dfn{conforming hosted implementation} supports the
458 whole standard including all the library facilities; a @dfn{conforming
459 freestanding implementation} is only required to provide certain
460 library facilities: those in @code{<float.h>}, @code{<limits.h>},
461 @code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
462 @code{<iso646.h>}; and in C99, also those in @code{<stdbool.h>} and
463 @code{<stdint.h>}. In addition, complex types, added in C99, are not
464 required for freestanding implementations. The standard also defines
465 two environments for programs, a @dfn{freestanding environment},
466 required of all implementations and which may not have library
467 facilities beyond those required of freestanding implementations,
468 where the handling of program startup and termination are
469 implementation-defined, and a @dfn{hosted environment}, which is not
470 required, in which all the library facilities are provided and startup
471 is through a function @code{int main (void)} or @code{int main (int,
472 char *[])}. An OS kernel would be a freestanding environment; a
473 program using the facilities of an operating system would normally be
474 in a hosted implementation.
476 @opindex ffreestanding
477 GCC aims towards being usable as a conforming freestanding
478 implementation, or as the compiler for a conforming hosted
479 implementation. By default, it will act as the compiler for a hosted
480 implementation, defining @code{__STDC_HOSTED__} as @code{1} and
481 presuming that when the names of ISO C functions are used, they have
482 the semantics defined in the standard. To make it act as a conforming
483 freestanding implementation for a freestanding environment, use the
484 option @option{-ffreestanding}; it will then define
485 @code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
486 meanings of function names from the standard library. To build an OS
487 kernel, you may well still need to make your own arrangements for
488 linking and startup. @xref{C Dialect Options,,Options Controlling C
491 GCC does not provide the library facilities required only of hosted
492 implementations, nor yet all the facilities required by C99 of
493 freestanding implementations; to use the facilities of a hosted
494 environment, you will need to find them elsewhere (for example, in the
495 GNU C library). @xref{Standard Libraries,,Standard Libraries}.
497 For references to Technical Corrigenda, Rationale documents and
498 information concerning the history of C that is available online, see
499 @uref{http://gcc.gnu.org/readings.html}
501 @c FIXME: details of C++ standard.
503 There is no formal written standard for Objective-C@. The most
504 authoritative manual is ``Object-Oriented Programming and the
505 Objective-C Language'', available at a number of web sites;
506 @uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/} has a
507 recent version, while @uref{http://www.toodarkpark.org/computers/objc/}
508 is an older example. @uref{http://www.gnustep.org} includes useful
511 @xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
512 Fortran}, for details of the Fortran language supported by GCC@.
514 @xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj},
515 for details of compatibility between @code{gcj} and the Java Platform.
517 @xref{References,,Language Definition References, chill, GNU Chill},
518 for details of the CHILL standard.
522 @include install-old.texi
531 @chapter Known Causes of Trouble with GCC
533 @cindex installation trouble
534 @cindex known causes of trouble
536 This section describes known problems that affect users of GCC@. Most
537 of these are not GCC bugs per se---if they were, we would fix them.
538 But the result for a user may be like the result of a bug.
540 Some of these problems are due to bugs in other software, some are
541 missing features that are too much work to add, and some are places
542 where people's opinions differ as to what is best.
545 * Actual Bugs:: Bugs we will fix later.
546 * Cross-Compiler Problems:: Common problems of cross compiling with GCC.
547 * Interoperation:: Problems using GCC with other compilers,
548 and with certain linkers, assemblers and debuggers.
549 * External Bugs:: Problems compiling certain programs.
550 * Incompatibilities:: GCC is incompatible with traditional C.
551 * Fixed Headers:: GCC uses corrected versions of system header files.
552 This is necessary, but doesn't always work smoothly.
553 * Standard Libraries:: GCC uses the system C library, which might not be
554 compliant with the ISO C standard.
555 * Disappointments:: Regrettable things we can't change, but not quite bugs.
556 * C++ Misunderstandings:: Common misunderstandings with GNU C++.
557 * Protoize Caveats:: Things to watch out for when using @code{protoize}.
558 * Non-bugs:: Things we think are right, but some others disagree.
559 * Warnings and Errors:: Which problems in your code get warnings,
560 and which get errors.
564 @section Actual Bugs We Haven't Fixed Yet
568 The @code{fixincludes} script interacts badly with automounters; if the
569 directory of system header files is automounted, it tends to be
570 unmounted while @code{fixincludes} is running. This would seem to be a
571 bug in the automounter. We don't know any good way to work around it.
574 The @code{fixproto} script will sometimes add prototypes for the
575 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
576 @code{jmp_buf} type before that type is defined. To work around this,
577 edit the offending file and place the typedef in front of the
581 @opindex pedantic-errors
582 When @option{-pedantic-errors} is specified, GCC will incorrectly give
583 an error message when a function name is specified in an expression
584 involving the comma operator.
587 @node Cross-Compiler Problems
588 @section Cross-Compiler Problems
590 You may run into problems with cross compilation on certain machines,
595 Cross compilation can run into trouble for certain machines because
596 some target machines' assemblers require floating point numbers to be
597 written as @emph{integer} constants in certain contexts.
599 The compiler writes these integer constants by examining the floating
600 point value as an integer and printing that integer, because this is
601 simple to write and independent of the details of the floating point
602 representation. But this does not work if the compiler is running on
603 a different machine with an incompatible floating point format, or
604 even a different byte-ordering.
606 In addition, correct constant folding of floating point values
607 requires representing them in the target machine's format.
608 (The C standard does not quite require this, but in practice
609 it is the only way to win.)
611 It is now possible to overcome these problems by defining macros such
612 as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
613 work for each target machine.
615 @xref{Cross-compilation}.
618 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
619 gcc.info, Using and Porting GCC}.
623 At present, the program @file{mips-tfile} which adds debug
624 support to object files on MIPS systems does not work in a cross
629 @section Interoperation
631 This section lists various difficulties encountered in using GCC
632 together with other compilers or with the assemblers, linkers,
633 libraries and debuggers on certain systems.
637 Objective-C does not work on the RS/6000.
640 G++ does not do name mangling in the same way as other C++
641 compilers. This means that object files compiled with one compiler
642 cannot be used with another.
644 This effect is intentional, to protect you from more subtle problems.
645 Compilers differ as to many internal details of C++ implementation,
646 including: how class instances are laid out, how multiple inheritance is
647 implemented, and how virtual function calls are handled. If the name
648 encoding were made the same, your programs would link against libraries
649 provided from other compilers---but the programs would then crash when
650 run. Incompatible libraries are then detected at link time, rather than
654 Older GDB versions sometimes fail to read the output of GCC version
655 2. If you have trouble, get GDB version 4.4 or later.
659 DBX rejects some files produced by GCC, though it accepts similar
660 constructs in output from PCC@. Until someone can supply a coherent
661 description of what is valid DBX input and what is not, there is
662 nothing I can do about these problems. You are on your own.
665 The GNU assembler (GAS) does not support PIC@. To generate PIC code, you
666 must use some other assembler, such as @file{/bin/as}.
669 On some BSD systems, including some versions of Ultrix, use of profiling
670 causes static variable destructors (currently used only in C++) not to
674 @cindex @code{vfork}, for the Sun-4
676 There is a bug in @code{vfork} on the Sun-4 which causes the registers
677 of the child process to clobber those of the parent. Because of this,
678 programs that call @code{vfork} are likely to lose when compiled
679 optimized with GCC when the child code alters registers which contain
680 C variables in the parent. This affects variables which are live in the
681 parent across the call to @code{vfork}.
683 If you encounter this, you can work around the problem by declaring
684 variables @code{volatile} in the function that calls @code{vfork}, until
685 the problem goes away, or by not declaring them @code{register} and not
686 using @option{-O} for those source files.
690 On some SGI systems, when you use @option{-lgl_s} as an option,
691 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
692 Naturally, this does not happen when you use GCC@.
693 You must specify all three options explicitly.
696 On a Sparc, GCC aligns all values of type @code{double} on an 8-byte
697 boundary, and it expects every @code{double} to be so aligned. The Sun
698 compiler usually gives @code{double} values 8-byte alignment, with one
699 exception: function arguments of type @code{double} may not be aligned.
701 As a result, if a function compiled with Sun CC takes the address of an
702 argument of type @code{double} and passes this pointer of type
703 @code{double *} to a function compiled with GCC, dereferencing the
704 pointer may cause a fatal signal.
706 One way to solve this problem is to compile your entire program with GCC@.
707 Another solution is to modify the function that is compiled with
708 Sun CC to copy the argument into a local variable; local variables
709 are always properly aligned. A third solution is to modify the function
710 that uses the pointer to dereference it via the following function
711 @code{access_double} instead of directly with @samp{*}:
715 access_double (double *unaligned_ptr)
717 union d2i @{ double d; int i[2]; @};
719 union d2i *p = (union d2i *) unaligned_ptr;
730 Storing into the pointer can be done likewise with the same union.
733 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
734 may allocate memory that is only 4 byte aligned. Since GCC on the
735 Sparc assumes that doubles are 8 byte aligned, this may result in a
736 fatal signal if doubles are stored in memory allocated by the
737 @file{libmalloc.a} library.
739 The solution is to not use the @file{libmalloc.a} library. Use instead
740 @code{malloc} and related functions from @file{libc.a}; they do not have
744 Sun forgot to include a static version of @file{libdl.a} with some
745 versions of SunOS (mainly 4.1). This results in undefined symbols when
746 linking static binaries (that is, if you use @option{-static}). If you
747 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
748 when linking, compile and link against the file
749 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
752 The 128-bit long double format that the Sparc port supports currently
753 works by using the architecturally defined quad-word floating point
754 instructions. Since there is no hardware that supports these
755 instructions they must be emulated by the operating system. Long
756 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
757 kernel emulator uses an obsolete and incompatible format. Long doubles
758 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
759 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
760 does not enable them by default. Long doubles appear to work in Sun OS
764 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
765 compile GCC correctly. We do not yet know why. However, GCC
766 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
767 compile itself properly on 9.01.
770 On the HP PA machine, ADB sometimes fails to work on functions compiled
771 with GCC@. Specifically, it fails to work on functions that use
772 @code{alloca} or variable-size arrays. This is because GCC doesn't
773 generate HP-UX unwind descriptors for such functions. It may even be
774 impossible to generate them.
777 Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
778 the preliminary GNU tools (@pxref{Installation}).
781 Taking the address of a label may generate errors from the HP-UX
782 PA assembler. GAS for the PA does not have this problem.
785 Using floating point parameters for indirect calls to static functions
786 will not work when using the HP assembler. There simply is no way for GCC
787 to specify what registers hold arguments for static functions when using
788 the HP assembler. GAS for the PA does not have this problem.
791 In extremely rare cases involving some very large functions you may
792 receive errors from the HP linker complaining about an out of bounds
793 unconditional branch offset. This used to occur more often in previous
794 versions of GCC, but is now exceptionally rare. If you should run
795 into it, you can work around by making your function smaller.
798 GCC compiled code sometimes emits warnings from the HP-UX assembler of
802 (warning) Use of GR3 when
803 frame >= 8192 may cause conflict.
806 These warnings are harmless and can be safely ignored.
809 The current version of the assembler (@file{/bin/as}) for the RS/6000
810 has certain problems that prevent the @option{-g} option in GCC from
811 working. Note that @file{Makefile.in} uses @option{-g} by default when
812 compiling @file{libgcc2.c}.
814 IBM has produced a fixed version of the assembler. The upgraded
815 assembler unfortunately was not included in any of the AIX 3.2 update
816 PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request
817 PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
818 See the file @file{README.RS6000} for more details on these updates.
820 You can test for the presence of a fixed assembler by using the
828 If the command exits normally, the assembler fix already is installed.
829 If the assembler complains that @option{-u} is an unknown flag, you need to
833 On the IBM RS/6000, compiling code of the form
844 will cause the linker to report an undefined symbol @code{foo}.
845 Although this behavior differs from most other systems, it is not a
846 bug because redefining an @code{extern} variable as @code{static}
847 is undefined in ISO C@.
850 AIX on the RS/6000 provides support (NLS) for environments outside of
851 the United States. Compilers and assemblers use NLS to support
852 locale-specific representations of various objects including
853 floating-point numbers (@samp{.} vs @samp{,} for separating decimal fractions).
854 There have been problems reported where the library linked with GCC does
855 not produce the same floating-point formats that the assembler accepts.
856 If you have this problem, set the @env{LANG} environment variable to
857 @samp{C} or @samp{En_US}.
860 @opindex fdollars-in-identifiers
861 Even if you specify @option{-fdollars-in-identifiers},
862 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
863 to a restriction in the IBM assembler. GAS supports these
867 On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC
868 version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2
869 by requesting PTF 421749 from IBM@.
872 @opindex mno-serialize-volatile
873 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
874 occurs when the @samp{fldcr} instruction is used. GCC uses
875 @samp{fldcr} on the 88100 to serialize volatile memory references. Use
876 the option @option{-mno-serialize-volatile} if your version of the
877 assembler has this bug.
880 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
881 messages from the linker. These warning messages complain of mismatched
882 psect attributes. You can ignore them. @xref{VMS Install}.
885 On NewsOS version 3, if you include both of the files @file{stddef.h}
886 and @file{sys/types.h}, you get an error because there are two typedefs
887 of @code{size_t}. You should change @file{sys/types.h} by adding these
888 lines around the definition of @code{size_t}:
893 @var{actual-typedef-here}
899 On the Alliant, the system's own convention for returning structures
900 and unions is unusual, and is not compatible with GCC no matter
901 what options are used.
906 @opindex mhc-struct-return
907 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
908 convention for structure and union returning. Use the option
909 @option{-mhc-struct-return} to tell GCC to use a convention compatible
912 @cindex Vax calling convention
913 @cindex Ultrix calling convention
916 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
917 by function calls. However, the C compiler uses conventions compatible
918 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
920 GCC uses the same convention as the Ultrix C compiler. You can use
921 these options to produce code compatible with the Fortran compiler:
924 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
928 On the WE32k, you may find that programs compiled with GCC do not
929 work with the standard shared C library. You may need to link with
930 the ordinary C compiler. If you do so, you must specify the following
934 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
937 The first specifies where to find the library @file{libgcc.a}
938 specified with the @option{-lgcc} option.
940 GCC does linking by invoking @command{ld}, just as @command{cc} does, and
941 there is no reason why it @emph{should} matter which compilation program
942 you use to invoke @command{ld}. If someone tracks this problem down,
943 it can probably be fixed easily.
946 On the Alpha, you may get assembler errors about invalid syntax as a
947 result of floating point constants. This is due to a bug in the C
948 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid
949 floating point numbers, they sometimes print @samp{NaN}.
952 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
953 sometimes reorders instructions incorrectly when optimization is turned
954 on. If you think this may be happening to you, try using the GNU
955 assembler; GAS version 2.1 supports ECOFF on Irix.
958 Or use the @option{-noasmopt} option when you compile GCC with itself,
959 and then again when you compile your program. (This is a temporary
960 kludge to turn off assembler optimization on Irix.) If this proves to
961 be what you need, edit the assembler spec in the file @file{specs} so
962 that it unconditionally passes @option{-O0} to the assembler, and never
963 passes @option{-O2} or @option{-O3}.
967 @section Problems Compiling Certain Programs
969 @c prevent bad page break with this line
970 Certain programs have problems compiling.
974 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
975 because of problems in DEC's versions of the X11 header files
976 @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
977 @option{-I/usr/include/mit} to use the MIT versions of the header files,
978 using the @option{-traditional} switch to turn off ISO C, or fixing the
979 header files by adding this:
983 #define NeedFunctionPrototypes 0
988 On various 386 Unix systems derived from System V, including SCO, ISC,
989 and ESIX, you may get error messages about running out of virtual memory
990 while compiling certain programs.
992 You can prevent this problem by linking GCC with the GNU malloc
993 (which thus replaces the malloc that comes with the system). GNU malloc
994 is available as a separate package, and also in the file
995 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
997 If you have installed GNU malloc as a separate library package, use this
998 option when you relink GCC:
1001 MALLOC=/usr/local/lib/libgmalloc.a
1004 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
1005 the object file to @file{gmalloc.o} and use this option when you relink
1013 @node Incompatibilities
1014 @section Incompatibilities of GCC
1015 @cindex incompatibilities of GCC
1016 @opindex traditional
1018 There are several noteworthy incompatibilities between GNU C and K&R
1019 (non-ISO) versions of C@. The @option{-traditional} option
1020 eliminates many of these incompatibilities, @emph{but not all}, by
1021 telling GCC to behave like a K&R C compiler.
1024 @cindex string constants
1025 @cindex read-only strings
1026 @cindex shared strings
1028 GCC normally makes string constants read-only. If several
1029 identical-looking string constants are used, GCC stores only one
1032 @cindex @code{mktemp}, and constant strings
1033 One consequence is that you cannot call @code{mktemp} with a string
1034 constant argument. The function @code{mktemp} always alters the
1035 string its argument points to.
1037 @cindex @code{sscanf}, and constant strings
1038 @cindex @code{fscanf}, and constant strings
1039 @cindex @code{scanf}, and constant strings
1040 Another consequence is that @code{sscanf} does not work on some systems
1041 when passed a string constant as its format control string or input.
1042 This is because @code{sscanf} incorrectly tries to write into the string
1043 constant. Likewise @code{fscanf} and @code{scanf}.
1045 @opindex fwritable-strings
1046 The best solution to these problems is to change the program to use
1047 @code{char}-array variables with initialization strings for these
1048 purposes instead of string constants. But if this is not possible,
1049 you can use the @option{-fwritable-strings} flag, which directs GCC
1050 to handle string constants the same way most C compilers do.
1051 @option{-traditional} also has this effect, among others.
1054 @code{-2147483648} is positive.
1056 This is because 2147483648 cannot fit in the type @code{int}, so
1057 (following the ISO C rules) its data type is @code{unsigned long int}.
1058 Negating this value yields 2147483648 again.
1061 GCC does not substitute macro arguments when they appear inside of
1062 string constants. For example, the following macro in GCC
1069 will produce output @code{"a"} regardless of what the argument @var{a} is.
1071 The @option{-traditional} option directs GCC to handle such cases
1072 (among others) in the old-fashioned (non-ISO) fashion.
1074 @cindex @code{setjmp} incompatibilities
1075 @cindex @code{longjmp} incompatibilities
1077 When you use @code{setjmp} and @code{longjmp}, the only automatic
1078 variables guaranteed to remain valid are those declared
1079 @code{volatile}. This is a consequence of automatic register
1080 allocation. Consider this function:
1094 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
1099 Here @code{a} may or may not be restored to its first value when the
1100 @code{longjmp} occurs. If @code{a} is allocated in a register, then
1101 its first value is restored; otherwise, it keeps the last value stored
1105 If you use the @option{-W} option with the @option{-O} option, you will
1106 get a warning when GCC thinks such a problem might be possible.
1108 The @option{-traditional} option directs GCC to put variables in
1109 the stack by default, rather than in registers, in functions that
1110 call @code{setjmp}. This results in the behavior found in
1111 traditional C compilers.
1114 Programs that use preprocessing directives in the middle of macro
1115 arguments do not work with GCC@. For example, a program like this
1126 ISO C does not permit such a construct. It would make sense to support
1127 it when @option{-traditional} is used, but it is too much work to
1131 K&R compilers allow comments to cross over an inclusion boundary
1132 (i.e.@: started in an include file and ended in the including file). I think
1133 this would be quite ugly and can't imagine it could be needed.
1135 @cindex external declaration scope
1136 @cindex scope of external declarations
1137 @cindex declaration scope
1139 Declarations of external variables and functions within a block apply
1140 only to the block containing the declaration. In other words, they
1141 have the same scope as any other declaration in the same place.
1143 In some other C compilers, a @code{extern} declaration affects all the
1144 rest of the file even if it happens within a block.
1146 The @option{-traditional} option directs GCC to treat all @code{extern}
1147 declarations as global, like traditional compilers.
1150 In traditional C, you can combine @code{long}, etc., with a typedef name,
1155 typedef long foo bar;
1158 In ISO C, this is not allowed: @code{long} and other type modifiers
1159 require an explicit @code{int}. Because this criterion is expressed
1160 by Bison grammar rules rather than C code, the @option{-traditional}
1161 flag cannot alter it.
1163 @cindex typedef names as function parameters
1165 PCC allows typedef names to be used as function parameters. The
1166 difficulty described immediately above applies here too.
1169 When in @option{-traditional} mode, GCC allows the following erroneous
1170 pair of declarations to appear together in a given scope:
1178 GCC treats all characters of identifiers as significant, even when in
1179 @option{-traditional} mode. According to K&R-1 (2.2), ``No more than the
1180 first eight characters are significant, although more may be used.''.
1181 Also according to K&R-1 (2.2), ``An identifier is a sequence of letters
1182 and digits; the first character must be a letter. The underscore _
1183 counts as a letter.'', but GCC also allows dollar signs in identifiers.
1187 PCC allows whitespace in the middle of compound assignment operators
1188 such as @samp{+=}. GCC, following the ISO standard, does not
1189 allow this. The difficulty described immediately above applies here
1195 GCC complains about unterminated character constants inside of
1196 preprocessing conditionals that fail. Some programs have English
1197 comments enclosed in conditionals that are guaranteed to fail; if these
1198 comments contain apostrophes, GCC will probably report an error. For
1199 example, this code would produce an error:
1203 You can't expect this to work.
1207 The best solution to such a problem is to put the text into an actual
1208 C comment delimited by @samp{/*@dots{}*/}. However,
1209 @option{-traditional} suppresses these error messages.
1212 Many user programs contain the declaration @samp{long time ();}. In the
1213 past, the system header files on many systems did not actually declare
1214 @code{time}, so it did not matter what type your program declared it to
1215 return. But in systems with ISO C headers, @code{time} is declared to
1216 return @code{time_t}, and if that is not the same as @code{long}, then
1217 @samp{long time ();} is erroneous.
1219 The solution is to change your program to use appropriate system headers
1220 (@code{<time.h>} on systems with ISO C headers) and not to declare
1221 @code{time} if the system header files declare it, or failing that to
1222 use @code{time_t} as the return type of @code{time}.
1224 @cindex @code{float} as function value type
1226 When compiling functions that return @code{float}, PCC converts it to
1227 a double. GCC actually returns a @code{float}. If you are concerned
1228 with PCC compatibility, you should declare your functions to return
1229 @code{double}; you might as well say what you mean.
1234 When compiling functions that return structures or unions, GCC
1235 output code normally uses a method different from that used on most
1236 versions of Unix. As a result, code compiled with GCC cannot call
1237 a structure-returning function compiled with PCC, and vice versa.
1239 The method used by GCC is as follows: a structure or union which is
1240 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
1241 with any other size is stored into an address supplied by the caller
1242 (usually in a special, fixed register, but on some machines it is passed
1243 on the stack). The machine-description macros @code{STRUCT_VALUE} and
1244 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
1246 By contrast, PCC on most target machines returns structures and unions
1247 of any size by copying the data into an area of static storage, and then
1248 returning the address of that storage as if it were a pointer value.
1249 The caller must copy the data from that memory area to the place where
1250 the value is wanted. GCC does not use this method because it is
1251 slower and nonreentrant.
1253 On some newer machines, PCC uses a reentrant convention for all
1254 structure and union returning. GCC on most of these machines uses a
1255 compatible convention when returning structures and unions in memory,
1256 but still returns small structures and unions in registers.
1258 @opindex fpcc-struct-return
1259 You can tell GCC to use a compatible convention for all structure and
1260 union returning with the option @option{-fpcc-struct-return}.
1262 @cindex preprocessing tokens
1263 @cindex preprocessing numbers
1265 GCC complains about program fragments such as @samp{0x74ae-0x4000}
1266 which appear to be two hexadecimal constants separated by the minus
1267 operator. Actually, this string is a single @dfn{preprocessing token}.
1268 Each such token must correspond to one token in C@. Since this does not,
1269 GCC prints an error message. Although it may appear obvious that what
1270 is meant is an operator and two values, the ISO C standard specifically
1271 requires that this be treated as erroneous.
1273 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
1274 begins with a digit and is followed by letters, underscores, digits,
1275 periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
1276 @samp{p-}, @samp{P+}, or @samp{P-} character sequences. (In strict C89
1277 mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
1278 appear in preprocessing numbers.)
1280 To make the above program fragment valid, place whitespace in front of
1281 the minus sign. This whitespace will end the preprocessing number.
1285 @section Fixed Header Files
1287 GCC needs to install corrected versions of some system header files.
1288 This is because most target systems have some header files that won't
1289 work with GCC unless they are changed. Some have bugs, some are
1290 incompatible with ISO C, and some depend on special features of other
1293 Installing GCC automatically creates and installs the fixed header
1294 files, by running a program called @code{fixincludes} (or for certain
1295 targets an alternative such as @code{fixinc.svr4}). Normally, you
1296 don't need to pay attention to this. But there are cases where it
1297 doesn't do the right thing automatically.
1301 If you update the system's header files, such as by installing a new
1302 system version, the fixed header files of GCC are not automatically
1303 updated. The easiest way to update them is to reinstall GCC@. (If
1304 you want to be clever, look in the makefile and you can find a
1308 On some systems, in particular SunOS 4, header file directories contain
1309 machine-specific symbolic links in certain places. This makes it
1310 possible to share most of the header files among hosts running the
1311 same version of SunOS 4 on different machine models.
1313 The programs that fix the header files do not understand this special
1314 way of using symbolic links; therefore, the directory of fixed header
1315 files is good only for the machine model used to build it.
1317 In SunOS 4, only programs that look inside the kernel will notice the
1318 difference between machine models. Therefore, for most purposes, you
1319 need not be concerned about this.
1321 It is possible to make separate sets of fixed header files for the
1322 different machine models, and arrange a structure of symbolic links so
1323 as to use the proper set, but you'll have to do this by hand.
1326 On Lynxos, GCC by default does not fix the header files. This is
1327 because bugs in the shell cause the @code{fixincludes} script to fail.
1329 This means you will encounter problems due to bugs in the system header
1330 files. It may be no comfort that they aren't GCC's fault, but it
1331 does mean that there's nothing for us to do about them.
1334 @node Standard Libraries
1335 @section Standard Libraries
1338 GCC by itself attempts to be a conforming freestanding implementation.
1339 @xref{Standards,,Language Standards Supported by GCC}, for details of
1340 what this means. Beyond the library facilities required of such an
1341 implementation, the rest of the C library is supplied by the vendor of
1342 the operating system. If that C library doesn't conform to the C
1343 standards, then your programs might get warnings (especially when using
1344 @option{-Wall}) that you don't expect.
1346 For example, the @code{sprintf} function on SunOS 4.1.3 returns
1347 @code{char *} while the C standard says that @code{sprintf} returns an
1348 @code{int}. The @code{fixincludes} program could make the prototype for
1349 this function match the Standard, but that would be wrong, since the
1350 function will still return @code{char *}.
1352 If you need a Standard compliant library, then you need to find one, as
1353 GCC does not provide one. The GNU C library (called @code{glibc})
1354 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
1355 GNU/Linux and HURD-based GNU systems; no recent version of it supports
1356 other systems, though some very old versions did. Version 2.2 of the
1357 GNU C library includes nearly complete C99 support. You could also ask
1358 your operating system vendor if newer libraries are available.
1360 @node Disappointments
1361 @section Disappointments and Misunderstandings
1363 These problems are perhaps regrettable, but we don't know any practical
1368 Certain local variables aren't recognized by debuggers when you compile
1371 This occurs because sometimes GCC optimizes the variable out of
1372 existence. There is no way to tell the debugger how to compute the
1373 value such a variable ``would have had'', and it is not clear that would
1374 be desirable anyway. So GCC simply does not mention the eliminated
1375 variable when it writes debugging information.
1377 You have to expect a certain amount of disagreement between the
1378 executable and your source code, when you use optimization.
1380 @cindex conflicting types
1381 @cindex scope of declaration
1383 Users often think it is a bug when GCC reports an error for code
1387 int foo (struct mumble *);
1389 struct mumble @{ @dots{} @};
1391 int foo (struct mumble *x)
1395 This code really is erroneous, because the scope of @code{struct
1396 mumble} in the prototype is limited to the argument list containing it.
1397 It does not refer to the @code{struct mumble} defined with file scope
1398 immediately below---they are two unrelated types with similar names in
1401 But in the definition of @code{foo}, the file-scope type is used
1402 because that is available to be inherited. Thus, the definition and
1403 the prototype do not match, and you get an error.
1405 This behavior may seem silly, but it's what the ISO standard specifies.
1406 It is easy enough for you to make your code work by moving the
1407 definition of @code{struct mumble} above the prototype. It's not worth
1408 being incompatible with ISO C just to avoid an error for the example
1412 Accesses to bit-fields even in volatile objects works by accessing larger
1413 objects, such as a byte or a word. You cannot rely on what size of
1414 object is accessed in order to read or write the bit-field; it may even
1415 vary for a given bit-field according to the precise usage.
1417 If you care about controlling the amount of memory that is accessed, use
1418 volatile but do not use bit-fields.
1421 GCC comes with shell scripts to fix certain known problems in system
1422 header files. They install corrected copies of various header files in
1423 a special directory where only GCC will normally look for them. The
1424 scripts adapt to various systems by searching all the system header
1425 files for the problem cases that we know about.
1427 If new system header files are installed, nothing automatically arranges
1428 to update the corrected header files. You will have to reinstall GCC
1429 to fix the new header files. More specifically, go to the build
1430 directory and delete the files @file{stmp-fixinc} and
1431 @file{stmp-headers}, and the subdirectory @code{include}; then do
1432 @samp{make install} again.
1435 @cindex floating point precision
1436 On 68000 and x86 systems, for instance, you can get paradoxical results
1437 if you test the precise values of floating point numbers. For example,
1438 you can find that a floating point value which is not a NaN is not equal
1439 to itself. This results from the fact that the floating point registers
1440 hold a few more bits of precision than fit in a @code{double} in memory.
1441 Compiled code moves values between memory and floating point registers
1442 at its convenience, and moving them into memory truncates them.
1444 @opindex ffloat-store
1445 You can partially avoid this problem by using the @option{-ffloat-store}
1446 option (@pxref{Optimize Options}).
1449 On the MIPS, variable argument functions using @file{varargs.h}
1450 cannot have a floating point value for the first argument. The
1451 reason for this is that in the absence of a prototype in scope,
1452 if the first argument is a floating point, it is passed in a
1453 floating point register, rather than an integer register.
1455 If the code is rewritten to use the ISO standard @file{stdarg.h}
1456 method of variable arguments, and the prototype is in scope at
1457 the time of the call, everything will work fine.
1460 On the H8/300 and H8/300H, variable argument functions must be
1461 implemented using the ISO standard @file{stdarg.h} method of
1462 variable arguments. Furthermore, calls to functions using @file{stdarg.h}
1463 variable arguments must have a prototype for the called function
1464 in scope at the time of the call.
1467 @node C++ Misunderstandings
1468 @section Common Misunderstandings with GNU C++
1470 @cindex misunderstandings in C++
1471 @cindex surprises in C++
1472 @cindex C++ misunderstandings
1473 C++ is a complex language and an evolving one, and its standard
1474 definition (the ISO C++ standard) was only recently completed. As a
1475 result, your C++ compiler may occasionally surprise you, even when its
1476 behavior is correct. This section discusses some areas that frequently
1477 give rise to questions of this sort.
1480 * Static Definitions:: Static member declarations are not definitions
1481 * Temporaries:: Temporaries may vanish before you expect
1482 * Copy Assignment:: Copy Assignment operators copy virtual bases twice
1485 @node Static Definitions
1486 @subsection Declare @emph{and} Define Static Members
1488 @cindex C++ static data, declaring and defining
1489 @cindex static data in C++, declaring and defining
1490 @cindex declaring static data in C++
1491 @cindex defining static data in C++
1492 When a class has static data members, it is not enough to @emph{declare}
1493 the static member; you must also @emph{define} it. For example:
1504 This declaration only establishes that the class @code{Foo} has an
1505 @code{int} named @code{Foo::bar}, and a member function named
1506 @code{Foo::method}. But you still need to define @emph{both}
1507 @code{method} and @code{bar} elsewhere. According to the ISO
1508 standard, you must supply an initializer in one (and only one) source
1515 Other C++ compilers may not correctly implement the standard behavior.
1516 As a result, when you switch to @code{g++} from one of these compilers,
1517 you may discover that a program that appeared to work correctly in fact
1518 does not conform to the standard: @code{g++} reports as undefined
1519 symbols any static data members that lack definitions.
1522 @subsection Temporaries May Vanish Before You Expect
1524 @cindex temporaries, lifetime of
1525 @cindex portions of temporary objects, pointers to
1526 It is dangerous to use pointers or references to @emph{portions} of a
1527 temporary object. The compiler may very well delete the object before
1528 you expect it to, leaving a pointer to garbage. The most common place
1529 where this problem crops up is in classes like string classes,
1530 especially ones that define a conversion function to type @code{char *}
1531 or @code{const char *}---which is one reason why the standard
1532 @code{string} class requires you to call the @code{c_str} member
1533 function. However, any class that returns a pointer to some internal
1534 structure is potentially subject to this problem.
1536 For example, a program may use a function @code{strfunc} that returns
1537 @code{string} objects, and another function @code{charfunc} that
1538 operates on pointers to @code{char}:
1542 void charfunc (const char *);
1547 const char *p = strfunc().c_str();
1556 In this situation, it may seem reasonable to save a pointer to the C
1557 string returned by the @code{c_str} member function and use that rather
1558 than call @code{c_str} repeatedly. However, the temporary string
1559 created by the call to @code{strfunc} is destroyed after @code{p} is
1560 initialized, at which point @code{p} is left pointing to freed memory.
1562 Code like this may run successfully under some other compilers,
1563 particularly obsolete cfront-based compilers that delete temporaries
1564 along with normal local variables. However, the GNU C++ behavior is
1565 standard-conforming, so if your program depends on late destruction of
1566 temporaries it is not portable.
1568 The safe way to write such code is to give the temporary a name, which
1569 forces it to remain until the end of the scope of the name. For
1573 string& tmp = strfunc ();
1574 charfunc (tmp.c_str ());
1577 @node Copy Assignment
1578 @subsection Implicit Copy-Assignment for Virtual Bases
1580 When a base class is virtual, only one subobject of the base class
1581 belongs to each full object. Also, the constructors and destructors are
1582 invoked only once, and called from the most-derived class. However, such
1583 objects behave unspecified when being assigned. For example:
1588 Base(char *n) : name(strdup(n))@{@}
1589 Base& operator= (const Base& other)@{
1591 name = strdup (other.name);
1595 struct A:virtual Base@{
1600 struct B:virtual Base@{
1605 struct Derived:public A, public B@{
1606 Derived():Base("Derived")@{@}
1609 void func(Derived &d1, Derived &d2)
1615 The C++ standard specifies that @samp{Base::Base} is only called once
1616 when constructing or copy-constructing a Derived object. It is
1617 unspecified whether @samp{Base::operator=} is called more than once when
1618 the implicit copy-assignment for Derived objects is invoked (as it is
1619 inside @samp{func} in the example).
1621 g++ implements the ``intuitive'' algorithm for copy-assignment: assign all
1622 direct bases, then assign all members. In that algorithm, the virtual
1623 base subobject can be encountered many times. In the example, copying
1624 proceeds in the following order: @samp{val}, @samp{name} (via
1625 @code{strdup}), @samp{bval}, and @samp{name} again.
1627 If application code relies on copy-assignment, a user-defined
1628 copy-assignment operator removes any uncertainties. With such an
1629 operator, the application can define whether and how the virtual base
1630 subobject is assigned.
1632 @node Protoize Caveats
1633 @section Caveats of using @command{protoize}
1635 The conversion programs @command{protoize} and @command{unprotoize} can
1636 sometimes change a source file in a way that won't work unless you
1641 @command{protoize} can insert references to a type name or type tag before
1642 the definition, or in a file where they are not defined.
1644 If this happens, compiler error messages should show you where the new
1645 references are, so fixing the file by hand is straightforward.
1648 There are some C constructs which @command{protoize} cannot figure out.
1649 For example, it can't determine argument types for declaring a
1650 pointer-to-function variable; this you must do by hand. @command{protoize}
1651 inserts a comment containing @samp{???} each time it finds such a
1652 variable; so you can find all such variables by searching for this
1653 string. ISO C does not require declaring the argument types of
1654 pointer-to-function types.
1657 Using @command{unprotoize} can easily introduce bugs. If the program
1658 relied on prototypes to bring about conversion of arguments, these
1659 conversions will not take place in the program without prototypes.
1660 One case in which you can be sure @command{unprotoize} is safe is when
1661 you are removing prototypes that were made with @command{protoize}; if
1662 the program worked before without any prototypes, it will work again
1665 @opindex Wconversion
1666 You can find all the places where this problem might occur by compiling
1667 the program with the @option{-Wconversion} option. It prints a warning
1668 whenever an argument is converted.
1671 Both conversion programs can be confused if there are macro calls in and
1672 around the text to be converted. In other words, the standard syntax
1673 for a declaration or definition must not result from expanding a macro.
1674 This problem is inherent in the design of C and cannot be fixed. If
1675 only a few functions have confusing macro calls, you can easily convert
1679 @command{protoize} cannot get the argument types for a function whose
1680 definition was not actually compiled due to preprocessing conditionals.
1681 When this happens, @command{protoize} changes nothing in regard to such
1682 a function. @command{protoize} tries to detect such instances and warn
1685 You can generally work around this problem by using @command{protoize} step
1686 by step, each time specifying a different set of @option{-D} options for
1687 compilation, until all of the functions have been converted. There is
1688 no automatic way to verify that you have got them all, however.
1691 Confusion may result if there is an occasion to convert a function
1692 declaration or definition in a region of source code where there is more
1693 than one formal parameter list present. Thus, attempts to convert code
1694 containing multiple (conditionally compiled) versions of a single
1695 function header (in the same vicinity) may not produce the desired (or
1698 If you plan on converting source files which contain such code, it is
1699 recommended that you first make sure that each conditionally compiled
1700 region of source code which contains an alternative function header also
1701 contains at least one additional follower token (past the final right
1702 parenthesis of the function header). This should circumvent the
1706 @command{unprotoize} can become confused when trying to convert a function
1707 definition or declaration which contains a declaration for a
1708 pointer-to-function formal argument which has the same name as the
1709 function being defined or declared. We recommend you avoid such choices
1710 of formal parameter names.
1713 You might also want to correct some of the indentation by hand and break
1714 long lines. (The conversion programs don't write lines longer than
1715 eighty characters in any case.)
1719 @section Certain Changes We Don't Want to Make
1721 This section lists changes that people frequently request, but which
1722 we do not make because we think GCC is better without them.
1726 Checking the number and type of arguments to a function which has an
1727 old-fashioned definition and no prototype.
1729 Such a feature would work only occasionally---only for calls that appear
1730 in the same file as the called function, following the definition. The
1731 only way to check all calls reliably is to add a prototype for the
1732 function. But adding a prototype eliminates the motivation for this
1733 feature. So the feature is not worthwhile.
1736 Warning about using an expression whose type is signed as a shift count.
1738 Shift count operands are probably signed more often than unsigned.
1739 Warning about this would cause far more annoyance than good.
1742 Warning about assigning a signed value to an unsigned variable.
1744 Such assignments must be very common; warning about them would cause
1745 more annoyance than good.
1748 Warning when a non-void function value is ignored.
1750 Coming as I do from a Lisp background, I balk at the idea that there is
1751 something dangerous about discarding a value. There are functions that
1752 return values which some callers may find useful; it makes no sense to
1753 clutter the program with a cast to @code{void} whenever the value isn't
1757 @opindex fshort-enums
1758 Making @option{-fshort-enums} the default.
1760 This would cause storage layout to be incompatible with most other C
1761 compilers. And it doesn't seem very important, given that you can get
1762 the same result in other ways. The case where it matters most is when
1763 the enumeration-valued object is inside a structure, and in that case
1764 you can specify a field width explicitly.
1767 Making bit-fields unsigned by default on particular machines where ``the
1768 ABI standard'' says to do so.
1770 The ISO C standard leaves it up to the implementation whether a bit-field
1771 declared plain @code{int} is signed or not. This in effect creates two
1772 alternative dialects of C@.
1774 @opindex fsigned-bitfields
1775 @opindex funsigned-bitfields
1776 The GNU C compiler supports both dialects; you can specify the signed
1777 dialect with @option{-fsigned-bitfields} and the unsigned dialect with
1778 @option{-funsigned-bitfields}. However, this leaves open the question of
1779 which dialect to use by default.
1781 Currently, the preferred dialect makes plain bit-fields signed, because
1782 this is simplest. Since @code{int} is the same as @code{signed int} in
1783 every other context, it is cleanest for them to be the same in bit-fields
1786 Some computer manufacturers have published Application Binary Interface
1787 standards which specify that plain bit-fields should be unsigned. It is
1788 a mistake, however, to say anything about this issue in an ABI@. This is
1789 because the handling of plain bit-fields distinguishes two dialects of C@.
1790 Both dialects are meaningful on every type of machine. Whether a
1791 particular object file was compiled using signed bit-fields or unsigned
1792 is of no concern to other object files, even if they access the same
1793 bit-fields in the same data structures.
1795 A given program is written in one or the other of these two dialects.
1796 The program stands a chance to work on most any machine if it is
1797 compiled with the proper dialect. It is unlikely to work at all if
1798 compiled with the wrong dialect.
1800 Many users appreciate the GNU C compiler because it provides an
1801 environment that is uniform across machines. These users would be
1802 inconvenienced if the compiler treated plain bit-fields differently on
1805 Occasionally users write programs intended only for a particular machine
1806 type. On these occasions, the users would benefit if the GNU C compiler
1807 were to support by default the same dialect as the other compilers on
1808 that machine. But such applications are rare. And users writing a
1809 program to run on more than one type of machine cannot possibly benefit
1810 from this kind of compatibility.
1812 This is why GCC does and will treat plain bit-fields in the same
1813 fashion on all types of machines (by default).
1815 There are some arguments for making bit-fields unsigned by default on all
1816 machines. If, for example, this becomes a universal de facto standard,
1817 it would make sense for GCC to go along with it. This is something
1818 to be considered in the future.
1820 (Of course, users strongly concerned about portability should indicate
1821 explicitly in each bit-field whether it is signed or not. In this way,
1822 they write programs which have the same meaning in both C dialects.)
1826 @opindex traditional
1828 Undefining @code{__STDC__} when @option{-ansi} is not used.
1830 Currently, GCC defines @code{__STDC__} as long as you don't use
1831 @option{-traditional}. This provides good results in practice.
1833 Programmers normally use conditionals on @code{__STDC__} to ask whether
1834 it is safe to use certain features of ISO C, such as function
1835 prototypes or ISO token concatenation. Since plain @command{gcc} supports
1836 all the features of ISO C, the correct answer to these questions is
1839 Some users try to use @code{__STDC__} to check for the availability of
1840 certain library facilities. This is actually incorrect usage in an ISO
1841 C program, because the ISO C standard says that a conforming
1842 freestanding implementation should define @code{__STDC__} even though it
1843 does not have the library facilities. @samp{gcc -ansi -pedantic} is a
1844 conforming freestanding implementation, and it is therefore required to
1845 define @code{__STDC__}, even though it does not come with an ISO C
1848 Sometimes people say that defining @code{__STDC__} in a compiler that
1849 does not completely conform to the ISO C standard somehow violates the
1850 standard. This is illogical. The standard is a standard for compilers
1851 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
1852 compilers such as plain @command{gcc}. Whatever the ISO C standard says
1853 is relevant to the design of plain @command{gcc} without @option{-ansi} only
1854 for pragmatic reasons, not as a requirement.
1856 GCC normally defines @code{__STDC__} to be 1, and in addition
1857 defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
1858 or a @option{-std} option for strict conformance to some version of ISO C@.
1859 On some hosts, system include files use a different convention, where
1860 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
1861 conformance to the C Standard. GCC follows the host convention when
1862 processing system include files, but when processing user files it follows
1863 the usual GNU C convention.
1866 Undefining @code{__STDC__} in C++.
1868 Programs written to compile with C++-to-C translators get the
1869 value of @code{__STDC__} that goes with the C compiler that is
1870 subsequently used. These programs must test @code{__STDC__}
1871 to determine what kind of C preprocessor that compiler uses:
1872 whether they should concatenate tokens in the ISO C fashion
1873 or in the traditional fashion.
1875 These programs work properly with GNU C++ if @code{__STDC__} is defined.
1876 They would not work otherwise.
1878 In addition, many header files are written to provide prototypes in ISO
1879 C but not in traditional C@. Many of these header files can work without
1880 change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
1881 is not defined, they will all fail, and will all need to be changed to
1882 test explicitly for C++ as well.
1885 Deleting ``empty'' loops.
1887 Historically, GCC has not deleted ``empty'' loops under the
1888 assumption that the most likely reason you would put one in a program is
1889 to have a delay, so deleting them will not make real programs run any
1892 However, the rationale here is that optimization of a nonempty loop
1893 cannot produce an empty one, which holds for C but is not always the
1896 @opindex funroll-loops
1897 Moreover, with @option{-funroll-loops} small ``empty'' loops are already
1898 removed, so the current behavior is both sub-optimal and inconsistent
1899 and will change in the future.
1902 Making side effects happen in the same order as in some other compiler.
1904 @cindex side effects, order of evaluation
1905 @cindex order of evaluation, side effects
1906 It is never safe to depend on the order of evaluation of side effects.
1907 For example, a function call like this may very well behave differently
1908 from one compiler to another:
1911 void func (int, int);
1917 There is no guarantee (in either the C or the C++ standard language
1918 definitions) that the increments will be evaluated in any particular
1919 order. Either increment might happen first. @code{func} might get the
1920 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
1923 Not allowing structures with volatile fields in registers.
1925 Strictly speaking, there is no prohibition in the ISO C standard
1926 against allowing structures with volatile fields in registers, but
1927 it does not seem to make any sense and is probably not what you wanted
1928 to do. So the compiler will give an error message in this case.
1931 Making certain warnings into errors by default.
1933 Some ISO C testsuites report failure when the compiler does not produce
1934 an error message for a certain program.
1936 @opindex pedantic-errors
1937 ISO C requires a ``diagnostic'' message for certain kinds of invalid
1938 programs, but a warning is defined by GCC to count as a diagnostic. If
1939 GCC produces a warning but not an error, that is correct ISO C support.
1940 If test suites call this ``failure'', they should be run with the GCC
1941 option @option{-pedantic-errors}, which will turn these warnings into
1946 @node Warnings and Errors
1947 @section Warning Messages and Error Messages
1949 @cindex error messages
1950 @cindex warnings vs errors
1951 @cindex messages, warning and error
1952 The GNU compiler can produce two kinds of diagnostics: errors and
1953 warnings. Each kind has a different purpose:
1957 @dfn{Errors} report problems that make it impossible to compile your
1958 program. GCC reports errors with the source file name and line
1959 number where the problem is apparent.
1962 @dfn{Warnings} report other unusual conditions in your code that
1963 @emph{may} indicate a problem, although compilation can (and does)
1964 proceed. Warning messages also report the source file name and line
1965 number, but include the text @samp{warning:} to distinguish them
1966 from error messages.
1969 Warnings may indicate danger points where you should check to make sure
1970 that your program really does what you intend; or the use of obsolete
1971 features; or the use of nonstandard features of GNU C or C++. Many
1972 warnings are issued only if you ask for them, with one of the @option{-W}
1973 options (for instance, @option{-Wall} requests a variety of useful
1977 @opindex pedantic-errors
1978 GCC always tries to compile your program if possible; it never
1979 gratuitously rejects a program whose meaning is clear merely because
1980 (for instance) it fails to conform to a standard. In some cases,
1981 however, the C and C++ standards specify that certain extensions are
1982 forbidden, and a diagnostic @emph{must} be issued by a conforming
1983 compiler. The @option{-pedantic} option tells GCC to issue warnings in
1984 such cases; @option{-pedantic-errors} says to make them errors instead.
1985 This does not mean that @emph{all} non-ISO constructs get warnings
1988 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
1989 more detail on these and related command-line options.
1992 @chapter Reporting Bugs
1994 @cindex reporting bugs
1996 Your bug reports play an essential role in making GCC reliable.
1998 When you encounter a problem, the first thing to do is to see if it is
1999 already known. @xref{Trouble}. If it isn't known, then you should
2002 Reporting a bug may help you by bringing a solution to your problem, or
2003 it may not. (If it does not, look in the service directory; see
2004 @ref{Service}.) In any case, the principal function of a bug report is
2005 to help the entire community by making the next version of GCC work
2006 better. Bug reports are your contribution to the maintenance of GCC@.
2008 Since the maintainers are very overloaded, we cannot respond to every
2009 bug report. However, if the bug has not been fixed, we are likely to
2010 send you a patch and ask you to tell us whether it works.
2012 In order for a bug report to serve its purpose, you must include the
2013 information that makes for fixing the bug.
2016 * Criteria: Bug Criteria. Have you really found a bug?
2017 * Where: Bug Lists. Where to send your bug report.
2018 * Reporting: Bug Reporting. How to report a bug effectively.
2019 * GNATS: gccbug. You can use a bug reporting tool.
2020 * Patches: Sending Patches. How to send a patch for GCC.
2021 * Known: Trouble. Known problems.
2022 * Help: Service. Where to ask for help.
2025 @node Bug Criteria,Bug Lists,,Bugs
2026 @section Have You Found a Bug?
2027 @cindex bug criteria
2029 If you are not sure whether you have found a bug, here are some guidelines:
2032 @cindex fatal signal
2035 If the compiler gets a fatal signal, for any input whatever, that is a
2036 compiler bug. Reliable compilers never crash.
2038 @cindex invalid assembly code
2039 @cindex assembly code, invalid
2041 If the compiler produces invalid assembly code, for any input whatever
2042 (except an @code{asm} statement), that is a compiler bug, unless the
2043 compiler reports errors (not just warnings) which would ordinarily
2044 prevent the assembler from being run.
2046 @cindex undefined behavior
2047 @cindex undefined function value
2048 @cindex increment operators
2050 If the compiler produces valid assembly code that does not correctly
2051 execute the input source code, that is a compiler bug.
2053 However, you must double-check to make sure, because you may have run
2054 into an incompatibility between GNU C and traditional C
2055 (@pxref{Incompatibilities}). These incompatibilities might be considered
2056 bugs, but they are inescapable consequences of valuable features.
2058 Or you may have a program whose behavior is undefined, which happened
2059 by chance to give the desired results with another C or C++ compiler.
2061 For example, in many nonoptimizing compilers, you can write @samp{x;}
2062 at the end of a function instead of @samp{return x;}, with the same
2063 results. But the value of the function is undefined if @code{return}
2064 is omitted; it is not a bug when GCC produces different results.
2066 Problems often result from expressions with two increment operators,
2067 as in @code{f (*p++, *p++)}. Your previous compiler might have
2068 interpreted that expression the way you intended; GCC might
2069 interpret it another way. Neither compiler is wrong. The bug is
2072 After you have localized the error to a single source line, it should
2073 be easy to check for these things. If your program is correct and
2074 well defined, you have found a compiler bug.
2077 If the compiler produces an error message for valid input, that is a
2080 @cindex invalid input
2082 If the compiler does not produce an error message for invalid input,
2083 that is a compiler bug. However, you should note that your idea of
2084 ``invalid input'' might be my idea of ``an extension'' or ``support
2085 for traditional practice''.
2088 If you are an experienced user of one of the languages GCC supports, your
2089 suggestions for improvement of GCC are welcome in any case.
2092 @node Bug Lists,Bug Reporting,Bug Criteria,Bugs
2093 @section Where to Report Bugs
2094 @cindex bug report mailing lists
2095 @kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
2096 Send bug reports for the GNU Compiler Collection to
2097 @email{gcc-bugs@@gcc.gnu.org}. In accordance with the GNU-wide
2098 convention, in which bug reports for tool ``foo'' are sent
2099 to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
2100 may also be used; it will forward to the address given above.
2102 Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or
2103 more up-to-date bug reporting instructions before you post a bug report.
2105 @node Bug Reporting,gccbug,Bug Lists,Bugs
2106 @section How to Report Bugs
2107 @cindex compiler bugs, reporting
2109 The fundamental principle of reporting bugs usefully is this:
2110 @strong{report all the facts}. If you are not sure whether to state a
2111 fact or leave it out, state it!
2113 Often people omit facts because they think they know what causes the
2114 problem and they conclude that some details don't matter. Thus, you might
2115 assume that the name of the variable you use in an example does not matter.
2116 Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
2117 stray memory reference which happens to fetch from the location where that
2118 name is stored in memory; perhaps, if the name were different, the contents
2119 of that location would fool the compiler into doing the right thing despite
2120 the bug. Play it safe and give a specific, complete example. That is the
2121 easiest thing for you to do, and the most helpful.
2123 Keep in mind that the purpose of a bug report is to enable someone to
2124 fix the bug if it is not known. It isn't very important what happens if
2125 the bug is already known. Therefore, always write your bug reports on
2126 the assumption that the bug is not known.
2128 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2129 bell?'' This cannot help us fix a bug, so it is basically useless. We
2130 respond by asking for enough details to enable us to investigate.
2131 You might as well expedite matters by sending them to begin with.
2133 Try to make your bug report self-contained. If we have to ask you for
2134 more information, it is best if you include all the previous information
2135 in your response, as well as the information that was missing.
2137 Please report each bug in a separate message. This makes it easier for
2138 us to track which bugs have been fixed and to forward your bugs reports
2139 to the appropriate maintainer.
2141 To enable someone to investigate the bug, you should include all these
2146 The version of GCC@. You can get this by running it with the
2149 Without this, we won't know whether there is any point in looking for
2150 the bug in the current version of GCC@.
2153 A complete input file that will reproduce the bug. If the bug is in the
2154 C preprocessor, send a source file and any header files that it
2155 requires. If the bug is in the compiler proper (@file{cc1}), send the
2156 preprocessor output generated by adding @option{-save-temps} to the
2157 compilation command (@pxref{Debugging Options}). When you do this, use
2158 the same @option{-I}, @option{-D} or @option{-U} options that you used in
2159 actual compilation. Then send the @var{input}.i or @var{input}.ii files
2162 A single statement is not enough of an example. In order to compile it,
2163 it must be embedded in a complete file of compiler input; and the bug
2164 might depend on the details of how this is done.
2166 Without a real example one can compile, all anyone can do about your bug
2167 report is wish you luck. It would be futile to try to guess how to
2168 provoke the bug. For example, bugs in register allocation and reloading
2169 frequently depend on every little detail of the function they happen in.
2171 Even if the input file that fails comes from a GNU program, you should
2172 still send the complete test case. Don't ask the GCC maintainers to
2173 do the extra work of obtaining the program in question---they are all
2174 overworked as it is. Also, the problem may depend on what is in the
2175 header files on your system; it is unreliable for the GCC maintainers
2176 to try the problem with the header files available to them. By sending
2177 CPP output, you can eliminate this source of uncertainty and save us
2178 a certain percentage of wild goose chases.
2181 The command arguments you gave GCC to compile that example
2182 and observe the bug. For example, did you use @option{-O}? To guarantee
2183 you won't omit something important, list all the options.
2185 If we were to try to guess the arguments, we would probably guess wrong
2186 and then we would not encounter the bug.
2189 The type of machine you are using, and the operating system name and
2193 The operands you gave to the @code{configure} command when you installed
2197 A complete list of any modifications you have made to the compiler
2198 source. (We don't promise to investigate the bug unless it happens in
2199 an unmodified compiler. But if you've made modifications and don't tell
2200 us, then you are sending us on a wild goose chase.)
2202 Be precise about these changes. A description in English is not
2203 enough---send a context diff for them.
2205 Adding files of your own (such as a machine description for a machine we
2206 don't support) is a modification of the compiler source.
2209 Details of any other deviations from the standard procedure for installing
2213 A description of what behavior you observe that you believe is
2214 incorrect. For example, ``The compiler gets a fatal signal,'' or,
2215 ``The assembler instruction at line 208 in the output is incorrect.''
2217 Of course, if the bug is that the compiler gets a fatal signal, then one
2218 can't miss it. But if the bug is incorrect output, the maintainer might
2219 not notice unless it is glaringly wrong. None of us has time to study
2220 all the assembler code from a 50-line C program just on the chance that
2221 one instruction might be wrong. We need @emph{you} to do this part!
2223 Even if the problem you experience is a fatal signal, you should still
2224 say so explicitly. Suppose something strange is going on, such as, your
2225 copy of the compiler is out of synch, or you have encountered a bug in
2226 the C library on your system. (This has happened!) Your copy might
2227 crash and the copy here would not. If you @i{said} to expect a crash,
2228 then when the compiler here fails to crash, we would know that the bug
2229 was not happening. If you don't say to expect a crash, then we would
2230 not know whether the bug was happening. We would not be able to draw
2231 any conclusion from our observations.
2233 If the problem is a diagnostic when compiling GCC with some other
2234 compiler, say whether it is a warning or an error.
2236 Often the observed symptom is incorrect output when your program is run.
2237 Sad to say, this is not enough information unless the program is short
2238 and simple. None of us has time to study a large program to figure out
2239 how it would work if compiled correctly, much less which line of it was
2240 compiled wrong. So you will have to do that. Tell us which source line
2241 it is, and what incorrect result happens when that line is executed. A
2242 person who understands the program can find this as easily as finding a
2243 bug in the program itself.
2246 If you send examples of assembler code output from GCC,
2247 please use @option{-g} when you make them. The debugging information
2248 includes source line numbers which are essential for correlating the
2249 output with the input.
2252 If you wish to mention something in the GCC source, refer to it by
2253 context, not by line number.
2255 The line numbers in the development sources don't match those in your
2256 sources. Your line numbers would convey no useful information to the
2260 Additional information from a debugger might enable someone to find a
2261 problem on a machine which he does not have available. However, you
2262 need to think when you collect this information if you want it to have
2263 any chance of being useful.
2265 @cindex backtrace for bug reports
2266 For example, many people send just a backtrace, but that is never
2267 useful by itself. A simple backtrace with arguments conveys little
2268 about GCC because the compiler is largely data-driven; the same
2269 functions are called over and over for different RTL insns, doing
2270 different things depending on the details of the insn.
2272 Most of the arguments listed in the backtrace are useless because they
2273 are pointers to RTL list structure. The numeric values of the
2274 pointers, which the debugger prints in the backtrace, have no
2275 significance whatever; all that matters is the contents of the objects
2276 they point to (and most of the contents are other such pointers).
2278 In addition, most compiler passes consist of one or more loops that
2279 scan the RTL insn sequence. The most vital piece of information about
2280 such a loop---which insn it has reached---is usually in a local variable,
2284 What you need to provide in addition to a backtrace are the values of
2285 the local variables for several stack frames up. When a local
2286 variable or an argument is an RTX, first print its value and then use
2287 the GDB command @code{pr} to print the RTL expression that it points
2288 to. (If GDB doesn't run on your machine, use your debugger to call
2289 the function @code{debug_rtx} with the RTX as an argument.) In
2290 general, whenever a variable is a pointer, its value is no use
2291 without the data it points to.
2294 Here are some things that are not necessary:
2298 A description of the envelope of the bug.
2300 Often people who encounter a bug spend a lot of time investigating
2301 which changes to the input file will make the bug go away and which
2302 changes will not affect it.
2304 This is often time consuming and not very useful, because the way we
2305 will find the bug is by running a single example under the debugger with
2306 breakpoints, not by pure deduction from a series of examples. You might
2307 as well save your time for something else.
2309 Of course, if you can find a simpler example to report @emph{instead} of
2310 the original one, that is a convenience. Errors in the output will be
2311 easier to spot, running under the debugger will take less time, etc.
2312 Most GCC bugs involve just one function, so the most straightforward
2313 way to simplify an example is to delete all the function definitions
2314 except the one where the bug occurs. Those earlier in the file may be
2315 replaced by external declarations if the crucial function depends on
2316 them. (Exception: inline functions may affect compilation of functions
2317 defined later in the file.)
2319 However, simplification is not vital; if you don't want to do this,
2320 report the bug anyway and send the entire test case you used.
2323 In particular, some people insert conditionals @samp{#ifdef BUG} around
2324 a statement which, if removed, makes the bug not happen. These are just
2325 clutter; we won't pay any attention to them anyway. Besides, you should
2326 send us cpp output, and that can't have conditionals.
2329 A patch for the bug.
2331 A patch for the bug is useful if it is a good one. But don't omit the
2332 necessary information, such as the test case, on the assumption that a
2333 patch is all we need. We might see problems with your patch and decide
2334 to fix the problem another way, or we might not understand it at all.
2336 Sometimes with a program as complicated as GCC it is very hard to
2337 construct an example that will make the program follow a certain path
2338 through the code. If you don't send the example, we won't be able to
2339 construct one, so we won't be able to verify that the bug is fixed.
2341 And if we can't understand what bug you are trying to fix, or why your
2342 patch should be an improvement, we won't install it. A test case will
2343 help us to understand.
2345 @xref{Sending Patches}, for guidelines on how to make it easy for us to
2346 understand and install your patches.
2349 A guess about what the bug is or what it depends on.
2351 Such guesses are usually wrong. Even I can't guess right about such
2352 things without first using the debugger to find the facts.
2357 We have no way of examining a core dump for your type of machine
2358 unless we have an identical system---and if we do have one,
2359 we should be able to reproduce the crash ourselves.
2362 @node gccbug,Sending Patches, Bug Reporting, Bugs
2363 @section The gccbug script
2364 @cindex gccbug script
2366 To simplify creation of bug reports, and to allow better tracking of
2367 reports, we use the GNATS bug tracking system. Part of that system is
2368 the @code{gccbug} script. This is a Unix shell script, so you need a
2369 shell to run it. It is normally installed in the same directory where
2370 @code{gcc} is installed.
2372 The gccbug script is derived from send-pr, @pxref{using
2373 send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
2374 invoked, it starts a text editor so you can fill out the various fields
2375 of the report. When the you quit the editor, the report is automatically
2376 send to the bug reporting address.
2378 A number of fields in this bug report form are specific to GCC, and are
2379 explained at @uref{http://gcc.gnu.org/gnats.html}.
2381 @node Sending Patches,, gccbug, Bugs
2382 @section Sending Patches for GCC
2384 If you would like to write bug fixes or improvements for the GNU C
2385 compiler, that is very helpful. Send suggested fixes to the patches
2386 mailing list, @email{gcc-patches@@gcc.gnu.org}.
2388 Please follow these guidelines so we can study your patches efficiently.
2389 If you don't follow these guidelines, your information might still be
2390 useful, but using it will take extra work. Maintaining GCC is a lot
2391 of work in the best of circumstances, and we can't keep up unless you do
2396 Send an explanation with your changes of what problem they fix or what
2397 improvement they bring about. For a bug fix, just include a copy of the
2398 bug report, and explain why the change fixes the bug.
2400 (Referring to a bug report is not as good as including it, because then
2401 we will have to look it up, and we have probably already deleted it if
2402 we've already fixed the bug.)
2405 Always include a proper bug report for the problem you think you have
2406 fixed. We need to convince ourselves that the change is right before
2407 installing it. Even if it is right, we might have trouble judging it if
2408 we don't have a way to reproduce the problem.
2411 Include all the comments that are appropriate to help people reading the
2412 source in the future understand why this change was needed.
2415 Don't mix together changes made for different reasons.
2416 Send them @emph{individually}.
2418 If you make two changes for separate reasons, then we might not want to
2419 install them both. We might want to install just one. If you send them
2420 all jumbled together in a single set of diffs, we have to do extra work
2421 to disentangle them---to figure out which parts of the change serve
2422 which purpose. If we don't have time for this, we might have to ignore
2423 your changes entirely.
2425 If you send each change as soon as you have written it, with its own
2426 explanation, then the two changes never get tangled up, and we can
2427 consider each one properly without any extra work to disentangle them.
2429 Ideally, each change you send should be impossible to subdivide into
2430 parts that we might want to consider separately, because each of its
2431 parts gets its motivation from the other parts.
2434 Send each change as soon as that change is finished. Sometimes people
2435 think they are helping us by accumulating many changes to send them all
2436 together. As explained above, this is absolutely the worst thing you
2439 Since you should send each change separately, you might as well send it
2440 right away. That gives us the option of installing it immediately if it
2444 Use @samp{diff -c} to make your diffs. Diffs without context are hard
2445 for us to install reliably. More than that, they make it hard for us to
2446 study the diffs to decide whether we want to install them. Unidiff
2447 format is better than contextless diffs, but not as easy to read as
2450 If you have GNU diff, use @samp{diff -cp}, which shows the name of the
2451 function that each change occurs in.
2454 Write the change log entries for your changes. We get lots of changes,
2455 and we don't have time to do all the change log writing ourselves.
2457 Read the @file{ChangeLog} file to see what sorts of information to put
2458 in, and to learn the style that we use. The purpose of the change log
2459 is to show people where to find what was changed. So you need to be
2460 specific about what functions you changed; in large functions, it's
2461 often helpful to indicate where within the function the change was.
2463 On the other hand, once you have shown people where to find the change,
2464 you need not explain its purpose. Thus, if you add a new function, all
2465 you need to say about it is that it is new. If you feel that the
2466 purpose needs explaining, it probably does---but the explanation will be
2467 much more useful if you put it in comments in the code.
2469 If you would like your name to appear in the header line for who made
2470 the change, send us the header line.
2473 When you write the fix, keep in mind that we can't install a change that
2474 would break other systems.
2476 People often suggest fixing a problem by changing machine-independent
2477 files such as @file{toplev.c} to do something special that a particular
2478 system needs. Sometimes it is totally obvious that such changes would
2479 break GCC for almost all users. We can't possibly make a change like
2480 that. At best it might tell us how to write another patch that would
2481 solve the problem acceptably.
2483 Sometimes people send fixes that @emph{might} be an improvement in
2484 general---but it is hard to be sure of this. It's hard to install
2485 such changes because we have to study them very carefully. Of course,
2486 a good explanation of the reasoning by which you concluded the change
2487 was correct can help convince us.
2489 The safest changes are changes to the configuration files for a
2490 particular machine. These are safe because they can't create new bugs
2493 Please help us keep up with the workload by designing the patch in a
2494 form that is good to install.
2498 @chapter How To Get Help with GCC
2500 If you need help installing, using or changing GCC, there are two
2505 Send a message to a suitable network mailing list. First try
2506 @email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
2507 that brings no response, try @email{gcc@@gcc.gnu.org}. For help
2508 changing GCC, ask @email{gcc@@gcc.gnu.org}. If you think you have found
2509 a bug in GCC, please report it following the instructions at
2510 @pxref{Bug Reporting}.
2513 Look in the service directory for someone who might help you for a fee.
2514 The service directory is found at
2515 @uref{http://www.gnu.org/prep/service.html}.
2518 @c For further information, see
2519 @c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}.
2520 @c FIXME: this URL may be too volatile, this FAQ entry needs to move to
2521 @c the regular web pages before we can uncomment the reference.
2524 @chapter Contributing to GCC Development
2526 If you would like to help pretest GCC releases to assure they work well,
2527 our current development sources are available by CVS (see
2528 @uref{http://gcc.gnu.org/cvs.html}). Source and binary snapshots are
2529 also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
2531 If you would like to work on improvements to GCC, please read
2532 @uref{http://gcc.gnu.org/contribute.html} and
2533 @uref{http://gcc.gnu.org/contributewhy.html} for information on how to
2534 make useful contributions and avoid duplication of effort. Suggested
2535 projects are listed at @uref{http://gcc.gnu.org/projects/}.
2538 @chapter Using GCC on VMS
2540 @c prevent bad page break with this line
2541 Here is how to use GCC on VMS@.
2544 * Include Files and VMS:: Where the preprocessor looks for the include files.
2545 * Global Declarations:: How to do globaldef, globalref and globalvalue with
2547 * VMS Misc:: Misc information.
2550 @node Include Files and VMS
2551 @section Include Files and VMS
2553 @cindex include files and VMS
2554 @cindex VMS and include files
2555 @cindex header files and VMS
2556 Due to the differences between the filesystems of Unix and VMS, GCC
2557 attempts to translate file names in @samp{#include} into names that VMS
2558 will understand. The basic strategy is to prepend a prefix to the
2559 specification of the include file, convert the whole filename to a VMS
2560 filename, and then try to open the file. GCC tries various prefixes
2561 one by one until one of them succeeds:
2565 The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
2566 where GNU C header files are traditionally stored. If you wish to store
2567 header files in non-standard locations, then you can assign the logical
2568 @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
2569 list is suitable for use with a rooted logical.
2572 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where
2573 VAX-C header files are traditionally stored.
2576 If the include file specification by itself is a valid VMS filename, the
2577 preprocessor then uses this name with no prefix in an attempt to open
2581 If the file specification is not a valid VMS filename (i.e.@: does not
2582 contain a device or a directory specifier, and contains a @samp{/}
2583 character), the preprocessor tries to convert it from Unix syntax to
2586 Conversion works like this: the first directory name becomes a device,
2587 and the rest of the directories are converted into VMS-format directory
2588 names. For example, the name @file{X11/foobar.h} is
2589 translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
2590 whichever one can be opened. This strategy allows you to assign a
2591 logical name to point to the actual location of the header files.
2594 If none of these strategies succeeds, the @samp{#include} fails.
2597 Include directives of the form:
2604 are a common source of incompatibility between VAX-C and GCC@. VAX-C
2605 treats this much like a standard @code{#include <foobar.h>} directive.
2606 That is incompatible with the ISO C behavior implemented by GCC: to
2607 expand the name @code{foobar} as a macro. Macro expansion should
2608 eventually yield one of the two standard formats for @code{#include}:
2611 #include "@var{file}"
2612 #include <@var{file}>
2615 If you have this problem, the best solution is to modify the source to
2616 convert the @code{#include} directives to one of the two standard forms.
2617 That will work with either compiler. If you want a quick and dirty fix,
2618 define the file names as macros with the proper expansion, like this:
2621 #define stdio <stdio.h>
2625 This will work, as long as the name doesn't conflict with anything else
2628 Another source of incompatibility is that VAX-C assumes that:
2635 is actually asking for the file @file{foobar.h}. GCC does not
2636 make this assumption, and instead takes what you ask for literally;
2637 it tries to read the file @file{foobar}. The best way to avoid this
2638 problem is to always specify the desired file extension in your include
2641 GCC for VMS is distributed with a set of include files that is
2642 sufficient to compile most general purpose programs. Even though the
2643 GCC distribution does not contain header files to define constants
2644 and structures for some VMS system-specific functions, there is no
2645 reason why you cannot use GCC with any of these functions. You first
2646 may have to generate or create header files, either by using the public
2647 domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
2648 extracting the relevant modules from one of the system macro libraries,
2649 and using an editor to construct a C header file.
2651 A @code{#include} file name cannot contain a DECNET node name. The
2652 preprocessor reports an I/O error if you attempt to use a node name,
2653 whether explicitly, or implicitly via a logical name.
2655 @node Global Declarations
2656 @section Global Declarations and VMS
2660 @findex GLOBALVALUEDEF
2661 @findex GLOBALVALUEREF
2662 GCC does not provide the @code{globalref}, @code{globaldef} and
2663 @code{globalvalue} keywords of VAX-C@. You can get the same effect with
2664 an obscure feature of GAS, the GNU assembler. (This requires GAS
2665 version 1.39 or later.) The following macros allow you to use this
2666 feature in a fairly natural way:
2670 #define GLOBALREF(TYPE,NAME) \
2672 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
2673 #define GLOBALDEF(TYPE,NAME,VALUE) \
2675 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
2677 #define GLOBALVALUEREF(TYPE,NAME) \
2678 const TYPE NAME[1] \
2679 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
2680 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2681 const TYPE NAME[1] \
2682 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \
2685 #define GLOBALREF(TYPE,NAME) \
2687 #define GLOBALDEF(TYPE,NAME,VALUE) \
2688 globaldef TYPE NAME = VALUE
2689 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2690 globalvalue TYPE NAME = VALUE
2691 #define GLOBALVALUEREF(TYPE,NAME) \
2692 globalvalue TYPE NAME
2697 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
2698 name is removed by the assembler, after it has modified the attributes
2699 of the symbol). These macros are provided in the VMS binaries
2700 distribution in a header file @file{GNU_HACKS.H}. An example of the
2704 GLOBALREF (int, ijk);
2705 GLOBALDEF (int, jkl, 0);
2708 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
2709 straightforwardly for arrays, since there is no way to insert the array
2710 dimension into the declaration at the right place. However, you can
2711 declare an array with these macros if you first define a typedef for the
2712 array type, like this:
2715 typedef int intvector[10];
2716 GLOBALREF (intvector, foo);
2719 Array and structure initializers will also break the macros; you can
2720 define the initializer to be a macro of its own, or you can expand the
2721 @code{GLOBALDEF} macro by hand. You may find a case where you wish to
2722 use the @code{GLOBALDEF} macro with a large array, but you are not
2723 interested in explicitly initializing each element of the array. In
2724 such cases you can use an initializer like: @code{@{0,@}}, which will
2725 initialize the entire array to @code{0}.
2727 A shortcoming of this implementation is that a variable declared with
2728 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For
2729 example, the declaration:
2732 GLOBALVALUEREF(int, ijk);
2736 declares the variable @code{ijk} as an array of type @code{int [1]}.
2737 This is done because a globalvalue is actually a constant; its ``value''
2738 is what the linker would normally consider an address. That is not how
2739 an integer value works in C, but it is how an array works. So treating
2740 the symbol as an array name gives consistent results---with the
2741 exception that the value seems to have the wrong type. @strong{Don't
2742 try to access an element of the array.} It doesn't have any elements.
2743 The array ``address'' may not be the address of actual storage.
2745 The fact that the symbol is an array may lead to warnings where the
2746 variable is used. Insert type casts to avoid the warnings. Here is an
2747 example; it takes advantage of the ISO C feature allowing macros that
2748 expand to use the same name as the macro itself.
2751 GLOBALVALUEREF (int, ss$_normal);
2752 GLOBALVALUEDEF (int, xyzzy,123);
2754 #define ss$_normal ((int) ss$_normal)
2755 #define xyzzy ((int) xyzzy)
2759 Don't use @code{globaldef} or @code{globalref} with a variable whose
2760 type is an enumeration type; this is not implemented. Instead, make the
2761 variable an integer, and use a @code{globalvaluedef} for each of the
2762 enumeration values. An example of this would be:
2766 GLOBALDEF (int, color, 0);
2767 GLOBALVALUEDEF (int, RED, 0);
2768 GLOBALVALUEDEF (int, BLUE, 1);
2769 GLOBALVALUEDEF (int, GREEN, 3);
2771 enum globaldef color @{RED, BLUE, GREEN = 3@};
2776 @section Other VMS Issues
2778 @cindex exit status and VMS
2779 @cindex return value of @code{main}
2780 @cindex @code{main} and the exit status
2781 GCC automatically arranges for @code{main} to return 1 by default if
2782 you fail to specify an explicit return value. This will be interpreted
2783 by VMS as a status code indicating a normal successful completion.
2784 Version 1 of GCC did not provide this default.
2786 GCC on VMS works only with the GNU assembler, GAS@. You need version
2787 1.37 or later of GAS in order to produce value debugging information for
2788 the VMS debugger. Use the ordinary VMS linker with the object files
2791 @cindex shared VMS run time system
2792 @cindex @file{VAXCRTL}
2793 Under previous versions of GCC, the generated code would occasionally
2794 give strange results when linked to the sharable @file{VAXCRTL} library.
2795 Now this should work.
2797 A caveat for use of @code{const} global variables: the @code{const}
2798 modifier must be specified in every external declaration of the variable
2799 in all of the source files that use that variable. Otherwise the linker
2800 will issue warnings about conflicting attributes for the variable. Your
2801 program will still work despite the warnings, but the variable will be
2802 placed in writable storage.
2804 @cindex name augmentation
2805 @cindex case sensitivity and VMS
2806 @cindex VMS and case sensitivity
2807 Although the VMS linker does distinguish between upper and lower case
2808 letters in global symbols, most VMS compilers convert all such symbols
2809 into upper case and most run-time library routines also have upper case
2810 names. To be able to reliably call such routines, GCC (by means of
2811 the assembler GAS) converts global symbols into upper case like other
2812 VMS compilers. However, since the usual practice in C is to distinguish
2813 case, GCC (via GAS) tries to preserve usual C behavior by augmenting
2814 each name that is not all lower case. This means truncating the name
2815 to at most 23 characters and then adding more characters at the end
2816 which encode the case pattern of those 23. Names which contain at
2817 least one dollar sign are an exception; they are converted directly into
2818 upper case without augmentation.
2820 Name augmentation yields bad results for programs that use precompiled
2821 libraries (such as Xlib) which were generated by another compiler. You
2822 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
2823 it makes external C functions and variables case-independent as is usual
2824 on VMS@. Alternatively, you could write all references to the functions
2825 and variables in such libraries using lower case; this will work on VMS,
2826 but is not portable to other systems. The compiler option @samp{/NAMES}
2827 also provides control over global name handling.
2829 Function and variable names are handled somewhat differently with G++.
2830 The GNU C++ compiler performs @dfn{name mangling} on function
2831 names, which means that it adds information to the function name to
2832 describe the data types of the arguments that the function takes. One
2833 result of this is that the name of a function can become very long.
2834 Since the VMS linker only recognizes the first 31 characters in a name,
2835 special action is taken to ensure that each function and variable has a
2836 unique name that can be represented in 31 characters.
2838 If the name (plus a name augmentation, if required) is less than 32
2839 characters in length, then no special action is performed. If the name
2840 is longer than 31 characters, the assembler (GAS) will generate a
2841 hash string based upon the function name, truncate the function name to
2842 23 characters, and append the hash string to the truncated name. If the
2843 @samp{/VERBOSE} compiler option is used, the assembler will print both
2844 the full and truncated names of each symbol that is truncated.
2846 The @samp{/NOCASE_HACK} compiler option should not be used when you are
2847 compiling programs that use libg++. libg++ has several instances of
2848 objects (i.e. @code{Filebuf} and @code{filebuf}) which become
2849 indistinguishable in a case-insensitive environment. This leads to
2850 cases where you need to inhibit augmentation selectively (if you were
2851 using libg++ and Xlib in the same program, for example). There is no
2852 special feature for doing this, but you can get the result by defining a
2853 macro for each mixed case symbol for which you wish to inhibit
2854 augmentation. The macro should expand into the lower case equivalent of
2855 itself. For example:
2858 #define StuDlyCapS studlycaps
2861 These macro definitions can be placed in a header file to minimize the
2862 number of changes to your source code.
2865 @chapter Makefile Targets
2866 @cindex makefile targets
2867 @cindex targets, makefile
2871 This is the default target. Depending on what your build/host/target
2872 configuration is, it coordinates all the things that need to be built.
2875 Produce info-formatted documentation. Also, @code{make dvi} is
2876 available for DVI-formatted documentation, and @code{make
2877 generated-manpages} to generate man pages.
2880 Delete the files made while building the compiler.
2883 That, and all the other files built by @code{make all}.
2886 That, and all the files created by @code{configure}.
2889 That, and any temporary or intermediate files, like emacs backup files.
2891 @item maintainer-clean
2892 Distclean plus any file that can be generated from other files. Note
2893 that additional tools may be required beyond what is normally needed to
2900 Deletes installed files.
2903 Run the testsuite. This creates a @file{testsuite} subdirectory that
2904 has various @file{.sum} and @file{.log} files containing the results of
2905 the testing. You can run subsets with, for example, @code{make check-gcc}.
2906 You can specify specific tests by setting RUNTESTFLAGS to be the name
2907 of the @file{.exp} file, optionally followed by (for some tests) an equals
2908 and a file wildcard, like:
2911 make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
2914 Note that running the testsuite may require additional tools be
2915 installed, such as TCL or dejagnu.
2918 Builds gcc three times---once with the native compiler, once with the
2919 native-built compiler it just built, and once with the compiler it built
2920 the second time. In theory, the last two should produce the same
2921 results, which @code{make compare} can check. Each step of this process
2922 is called a ``stage'', and the results of each stage @var{N}
2923 (@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}.
2925 @item bootstrap-lean
2926 Like @code{bootstrap}, except that the various stages are removed once
2927 they're no longer needed. This saves disk space.
2930 Once bootstrapped, this incrementally rebuilds each of the three stages,
2931 one at a time. It does this by ``bubbling'' the stages up from their
2932 subdirectories, rebuilding them, and copying them back to their
2933 subdirectories. This will allow you to, for example, quickly rebuild a
2934 bootstrapped compiler after changing the sources, without having to do a
2938 Rebuilds the most recently built stage. Since each stage requires
2939 special invocation, using this target means you don't have to keep track
2940 of which stage you're on or what invocation that stage needs.
2943 Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}).
2945 @item stage@var{N} (@var{N} = 1@dots{}4)
2946 For each stage, moves the appropriate files to the @file{stage@var{N}}
2949 @item unstage@var{N} (@var{N} = 1@dots{}4)
2950 Undoes the corresponding @code{stage@var{N}}.
2952 @item restage@var{N} (@var{N} = 1@dots{}4)
2953 Undoes the corresponding @code{stage@var{N}} and rebuilds it with the
2957 Compares the results of stages 2 and 3. This ensures that the compiler
2958 is running properly, since it should produce the same object files
2959 regardless of how it itself was compiled.
2967 @chapter GCC and Portability
2969 @cindex GCC and portability
2971 The main goal of GCC was to make a good, fast compiler for machines in
2972 the class that the GNU system aims to run on: 32-bit machines that address
2973 8-bit bytes and have several general registers. Elegance, theoretical
2974 power and simplicity are only secondary.
2976 GCC gets most of the information about the target machine from a machine
2977 description which gives an algebraic formula for each of the machine's
2978 instructions. This is a very clean way to describe the target. But when
2979 the compiler needs information that is difficult to express in this
2980 fashion, I have not hesitated to define an ad-hoc parameter to the machine
2981 description. The purpose of portability is to reduce the total work needed
2982 on the compiler; it was not of interest for its own sake.
2985 @cindex autoincrement addressing, availability
2987 GCC does not contain machine dependent code, but it does contain code
2988 that depends on machine parameters such as endianness (whether the most
2989 significant byte has the highest or lowest address of the bytes in a word)
2990 and the availability of autoincrement addressing. In the RTL-generation
2991 pass, it is often necessary to have multiple strategies for generating code
2992 for a particular kind of syntax tree, strategies that are usable for different
2993 combinations of parameters. Often I have not tried to address all possible
2994 cases, but only the common ones or only the ones that I have encountered.
2995 As a result, a new target may require additional strategies. You will know
2996 if this happens because the compiler will call @code{abort}. Fortunately,
2997 the new strategies can be added in a machine-independent fashion, and will
2998 affect only the target machines that need them.
3003 @chapter Interfacing to GCC Output
3004 @cindex interfacing to GCC output
3005 @cindex run-time conventions
3006 @cindex function call conventions
3007 @cindex conventions, run-time
3009 GCC is normally configured to use the same function calling convention
3010 normally in use on the target system. This is done with the
3011 machine-description macros described (@pxref{Target Macros}).
3013 @cindex unions, returning
3014 @cindex structures, returning
3015 @cindex returning structures and unions
3016 However, returning of structure and union values is done differently on
3017 some target machines. As a result, functions compiled with PCC
3018 returning such types cannot be called from code compiled with GCC,
3019 and vice versa. This does not cause trouble often because few Unix
3020 library routines return structures or unions.
3022 GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
3023 long in the same registers used for @code{int} or @code{double} return
3024 values. (GCC typically allocates variables of such types in
3025 registers also.) Structures and unions of other sizes are returned by
3026 storing them into an address passed by the caller (usually in a
3027 register). The machine-description macros @code{STRUCT_VALUE} and
3028 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
3030 By contrast, PCC on most target machines returns structures and unions
3031 of any size by copying the data into an area of static storage, and then
3032 returning the address of that storage as if it were a pointer value.
3033 The caller must copy the data from that memory area to the place where
3034 the value is wanted. This is slower than the method used by GCC, and
3035 fails to be reentrant.
3037 On some target machines, such as RISC machines and the 80386, the
3038 standard system convention is to pass to the subroutine the address of
3039 where to return the value. On these machines, GCC has been
3040 configured to be compatible with the standard compiler, when this method
3041 is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3043 @cindex argument passing
3044 @cindex passing arguments
3045 GCC uses the system's standard convention for passing arguments. On
3046 some machines, the first few arguments are passed in registers; in
3047 others, all are passed on the stack. It would be possible to use
3048 registers for argument passing on any machine, and this would probably
3049 result in a significant speedup. But the result would be complete
3050 incompatibility with code that follows the standard convention. So this
3051 change is practical only if you are switching to GCC as the sole C
3052 compiler for the system. We may implement register argument passing on
3053 certain machines once we have a complete GNU system so that we can
3054 compile the libraries with GCC@.
3056 On some machines (particularly the Sparc), certain types of arguments
3057 are passed ``by invisible reference''. This means that the value is
3058 stored in memory, and the address of the memory location is passed to
3061 @cindex @code{longjmp} and automatic variables
3062 If you use @code{longjmp}, beware of automatic variables. ISO C says that
3063 automatic variables that are not declared @code{volatile} have undefined
3064 values after a @code{longjmp}. And this is all GCC promises to do,
3065 because it is very difficult to restore register variables correctly, and
3066 one of GCC's features is that it can put variables in registers without
3069 If you want a variable to be unaltered by @code{longjmp}, and you don't
3070 want to write @code{volatile} because old C compilers don't accept it,
3071 just take the address of the variable. If a variable's address is ever
3072 taken, even if just to compute it and ignore it, then the variable cannot
3083 @cindex arithmetic libraries
3084 @cindex math libraries
3085 @opindex msoft-float
3086 Code compiled with GCC may call certain library routines. Most of
3087 them handle arithmetic for which there are no instructions. This
3088 includes multiply and divide on some machines, and floating point
3089 operations on any machine for which floating point support is disabled
3090 with @option{-msoft-float}. Some standard parts of the C library, such as
3091 @code{bcopy} or @code{memcpy}, are also called automatically. The usual
3092 function call interface is used for calling the library routines.
3094 Some of these routines can be defined in mostly machine-independent C;
3095 they appear in @file{libgcc2.c}. Others must be hand-written in
3096 assembly language for each processor. Wherever they are defined, they
3097 are compiled into the support library, @file{libgcc.a}, which is
3098 automatically searched when you link programs with GCC@.
3103 @chapter Passes and Files of the Compiler
3104 @cindex passes and files of the compiler
3105 @cindex files and passes of the compiler
3106 @cindex compiler passes and files
3108 @cindex top level of compiler
3109 The overall control structure of the compiler is in @file{toplev.c}. This
3110 file is responsible for initialization, decoding arguments, opening and
3111 closing files, and sequencing the passes.
3113 @cindex parsing pass
3114 The parsing pass is invoked only once, to parse the entire input. A
3115 high level tree representation is then generated from the input,
3116 one function at a time. This tree code is then transformed into RTL
3117 intermediate code, and processed. The files involved in transforming
3118 the trees into RTL are @file{expr.c}, @file{expmed.c}, and
3120 @c Note, the above files aren't strictly the only files involved. It's
3121 @c all over the place (function.c, final.c,etc). However, those are
3122 @c the files that are supposed to be directly involved, and have
3123 @c their purpose listed as such, so i've only listed them.
3124 The order of trees that are processed, is not
3125 necessarily the same order they are generated from
3126 the input, due to deferred inlining, and other considerations.
3128 @findex rest_of_compilation
3129 @findex rest_of_decl_compilation
3130 Each time the parsing pass reads a complete function definition or
3131 top-level declaration, it calls either the function
3132 @code{rest_of_compilation}, or the function
3133 @code{rest_of_decl_compilation} in @file{toplev.c}, which are
3134 responsible for all further processing necessary, ending with output of
3135 the assembler language. All other compiler passes run, in sequence,
3136 within @code{rest_of_compilation}. When that function returns from
3137 compiling a function definition, the storage used for that function
3138 definition's compilation is entirely freed, unless it is an inline
3139 function, or was deferred for some reason (this can occur in
3140 templates, for example).
3142 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3145 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3148 Here is a list of all the passes of the compiler and their source files.
3149 Also included is a description of where debugging dumps can be requested
3150 with @option{-d} options.
3154 Parsing. This pass reads the entire text of a function definition,
3155 constructing a high level tree representation. (Because of the semantic
3156 analysis that takes place during this pass, it does more than is
3157 formally considered to be parsing.)
3159 The tree representation does not entirely follow C syntax, because it is
3160 intended to support other languages as well.
3162 Language-specific data type analysis is also done in this pass, and every
3163 tree node that represents an expression has a data type attached.
3164 Variables are represented as declaration nodes.
3166 The language-independent source files for parsing are
3167 @file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}.
3168 There are also header files @file{tree.h} and @file{tree.def}
3169 which define the format of the tree representation.
3171 C Preprocessing, for language front ends, that want or require it, is
3172 performed by cpplib, which is covered in seperate documentation. In
3173 particular, the internals are covered in @xref{Top, ,Cpplib internals, cppinternals, Cpplib Internals}.
3176 @c Avoiding overfull is tricky here.
3177 The source files to parse C are
3178 @file{c-aux-info.c},
3186 along with a header file
3188 and some files shared with Objective-C and C++.
3190 The source files for parsing C++ are in @file{cp/}.
3191 They are @file{parse.y},
3193 @file{cvt.c}, @file{decl.c}, @file{decl2.c},
3195 @file{expr.c}, @file{init.c}, @file{lex.c},
3196 @file{method.c}, @file{ptree.c},
3197 @file{search.c}, @file{spew.c},
3198 @file{semantics.c}, @file{tree.c},
3199 @file{typeck2.c}, and
3200 @file{typeck.c}, along with header files @file{cp-tree.def},
3201 @file{cp-tree.h}, and @file{decl.h}.
3203 The special source files for parsing Objective-C are in @file{objc/}.
3204 They are @file{objc-parse.y}, @file{objc-act.c}, @file{objc-tree.def}, and
3205 @file{objc-act.h}. Certain C-specific files are used for this as
3210 @file{c-common.def},
3216 @file{c-semantics.c},
3217 along with header files
3223 are also used for all of the above languages.
3226 @cindex Tree optimization
3228 Tree optimization. This is the optimization of the tree
3229 representation, before converting into RTL code.
3231 @cindex inline on trees, automatic
3232 Currently, the main optimization performed here is tree-based
3234 This is implemented for C++ in @file{cp/optimize.c}. Note that
3235 tree based inlining turns off rtx based inlining (since it's more
3236 powerful, it would be a waste of time to do rtx based inlining in
3238 The C front end currently does not perform tree based inlining.
3240 @cindex constant folding
3241 @cindex arithmetic simplifications
3242 @cindex simplifications, arithmetic
3243 Constant folding and some arithmetic simplifications are also done
3244 during this pass, on the tree representation.
3245 The routines that perform these tasks are located in @file{fold-const.c}.
3247 @cindex RTL generation
3249 RTL generation. This is the conversion of syntax tree into RTL code.
3251 @cindex target-parameter-dependent code
3252 This is where the bulk of target-parameter-dependent code is found,
3253 since often it is necessary for strategies to apply only when certain
3254 standard kinds of instructions are available. The purpose of named
3255 instruction patterns is to provide this information to the RTL
3258 @cindex tail recursion optimization
3259 Optimization is done in this pass for @code{if}-conditions that are
3260 comparisons, boolean operations or conditional expressions. Tail
3261 recursion is detected at this time also. Decisions are made about how
3262 best to arrange loops and how to output @code{switch} statements.
3264 @c Avoiding overfull is tricky here.
3265 The source files for RTL generation include
3273 and @file{emit-rtl.c}.
3275 @file{insn-emit.c}, generated from the machine description by the
3276 program @code{genemit}, is used in this pass. The header file
3277 @file{expr.h} is used for communication within this pass.
3281 The header files @file{insn-flags.h} and @file{insn-codes.h},
3282 generated from the machine description by the programs @code{genflags}
3283 and @code{gencodes}, tell this pass which standard names are available
3284 for use and which patterns correspond to them.
3286 Aside from debugging information output, none of the following passes
3287 refers to the tree structure representation of the function (only
3288 part of which is saved).
3290 @cindex inline on rtx, automatic
3291 The decision of whether the function can and should be expanded inline
3292 in its subsequent callers is made at the end of rtl generation. The
3293 function must meet certain criteria, currently related to the size of
3294 the function and the types and number of parameters it has. Note that
3295 this function may contain loops, recursive calls to itself
3296 (tail-recursive functions can be inlined!), gotos, in short, all
3297 constructs supported by GCC@. The file @file{integrate.c} contains
3298 the code to save a function's rtl for later inlining and to inline that
3299 rtl when the function is called. The header file @file{integrate.h}
3300 is also used for this purpose.
3303 The option @option{-dr} causes a debugging dump of the RTL code after
3304 this pass. This dump file's name is made by appending @samp{.rtl} to
3305 the input file name.
3307 @c Should the exception handling pass be talked about here?
3309 @cindex sibling call optimization
3311 Sibiling call optimization. This pass performs tail recursion
3312 elimination, and tail and sibling call optimizations. The purpose of
3313 these optimizations is to reduce the overhead of function calls,
3316 The source file of this pass is @file{sibcall.c}
3319 The option @option{-di} causes a debugging dump of the RTL code after
3320 this pass is run. This dump file's name is made by appending
3321 @samp{.sibling} to the input file name.
3323 @cindex jump optimization
3324 @cindex unreachable code
3327 Jump optimization. This pass simplifies jumps to the following
3328 instruction, jumps across jumps, and jumps to jumps. It deletes
3329 unreferenced labels and unreachable code, except that unreachable code
3330 that contains a loop is not recognized as unreachable in this pass.
3331 (Such loops are deleted later in the basic block analysis.) It also
3332 converts some code originally written with jumps into sequences of
3333 instructions that directly set values from the results of comparisons,
3334 if the machine has such instructions.
3336 Jump optimization is performed two or three times. The first time is
3337 immediately following RTL generation. The second time is after CSE,
3338 but only if CSE says repeated jump optimization is needed. The
3339 last time is right before the final pass. That time, cross-jumping
3340 and deletion of no-op move instructions are done together with the
3341 optimizations described above.
3343 The source file of this pass is @file{jump.c}.
3346 The option @option{-dj} causes a debugging dump of the RTL code after
3347 this pass is run for the first time. This dump file's name is made by
3348 appending @samp{.jump} to the input file name.
3351 @cindex register use analysis
3353 Register scan. This pass finds the first and last use of each
3354 register, as a guide for common subexpression elimination. Its source
3355 is in @file{regclass.c}.
3357 @cindex jump threading
3359 @opindex fthread-jumps
3360 Jump threading. This pass detects a condition jump that branches to an
3361 identical or inverse test. Such jumps can be @samp{threaded} through
3362 the second conditional test. The source code for this pass is in
3363 @file{jump.c}. This optimization is only performed if
3364 @option{-fthread-jumps} is enabled.
3366 @cindex SSA optimizations
3367 @cindex Single Static Assignment optimizations
3370 Static Single Assignment (SSA) based optimization passes. The
3371 SSA conversion passes (to/from) are turned on by the @option{-fssa}
3372 option (it is also done automatically if you enable an SSA optimization pass).
3373 These passes utilize a form called Static Single Assignment. In SSA form,
3374 each variable (pseudo register) is only set once, giving you def-use
3375 and use-def chains for free, and enabling a lot more optimization
3376 passes to be run in linear time.
3377 Conversion to and from SSA form is handled by functions in
3381 The option @option{-de} causes a debugging dump of the RTL code after
3382 this pass. This dump file's name is made by appending @samp{.ssa} to
3383 the input file name.
3386 @cindex DCE, SSA based
3387 @cindex dead code elimination
3390 SSA Aggressive Dead Code Elimination. Turned on by the @option{-fssa-dce}
3391 option. This pass performs elimination of code considered unnecessary because
3392 it has no externally visible effects on the program. It operates in
3396 The option @option{-dX} causes a debugging dump of the RTL code after
3397 this pass. This dump file's name is made by appending @samp{.ssadce} to
3398 the input file name.
3401 @cindex common subexpression elimination
3402 @cindex constant propagation
3404 Common subexpression elimination. This pass also does constant
3405 propagation. Its source files are @file{cse.c}, and @file{cselib.c}.
3406 If constant propagation causes conditional jumps to become
3407 unconditional or to become no-ops, jump optimization is run again when
3411 The option @option{-ds} causes a debugging dump of the RTL code after
3412 this pass. This dump file's name is made by appending @samp{.cse} to
3413 the input file name.
3415 @cindex global common subexpression elimination
3416 @cindex constant propagation
3417 @cindex copy propagation
3419 Global common subexpression elimination. This pass performs two
3420 different types of GCSE depending on whether you are optimizing for
3421 size or not (LCM based GCSE tends to increase code size for a gain in
3422 speed, while Morel-Renvoise based GCSE does not).
3423 When optimizing for size, GCSE is done using Morel-Renvoise Partial
3424 Redundancy Elimination, with the exception that it does not try to move
3425 invariants out of loops---that is left to the loop optimization pass.
3426 If MR PRE GCSE is done, code hoisting (aka unification) is also done, as
3427 well as load motion.
3428 If you are optimizing for speed, LCM (lazy code motion) based GCSE is
3429 done. LCM is based on the work of Knoop, Ruthing, and Steffen. LCM
3430 based GCSE also does loop invariant code motion. We also perform load
3431 and store motion when optimizing for speed.
3432 Regardless of which type of GCSE is used, the GCSE pass also performs
3433 global constant and copy propagation.
3435 The source file for this pass is @file{gcse.c}, and the LCM routines
3436 are in @file{lcm.c}.
3439 The option @option{-dG} causes a debugging dump of the RTL code after
3440 this pass. This dump file's name is made by appending @samp{.gcse} to
3441 the input file name.
3443 @cindex loop optimization
3445 @cindex strength-reduction
3447 Loop optimization. This pass moves constant expressions out of loops,
3448 and optionally does strength-reduction and loop unrolling as well.
3449 Its source files are @file{loop.c} and @file{unroll.c}, plus the header
3450 @file{loop.h} used for communication between them. Loop unrolling uses
3451 some functions in @file{integrate.c} and the header @file{integrate.h}.
3452 Loop dependency analysis routines are contained in @file{dependence.c}.
3455 The option @option{-dL} causes a debugging dump of the RTL code after
3456 this pass. This dump file's name is made by appending @samp{.loop} to
3457 the input file name.
3460 @opindex frerun-cse-after-loop
3461 If @option{-frerun-cse-after-loop} was enabled, a second common
3462 subexpression elimination pass is performed after the loop optimization
3463 pass. Jump threading is also done again at this time if it was specified.
3466 The option @option{-dt} causes a debugging dump of the RTL code after
3467 this pass. This dump file's name is made by appending @samp{.cse2} to
3468 the input file name.
3470 @cindex data flow analysis
3471 @cindex analysis, data flow
3472 @cindex basic blocks
3474 Data flow analysis (@file{flow.c}). This pass divides the program
3475 into basic blocks (and in the process deletes unreachable loops); then
3476 it computes which pseudo-registers are live at each point in the
3477 program, and makes the first instruction that uses a value point at
3478 the instruction that computed the value.
3480 @cindex autoincrement/decrement analysis
3481 This pass also deletes computations whose results are never used, and
3482 combines memory references with add or subtract instructions to make
3483 autoincrement or autodecrement addressing.
3486 The option @option{-df} causes a debugging dump of the RTL code after
3487 this pass. This dump file's name is made by appending @samp{.flow} to
3488 the input file name. If stupid register allocation is in use, this
3489 dump file reflects the full results of such allocation.
3491 @cindex instruction combination
3493 Instruction combination (@file{combine.c}). This pass attempts to
3494 combine groups of two or three instructions that are related by data
3495 flow into single instructions. It combines the RTL expressions for
3496 the instructions by substitution, simplifies the result using algebra,
3497 and then attempts to match the result against the machine description.
3500 The option @option{-dc} causes a debugging dump of the RTL code after
3501 this pass. This dump file's name is made by appending @samp{.combine}
3502 to the input file name.
3504 @cindex if conversion
3506 If-conversion is a transformation that transforms control dependencies
3507 into data dependencies (IE it transforms conditional code into a
3508 single control stream).
3509 It is implemented in the file @file{ifcvt.c}.
3512 The option @option{-dE} causes a debugging dump of the RTL code after
3513 this pass. This dump file's name is made by appending @samp{.ce} to
3514 the input file name.
3516 @cindex register movement
3518 Register movement (@file{regmove.c}). This pass looks for cases where
3519 matching constraints would force an instruction to need a reload, and
3520 this reload would be a register to register move. It then attempts
3521 to change the registers used by the instruction to avoid the move
3525 The option @option{-dN} causes a debugging dump of the RTL code after
3526 this pass. This dump file's name is made by appending @samp{.regmove}
3527 to the input file name.
3529 @cindex instruction scheduling
3530 @cindex scheduling, instruction
3532 Instruction scheduling (@file{sched.c}). This pass looks for
3533 instructions whose output will not be available by the time that it is
3534 used in subsequent instructions. (Memory loads and floating point
3535 instructions often have this behavior on RISC machines). It re-orders
3536 instructions within a basic block to try to separate the definition and
3537 use of items that otherwise would cause pipeline stalls.
3539 Instruction scheduling is performed twice. The first time is immediately
3540 after instruction combination and the second is immediately after reload.
3543 The option @option{-dS} causes a debugging dump of the RTL code after this
3544 pass is run for the first time. The dump file's name is made by
3545 appending @samp{.sched} to the input file name.
3547 @cindex register class preference pass
3549 Register class preferencing. The RTL code is scanned to find out
3550 which register class is best for each pseudo register. The source
3551 file is @file{regclass.c}.
3553 @cindex register allocation
3554 @cindex local register allocation
3556 Local register allocation (@file{local-alloc.c}). This pass allocates
3557 hard registers to pseudo registers that are used only within one basic
3558 block. Because the basic block is linear, it can use fast and
3559 powerful techniques to do a very good job.
3562 The option @option{-dl} causes a debugging dump of the RTL code after
3563 this pass. This dump file's name is made by appending @samp{.lreg} to
3564 the input file name.
3566 @cindex global register allocation
3568 Global register allocation (@file{global.c}). This pass
3569 allocates hard registers for the remaining pseudo registers (those
3570 whose life spans are not contained in one basic block).
3574 Reloading. This pass renumbers pseudo registers with the hardware
3575 registers numbers they were allocated. Pseudo registers that did not
3576 get hard registers are replaced with stack slots. Then it finds
3577 instructions that are invalid because a value has failed to end up in
3578 a register, or has ended up in a register of the wrong kind. It fixes
3579 up these instructions by reloading the problematical values
3580 temporarily into registers. Additional instructions are generated to
3583 The reload pass also optionally eliminates the frame pointer and inserts
3584 instructions to save and restore call-clobbered registers around calls.
3586 Source files are @file{reload.c} and @file{reload1.c}, plus the header
3587 @file{reload.h} used for communication between them.
3590 The option @option{-dg} causes a debugging dump of the RTL code after
3591 this pass. This dump file's name is made by appending @samp{.greg} to
3592 the input file name.
3594 @cindex instruction scheduling
3595 @cindex scheduling, instruction
3597 Instruction scheduling is repeated here to try to avoid pipeline stalls
3598 due to memory loads generated for spilled pseudo registers.
3601 The option @option{-dR} causes a debugging dump of the RTL code after
3602 this pass. This dump file's name is made by appending @samp{.sched2}
3603 to the input file name.
3605 @cindex basic block reordering
3606 @cindex reordering, block
3608 Basic block reordering. This pass implements profile guided code
3609 positioning. If profile information is not available, various types of
3610 static analysis are performed to make the predictions normally coming
3611 from the profile feedback (IE execution frequency, branch probability,
3612 etc). It is implemented in the file @file{bb-reorder.c}, and the
3613 various prediction routines are in @file{predict.c}.
3616 The option @option{-dB} causes a debugging dump of the RTL code after
3617 this pass. This dump file's name is made by appending @samp{.bbro} to
3618 the input file name.
3620 @cindex cross-jumping
3621 @cindex no-op move instructions
3623 Jump optimization is repeated, this time including cross-jumping
3624 and deletion of no-op move instructions.
3627 The option @option{-dJ} causes a debugging dump of the RTL code after
3628 this pass. This dump file's name is made by appending @samp{.jump2}
3629 to the input file name.
3631 @cindex delayed branch scheduling
3632 @cindex scheduling, delayed branch
3634 Delayed branch scheduling. This optional pass attempts to find
3635 instructions that can go into the delay slots of other instructions,
3636 usually jumps and calls. The source file name is @file{reorg.c}.
3639 The option @option{-dd} causes a debugging dump of the RTL code after
3640 this pass. This dump file's name is made by appending @samp{.dbr}
3641 to the input file name.
3643 @cindex branch shortening
3645 Branch shortening. On many RISC machines, branch instructions have a
3646 limited range. Thus, longer sequences of instructions must be used for
3647 long branches. In this pass, the compiler figures out what how far each
3648 instruction will be from each other instruction, and therefore whether
3649 the usual instructions, or the longer sequences, must be used for each
3652 @cindex register-to-stack conversion
3654 Conversion from usage of some hard registers to usage of a register
3655 stack may be done at this point. Currently, this is supported only
3656 for the floating-point registers of the Intel 80387 coprocessor. The
3657 source file name is @file{reg-stack.c}.
3660 The options @option{-dk} causes a debugging dump of the RTL code after
3661 this pass. This dump file's name is made by appending @samp{.stack}
3662 to the input file name.
3665 @cindex peephole optimization
3667 Final. This pass outputs the assembler code for the function. It is
3668 also responsible for identifying spurious test and compare
3669 instructions. Machine-specific peephole optimizations are performed
3670 at the same time. The function entry and exit sequences are generated
3671 directly as assembler code in this pass; they never exist as RTL@.
3673 The source files are @file{final.c} plus @file{insn-output.c}; the
3674 latter is generated automatically from the machine description by the
3675 tool @file{genoutput}. The header file @file{conditions.h} is used
3676 for communication between these files.
3678 @cindex debugging information generation
3680 Debugging information output. This is run after final because it must
3681 output the stack slot offsets for pseudo registers that did not get
3682 hard registers. Source files are @file{dbxout.c} for DBX symbol table
3683 format, @file{sdbout.c} for SDB symbol table format, @file{dwarfout.c}
3684 for DWARF symbol table format, and the files @file{dwarf2out.c} and
3685 @file{dwarf2asm.c} for DWARF2 symbol table format.
3688 Some additional files are used by all or many passes:
3692 Every pass uses @file{machmode.def} and @file{machmode.h} which define
3696 Several passes use @file{real.h}, which defines the default
3697 representation of floating point constants and how to operate on them.
3700 All the passes that work with RTL use the header files @file{rtl.h}
3701 and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
3702 @code{gen*} also use these files to read and work with the machine
3706 All the tools that read the machine description use support routines
3707 found in @file{gensupport.c}, @file{errors.c}, and @file{read-rtl.c}.
3711 Several passes refer to the header file @file{insn-config.h} which
3712 contains a few parameters (C macro definitions) generated
3713 automatically from the machine description RTL by the tool
3716 @cindex instruction recognizer
3718 Several passes use the instruction recognizer, which consists of
3719 @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
3720 and @file{insn-extract.c} that are generated automatically from the
3721 machine description by the tools @file{genrecog} and
3725 Several passes use the header files @file{regs.h} which defines the
3726 information recorded about pseudo register usage, and @file{basic-block.h}
3727 which defines the information recorded about basic blocks.
3730 @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
3731 with a bit for each hard register, and some macros to manipulate it.
3732 This type is just @code{int} if the machine has few enough hard registers;
3733 otherwise it is an array of @code{int} and some of the macros expand
3737 Several passes use instruction attributes. A definition of the
3738 attributes defined for a particular machine is in file
3739 @file{insn-attr.h}, which is generated from the machine description by
3740 the program @file{genattr}. The file @file{insn-attrtab.c} contains
3741 subroutines to obtain the attribute values for insns. It is generated
3742 from the machine description by the program @file{genattrtab}.
3747 @include c-tree.texi
3755 @chapter The Configuration File
3756 @cindex configuration file
3757 @cindex @file{xm-@var{machine}.h}
3759 The configuration file @file{xm-@var{machine}.h} contains macro
3760 definitions that describe the machine and system on which the compiler
3761 is running, unlike the definitions in @file{@var{machine}.h}, which
3762 describe the machine for which the compiler is producing output. Most
3763 of the values in @file{xm-@var{machine}.h} are actually the same on all
3764 machines that GCC runs on, so large parts of all configuration files
3765 are identical. But there are some macros that vary:
3770 Define this macro if the host system is System V@.
3774 Define this macro if the host system is VMS@.
3776 @findex FATAL_EXIT_CODE
3777 @item FATAL_EXIT_CODE
3778 A C expression for the status code to be returned when the compiler
3779 exits after serious errors. The default is the system-provided macro
3780 @samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
3781 macro. Define this macro only if these defaults are incorrect.
3783 @findex SUCCESS_EXIT_CODE
3784 @item SUCCESS_EXIT_CODE
3785 A C expression for the status code to be returned when the compiler
3786 exits without serious errors. (Warnings are not serious errors.) The
3787 default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
3788 the system doesn't define that macro. Define this macro only if these
3789 defaults are incorrect.
3791 @findex HOST_WORDS_BIG_ENDIAN
3792 @item HOST_WORDS_BIG_ENDIAN
3793 Defined if the host machine stores words of multi-word values in
3794 big-endian order. (GCC does not depend on the host byte ordering
3797 @findex HOST_FLOAT_WORDS_BIG_ENDIAN
3798 @item HOST_FLOAT_WORDS_BIG_ENDIAN
3799 Define this macro to be 1 if the host machine stores @code{DFmode},
3800 @code{XFmode} or @code{TFmode} floating point numbers in memory with the
3801 word containing the sign bit at the lowest address; otherwise, define it
3804 This macro need not be defined if the ordering is the same as for
3805 multi-word integers.
3807 @findex HOST_FLOAT_FORMAT
3808 @item HOST_FLOAT_FORMAT
3809 A numeric code distinguishing the floating point format for the host
3810 machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
3811 alternatives and default.
3813 @findex HOST_BITS_PER_CHAR
3814 @item HOST_BITS_PER_CHAR
3815 A C expression for the number of bits in @code{char} on the host
3818 @findex HOST_BITS_PER_SHORT
3819 @item HOST_BITS_PER_SHORT
3820 A C expression for the number of bits in @code{short} on the host
3823 @findex HOST_BITS_PER_INT
3824 @item HOST_BITS_PER_INT
3825 A C expression for the number of bits in @code{int} on the host
3828 @findex HOST_BITS_PER_LONG
3829 @item HOST_BITS_PER_LONG
3830 A C expression for the number of bits in @code{long} on the host
3833 @findex HOST_BITS_PER_LONGLONG
3834 @item HOST_BITS_PER_LONGLONG
3835 A C expression for the number of bits in @code{long long} on the host
3838 @findex ONLY_INT_FIELDS
3839 @item ONLY_INT_FIELDS
3840 Define this macro to indicate that the host compiler only supports
3841 @code{int} bit-fields, rather than other integral types, including
3842 @code{enum}, as do most C compilers.
3844 @findex OBSTACK_CHUNK_SIZE
3845 @item OBSTACK_CHUNK_SIZE
3846 A C expression for the size of ordinary obstack chunks.
3847 If you don't define this, a usually-reasonable default is used.
3849 @findex OBSTACK_CHUNK_ALLOC
3850 @item OBSTACK_CHUNK_ALLOC
3851 The function used to allocate obstack chunks.
3852 If you don't define this, @code{xmalloc} is used.
3854 @findex OBSTACK_CHUNK_FREE
3855 @item OBSTACK_CHUNK_FREE
3856 The function used to free obstack chunks.
3857 If you don't define this, @code{free} is used.
3859 @findex USE_C_ALLOCA
3861 Define this macro to indicate that the compiler is running with the
3862 @code{alloca} implemented in C@. This version of @code{alloca} can be
3863 found in the file @file{alloca.c}; to use it, you must also alter the
3864 @file{Makefile} variable @code{ALLOCA}. (This is done automatically
3865 for the systems on which we know it is needed.)
3867 If you do define this macro, you should probably do it as follows:
3871 #define USE_C_ALLOCA
3873 #define alloca __builtin_alloca
3878 so that when the compiler is compiled with GCC it uses the more
3879 efficient built-in @code{alloca} function.
3881 @item FUNCTION_CONVERSION_BUG
3882 @findex FUNCTION_CONVERSION_BUG
3883 Define this macro to indicate that the host compiler does not properly
3884 handle converting a function value to a pointer-to-function when it is
3885 used in an expression.
3887 @findex MULTIBYTE_CHARS
3888 @item MULTIBYTE_CHARS
3889 Define this macro to enable support for multibyte characters in the
3890 input to GCC@. This requires that the host system support the ISO C
3891 library functions for converting multibyte characters to wide
3896 Define this if your system is POSIX.1 compliant.
3898 @findex PATH_SEPARATOR
3899 @item PATH_SEPARATOR
3900 Define this macro to be a C character constant representing the
3901 character used to separate components in paths. The default value is
3904 @findex DIR_SEPARATOR
3906 If your system uses some character other than slash to separate
3907 directory names within a file specification, define this macro to be a C
3908 character constant specifying that character. When GCC displays file
3909 names, the character you specify will be used. GCC will test for
3910 both slash and the character you specify when parsing filenames.
3912 @findex DIR_SEPARATOR_2
3913 @item DIR_SEPARATOR_2
3914 If your system uses an alternative character other than
3915 @samp{DIR_SEPARATOR} to separate directory names within a file
3916 specification, define this macro to be a C character constant specifying
3917 that character. If you define this macro, GCC will test for slash,
3918 @samp{DIR_SEPARATOR}, and @samp{DIR_SEPARATOR_2} when parsing filenames.
3920 @findex TARGET_OBJECT_SUFFIX
3921 @item TARGET_OBJECT_SUFFIX
3922 Define this macro to be a C string representing the suffix for object
3923 files on your target machine. If you do not define this macro, GCC will
3924 use @samp{.o} as the suffix for object files.
3926 @findex TARGET_EXECUTABLE_SUFFIX
3927 @item TARGET_EXECUTABLE_SUFFIX
3928 Define this macro to be a C string representing the suffix to be
3929 automatically added to executable files on your target machine. If you
3930 do not define this macro, GCC will use the null string as the suffix for
3933 @findex HOST_OBJECT_SUFFIX
3934 @item HOST_OBJECT_SUFFIX
3935 Define this macro to be a C string representing the suffix for object
3936 files on your host machine (@samp{xm-*.h}). If you do not define this
3937 macro, GCC will use @samp{.o} as the suffix for object files.
3939 @findex HOST_EXECUTABLE_SUFFIX
3940 @item HOST_EXECUTABLE_SUFFIX
3941 Define this macro to be a C string representing the suffix for
3942 executable files on your host machine (@samp{xm-*.h}). If you do not
3943 define this macro, GCC will use the null string as the suffix for
3946 @findex HOST_BIT_BUCKET
3947 @item HOST_BIT_BUCKET
3948 The name of a file or file-like object on the host system which acts as
3949 a ``bit bucket''. If you do not define this macro, GCC will use
3950 @samp{/dev/null} as the bit bucket. If the target does not support a
3951 bit bucket, this should be defined to the null string, or some other
3952 illegal filename. If the bit bucket is not writable, GCC will use a
3953 temporary file instead.
3955 @findex COLLECT_EXPORT_LIST
3956 @item COLLECT_EXPORT_LIST
3957 If defined, @code{collect2} will scan the individual object files
3958 specified on its command line and create an export list for the linker.
3959 Define this macro for systems like AIX, where the linker discards
3960 object files that are not referenced from @code{main} and uses export
3963 @findex COLLECT2_HOST_INITIALIZATION
3964 @item COLLECT2_HOST_INITIALIZATION
3965 If defined, a C statement (sans semicolon) that performs host-dependent
3966 initialization when @code{collect2} is being initialized.
3968 @findex GCC_DRIVER_HOST_INITIALIZATION
3969 @item GCC_DRIVER_HOST_INITIALIZATION
3970 If defined, a C statement (sans semicolon) that performs host-dependent
3971 initialization when a compilation driver is being initialized.
3973 @findex UPDATE_PATH_HOST_CANONICALIZE
3974 @item UPDATE_PATH_HOST_CANONICALIZE (@var{path}, @var{key})
3975 If defined, a C statement (sans semicolon) that performs host-dependent
3976 canonicalization when a path used in a compilation driver or preprocessor is
3977 canonicalized. @var{path} is the path to be canonicalized, and @var{key} is
3978 a translation prefix when its value isn't @code{NULL}. If the C statement
3979 does canonicalize @var{path}, the new path should be returned.
3984 In addition, configuration files for system V define @code{bcopy},
3985 @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
3986 as a macro when compiled with GCC, in order to take advantage of the
3987 benefit of GCC's built-in @code{alloca}.
3990 @chapter Makefile Fragments
3991 @cindex makefile fragment
3993 When you configure GCC using the @file{configure} script
3994 (@pxref{Installation}), it will construct the file @file{Makefile} from
3995 the template file @file{Makefile.in}. When it does this, it will
3996 incorporate makefile fragment files from the @file{config} directory,
3997 named @file{t-@var{target}} and @file{x-@var{host}}. If these files do
3998 not exist, it means nothing needs to be added for a given target or
4002 * Target Fragment:: Writing the @file{t-@var{target}} file.
4003 * Host Fragment:: Writing the @file{x-@var{host}} file.
4006 @node Target Fragment
4007 @section The Target Makefile Fragment
4008 @cindex target makefile fragment
4009 @cindex @file{t-@var{target}}
4011 The target makefile fragment, @file{t-@var{target}}, defines special
4012 target dependent variables and targets used in the @file{Makefile}:
4015 @findex LIBGCC2_CFLAGS
4016 @item LIBGCC2_CFLAGS
4017 Compiler flags to use when compiling @file{libgcc2.c}.
4019 @findex LIB2FUNCS_EXTRA
4020 @item LIB2FUNCS_EXTRA
4021 A list of source file names to be compiled or assembled and inserted
4022 into @file{libgcc.a}.
4024 @findex Floating Point Emulation
4025 @item Floating Point Emulation
4026 To have GCC include software floating point libraries in @file{libgcc.a}
4027 define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
4029 # We want fine grained libraries, so use the new code
4030 # to build the floating point emulation libraries.
4035 fp-bit.c: $(srcdir)/config/fp-bit.c
4036 echo '#define FLOAT' > fp-bit.c
4037 cat $(srcdir)/config/fp-bit.c >> fp-bit.c
4039 dp-bit.c: $(srcdir)/config/fp-bit.c
4040 cat $(srcdir)/config/fp-bit.c > dp-bit.c
4043 You may need to provide additional #defines at the beginning of @file{fp-bit.c}
4044 and @file{dp-bit.c} to control target endianness and other options.
4047 @findex CRTSTUFF_T_CFLAGS
4048 @item CRTSTUFF_T_CFLAGS
4049 Special flags used when compiling @file{crtstuff.c}.
4050 @xref{Initialization}.
4052 @findex CRTSTUFF_T_CFLAGS_S
4053 @item CRTSTUFF_T_CFLAGS_S
4054 Special flags used when compiling @file{crtstuff.c} for shared
4055 linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
4056 in @code{EXTRA-PARTS}.
4057 @xref{Initialization}.
4059 @findex MULTILIB_OPTIONS
4060 @item MULTILIB_OPTIONS
4061 For some targets, invoking GCC in different ways produces objects
4062 that can not be linked together. For example, for some targets GCC
4063 produces both big and little endian code. For these targets, you must
4064 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
4065 each set of incompatible options. When GCC invokes the linker, it
4066 arranges to link in the right version of @file{libgcc.a}, based on
4067 the command line options used.
4069 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
4070 special versions of @file{libgcc.a} must be built. Write options that
4071 are mutually incompatible side by side, separated by a slash. Write
4072 options that may be used together separated by a space. The build
4073 procedure will build all combinations of compatible options.
4075 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
4076 msoft-float}, @file{Makefile} will build special versions of
4077 @file{libgcc.a} using the following sets of options: @option{-m68000},
4078 @option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
4079 @samp{-m68020 -msoft-float}.
4081 @findex MULTILIB_DIRNAMES
4082 @item MULTILIB_DIRNAMES
4083 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
4084 directory names that should be used to hold the various libraries.
4085 Write one element in @code{MULTILIB_DIRNAMES} for each element in
4086 @code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
4087 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
4090 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
4091 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
4092 @samp{m68000 m68020 msoft-float}. You may specify a different value if
4093 you desire a different set of directory names.
4095 @findex MULTILIB_MATCHES
4096 @item MULTILIB_MATCHES
4097 Sometimes the same option may be written in two different ways. If an
4098 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
4099 any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
4100 items of the form @samp{option=option} to describe all relevant
4101 synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
4103 @findex MULTILIB_EXCEPTIONS
4104 @item MULTILIB_EXCEPTIONS
4105 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
4106 specified, there are combinations that should not be built. In that
4107 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
4108 in shell case syntax that should not be built.
4110 For example, in the PowerPC embedded ABI support, it is not desirable
4111 to build libraries compiled with the @option{-mcall-aix} option
4112 and either of the @option{-fleading-underscore} or @option{-mlittle} options
4113 at the same time. Therefore @code{MULTILIB_EXCEPTIONS} is set to
4114 @code{*mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*}.
4116 @findex MULTILIB_EXTRA_OPTS
4117 @item MULTILIB_EXTRA_OPTS
4118 Sometimes it is desirable that when building multiple versions of
4119 @file{libgcc.a} certain options should always be passed on to the
4120 compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
4121 of options to be used for all builds.
4125 @section The Host Makefile Fragment
4126 @cindex host makefile fragment
4127 @cindex @file{x-@var{host}}
4129 The host makefile fragment, @file{x-@var{host}}, defines special host
4130 dependent variables and targets used in the @file{Makefile}:
4135 The compiler to use when building the first stage.
4139 The install program to use.
4143 @include funding.texi
4146 @unnumbered Linux and the GNU Project
4148 Many computer users run a modified version of the GNU system every
4149 day, without realizing it. Through a peculiar turn of events, the
4150 version of GNU which is widely used today is more often known as
4151 ``Linux'', and many users are not aware of the extent of its
4152 connection with the GNU Project.
4154 There really is a Linux; it is a kernel, and these people are using
4155 it. But you can't use a kernel by itself; a kernel is useful only as
4156 part of a whole system. The system in which Linux is typically used
4157 is a modified variant of the GNU system---in other words, a Linux-based
4160 Many users are not fully aware of the distinction between the kernel,
4161 which is Linux, and the whole system, which they also call ``Linux''.
4162 The ambiguous use of the name doesn't promote understanding.
4164 Programmers generally know that Linux is a kernel. But since they
4165 have generally heard the whole system called ``Linux'' as well, they
4166 often envisage a history which fits that name. For example, many
4167 believe that once Linus Torvalds finished writing the kernel, his
4168 friends looked around for other free software, and for no particular
4169 reason most everything necessary to make a Unix-like system was
4172 What they found was no accident---it was the GNU system. The available
4173 free software added up to a complete system because the GNU Project
4174 had been working since 1984 to make one. The GNU Manifesto
4175 had set forth the goal of developing a free Unix-like system, called
4176 GNU@. By the time Linux was written, the system was almost finished.
4178 Most free software projects have the goal of developing a particular
4179 program for a particular job. For example, Linus Torvalds set out to
4180 write a Unix-like kernel (Linux); Donald Knuth set out to write a text
4181 formatter (TeX); Bob Scheifler set out to develop a window system (X
4182 Windows). It's natural to measure the contribution of this kind of
4183 project by specific programs that came from the project.
4185 If we tried to measure the GNU Project's contribution in this way,
4186 what would we conclude? One CD-ROM vendor found that in their ``Linux
4187 distribution'', GNU software was the largest single contingent, around
4188 28% of the total source code, and this included some of the essential
4189 major components without which there could be no system. Linux itself
4190 was about 3%. So if you were going to pick a name for the system
4191 based on who wrote the programs in the system, the most appropriate
4192 single choice would be ``GNU''@.
4194 But we don't think that is the right way to consider the question.
4195 The GNU Project was not, is not, a project to develop specific
4196 software packages. It was not a project to develop a C compiler,
4197 although we did. It was not a project to develop a text editor,
4198 although we developed one. The GNU Project's aim was to develop
4199 @emph{a complete free Unix-like system}.
4201 Many people have made major contributions to the free software in the
4202 system, and they all deserve credit. But the reason it is @emph{a
4203 system}---and not just a collection of useful programs---is because the
4204 GNU Project set out to make it one. We wrote the programs that were
4205 needed to make a @emph{complete} free system. We wrote essential but
4206 unexciting major components, such as the assembler and linker, because
4207 you can't have a system without them. A complete system needs more
4208 than just programming tools, so we wrote other components as well,
4209 such as the Bourne Again SHell, the PostScript interpreter
4210 Ghostscript, and the GNU C library.
4212 By the early 90s we had put together the whole system aside from the
4213 kernel (and we were also working on a kernel, the GNU Hurd, which runs
4214 on top of Mach). Developing this kernel has been a lot harder than we
4215 expected, and we are still working on finishing it.
4217 Fortunately, you don't have to wait for it, because Linux is working
4218 now. When Linus Torvalds wrote Linux, he filled the last major gap.
4219 People could then put Linux together with the GNU system to make a
4220 complete free system: a Linux-based GNU system (or GNU/Linux system,
4223 Putting them together sounds simple, but it was not a trivial job.
4224 The GNU C library (called glibc for short) needed substantial changes.
4225 Integrating a complete system as a distribution that would work ``out
4226 of the box'' was a big job, too. It required addressing the issue of
4227 how to install and boot the system---a problem we had not tackled,
4228 because we hadn't yet reached that point. The people who developed
4229 the various system distributions made a substantial contribution.
4231 The GNU Project supports GNU/Linux systems as well as @emph{the}
4232 GNU system---even with funds. We funded the rewriting of the
4233 Linux-related extensions to the GNU C library, so that now they are
4234 well integrated, and the newest GNU/Linux systems use the current
4235 library release with no changes. We also funded an early stage of the
4236 development of Debian GNU/Linux.
4238 We use Linux-based GNU systems today for most of our work, and we hope
4239 you use them too. But please don't confuse the public by using the
4240 name ``Linux'' ambiguously. Linux is the kernel, one of the essential
4241 major components of the system. The system as a whole is more or less
4245 @unnumbered GNU GENERAL PUBLIC LICENSE
4246 @center Version 2, June 1991
4249 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
4250 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
4252 Everyone is permitted to copy and distribute verbatim copies
4253 of this license document, but changing it is not allowed.
4256 @unnumberedsec Preamble
4258 The licenses for most software are designed to take away your
4259 freedom to share and change it. By contrast, the GNU General Public
4260 License is intended to guarantee your freedom to share and change free
4261 software---to make sure the software is free for all its users. This
4262 General Public License applies to most of the Free Software
4263 Foundation's software and to any other program whose authors commit to
4264 using it. (Some other Free Software Foundation software is covered by
4265 the GNU Library General Public License instead.) You can apply it to
4268 When we speak of free software, we are referring to freedom, not
4269 price. Our General Public Licenses are designed to make sure that you
4270 have the freedom to distribute copies of free software (and charge for
4271 this service if you wish), that you receive source code or can get it
4272 if you want it, that you can change the software or use pieces of it
4273 in new free programs; and that you know you can do these things.
4275 To protect your rights, we need to make restrictions that forbid
4276 anyone to deny you these rights or to ask you to surrender the rights.
4277 These restrictions translate to certain responsibilities for you if you
4278 distribute copies of the software, or if you modify it.
4280 For example, if you distribute copies of such a program, whether
4281 gratis or for a fee, you must give the recipients all the rights that
4282 you have. You must make sure that they, too, receive or can get the
4283 source code. And you must show them these terms so they know their
4286 We protect your rights with two steps: (1) copyright the software, and
4287 (2) offer you this license which gives you legal permission to copy,
4288 distribute and/or modify the software.
4290 Also, for each author's protection and ours, we want to make certain
4291 that everyone understands that there is no warranty for this free
4292 software. If the software is modified by someone else and passed on, we
4293 want its recipients to know that what they have is not the original, so
4294 that any problems introduced by others will not reflect on the original
4295 authors' reputations.
4297 Finally, any free program is threatened constantly by software
4298 patents. We wish to avoid the danger that redistributors of a free
4299 program will individually obtain patent licenses, in effect making the
4300 program proprietary. To prevent this, we have made it clear that any
4301 patent must be licensed for everyone's free use or not licensed at all.
4303 The precise terms and conditions for copying, distribution and
4304 modification follow.
4307 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4310 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4315 This License applies to any program or other work which contains
4316 a notice placed by the copyright holder saying it may be distributed
4317 under the terms of this General Public License. The ``Program'', below,
4318 refers to any such program or work, and a ``work based on the Program''
4319 means either the Program or any derivative work under copyright law:
4320 that is to say, a work containing the Program or a portion of it,
4321 either verbatim or with modifications and/or translated into another
4322 language. (Hereinafter, translation is included without limitation in
4323 the term ``modification''.) Each licensee is addressed as ``you''.
4325 Activities other than copying, distribution and modification are not
4326 covered by this License; they are outside its scope. The act of
4327 running the Program is not restricted, and the output from the Program
4328 is covered only if its contents constitute a work based on the
4329 Program (independent of having been made by running the Program).
4330 Whether that is true depends on what the Program does.
4333 You may copy and distribute verbatim copies of the Program's
4334 source code as you receive it, in any medium, provided that you
4335 conspicuously and appropriately publish on each copy an appropriate
4336 copyright notice and disclaimer of warranty; keep intact all the
4337 notices that refer to this License and to the absence of any warranty;
4338 and give any other recipients of the Program a copy of this License
4339 along with the Program.
4341 You may charge a fee for the physical act of transferring a copy, and
4342 you may at your option offer warranty protection in exchange for a fee.
4345 You may modify your copy or copies of the Program or any portion
4346 of it, thus forming a work based on the Program, and copy and
4347 distribute such modifications or work under the terms of Section 1
4348 above, provided that you also meet all of these conditions:
4352 You must cause the modified files to carry prominent notices
4353 stating that you changed the files and the date of any change.
4356 You must cause any work that you distribute or publish, that in
4357 whole or in part contains or is derived from the Program or any
4358 part thereof, to be licensed as a whole at no charge to all third
4359 parties under the terms of this License.
4362 If the modified program normally reads commands interactively
4363 when run, you must cause it, when started running for such
4364 interactive use in the most ordinary way, to print or display an
4365 announcement including an appropriate copyright notice and a
4366 notice that there is no warranty (or else, saying that you provide
4367 a warranty) and that users may redistribute the program under
4368 these conditions, and telling the user how to view a copy of this
4369 License. (Exception: if the Program itself is interactive but
4370 does not normally print such an announcement, your work based on
4371 the Program is not required to print an announcement.)
4374 These requirements apply to the modified work as a whole. If
4375 identifiable sections of that work are not derived from the Program,
4376 and can be reasonably considered independent and separate works in
4377 themselves, then this License, and its terms, do not apply to those
4378 sections when you distribute them as separate works. But when you
4379 distribute the same sections as part of a whole which is a work based
4380 on the Program, the distribution of the whole must be on the terms of
4381 this License, whose permissions for other licensees extend to the
4382 entire whole, and thus to each and every part regardless of who wrote it.
4384 Thus, it is not the intent of this section to claim rights or contest
4385 your rights to work written entirely by you; rather, the intent is to
4386 exercise the right to control the distribution of derivative or
4387 collective works based on the Program.
4389 In addition, mere aggregation of another work not based on the Program
4390 with the Program (or with a work based on the Program) on a volume of
4391 a storage or distribution medium does not bring the other work under
4392 the scope of this License.
4395 You may copy and distribute the Program (or a work based on it,
4396 under Section 2) in object code or executable form under the terms of
4397 Sections 1 and 2 above provided that you also do one of the following:
4401 Accompany it with the complete corresponding machine-readable
4402 source code, which must be distributed under the terms of Sections
4403 1 and 2 above on a medium customarily used for software interchange; or,
4406 Accompany it with a written offer, valid for at least three
4407 years, to give any third party, for a charge no more than your
4408 cost of physically performing source distribution, a complete
4409 machine-readable copy of the corresponding source code, to be
4410 distributed under the terms of Sections 1 and 2 above on a medium
4411 customarily used for software interchange; or,
4414 Accompany it with the information you received as to the offer
4415 to distribute corresponding source code. (This alternative is
4416 allowed only for noncommercial distribution and only if you
4417 received the program in object code or executable form with such
4418 an offer, in accord with Subsection b above.)
4421 The source code for a work means the preferred form of the work for
4422 making modifications to it. For an executable work, complete source
4423 code means all the source code for all modules it contains, plus any
4424 associated interface definition files, plus the scripts used to
4425 control compilation and installation of the executable. However, as a
4426 special exception, the source code distributed need not include
4427 anything that is normally distributed (in either source or binary
4428 form) with the major components (compiler, kernel, and so on) of the
4429 operating system on which the executable runs, unless that component
4430 itself accompanies the executable.
4432 If distribution of executable or object code is made by offering
4433 access to copy from a designated place, then offering equivalent
4434 access to copy the source code from the same place counts as
4435 distribution of the source code, even though third parties are not
4436 compelled to copy the source along with the object code.
4439 You may not copy, modify, sublicense, or distribute the Program
4440 except as expressly provided under this License. Any attempt
4441 otherwise to copy, modify, sublicense or distribute the Program is
4442 void, and will automatically terminate your rights under this License.
4443 However, parties who have received copies, or rights, from you under
4444 this License will not have their licenses terminated so long as such
4445 parties remain in full compliance.
4448 You are not required to accept this License, since you have not
4449 signed it. However, nothing else grants you permission to modify or
4450 distribute the Program or its derivative works. These actions are
4451 prohibited by law if you do not accept this License. Therefore, by
4452 modifying or distributing the Program (or any work based on the
4453 Program), you indicate your acceptance of this License to do so, and
4454 all its terms and conditions for copying, distributing or modifying
4455 the Program or works based on it.
4458 Each time you redistribute the Program (or any work based on the
4459 Program), the recipient automatically receives a license from the
4460 original licensor to copy, distribute or modify the Program subject to
4461 these terms and conditions. You may not impose any further
4462 restrictions on the recipients' exercise of the rights granted herein.
4463 You are not responsible for enforcing compliance by third parties to
4467 If, as a consequence of a court judgment or allegation of patent
4468 infringement or for any other reason (not limited to patent issues),
4469 conditions are imposed on you (whether by court order, agreement or
4470 otherwise) that contradict the conditions of this License, they do not
4471 excuse you from the conditions of this License. If you cannot
4472 distribute so as to satisfy simultaneously your obligations under this
4473 License and any other pertinent obligations, then as a consequence you
4474 may not distribute the Program at all. For example, if a patent
4475 license would not permit royalty-free redistribution of the Program by
4476 all those who receive copies directly or indirectly through you, then
4477 the only way you could satisfy both it and this License would be to
4478 refrain entirely from distribution of the Program.
4480 If any portion of this section is held invalid or unenforceable under
4481 any particular circumstance, the balance of the section is intended to
4482 apply and the section as a whole is intended to apply in other
4485 It is not the purpose of this section to induce you to infringe any
4486 patents or other property right claims or to contest validity of any
4487 such claims; this section has the sole purpose of protecting the
4488 integrity of the free software distribution system, which is
4489 implemented by public license practices. Many people have made
4490 generous contributions to the wide range of software distributed
4491 through that system in reliance on consistent application of that
4492 system; it is up to the author/donor to decide if he or she is willing
4493 to distribute software through any other system and a licensee cannot
4496 This section is intended to make thoroughly clear what is believed to
4497 be a consequence of the rest of this License.
4500 If the distribution and/or use of the Program is restricted in
4501 certain countries either by patents or by copyrighted interfaces, the
4502 original copyright holder who places the Program under this License
4503 may add an explicit geographical distribution limitation excluding
4504 those countries, so that distribution is permitted only in or among
4505 countries not thus excluded. In such case, this License incorporates
4506 the limitation as if written in the body of this License.
4509 The Free Software Foundation may publish revised and/or new versions
4510 of the General Public License from time to time. Such new versions will
4511 be similar in spirit to the present version, but may differ in detail to
4512 address new problems or concerns.
4514 Each version is given a distinguishing version number. If the Program
4515 specifies a version number of this License which applies to it and ``any
4516 later version'', you have the option of following the terms and conditions
4517 either of that version or of any later version published by the Free
4518 Software Foundation. If the Program does not specify a version number of
4519 this License, you may choose any version ever published by the Free Software
4523 If you wish to incorporate parts of the Program into other free
4524 programs whose distribution conditions are different, write to the author
4525 to ask for permission. For software which is copyrighted by the Free
4526 Software Foundation, write to the Free Software Foundation; we sometimes
4527 make exceptions for this. Our decision will be guided by the two goals
4528 of preserving the free status of all derivatives of our free software and
4529 of promoting the sharing and reuse of software generally.
4532 @heading NO WARRANTY
4539 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
4540 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
4541 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
4542 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
4543 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
4544 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
4545 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
4546 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
4547 REPAIR OR CORRECTION.
4550 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
4551 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
4552 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
4553 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
4554 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
4555 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
4556 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
4557 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
4558 POSSIBILITY OF SUCH DAMAGES.
4562 @heading END OF TERMS AND CONDITIONS
4565 @center END OF TERMS AND CONDITIONS
4569 @unnumberedsec How to Apply These Terms to Your New Programs
4571 If you develop a new program, and you want it to be of the greatest
4572 possible use to the public, the best way to achieve this is to make it
4573 free software which everyone can redistribute and change under these terms.
4575 To do so, attach the following notices to the program. It is safest
4576 to attach them to the start of each source file to most effectively
4577 convey the exclusion of warranty; and each file should have at least
4578 the ``copyright'' line and a pointer to where the full notice is found.
4581 @var{one line to give the program's name and a brief idea of what it does.}
4582 Copyright (C) @var{yyyy} @var{name of author}
4584 This program is free software; you can redistribute it and/or modify
4585 it under the terms of the GNU General Public License as published by
4586 the Free Software Foundation; either version 2 of the License, or
4587 (at your option) any later version.
4589 This program is distributed in the hope that it will be useful,
4590 but WITHOUT ANY WARRANTY; without even the implied warranty of
4591 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4592 GNU General Public License for more details.
4594 You should have received a copy of the GNU General Public License
4595 along with this program; if not, write to the Free Software
4596 Foundation, Inc., 59 Temple Place - Suite 330,
4597 Boston, MA 02111-1307, USA.
4600 Also add information on how to contact you by electronic and paper mail.
4602 If the program is interactive, make it output a short notice like this
4603 when it starts in an interactive mode:
4606 Gnomovision version 69, Copyright (C) @var{yyyy} @var{name of author}
4607 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
4609 This is free software, and you are welcome to redistribute it
4610 under certain conditions; type `show c' for details.
4613 The hypothetical commands @samp{show w} and @samp{show c} should show
4614 the appropriate parts of the General Public License. Of course, the
4615 commands you use may be called something other than @samp{show w} and
4616 @samp{show c}; they could even be mouse-clicks or menu items---whatever
4619 You should also get your employer (if you work as a programmer) or your
4620 school, if any, to sign a ``copyright disclaimer'' for the program, if
4621 necessary. Here is a sample; alter the names:
4624 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
4625 `Gnomovision' (which makes passes at compilers) written by James Hacker.
4627 @var{signature of Ty Coon}, 1 April 1989
4628 Ty Coon, President of Vice
4633 @c ---------------------------------------------------------------------
4635 @c ---------------------------------------------------------------------
4640 @unnumbered Contributors to GCC
4641 @cindex contributors
4642 @include contrib.texi
4644 @c ---------------------------------------------------------------------
4646 @c ---------------------------------------------------------------------
4649 @unnumbered Option Index
4651 GCC's command line options are indexed here without any initial @samp{-}
4652 or @samp{--}. Where an option has both positive and negative forms
4653 (such as @option{-f@var{option}} and @option{-fno-@var{option}}),
4654 relevant entries in the manual are indexed under the most appropriate
4655 form; it may sometimes be useful to look up both forms.
4664 @c ---------------------------------------------------------------------
4666 @c ---------------------------------------------------------------------