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
38 @c -continuity of phrasing; ie, bit-field vs bitfield in rtl.texi
39 @c -overfulls. do a search for "mew" in the files, and you will see
40 @c overfulls that i noted but could not deal with.
41 @c -have to add text: beginning of chapter 8
44 @c anything else? --mew 10feb93
46 @macro gcctabopt{body}
49 @macro gccoptlist{body}
54 @c Makeinfo handles the above macro OK, TeX needs manual line breaks;
55 @c they get lost at some point in handling the macro. But if @macro is
56 @c used here rather than @alias, it produces double line breaks.
67 @settitle Using and Porting the GNU Compiler Collection (GCC)
70 @c seems reasonable to assume at least one of INTERNALS or USING is set...
72 @settitle Using the GNU Compiler Collection
75 @settitle Porting the GNU Compiler Collection
82 @c Use with @@smallbook.
84 @c Cause even numbered pages to be printed on the left hand side of
85 @c the page and odd numbered pages to be printed on the right hand
86 @c side of the page. Using this, you can print on both sides of a
87 @c sheet of paper and have the text on the same part of the sheet.
89 @c The text on right hand pages is pushed towards the right hand
90 @c margin and the text on left hand pages is pushed toward the left
92 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
95 @c \global\bindingoffset=0.75in
96 @c \global\normaloffset =0.75in
100 @dircategory Programming
102 * gcc: (gcc). The GNU Compiler Collection.
106 This file documents the use and the internals of the GNU compiler.
110 This file documents the internals of the GNU compiler.
113 This file documents the use of the GNU compiler.
116 Published by the Free Software Foundation@*
117 59 Temple Place - Suite 330@*
118 Boston, MA 02111-1307 USA
120 @c When you update the list of years below, search for copyright{} and
121 @c update the other copy too.
122 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
123 1999, 2000, 2001 Free Software Foundation, Inc.
125 Permission is granted to make and distribute verbatim copies of
126 this manual provided the copyright notice and this permission notice
127 are preserved on all copies.
130 Permission is granted to process this file through Tex and print the
131 results, provided the printed document carries copying permission
132 notice identical to this one except for the removal of this paragraph
133 (this paragraph not being relevant to the printed manual).
136 Permission is granted to copy and distribute modified versions of this
137 manual under the conditions for verbatim copying, provided also that the
138 sections entitled ``GNU General Public License'' and ``Funding for Free
139 Software'' are included exactly as in the original, and provided that
140 the entire resulting derived work is distributed under the terms of a
141 permission notice identical to this one.
143 Permission is granted to copy and distribute translations of this manual
144 into another language, under the above conditions for modified versions,
145 except that the sections entitled ``GNU General Public License'' and
146 ``Funding for Free Software'', and this permission notice, may be
147 included in translations approved by the Free Software Foundation
148 instead of in the original English.
151 @setchapternewpage odd
156 @center @titlefont{Using and Porting the GNU Compiler Collection}
161 @title Using the GNU Compiler Collection
164 @title Porting the GNU Compiler Collection
167 @center Richard M. Stallman
169 @center Last updated 13 January 2001
171 @c The version number appears five times more in this file.
175 @vskip 0pt plus 1filll
176 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
177 1999, 2000, 2001 Free Software Foundation, Inc.
179 For GCC Version 2.97@*
181 Published by the Free Software Foundation @*
182 59 Temple Place - Suite 330@*
183 Boston, MA 02111-1307, USA@*
184 Last printed April, 1998.@*
185 Printed copies are available for $50 each.@*
188 Permission is granted to make and distribute verbatim copies of
189 this manual provided the copyright notice and this permission notice
190 are preserved on all copies.
192 Permission is granted to copy and distribute modified versions of this
193 manual under the conditions for verbatim copying, provided also that the
194 sections entitled ``GNU General Public License'' and ``Funding for Free
195 Software'' are included exactly as in the original, and provided that
196 the entire resulting derived work is distributed under the terms of a
197 permission notice identical to this one.
199 Permission is granted to copy and distribute translations of this manual
200 into another language, under the above conditions for modified versions,
201 except that the sections entitled ``GNU General Public License'' and
202 ``Funding for Free Software'', and this permission notice, may be
203 included in translations approved by the Free Software Foundation
204 instead of in the original English.
208 @node Top, G++ and GCC,, (DIR)
214 This manual documents how to run, install and port the GNU
215 compiler, as well as its new features and incompatibilities, and how to
216 report bugs. It corresponds to GCC version 2.97.
221 This manual documents how to run and install the GNU compiler,
222 as well as its new features and incompatibilities, and how to report
223 bugs. It corresponds to GCC version 2.97.
226 This manual documents how to port the GNU compiler,
227 as well as its new features and incompatibilities, and how to report
228 bugs. It corresponds to GCC version 2.97.
233 * G++ and GCC:: You can compile C or C++ programs.
234 * Standards:: Language standards supported by GCC.
235 * Invoking GCC:: Command options supported by @samp{gcc}.
236 * Installation:: How to configure, compile and install GCC.
237 * C Extensions:: GNU extensions to the C language family.
238 * C++ Extensions:: GNU extensions to the C++ language.
239 * Gcov:: gcov: a GCC test coverage program.
240 * Trouble:: If you have trouble installing GCC.
241 * Bugs:: How, why and where to report bugs.
242 * Service:: How to find suppliers of support for GCC.
243 * Contributing:: How to contribute to testing and developing GCC.
244 * VMS:: Using GCC on VMS.
245 * Makefile:: List of Makefile targets.
248 * Portability:: Goals of GCC's portability features.
249 * Interface:: Function-call interface of GCC output.
250 * Passes:: Order of passes, what they do, and what each file is for.
251 * RTL:: The intermediate representation that most passes work on.
252 * Machine Desc:: How to write machine description instruction patterns.
253 * Target Macros:: How to write the machine description C macros.
254 * Config:: Writing the @file{xm-@var{machine}.h} file.
255 * Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
258 * Funding:: How to help assure funding for free software.
259 * GNU/Linux:: Linux and the GNU Project
261 * Copying:: GNU General Public License says
262 how you can copy and share GCC.
263 * Contributors:: People who have contributed to GCC.
265 * Index:: Index of concepts and symbol names.
270 @chapter Compile C, C++, Objective C, Fortran, Java or CHILL
273 Several versions of the compiler (C, C++, Objective C, Fortran, Java
274 and CHILL) are integrated; this is why we use the name
275 ``GNU Compiler Collection''. GCC can compile programs written in any of these
276 languages. The Fortran, CHILL, and Java compilers are described in
280 ``GCC'' is a common shorthand term for the GNU Compiler Collection. This is both
281 the most general name for the compiler, and the name used when the
282 emphasis is on compiling C programs (as the abbreviation formerly
283 stood for ``GNU C Compiler'').
287 When referring to C++ compilation, it is usual to call the compiler
288 ``G++''. Since there is only one compiler, it is also accurate to call
289 it ``GCC'' no matter what the language context; however, the term
290 ``G++'' is more useful when the emphasis is on compiling C++ programs.
292 We use the name ``GCC'' to refer to the compilation system as a
293 whole, and more specifically to the language-independent part of the
294 compiler. For example, we refer to the optimization options as
295 affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
297 Front ends for other languages, such as Ada 95 and Pascal exist but
298 have not yet been integrated into GCC. These front-ends, like that for C++,
299 are built in subdirectories of GCC and link to it. The result is an
300 integrated compiler that can compile programs written in C, C++,
301 Objective C, or any of the languages for which you have installed front
304 In this manual, we only discuss the options for the C, Objective-C, and
305 C++ compilers and those of the GCC core. Consult the documentation
306 of the other front ends for the options to use when compiling programs
307 written in other languages.
309 @cindex compiler compared to C++ preprocessor
310 @cindex intermediate C version, nonexistent
311 @cindex C intermediate output, nonexistent
312 G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object
313 code directly from your C++ program source. There is no intermediate C
314 version of the program. (By contrast, for example, some other
315 implementations use a program that generates a C program from your C++
316 source.) Avoiding an intermediate C representation of the program means
317 that you get better object code, and better debugging information. The
318 GNU debugger, GDB, works with this information in the object code to
319 give you comprehensive C++ source-level editing capabilities
320 (@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
322 @c FIXME! Someone who knows something about Objective C ought to put in
323 @c a paragraph or two about it here, and move the index entry down when
324 @c there is more to point to than the general mention in the 1st par.
327 @chapter Language Standards Supported by GCC
330 @cindex ANSI C standard
334 @cindex ANSI X3.159-1989
336 @cindex ISO C standard
351 @cindex Technical Corrigenda
353 @cindex Technical Corrigendum 1
355 @cindex Technical Corrigendum 2
357 @cindex freestanding implementation
358 @cindex freestanding environment
359 @cindex hosted implementation
360 @cindex hosted environment
361 @findex __STDC_HOSTED__
363 For each language compiled by GCC for which there is a standard, GCC
364 attempts to follow one or more versions of that standard, possibly
365 with some exceptions, and possibly with some extensions.
367 GCC supports three versions of the C standard, although support for
368 the most recent version is not yet complete.
370 The original ANSI C standard (X3.159-1989) was ratified in 1989 and
371 published in 1990. This standard was ratified as an ISO standard
372 (ISO/IEC 9899:1990) later in 1990. There were no technical
373 differences between these publications, although the sections of the
374 ANSI standard were renumbered and became clauses in the ISO standard.
375 This standard, in both its forms, is commonly known as @dfn{C89}, or
376 occasionally as @dfn{C90}, from the dates of ratification. The ANSI
377 standard, but not the ISO standard, also came with a Rationale
378 document. To select this standard in GCC, use one of the options
379 @samp{-ansi}, @samp{-std=c89} or @samp{-std=iso9899:1990}; to obtain
380 all the diagnostics required by the standard, you should also specify
381 @samp{-pedantic} (or @samp{-pedantic-errors} if you want them to be
382 errors rather than warnings). @xref{C Dialect Options,,Options
383 Controlling C Dialect}.
385 Errors in the 1990 ISO C standard were corrected in two Technical
386 Corrigenda published in 1994 and 1996. GCC does not support the
389 An amendment to the 1990 standard was published in 1995. This
390 amendment added digraphs and @code{__STDC_VERSION__} to the language,
391 but otherwise concerned the library. This amendment is commonly known
392 as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
393 @dfn{C95}. To select this standard in GCC, use the option
394 @samp{-std=iso9899:199409} (with, as for other standard versions,
395 @samp{-pedantic} to receive all required diagnostics).
397 A new edition of the ISO C standard was published in 1999 as ISO/IEC
398 9899:1999, and is commonly known as @dfn{C99}. GCC has incomplete
399 support for this standard version; see
400 @uref{http://gcc.gnu.org/c99status.html} for details. To select this
401 standard, use @samp{-std=c99} or @samp{-std=iso9899:1999}. (While in
402 development, drafts of this standard version were referred to as
405 GCC also has some limited support for traditional (pre-ISO) C with the
406 @samp{-traditional} option. This support may be of use for compiling
407 some very old programs that have not been updated to ISO C, but should
408 not be used for new programs. It will not work with some modern C
409 libraries such as the GNU C library.
411 By default, GCC provides some extensions to the C language that on
412 rare occasions conflict with the C standard. @xref{C
413 Extensions,,Extensions to the C Language Family}. Use of the
414 @samp{-std} options listed above will disable these extensions where
415 they conflict with the C standard version selected. You may also
416 select an extended version of the C language explicitly with
417 @samp{-std=gnu89} (for C89 with GNU extensions) or @samp{-std=gnu99}
418 (for C99 with GNU extensions). The default, if no C language dialect
419 options are given, is @samp{-std=gnu89}; this will change to
420 @samp{-std=gnu99} in some future release when the C99 support is
421 complete. Some features that are part of the C99 standard are
422 accepted as extensions in C89 mode.
424 The ISO C standard defines (in clause 4) two classes of conforming
425 implementation. A @dfn{conforming hosted implementation} supports the
426 whole standard including all the library facilities; a @dfn{conforming
427 freestanding implementation} is only required to provide certain
428 library facilities: those in @code{<float.h>}, @code{<limits.h>},
429 @code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
430 @code{<iso646.h>}; and in C99, also those in @code{<stdbool.h>} and
431 @code{<stdint.h>}. In addition, complex types, added in C99, are not
432 required for freestanding implementations. The standard also defines
433 two environments for programs, a @dfn{freestanding environment},
434 required of all implementations and which may not have library
435 facilities beyond those required of freestanding implementations,
436 where the handling of program startup and termination are
437 implementation-defined, and a @dfn{hosted environment}, which is not
438 required, in which all the library facilities are provided and startup
439 is through a function @code{int main (void)} or @code{int main (int,
440 char *[])}. An OS kernel would be a freestanding environment; a
441 program using the facilities of an operating system would normally be
442 in a hosted implementation.
444 GNU CC aims towards being usable as a conforming freestanding
445 implementation, or as the compiler for a conforming hosted
446 implementation. By default, it will act as the compiler for a hosted
447 implementation, defining @code{__STDC_HOSTED__} as @code{1} and
448 presuming that when the names of ISO C functions are used, they have
449 the semantics defined in the standard. To make it act as a conforming
450 freestanding implementation for a freestanding environment, use the
451 option @samp{-ffreestanding}; it will then define
452 @code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
453 meanings of function names from the standard library. To build an OS
454 kernel, you may well still need to make your own arrangements for
455 linking and startup. @xref{C Dialect Options,,Options Controlling C
458 GNU CC does not provide the library facilities required only of hosted
459 implementations, nor yet all the facilities required by C99 of
460 freestanding implementations; to use the facilities of a hosted
461 environment, you will need to find them elsewhere (for example, in the
462 GNU C library). @xref{Standard Libraries,,Standard Libraries}.
464 For references to Technical Corrigenda, Rationale documents and
465 information concerning the history of C that is available online, see
466 @uref{http://gcc.gnu.org/readings.html}
468 @c FIXME: details of C++ standard.
469 @c FIXME: definitions of Java and Objective C.
471 @xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
472 Fortran}, for details of the Fortran language supported by GCC.
474 @xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj},
475 for details of compatibility between @code{gcj} and the Java Platform.
477 @xref{References,,Language Definition References, chill, GNU Chill},
478 for details of the CHILL standard.
482 @include install.texi
489 @chapter Known Causes of Trouble with GCC
491 @cindex installation trouble
492 @cindex known causes of trouble
494 This section describes known problems that affect users of GCC. Most
495 of these are not GCC bugs per se---if they were, we would fix them.
496 But the result for a user may be like the result of a bug.
498 Some of these problems are due to bugs in other software, some are
499 missing features that are too much work to add, and some are places
500 where people's opinions differ as to what is best.
503 * Actual Bugs:: Bugs we will fix later.
504 * Installation Problems:: Problems that manifest when you install GCC.
505 * Cross-Compiler Problems:: Common problems of cross compiling with GCC.
506 * Interoperation:: Problems using GCC with other compilers,
507 and with certain linkers, assemblers and debuggers.
508 * External Bugs:: Problems compiling certain programs.
509 * Incompatibilities:: GCC is incompatible with traditional C.
510 * Fixed Headers:: GNU C uses corrected versions of system header files.
511 This is necessary, but doesn't always work smoothly.
512 * Standard Libraries:: GNU C uses the system C library, which might not be
513 compliant with the ISO C standard.
514 * Disappointments:: Regrettable things we can't change, but not quite bugs.
515 * C++ Misunderstandings:: Common misunderstandings with GNU C++.
516 * Protoize Caveats:: Things to watch out for when using @code{protoize}.
517 * Non-bugs:: Things we think are right, but some others disagree.
518 * Warnings and Errors:: Which problems in your code get warnings,
519 and which get errors.
523 @section Actual Bugs We Haven't Fixed Yet
527 The @code{fixincludes} script interacts badly with automounters; if the
528 directory of system header files is automounted, it tends to be
529 unmounted while @code{fixincludes} is running. This would seem to be a
530 bug in the automounter. We don't know any good way to work around it.
533 The @code{fixproto} script will sometimes add prototypes for the
534 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
535 @code{jmp_buf} type before that type is defined. To work around this,
536 edit the offending file and place the typedef in front of the
540 There are several obscure case of mis-using struct, union, and
541 enum tags that are not detected as errors by the compiler.
544 When @samp{-pedantic-errors} is specified, GCC will incorrectly give
545 an error message when a function name is specified in an expression
546 involving the comma operator.
549 Loop unrolling doesn't work properly for certain C++ programs. This is
550 a bug in the C++ front end. It sometimes emits incorrect debug info, and
551 the loop unrolling code is unable to recover from this error.
554 @node Installation Problems
555 @section Installation Problems
557 This is a list of problems (and some apparent problems which don't
558 really mean anything is wrong) that show up during installation of GNU
563 On certain systems, defining certain environment variables such as
564 @code{CC} can interfere with the functioning of @code{make}.
567 If you encounter seemingly strange errors when trying to build the
568 compiler in a directory other than the source directory, it could be
569 because you have previously configured the compiler in the source
570 directory. Make sure you have done all the necessary preparations.
574 If you build GCC on a BSD system using a directory stored in a System
575 V file system, problems may occur in running @code{fixincludes} if the
576 System V file system doesn't support symbolic links. These problems
577 result in a failure to fix the declaration of @code{size_t} in
578 @file{sys/types.h}. If you find that @code{size_t} is a signed type and
579 that type mismatches occur, this could be the cause.
581 The solution is not to use such a directory for building GCC.
584 In previous versions of GCC, the @code{gcc} driver program looked for
585 @code{as} and @code{ld} in various places; for example, in files
586 beginning with @file{/usr/local/lib/gcc-}. GCC version 2 looks for
587 them in the directory
588 @file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}.
590 Thus, to use a version of @code{as} or @code{ld} that is not the system
591 default, for example @code{gas} or GNU @code{ld}, you must put them in
592 that directory (or make links to them from that directory).
595 Some commands executed when making the compiler may fail (return a
596 non-zero status) and be ignored by @code{make}. These failures, which
597 are often due to files that were not found, are expected, and can safely
601 It is normal to have warnings in compiling certain files about
602 unreachable code and about enumeration type clashes. These files' names
603 begin with @samp{insn-}. Also, @file{real.c} may get some warnings that
607 Sometimes @code{make} recompiles parts of the compiler when installing
608 the compiler. In one case, this was traced down to a bug in
609 @code{make}. Either ignore the problem or switch to GNU Make.
612 If you have installed a program known as purify, you may find that it
613 causes errors while linking @code{enquire}, which is part of building
614 GCC. The fix is to get rid of the file @code{real-ld} which purify
615 installs---so that GCC won't try to use it.
618 On GNU/Linux SLS 1.01, there is a problem with @file{libc.a}: it does not
619 contain the obstack functions. However, GCC assumes that the obstack
620 functions are in @file{libc.a} when it is the GNU C library. To work
621 around this problem, change the @code{__GNU_LIBRARY__} conditional
622 around line 31 to @samp{#if 1}.
625 On some 386 systems, building the compiler never finishes because
626 @code{enquire} hangs due to a hardware problem in the motherboard---it
627 reports floating point exceptions to the kernel incorrectly. You can
628 install GCC except for @file{float.h} by patching out the command to
629 run @code{enquire}. You may also be able to fix the problem for real by
630 getting a replacement motherboard. This problem was observed in
631 Revision E of the Micronics motherboard, and is fixed in Revision F.
632 It has also been observed in the MYLEX MXA-33 motherboard.
634 If you encounter this problem, you may also want to consider removing
635 the FPU from the socket during the compilation. Alternatively, if you
636 are running SCO Unix, you can reboot and force the FPU to be ignored.
637 To do this, type @samp{hd(40)unix auto ignorefpu}.
640 On some 386 systems, GCC crashes trying to compile @file{enquire.c}.
641 This happens on machines that don't have a 387 FPU chip. On 386
642 machines, the system kernel is supposed to emulate the 387 when you
643 don't have one. The crash is due to a bug in the emulator.
645 One of these systems is the Unix from Interactive Systems: 386/ix.
646 On this system, an alternate emulator is provided, and it does work.
647 To use it, execute this command as super-user:
650 ln /etc/emulator.rel1 /etc/emulator
654 and then reboot the system. (The default emulator file remains present
655 under the name @file{emulator.dflt}.)
657 Try using @file{/etc/emulator.att}, if you have such a problem on the
660 Another system which has this problem is Esix. We don't know whether it
661 has an alternate emulator that works.
663 On NetBSD 0.8, a similar problem manifests itself as these error messages:
666 enquire.c: In function `fprop':
667 enquire.c:2328: floating overflow
671 On SCO systems, when compiling GCC with the system's compiler,
672 do not use @samp{-O}. Some versions of the system's compiler miscompile
675 @cindex @code{genflags}, crash on Sun 4
677 Sometimes on a Sun 4 you may observe a crash in the program
678 @code{genflags} or @code{genoutput} while building GCC. This is said to
679 be due to a bug in @code{sh}. You can probably get around it by running
680 @code{genflags} or @code{genoutput} manually and then retrying the
684 On Solaris 2, executables of GCC version 2.0.2 are commonly
685 available, but they have a bug that shows up when compiling current
686 versions of GCC: undefined symbol errors occur during assembly if you
689 The solution is to compile the current version of GCC without
690 @samp{-g}. That makes a working compiler which you can use to recompile
694 Solaris 2 comes with a number of optional OS packages. Some of these
695 packages are needed to use GCC fully. If you did not install all
696 optional packages when installing Solaris, you will need to verify that
697 the packages that GCC needs are installed.
699 To check whether an optional package is installed, use
700 the @code{pkginfo} command. To add an optional package, use the
701 @code{pkgadd} command. For further details, see the Solaris
704 For Solaris 2.0 and 2.1, GCC needs six packages: @samp{SUNWarc},
705 @samp{SUNWbtool}, @samp{SUNWesu}, @samp{SUNWhea}, @samp{SUNWlibm}, and
708 For Solaris 2.2, GCC needs an additional seventh package: @samp{SUNWsprot}.
711 On Solaris 2, trying to use the linker and other tools in
712 @file{/usr/ucb} to install GCC has been observed to cause trouble.
713 For example, the linker may hang indefinitely. The fix is to remove
714 @file{/usr/ucb} from your @code{PATH}.
717 If you use the 1.31 version of the MIPS assembler (such as was shipped
718 with Ultrix 3.1), you will need to use the -fno-delayed-branch switch
719 when optimizing floating point code. Otherwise, the assembler will
720 complain when the GCC compiler fills a branch delay slot with a
721 floating point instruction, such as @code{add.d}.
724 If on a MIPS system you get an error message saying ``does not have gp
725 sections for all it's [sic] sectons [sic]'', don't worry about it. This
726 happens whenever you use GAS with the MIPS linker, but there is not
727 really anything wrong, and it is okay to use the output file. You can
728 stop such warnings by installing the GNU linker.
730 It would be nice to extend GAS to produce the gp tables, but they are
731 optional, and there should not be a warning about their absence.
734 In Ultrix 4.0 on the MIPS machine, @file{stdio.h} does not work with GNU
735 CC at all unless it has been fixed with @code{fixincludes}. This causes
736 problems in building GCC. Once GCC is installed, the problems go
739 To work around this problem, when making the stage 1 compiler, specify
743 GCC_FOR_TARGET="./xgcc -B./ -I./include"
746 When making stage 2 and stage 3, specify this option:
749 CFLAGS="-g -I./include"
753 Users have reported some problems with version 2.0 of the MIPS
754 compiler tools that were shipped with Ultrix 4.1. Version 2.10
755 which came with Ultrix 4.2 seems to work fine.
757 Users have also reported some problems with version 2.20 of the
758 MIPS compiler tools that were shipped with RISC/os 4.x. The earlier
759 version 2.11 seems to work fine.
762 Some versions of the MIPS linker will issue an assertion failure
763 when linking code that uses @code{alloca} against shared
764 libraries on RISC-OS 5.0, and DEC's OSF/1 systems. This is a bug
765 in the linker, that is supposed to be fixed in future revisions.
766 To protect against this, GCC passes @samp{-non_shared} to the
767 linker unless you pass an explicit @samp{-shared} or
768 @samp{-call_shared} switch.
771 On System V release 3, you may get this error message
775 ld fatal: failed to write symbol name @var{something}
776 in strings table for file @var{whatever}
779 This probably indicates that the disk is full or your ULIMIT won't allow
780 the file to be as large as it needs to be.
782 This problem can also result because the kernel parameter @code{MAXUMEM}
783 is too small. If so, you must regenerate the kernel and make the value
784 much larger. The default value is reported to be 1024; a value of 32768
785 is said to work. Smaller values may also work.
788 On System V, if you get an error like this,
791 /usr/local/lib/bison.simple: In function `yyparse':
792 /usr/local/lib/bison.simple:625: virtual memory exhausted
796 that too indicates a problem with disk space, ULIMIT, or @code{MAXUMEM}.
799 Current GCC versions probably do not work on version 2 of the NeXT
803 On NeXTStep 3.0, the Objective C compiler does not work, due,
804 apparently, to a kernel bug that it happens to trigger. This problem
805 does not happen on 3.1.
808 On the Tower models 4@var{n}0 and 6@var{n}0, by default a process is not
809 allowed to have more than one megabyte of memory. GCC cannot compile
810 itself (or many other programs) with @samp{-O} in that much memory.
812 To solve this problem, reconfigure the kernel adding the following line
813 to the configuration file:
820 On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a bug
821 in the assembler that must be fixed before GCC can be built. This
822 bug manifests itself during the first stage of compilation, while
823 building @file{libgcc2.a}:
827 cc1: warning: `-g' option not supported on this version of GCC
828 cc1: warning: `-g1' option not supported on this version of GCC
829 ./xgcc: Internal compiler error: program as got fatal signal 11
832 A patched version of the assembler is available as the file
833 @uref{ftp://altdorf.ai.mit.edu/archive/cph/hpux-8.0-assembler}. If you
834 have HP software support, the patch can also be obtained directly from
835 HP, as described in the following note:
838 This is the patched assembler, to patch SR#1653-010439, where the
839 assembler aborts on floating point constants.
841 The bug is not really in the assembler, but in the shared library
842 version of the function ``cvtnum(3c)''. The bug on ``cvtnum(3c)'' is
843 SR#4701-078451. Anyway, the attached assembler uses the archive
844 library version of ``cvtnum(3c)'' and thus does not exhibit the bug.
847 This patch is also known as PHCO_4484.
850 On HP-UX version 8.05, but not on 8.07 or more recent versions,
851 the @code{fixproto} shell script triggers a bug in the system shell.
852 If you encounter this problem, upgrade your operating system or
853 use BASH (the GNU shell) to run @code{fixproto}.
856 Some versions of the Pyramid C compiler are reported to be unable to
857 compile GCC. You must use an older version of GCC for
858 bootstrapping. One indication of this problem is if you get a crash
859 when GCC compiles the function @code{muldi3} in file @file{libgcc2.c}.
861 You may be able to succeed by getting GCC version 1, installing it,
862 and using it to compile GCC version 2. The bug in the Pyramid C
863 compiler does not seem to affect GCC version 1.
866 There may be similar problems on System V Release 3.1 on 386 systems.
869 On the Intel Paragon (an i860 machine), if you are using operating
870 system version 1.0, you will get warnings or errors about redefinition
871 of @code{va_arg} when you build GCC.
873 If this happens, then you need to link most programs with the library
874 @file{iclib.a}. You must also modify @file{stdio.h} as follows: before
878 #if defined(__i860__) && !defined(_VA_LIST)
893 extern int vprintf(const char *, va_list );
894 extern int vsprintf(char *, const char *, va_list );
905 These problems don't exist in operating system version 1.1.
908 On the Altos 3068, programs compiled with GCC won't work unless you
909 fix a kernel bug. This happens using system versions V.2.2 1.0gT1 and
910 V.2.2 1.0e and perhaps later versions as well. See the file
914 You will get several sorts of compilation and linking errors on the
915 we32k if you don't follow the special instructions. @xref{Configurations}.
918 A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto
919 program to report an error of the form:
922 ./fixproto: sh internal 1K buffer overflow
925 To fix this, change the first line of the fixproto script to look like:
932 @node Cross-Compiler Problems
933 @section Cross-Compiler Problems
935 You may run into problems with cross compilation on certain machines,
940 Cross compilation can run into trouble for certain machines because
941 some target machines' assemblers require floating point numbers to be
942 written as @emph{integer} constants in certain contexts.
944 The compiler writes these integer constants by examining the floating
945 point value as an integer and printing that integer, because this is
946 simple to write and independent of the details of the floating point
947 representation. But this does not work if the compiler is running on
948 a different machine with an incompatible floating point format, or
949 even a different byte-ordering.
951 In addition, correct constant folding of floating point values
952 requires representing them in the target machine's format.
953 (The C standard does not quite require this, but in practice
954 it is the only way to win.)
956 It is now possible to overcome these problems by defining macros such
957 as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
958 work for each target machine.
960 @xref{Cross-compilation}.
963 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
964 gcc.info, Using and Porting GCC}.
968 At present, the program @file{mips-tfile} which adds debug
969 support to object files on MIPS systems does not work in a cross
974 @section Interoperation
976 This section lists various difficulties encountered in using GNU C or
977 GNU C++ together with other compilers or with the assemblers, linkers,
978 libraries and debuggers on certain systems.
982 Objective C does not work on the RS/6000.
985 GNU C++ does not do name mangling in the same way as other C++
986 compilers. This means that object files compiled with one compiler
987 cannot be used with another.
989 This effect is intentional, to protect you from more subtle problems.
990 Compilers differ as to many internal details of C++ implementation,
991 including: how class instances are laid out, how multiple inheritance is
992 implemented, and how virtual function calls are handled. If the name
993 encoding were made the same, your programs would link against libraries
994 provided from other compilers---but the programs would then crash when
995 run. Incompatible libraries are then detected at link time, rather than
999 Older GDB versions sometimes fail to read the output of GCC version
1000 2. If you have trouble, get GDB version 4.4 or later.
1004 DBX rejects some files produced by GCC, though it accepts similar
1005 constructs in output from PCC. Until someone can supply a coherent
1006 description of what is valid DBX input and what is not, there is
1007 nothing I can do about these problems. You are on your own.
1010 The GNU assembler (GAS) does not support PIC. To generate PIC code, you
1011 must use some other assembler, such as @file{/bin/as}.
1014 On some BSD systems, including some versions of Ultrix, use of profiling
1015 causes static variable destructors (currently used only in C++) not to
1019 Use of @samp{-I/usr/include} may cause trouble.
1021 Many systems come with header files that won't work with GCC unless
1022 corrected by @code{fixincludes}. The corrected header files go in a new
1023 directory; GCC searches this directory before @file{/usr/include}.
1024 If you use @samp{-I/usr/include}, this tells GCC to search
1025 @file{/usr/include} earlier on, before the corrected headers. The
1026 result is that you get the uncorrected header files.
1028 Instead, you should use these options (when compiling C programs):
1031 -I/usr/local/lib/gcc-lib/@var{target}/@var{version}/include -I/usr/include
1034 For C++ programs, GCC also uses a special directory that defines C++
1035 interfaces to standard C subroutines. This directory is meant to be
1036 searched @emph{before} other standard include directories, so that it
1037 takes precedence. If you are compiling C++ programs and specifying
1038 include directories explicitly, use this option first, then the two
1042 -I/usr/local/lib/g++-include
1046 @cindex @code{vfork}, for the Sun-4
1048 There is a bug in @code{vfork} on the Sun-4 which causes the registers
1049 of the child process to clobber those of the parent. Because of this,
1050 programs that call @code{vfork} are likely to lose when compiled
1051 optimized with GCC when the child code alters registers which contain
1052 C variables in the parent. This affects variables which are live in the
1053 parent across the call to @code{vfork}.
1055 If you encounter this, you can work around the problem by declaring
1056 variables @code{volatile} in the function that calls @code{vfork}, until
1057 the problem goes away, or by not declaring them @code{register} and not
1058 using @samp{-O} for those source files.
1062 On some SGI systems, when you use @samp{-lgl_s} as an option,
1063 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
1064 Naturally, this does not happen when you use GCC.
1065 You must specify all three options explicitly.
1068 On a Sparc, GCC aligns all values of type @code{double} on an 8-byte
1069 boundary, and it expects every @code{double} to be so aligned. The Sun
1070 compiler usually gives @code{double} values 8-byte alignment, with one
1071 exception: function arguments of type @code{double} may not be aligned.
1073 As a result, if a function compiled with Sun CC takes the address of an
1074 argument of type @code{double} and passes this pointer of type
1075 @code{double *} to a function compiled with GCC, dereferencing the
1076 pointer may cause a fatal signal.
1078 One way to solve this problem is to compile your entire program with GNU
1079 CC. Another solution is to modify the function that is compiled with
1080 Sun CC to copy the argument into a local variable; local variables
1081 are always properly aligned. A third solution is to modify the function
1082 that uses the pointer to dereference it via the following function
1083 @code{access_double} instead of directly with @samp{*}:
1087 access_double (double *unaligned_ptr)
1089 union d2i @{ double d; int i[2]; @};
1091 union d2i *p = (union d2i *) unaligned_ptr;
1102 Storing into the pointer can be done likewise with the same union.
1105 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
1106 may allocate memory that is only 4 byte aligned. Since GCC on the
1107 Sparc assumes that doubles are 8 byte aligned, this may result in a
1108 fatal signal if doubles are stored in memory allocated by the
1109 @file{libmalloc.a} library.
1111 The solution is to not use the @file{libmalloc.a} library. Use instead
1112 @code{malloc} and related functions from @file{libc.a}; they do not have
1116 Sun forgot to include a static version of @file{libdl.a} with some
1117 versions of SunOS (mainly 4.1). This results in undefined symbols when
1118 linking static binaries (that is, if you use @samp{-static}). If you
1119 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
1120 when linking, compile and link against the file
1121 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
1124 The 128-bit long double format that the Sparc port supports currently
1125 works by using the architecturally defined quad-word floating point
1126 instructions. Since there is no hardware that supports these
1127 instructions they must be emulated by the operating system. Long
1128 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
1129 kernel emulator uses an obsolete and incompatible format. Long doubles
1130 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
1131 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
1132 does not enable them by default. Long doubles appear to work in Sun OS
1136 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
1137 compile GCC correctly. We do not yet know why. However, GCC
1138 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
1139 compile itself properly on 9.01.
1142 On the HP PA machine, ADB sometimes fails to work on functions compiled
1143 with GCC. Specifically, it fails to work on functions that use
1144 @code{alloca} or variable-size arrays. This is because GCC doesn't
1145 generate HP-UX unwind descriptors for such functions. It may even be
1146 impossible to generate them.
1149 Debugging (@samp{-g}) is not supported on the HP PA machine, unless you use
1150 the preliminary GNU tools (@pxref{Installation}).
1153 Taking the address of a label may generate errors from the HP-UX
1154 PA assembler. GAS for the PA does not have this problem.
1157 Using floating point parameters for indirect calls to static functions
1158 will not work when using the HP assembler. There simply is no way for GCC
1159 to specify what registers hold arguments for static functions when using
1160 the HP assembler. GAS for the PA does not have this problem.
1163 In extremely rare cases involving some very large functions you may
1164 receive errors from the HP linker complaining about an out of bounds
1165 unconditional branch offset. This used to occur more often in previous
1166 versions of GCC, but is now exceptionally rare. If you should run
1167 into it, you can work around by making your function smaller.
1170 GCC compiled code sometimes emits warnings from the HP-UX assembler of
1174 (warning) Use of GR3 when
1175 frame >= 8192 may cause conflict.
1178 These warnings are harmless and can be safely ignored.
1181 The current version of the assembler (@file{/bin/as}) for the RS/6000
1182 has certain problems that prevent the @samp{-g} option in GCC from
1183 working. Note that @file{Makefile.in} uses @samp{-g} by default when
1184 compiling @file{libgcc2.c}.
1186 IBM has produced a fixed version of the assembler. The upgraded
1187 assembler unfortunately was not included in any of the AIX 3.2 update
1188 PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request
1189 PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
1190 See the file @file{README.RS6000} for more details on these updates.
1192 You can test for the presence of a fixed assembler by using the
1200 If the command exits normally, the assembler fix already is installed.
1201 If the assembler complains that "-u" is an unknown flag, you need to
1205 On the IBM RS/6000, compiling code of the form
1216 will cause the linker to report an undefined symbol @code{foo}.
1217 Although this behavior differs from most other systems, it is not a
1218 bug because redefining an @code{extern} variable as @code{static}
1219 is undefined in ISO C.
1222 AIX on the RS/6000 provides support (NLS) for environments outside of
1223 the United States. Compilers and assemblers use NLS to support
1224 locale-specific representations of various objects including
1225 floating-point numbers ("." vs "," for separating decimal fractions).
1226 There have been problems reported where the library linked with GCC does
1227 not produce the same floating-point formats that the assembler accepts.
1228 If you have this problem, set the LANG environment variable to "C" or
1232 Even if you specify @samp{-fdollars-in-identifiers},
1233 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
1234 to a restriction in the IBM assembler. GAS supports these
1238 On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC
1239 version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2
1240 by requesting PTF 421749 from IBM.
1243 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
1244 occurs when the @samp{fldcr} instruction is used. GCC uses
1245 @samp{fldcr} on the 88100 to serialize volatile memory references. Use
1246 the option @samp{-mno-serialize-volatile} if your version of the
1247 assembler has this bug.
1250 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
1251 messages from the linker. These warning messages complain of mismatched
1252 psect attributes. You can ignore them. @xref{VMS Install}.
1255 On NewsOS version 3, if you include both of the files @file{stddef.h}
1256 and @file{sys/types.h}, you get an error because there are two typedefs
1257 of @code{size_t}. You should change @file{sys/types.h} by adding these
1258 lines around the definition of @code{size_t}:
1263 @var{actual typedef here}
1269 On the Alliant, the system's own convention for returning structures
1270 and unions is unusual, and is not compatible with GCC no matter
1271 what options are used.
1276 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
1277 convention for structure and union returning. Use the option
1278 @samp{-mhc-struct-return} to tell GCC to use a convention compatible
1281 @cindex Vax calling convention
1282 @cindex Ultrix calling convention
1284 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
1285 by function calls. However, the C compiler uses conventions compatible
1286 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
1288 GCC uses the same convention as the Ultrix C compiler. You can use
1289 these options to produce code compatible with the Fortran compiler:
1292 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
1296 On the WE32k, you may find that programs compiled with GCC do not
1297 work with the standard shared C library. You may need to link with
1298 the ordinary C compiler. If you do so, you must specify the following
1302 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
1305 The first specifies where to find the library @file{libgcc.a}
1306 specified with the @samp{-lgcc} option.
1308 GCC does linking by invoking @code{ld}, just as @code{cc} does, and
1309 there is no reason why it @emph{should} matter which compilation program
1310 you use to invoke @code{ld}. If someone tracks this problem down,
1311 it can probably be fixed easily.
1314 On the Alpha, you may get assembler errors about invalid syntax as a
1315 result of floating point constants. This is due to a bug in the C
1316 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid
1317 floating point numbers, they sometimes print @samp{NaN}.
1320 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
1321 sometimes reorders instructions incorrectly when optimization is turned
1322 on. If you think this may be happening to you, try using the GNU
1323 assembler; GAS version 2.1 supports ECOFF on Irix.
1325 Or use the @samp{-noasmopt} option when you compile GCC with itself,
1326 and then again when you compile your program. (This is a temporary
1327 kludge to turn off assembler optimization on Irix.) If this proves to
1328 be what you need, edit the assembler spec in the file @file{specs} so
1329 that it unconditionally passes @samp{-O0} to the assembler, and never
1330 passes @samp{-O2} or @samp{-O3}.
1334 @section Problems Compiling Certain Programs
1336 @c prevent bad page break with this line
1337 Certain programs have problems compiling.
1341 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
1342 because of problems in DEC's versions of the X11 header files
1343 @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
1344 @samp{-I/usr/include/mit} to use the MIT versions of the header files,
1345 using the @samp{-traditional} switch to turn off ISO C, or fixing the
1346 header files by adding this:
1350 #define NeedFunctionPrototypes 0
1355 On various 386 Unix systems derived from System V, including SCO, ISC,
1356 and ESIX, you may get error messages about running out of virtual memory
1357 while compiling certain programs.
1359 You can prevent this problem by linking GCC with the GNU malloc
1360 (which thus replaces the malloc that comes with the system). GNU malloc
1361 is available as a separate package, and also in the file
1362 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
1364 If you have installed GNU malloc as a separate library package, use this
1365 option when you relink GCC:
1368 MALLOC=/usr/local/lib/libgmalloc.a
1371 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
1372 the object file to @file{gmalloc.o} and use this option when you relink
1380 @node Incompatibilities
1381 @section Incompatibilities of GCC
1382 @cindex incompatibilities of GCC
1384 There are several noteworthy incompatibilities between GNU C and K&R
1385 (non-ISO) versions of C. The @samp{-traditional} option
1386 eliminates many of these incompatibilities, @emph{but not all}, by
1387 telling GNU C to behave like a K&R C compiler.
1390 @cindex string constants
1391 @cindex read-only strings
1392 @cindex shared strings
1394 GCC normally makes string constants read-only. If several
1395 identical-looking string constants are used, GCC stores only one
1398 @cindex @code{mktemp}, and constant strings
1399 One consequence is that you cannot call @code{mktemp} with a string
1400 constant argument. The function @code{mktemp} always alters the
1401 string its argument points to.
1403 @cindex @code{sscanf}, and constant strings
1404 @cindex @code{fscanf}, and constant strings
1405 @cindex @code{scanf}, and constant strings
1406 Another consequence is that @code{sscanf} does not work on some systems
1407 when passed a string constant as its format control string or input.
1408 This is because @code{sscanf} incorrectly tries to write into the string
1409 constant. Likewise @code{fscanf} and @code{scanf}.
1411 The best solution to these problems is to change the program to use
1412 @code{char}-array variables with initialization strings for these
1413 purposes instead of string constants. But if this is not possible,
1414 you can use the @samp{-fwritable-strings} flag, which directs GCC
1415 to handle string constants the same way most C compilers do.
1416 @samp{-traditional} also has this effect, among others.
1419 @code{-2147483648} is positive.
1421 This is because 2147483648 cannot fit in the type @code{int}, so
1422 (following the ISO C rules) its data type is @code{unsigned long int}.
1423 Negating this value yields 2147483648 again.
1426 GCC does not substitute macro arguments when they appear inside of
1427 string constants. For example, the following macro in GCC
1434 will produce output @code{"a"} regardless of what the argument @var{a} is.
1436 The @samp{-traditional} option directs GCC to handle such cases
1437 (among others) in the old-fashioned (non-ISO) fashion.
1439 @cindex @code{setjmp} incompatibilities
1440 @cindex @code{longjmp} incompatibilities
1442 When you use @code{setjmp} and @code{longjmp}, the only automatic
1443 variables guaranteed to remain valid are those declared
1444 @code{volatile}. This is a consequence of automatic register
1445 allocation. Consider this function:
1459 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
1464 Here @code{a} may or may not be restored to its first value when the
1465 @code{longjmp} occurs. If @code{a} is allocated in a register, then
1466 its first value is restored; otherwise, it keeps the last value stored
1469 If you use the @samp{-W} option with the @samp{-O} option, you will
1470 get a warning when GCC thinks such a problem might be possible.
1472 The @samp{-traditional} option directs GNU C to put variables in
1473 the stack by default, rather than in registers, in functions that
1474 call @code{setjmp}. This results in the behavior found in
1475 traditional C compilers.
1478 Programs that use preprocessing directives in the middle of macro
1479 arguments do not work with GCC. For example, a program like this
1488 ISO C does not permit such a construct. It would make sense to support
1489 it when @samp{-traditional} is used, but it is too much work to
1493 K&R compilers allow comments to cross over an inclusion boundary (i.e.
1494 started in an include file and ended in the including file). I think
1495 this would be quite ugly and can't imagine it could be needed.
1497 @cindex external declaration scope
1498 @cindex scope of external declarations
1499 @cindex declaration scope
1501 Declarations of external variables and functions within a block apply
1502 only to the block containing the declaration. In other words, they
1503 have the same scope as any other declaration in the same place.
1505 In some other C compilers, a @code{extern} declaration affects all the
1506 rest of the file even if it happens within a block.
1508 The @samp{-traditional} option directs GNU C to treat all @code{extern}
1509 declarations as global, like traditional compilers.
1512 In traditional C, you can combine @code{long}, etc., with a typedef name,
1517 typedef long foo bar;
1520 In ISO C, this is not allowed: @code{long} and other type modifiers
1521 require an explicit @code{int}. Because this criterion is expressed
1522 by Bison grammar rules rather than C code, the @samp{-traditional}
1523 flag cannot alter it.
1525 @cindex typedef names as function parameters
1527 PCC allows typedef names to be used as function parameters. The
1528 difficulty described immediately above applies here too.
1531 When in @samp{-traditional} mode, GCC allows the following erroneous
1532 pair of declarations to appear together in a given scope:
1540 GCC treats all characters of identifiers as significant, even when in
1541 @samp{-traditional} mode. According to K&R-1 (2.2), ``No more than the
1542 first eight characters are significant, although more may be used.''.
1543 Also according to K&R-1 (2.2), ``An identifier is a sequence of letters
1544 and digits; the first character must be a letter. The underscore _
1545 counts as a letter.'', but GCC also allows dollar signs in identifiers.
1549 PCC allows whitespace in the middle of compound assignment operators
1550 such as @samp{+=}. GCC, following the ISO standard, does not
1551 allow this. The difficulty described immediately above applies here
1557 GCC complains about unterminated character constants inside of
1558 preprocessing conditionals that fail. Some programs have English
1559 comments enclosed in conditionals that are guaranteed to fail; if these
1560 comments contain apostrophes, GCC will probably report an error. For
1561 example, this code would produce an error:
1565 You can't expect this to work.
1569 The best solution to such a problem is to put the text into an actual
1570 C comment delimited by @samp{/*@dots{}*/}. However,
1571 @samp{-traditional} suppresses these error messages.
1574 Many user programs contain the declaration @samp{long time ();}. In the
1575 past, the system header files on many systems did not actually declare
1576 @code{time}, so it did not matter what type your program declared it to
1577 return. But in systems with ISO C headers, @code{time} is declared to
1578 return @code{time_t}, and if that is not the same as @code{long}, then
1579 @samp{long time ();} is erroneous.
1581 The solution is to change your program to use appropriate system headers
1582 (@code{<time.h>} on systems with ISO C headers) and not to declare
1583 @code{time} if the system header files declare it, or failing that to
1584 use @code{time_t} as the return type of @code{time}.
1586 @cindex @code{float} as function value type
1588 When compiling functions that return @code{float}, PCC converts it to
1589 a double. GCC actually returns a @code{float}. If you are concerned
1590 with PCC compatibility, you should declare your functions to return
1591 @code{double}; you might as well say what you mean.
1596 When compiling functions that return structures or unions, GCC
1597 output code normally uses a method different from that used on most
1598 versions of Unix. As a result, code compiled with GCC cannot call
1599 a structure-returning function compiled with PCC, and vice versa.
1601 The method used by GCC is as follows: a structure or union which is
1602 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
1603 with any other size is stored into an address supplied by the caller
1604 (usually in a special, fixed register, but on some machines it is passed
1605 on the stack). The machine-description macros @code{STRUCT_VALUE} and
1606 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
1608 By contrast, PCC on most target machines returns structures and unions
1609 of any size by copying the data into an area of static storage, and then
1610 returning the address of that storage as if it were a pointer value.
1611 The caller must copy the data from that memory area to the place where
1612 the value is wanted. GCC does not use this method because it is
1613 slower and nonreentrant.
1615 On some newer machines, PCC uses a reentrant convention for all
1616 structure and union returning. GCC on most of these machines uses a
1617 compatible convention when returning structures and unions in memory,
1618 but still returns small structures and unions in registers.
1620 You can tell GCC to use a compatible convention for all structure and
1621 union returning with the option @samp{-fpcc-struct-return}.
1623 @cindex preprocessing tokens
1624 @cindex preprocessing numbers
1626 GNU C complains about program fragments such as @samp{0x74ae-0x4000}
1627 which appear to be two hexadecimal constants separated by the minus
1628 operator. Actually, this string is a single @dfn{preprocessing token}.
1629 Each such token must correspond to one token in C. Since this does not,
1630 GNU C prints an error message. Although it may appear obvious that what
1631 is meant is an operator and two values, the ISO C standard specifically
1632 requires that this be treated as erroneous.
1634 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
1635 begins with a digit and is followed by letters, underscores, digits,
1636 periods and @samp{e+}, @samp{e-}, @samp{E+}, or @samp{E-} character
1639 To make the above program fragment valid, place whitespace in front of
1640 the minus sign. This whitespace will end the preprocessing number.
1644 @section Fixed Header Files
1646 GCC needs to install corrected versions of some system header files.
1647 This is because most target systems have some header files that won't
1648 work with GCC unless they are changed. Some have bugs, some are
1649 incompatible with ISO C, and some depend on special features of other
1652 Installing GCC automatically creates and installs the fixed header
1653 files, by running a program called @code{fixincludes} (or for certain
1654 targets an alternative such as @code{fixinc.svr4}). Normally, you
1655 don't need to pay attention to this. But there are cases where it
1656 doesn't do the right thing automatically.
1660 If you update the system's header files, such as by installing a new
1661 system version, the fixed header files of GCC are not automatically
1662 updated. The easiest way to update them is to reinstall GCC. (If
1663 you want to be clever, look in the makefile and you can find a
1667 On some systems, in particular SunOS 4, header file directories contain
1668 machine-specific symbolic links in certain places. This makes it
1669 possible to share most of the header files among hosts running the
1670 same version of SunOS 4 on different machine models.
1672 The programs that fix the header files do not understand this special
1673 way of using symbolic links; therefore, the directory of fixed header
1674 files is good only for the machine model used to build it.
1676 In SunOS 4, only programs that look inside the kernel will notice the
1677 difference between machine models. Therefore, for most purposes, you
1678 need not be concerned about this.
1680 It is possible to make separate sets of fixed header files for the
1681 different machine models, and arrange a structure of symbolic links so
1682 as to use the proper set, but you'll have to do this by hand.
1685 On Lynxos, GCC by default does not fix the header files. This is
1686 because bugs in the shell cause the @code{fixincludes} script to fail.
1688 This means you will encounter problems due to bugs in the system header
1689 files. It may be no comfort that they aren't GCC's fault, but it
1690 does mean that there's nothing for us to do about them.
1693 @node Standard Libraries
1694 @section Standard Libraries
1696 GCC by itself attempts to be a conforming freestanding implementation.
1697 @xref{Standards,,Language Standards Supported by GCC}, for details of
1698 what this means. Beyond the library facilities required of such an
1699 implementation, the rest of the C library is supplied by the vendor of
1700 the operating system. If that C library doesn't conform to the C
1701 standards, then your programs might get warnings (especially when using
1702 @samp{-Wall}) that you don't expect.
1704 For example, the @code{sprintf} function on SunOS 4.1.3 returns
1705 @code{char *} while the C standard says that @code{sprintf} returns an
1706 @code{int}. The @code{fixincludes} program could make the prototype for
1707 this function match the Standard, but that would be wrong, since the
1708 function will still return @code{char *}.
1710 If you need a Standard compliant library, then you need to find one, as
1711 GCC does not provide one. The GNU C library (called @code{glibc})
1712 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
1713 GNU/Linux and HURD-based GNU systems; no recent version of it supports
1714 other systems, though some very old versions did. Version 2.2 of the
1715 GNU C library includes nearly complete C99 support. You could also ask
1716 your operating system vendor if newer libraries are available.
1718 @node Disappointments
1719 @section Disappointments and Misunderstandings
1721 These problems are perhaps regrettable, but we don't know any practical
1726 Certain local variables aren't recognized by debuggers when you compile
1729 This occurs because sometimes GCC optimizes the variable out of
1730 existence. There is no way to tell the debugger how to compute the
1731 value such a variable ``would have had'', and it is not clear that would
1732 be desirable anyway. So GCC simply does not mention the eliminated
1733 variable when it writes debugging information.
1735 You have to expect a certain amount of disagreement between the
1736 executable and your source code, when you use optimization.
1738 @cindex conflicting types
1739 @cindex scope of declaration
1741 Users often think it is a bug when GCC reports an error for code
1745 int foo (struct mumble *);
1747 struct mumble @{ @dots{} @};
1749 int foo (struct mumble *x)
1753 This code really is erroneous, because the scope of @code{struct
1754 mumble} in the prototype is limited to the argument list containing it.
1755 It does not refer to the @code{struct mumble} defined with file scope
1756 immediately below---they are two unrelated types with similar names in
1759 But in the definition of @code{foo}, the file-scope type is used
1760 because that is available to be inherited. Thus, the definition and
1761 the prototype do not match, and you get an error.
1763 This behavior may seem silly, but it's what the ISO standard specifies.
1764 It is easy enough for you to make your code work by moving the
1765 definition of @code{struct mumble} above the prototype. It's not worth
1766 being incompatible with ISO C just to avoid an error for the example
1770 Accesses to bitfields even in volatile objects works by accessing larger
1771 objects, such as a byte or a word. You cannot rely on what size of
1772 object is accessed in order to read or write the bitfield; it may even
1773 vary for a given bitfield according to the precise usage.
1775 If you care about controlling the amount of memory that is accessed, use
1776 volatile but do not use bitfields.
1779 GCC comes with shell scripts to fix certain known problems in system
1780 header files. They install corrected copies of various header files in
1781 a special directory where only GCC will normally look for them. The
1782 scripts adapt to various systems by searching all the system header
1783 files for the problem cases that we know about.
1785 If new system header files are installed, nothing automatically arranges
1786 to update the corrected header files. You will have to reinstall GCC
1787 to fix the new header files. More specifically, go to the build
1788 directory and delete the files @file{stmp-fixinc} and
1789 @file{stmp-headers}, and the subdirectory @code{include}; then do
1790 @samp{make install} again.
1793 @cindex floating point precision
1794 On 68000 and x86 systems, for instance, you can get paradoxical results
1795 if you test the precise values of floating point numbers. For example,
1796 you can find that a floating point value which is not a NaN is not equal
1797 to itself. This results from the fact that the floating point registers
1798 hold a few more bits of precision than fit in a @code{double} in memory.
1799 Compiled code moves values between memory and floating point registers
1800 at its convenience, and moving them into memory truncates them.
1802 You can partially avoid this problem by using the @samp{-ffloat-store}
1803 option (@pxref{Optimize Options}).
1806 On the MIPS, variable argument functions using @file{varargs.h}
1807 cannot have a floating point value for the first argument. The
1808 reason for this is that in the absence of a prototype in scope,
1809 if the first argument is a floating point, it is passed in a
1810 floating point register, rather than an integer register.
1812 If the code is rewritten to use the ISO standard @file{stdarg.h}
1813 method of variable arguments, and the prototype is in scope at
1814 the time of the call, everything will work fine.
1817 On the H8/300 and H8/300H, variable argument functions must be
1818 implemented using the ISO standard @file{stdarg.h} method of
1819 variable arguments. Furthermore, calls to functions using @file{stdarg.h}
1820 variable arguments must have a prototype for the called function
1821 in scope at the time of the call.
1824 @node C++ Misunderstandings
1825 @section Common Misunderstandings with GNU C++
1827 @cindex misunderstandings in C++
1828 @cindex surprises in C++
1829 @cindex C++ misunderstandings
1830 C++ is a complex language and an evolving one, and its standard
1831 definition (the ISO C++ standard) was only recently completed. As a
1832 result, your C++ compiler may occasionally surprise you, even when its
1833 behavior is correct. This section discusses some areas that frequently
1834 give rise to questions of this sort.
1837 * Static Definitions:: Static member declarations are not definitions
1838 * Temporaries:: Temporaries may vanish before you expect
1839 * Copy Assignment:: Copy Assignment operators copy virtual bases twice
1842 @node Static Definitions
1843 @subsection Declare @emph{and} Define Static Members
1845 @cindex C++ static data, declaring and defining
1846 @cindex static data in C++, declaring and defining
1847 @cindex declaring static data in C++
1848 @cindex defining static data in C++
1849 When a class has static data members, it is not enough to @emph{declare}
1850 the static member; you must also @emph{define} it. For example:
1861 This declaration only establishes that the class @code{Foo} has an
1862 @code{int} named @code{Foo::bar}, and a member function named
1863 @code{Foo::method}. But you still need to define @emph{both}
1864 @code{method} and @code{bar} elsewhere. According to the ISO
1865 standard, you must supply an initializer in one (and only one) source
1872 Other C++ compilers may not correctly implement the standard behavior.
1873 As a result, when you switch to @code{g++} from one of these compilers,
1874 you may discover that a program that appeared to work correctly in fact
1875 does not conform to the standard: @code{g++} reports as undefined
1876 symbols any static data members that lack definitions.
1879 @subsection Temporaries May Vanish Before You Expect
1881 @cindex temporaries, lifetime of
1882 @cindex portions of temporary objects, pointers to
1883 It is dangerous to use pointers or references to @emph{portions} of a
1884 temporary object. The compiler may very well delete the object before
1885 you expect it to, leaving a pointer to garbage. The most common place
1886 where this problem crops up is in classes like string classes,
1887 especially ones that define a conversion function to type @code{char *}
1888 or @code{const char *} -- which is one reason why the standard
1889 @code{string} class requires you to call the @code{c_str} member
1890 function. However, any class that returns a pointer to some internal
1891 structure is potentially subject to this problem.
1893 For example, a program may use a function @code{strfunc} that returns
1894 @code{string} objects, and another function @code{charfunc} that
1895 operates on pointers to @code{char}:
1899 void charfunc (const char *);
1904 const char *p = strfunc().c_str();
1913 In this situation, it may seem reasonable to save a pointer to the C
1914 string returned by the @code{c_str} member function and use that rather
1915 than call @code{c_str} repeatedly. However, the temporary string
1916 created by the call to @code{strfunc} is destroyed after @code{p} is
1917 initialized, at which point @code{p} is left pointing to freed memory.
1919 Code like this may run successfully under some other compilers,
1920 particularly obsolete cfront-based compilers that delete temporaries
1921 along with normal local variables. However, the GNU C++ behavior is
1922 standard-conforming, so if your program depends on late destruction of
1923 temporaries it is not portable.
1925 The safe way to write such code is to give the temporary a name, which
1926 forces it to remain until the end of the scope of the name. For
1930 string& tmp = strfunc ();
1931 charfunc (tmp.c_str ());
1934 @node Copy Assignment
1935 @subsection Implicit Copy-Assignment for Virtual Bases
1937 When a base class is virtual, only one subobject of the base class
1938 belongs to each full object. Also, the constructors and destructors are
1939 invoked only once, and called from the most-derived class. However, such
1940 objects behave unspecified when being assigned. For example:
1945 Base(char *n) : name(strdup(n))@{@}
1946 Base& operator= (const Base& other)@{
1948 name = strdup (other.name);
1952 struct A:virtual Base@{
1957 struct B:virtual Base@{
1962 struct Derived:public A, public B@{
1963 Derived():Base("Derived")@{@}
1966 void func(Derived &d1, Derived &d2)
1972 The C++ standard specifies that @samp{Base::Base} is only called once
1973 when constructing or copy-constructing a Derived object. It is
1974 unspecified whether @samp{Base::operator=} is called more than once when
1975 the implicit copy-assignment for Derived objects is invoked (as it is
1976 inside @samp{func} in the example).
1978 g++ implements the "intuitive" algorithm for copy-assignment: assign all
1979 direct bases, then assign all members. In that algorithm, the virtual
1980 base subobject can be encountered many times. In the example, copying
1981 proceeds in the following order: @samp{val}, @samp{name} (via
1982 @code{strdup}), @samp{bval}, and @samp{name} again.
1984 If application code relies on copy-assignment, a user-defined
1985 copy-assignment operator removes any uncertainties. With such an
1986 operator, the application can define whether and how the virtual base
1987 subobject is assigned.
1989 @node Protoize Caveats
1990 @section Caveats of using @code{protoize}
1992 The conversion programs @code{protoize} and @code{unprotoize} can
1993 sometimes change a source file in a way that won't work unless you
1998 @code{protoize} can insert references to a type name or type tag before
1999 the definition, or in a file where they are not defined.
2001 If this happens, compiler error messages should show you where the new
2002 references are, so fixing the file by hand is straightforward.
2005 There are some C constructs which @code{protoize} cannot figure out.
2006 For example, it can't determine argument types for declaring a
2007 pointer-to-function variable; this you must do by hand. @code{protoize}
2008 inserts a comment containing @samp{???} each time it finds such a
2009 variable; so you can find all such variables by searching for this
2010 string. ISO C does not require declaring the argument types of
2011 pointer-to-function types.
2014 Using @code{unprotoize} can easily introduce bugs. If the program
2015 relied on prototypes to bring about conversion of arguments, these
2016 conversions will not take place in the program without prototypes.
2017 One case in which you can be sure @code{unprotoize} is safe is when
2018 you are removing prototypes that were made with @code{protoize}; if
2019 the program worked before without any prototypes, it will work again
2022 You can find all the places where this problem might occur by compiling
2023 the program with the @samp{-Wconversion} option. It prints a warning
2024 whenever an argument is converted.
2027 Both conversion programs can be confused if there are macro calls in and
2028 around the text to be converted. In other words, the standard syntax
2029 for a declaration or definition must not result from expanding a macro.
2030 This problem is inherent in the design of C and cannot be fixed. If
2031 only a few functions have confusing macro calls, you can easily convert
2035 @code{protoize} cannot get the argument types for a function whose
2036 definition was not actually compiled due to preprocessing conditionals.
2037 When this happens, @code{protoize} changes nothing in regard to such
2038 a function. @code{protoize} tries to detect such instances and warn
2041 You can generally work around this problem by using @code{protoize} step
2042 by step, each time specifying a different set of @samp{-D} options for
2043 compilation, until all of the functions have been converted. There is
2044 no automatic way to verify that you have got them all, however.
2047 Confusion may result if there is an occasion to convert a function
2048 declaration or definition in a region of source code where there is more
2049 than one formal parameter list present. Thus, attempts to convert code
2050 containing multiple (conditionally compiled) versions of a single
2051 function header (in the same vicinity) may not produce the desired (or
2054 If you plan on converting source files which contain such code, it is
2055 recommended that you first make sure that each conditionally compiled
2056 region of source code which contains an alternative function header also
2057 contains at least one additional follower token (past the final right
2058 parenthesis of the function header). This should circumvent the
2062 @code{unprotoize} can become confused when trying to convert a function
2063 definition or declaration which contains a declaration for a
2064 pointer-to-function formal argument which has the same name as the
2065 function being defined or declared. We recommend you avoid such choices
2066 of formal parameter names.
2069 You might also want to correct some of the indentation by hand and break
2070 long lines. (The conversion programs don't write lines longer than
2071 eighty characters in any case.)
2075 @section Certain Changes We Don't Want to Make
2077 This section lists changes that people frequently request, but which
2078 we do not make because we think GCC is better without them.
2082 Checking the number and type of arguments to a function which has an
2083 old-fashioned definition and no prototype.
2085 Such a feature would work only occasionally---only for calls that appear
2086 in the same file as the called function, following the definition. The
2087 only way to check all calls reliably is to add a prototype for the
2088 function. But adding a prototype eliminates the motivation for this
2089 feature. So the feature is not worthwhile.
2092 Warning about using an expression whose type is signed as a shift count.
2094 Shift count operands are probably signed more often than unsigned.
2095 Warning about this would cause far more annoyance than good.
2098 Warning about assigning a signed value to an unsigned variable.
2100 Such assignments must be very common; warning about them would cause
2101 more annoyance than good.
2104 Warning when a non-void function value is ignored.
2106 Coming as I do from a Lisp background, I balk at the idea that there is
2107 something dangerous about discarding a value. There are functions that
2108 return values which some callers may find useful; it makes no sense to
2109 clutter the program with a cast to @code{void} whenever the value isn't
2113 Assuming (for optimization) that the address of an external symbol is
2116 This assumption is false on certain systems when @samp{#pragma weak} is
2120 Making @samp{-fshort-enums} the default.
2122 This would cause storage layout to be incompatible with most other C
2123 compilers. And it doesn't seem very important, given that you can get
2124 the same result in other ways. The case where it matters most is when
2125 the enumeration-valued object is inside a structure, and in that case
2126 you can specify a field width explicitly.
2129 Making bitfields unsigned by default on particular machines where ``the
2130 ABI standard'' says to do so.
2132 The ISO C standard leaves it up to the implementation whether a bitfield
2133 declared plain @code{int} is signed or not. This in effect creates two
2134 alternative dialects of C.
2136 The GNU C compiler supports both dialects; you can specify the signed
2137 dialect with @samp{-fsigned-bitfields} and the unsigned dialect with
2138 @samp{-funsigned-bitfields}. However, this leaves open the question of
2139 which dialect to use by default.
2141 Currently, the preferred dialect makes plain bitfields signed, because
2142 this is simplest. Since @code{int} is the same as @code{signed int} in
2143 every other context, it is cleanest for them to be the same in bitfields
2146 Some computer manufacturers have published Application Binary Interface
2147 standards which specify that plain bitfields should be unsigned. It is
2148 a mistake, however, to say anything about this issue in an ABI. This is
2149 because the handling of plain bitfields distinguishes two dialects of C.
2150 Both dialects are meaningful on every type of machine. Whether a
2151 particular object file was compiled using signed bitfields or unsigned
2152 is of no concern to other object files, even if they access the same
2153 bitfields in the same data structures.
2155 A given program is written in one or the other of these two dialects.
2156 The program stands a chance to work on most any machine if it is
2157 compiled with the proper dialect. It is unlikely to work at all if
2158 compiled with the wrong dialect.
2160 Many users appreciate the GNU C compiler because it provides an
2161 environment that is uniform across machines. These users would be
2162 inconvenienced if the compiler treated plain bitfields differently on
2165 Occasionally users write programs intended only for a particular machine
2166 type. On these occasions, the users would benefit if the GNU C compiler
2167 were to support by default the same dialect as the other compilers on
2168 that machine. But such applications are rare. And users writing a
2169 program to run on more than one type of machine cannot possibly benefit
2170 from this kind of compatibility.
2172 This is why GCC does and will treat plain bitfields in the same
2173 fashion on all types of machines (by default).
2175 There are some arguments for making bitfields unsigned by default on all
2176 machines. If, for example, this becomes a universal de facto standard,
2177 it would make sense for GCC to go along with it. This is something
2178 to be considered in the future.
2180 (Of course, users strongly concerned about portability should indicate
2181 explicitly in each bitfield whether it is signed or not. In this way,
2182 they write programs which have the same meaning in both C dialects.)
2185 Undefining @code{__STDC__} when @samp{-ansi} is not used.
2187 Currently, GCC defines @code{__STDC__} as long as you don't use
2188 @samp{-traditional}. This provides good results in practice.
2190 Programmers normally use conditionals on @code{__STDC__} to ask whether
2191 it is safe to use certain features of ISO C, such as function
2192 prototypes or ISO token concatenation. Since plain @samp{gcc} supports
2193 all the features of ISO C, the correct answer to these questions is
2196 Some users try to use @code{__STDC__} to check for the availability of
2197 certain library facilities. This is actually incorrect usage in an ISO
2198 C program, because the ISO C standard says that a conforming
2199 freestanding implementation should define @code{__STDC__} even though it
2200 does not have the library facilities. @samp{gcc -ansi -pedantic} is a
2201 conforming freestanding implementation, and it is therefore required to
2202 define @code{__STDC__}, even though it does not come with an ISO C
2205 Sometimes people say that defining @code{__STDC__} in a compiler that
2206 does not completely conform to the ISO C standard somehow violates the
2207 standard. This is illogical. The standard is a standard for compilers
2208 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
2209 compilers such as plain @samp{gcc}. Whatever the ISO C standard says
2210 is relevant to the design of plain @samp{gcc} without @samp{-ansi} only
2211 for pragmatic reasons, not as a requirement.
2213 GCC normally defines @code{__STDC__} to be 1, and in addition
2214 defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
2215 or a @option{-std} option for strict conformance to some version of ISO C.
2216 On some hosts, system include files use a different convention, where
2217 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
2218 conformance to the C Standard. GCC follows the host convention when
2219 processing system include files, but when processing user files it follows
2220 the usual GNU C convention.
2223 Undefining @code{__STDC__} in C++.
2225 Programs written to compile with C++-to-C translators get the
2226 value of @code{__STDC__} that goes with the C compiler that is
2227 subsequently used. These programs must test @code{__STDC__}
2228 to determine what kind of C preprocessor that compiler uses:
2229 whether they should concatenate tokens in the ISO C fashion
2230 or in the traditional fashion.
2232 These programs work properly with GNU C++ if @code{__STDC__} is defined.
2233 They would not work otherwise.
2235 In addition, many header files are written to provide prototypes in ISO
2236 C but not in traditional C. Many of these header files can work without
2237 change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
2238 is not defined, they will all fail, and will all need to be changed to
2239 test explicitly for C++ as well.
2242 Deleting ``empty'' loops.
2244 Historically, GCC has not deleted ``empty'' loops under the
2245 assumption that the most likely reason you would put one in a program is
2246 to have a delay, so deleting them will not make real programs run any
2249 However, the rationale here is that optimization of a nonempty loop
2250 cannot produce an empty one, which holds for C but is not always the
2253 Moreover, with @samp{-funroll-loops} small ``empty'' loops are already
2254 removed, so the current behavior is both sub-optimal and inconsistent
2255 and will change in the future.
2258 Making side effects happen in the same order as in some other compiler.
2260 @cindex side effects, order of evaluation
2261 @cindex order of evaluation, side effects
2262 It is never safe to depend on the order of evaluation of side effects.
2263 For example, a function call like this may very well behave differently
2264 from one compiler to another:
2267 void func (int, int);
2273 There is no guarantee (in either the C or the C++ standard language
2274 definitions) that the increments will be evaluated in any particular
2275 order. Either increment might happen first. @code{func} might get the
2276 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
2279 Not allowing structures with volatile fields in registers.
2281 Strictly speaking, there is no prohibition in the ISO C standard
2282 against allowing structures with volatile fields in registers, but
2283 it does not seem to make any sense and is probably not what you wanted
2284 to do. So the compiler will give an error message in this case.
2287 Making certain warnings into errors by default.
2289 Some ISO C testsuites report failure when the compiler does not produce
2290 an error message for a certain program.
2292 ISO C requires a ``diagnostic'' message for certain kinds of invalid
2293 programs, but a warning is defined by GCC to count as a diagnostic. If
2294 GCC produces a warning but not an error, that is correct ISO C support.
2295 If test suites call this ``failure'', they should be run with the GCC
2296 option @samp{-pedantic-errors}, which will turn these warnings into
2301 @node Warnings and Errors
2302 @section Warning Messages and Error Messages
2304 @cindex error messages
2305 @cindex warnings vs errors
2306 @cindex messages, warning and error
2307 The GNU compiler can produce two kinds of diagnostics: errors and
2308 warnings. Each kind has a different purpose:
2312 @emph{Errors} report problems that make it impossible to compile your
2313 program. GCC reports errors with the source file name and line
2314 number where the problem is apparent.
2317 @emph{Warnings} report other unusual conditions in your code that
2318 @emph{may} indicate a problem, although compilation can (and does)
2319 proceed. Warning messages also report the source file name and line
2320 number, but include the text @samp{warning:} to distinguish them
2321 from error messages.
2324 Warnings may indicate danger points where you should check to make sure
2325 that your program really does what you intend; or the use of obsolete
2326 features; or the use of nonstandard features of GNU C or C++. Many
2327 warnings are issued only if you ask for them, with one of the @samp{-W}
2328 options (for instance, @samp{-Wall} requests a variety of useful
2331 GCC always tries to compile your program if possible; it never
2332 gratuitously rejects a program whose meaning is clear merely because
2333 (for instance) it fails to conform to a standard. In some cases,
2334 however, the C and C++ standards specify that certain extensions are
2335 forbidden, and a diagnostic @emph{must} be issued by a conforming
2336 compiler. The @samp{-pedantic} option tells GCC to issue warnings in
2337 such cases; @samp{-pedantic-errors} says to make them errors instead.
2338 This does not mean that @emph{all} non-ISO constructs get warnings
2341 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
2342 more detail on these and related command-line options.
2345 @chapter Reporting Bugs
2347 @cindex reporting bugs
2349 Your bug reports play an essential role in making GCC reliable.
2351 When you encounter a problem, the first thing to do is to see if it is
2352 already known. @xref{Trouble}. If it isn't known, then you should
2355 Reporting a bug may help you by bringing a solution to your problem, or
2356 it may not. (If it does not, look in the service directory; see
2357 @ref{Service}.) In any case, the principal function of a bug report is
2358 to help the entire community by making the next version of GCC work
2359 better. Bug reports are your contribution to the maintenance of GCC.
2361 Since the maintainers are very overloaded, we cannot respond to every
2362 bug report. However, if the bug has not been fixed, we are likely to
2363 send you a patch and ask you to tell us whether it works.
2365 In order for a bug report to serve its purpose, you must include the
2366 information that makes for fixing the bug.
2369 * Criteria: Bug Criteria. Have you really found a bug?
2370 * Where: Bug Lists. Where to send your bug report.
2371 * Reporting: Bug Reporting. How to report a bug effectively.
2372 * GNATS: gccbug. You can use a bug reporting tool.
2373 * Patches: Sending Patches. How to send a patch for GCC.
2374 * Known: Trouble. Known problems.
2375 * Help: Service. Where to ask for help.
2378 @node Bug Criteria,Bug Lists,,Bugs
2379 @section Have You Found a Bug?
2380 @cindex bug criteria
2382 If you are not sure whether you have found a bug, here are some guidelines:
2385 @cindex fatal signal
2388 If the compiler gets a fatal signal, for any input whatever, that is a
2389 compiler bug. Reliable compilers never crash.
2391 @cindex invalid assembly code
2392 @cindex assembly code, invalid
2394 If the compiler produces invalid assembly code, for any input whatever
2395 (except an @code{asm} statement), that is a compiler bug, unless the
2396 compiler reports errors (not just warnings) which would ordinarily
2397 prevent the assembler from being run.
2399 @cindex undefined behavior
2400 @cindex undefined function value
2401 @cindex increment operators
2403 If the compiler produces valid assembly code that does not correctly
2404 execute the input source code, that is a compiler bug.
2406 However, you must double-check to make sure, because you may have run
2407 into an incompatibility between GNU C and traditional C
2408 (@pxref{Incompatibilities}). These incompatibilities might be considered
2409 bugs, but they are inescapable consequences of valuable features.
2411 Or you may have a program whose behavior is undefined, which happened
2412 by chance to give the desired results with another C or C++ compiler.
2414 For example, in many nonoptimizing compilers, you can write @samp{x;}
2415 at the end of a function instead of @samp{return x;}, with the same
2416 results. But the value of the function is undefined if @code{return}
2417 is omitted; it is not a bug when GCC produces different results.
2419 Problems often result from expressions with two increment operators,
2420 as in @code{f (*p++, *p++)}. Your previous compiler might have
2421 interpreted that expression the way you intended; GCC might
2422 interpret it another way. Neither compiler is wrong. The bug is
2425 After you have localized the error to a single source line, it should
2426 be easy to check for these things. If your program is correct and
2427 well defined, you have found a compiler bug.
2430 If the compiler produces an error message for valid input, that is a
2433 @cindex invalid input
2435 If the compiler does not produce an error message for invalid input,
2436 that is a compiler bug. However, you should note that your idea of
2437 ``invalid input'' might be my idea of ``an extension'' or ``support
2438 for traditional practice''.
2441 If you are an experienced user of one of the languages GCC supports, your
2442 suggestions for improvement of GCC are welcome in any case.
2445 @node Bug Lists,Bug Reporting,Bug Criteria,Bugs
2446 @section Where to Report Bugs
2447 @cindex bug report mailing lists
2448 @kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
2449 Send bug reports for the GNU Compiler Collection to
2450 @email{gcc-bugs@@gcc.gnu.org}. In accordance with the GNU-wide
2451 convention, in which bug reports for tool ``foo'' are sent
2452 to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
2453 may also be used; it will forward to the address given above.
2455 Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or
2456 more up-to-date bug reporting instructions before you post a bug report.
2458 @node Bug Reporting,gccbug,Bug Lists,Bugs
2459 @section How to Report Bugs
2460 @cindex compiler bugs, reporting
2462 The fundamental principle of reporting bugs usefully is this:
2463 @strong{report all the facts}. If you are not sure whether to state a
2464 fact or leave it out, state it!
2466 Often people omit facts because they think they know what causes the
2467 problem and they conclude that some details don't matter. Thus, you might
2468 assume that the name of the variable you use in an example does not matter.
2469 Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
2470 stray memory reference which happens to fetch from the location where that
2471 name is stored in memory; perhaps, if the name were different, the contents
2472 of that location would fool the compiler into doing the right thing despite
2473 the bug. Play it safe and give a specific, complete example. That is the
2474 easiest thing for you to do, and the most helpful.
2476 Keep in mind that the purpose of a bug report is to enable someone to
2477 fix the bug if it is not known. It isn't very important what happens if
2478 the bug is already known. Therefore, always write your bug reports on
2479 the assumption that the bug is not known.
2481 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2482 bell?'' This cannot help us fix a bug, so it is basically useless. We
2483 respond by asking for enough details to enable us to investigate.
2484 You might as well expedite matters by sending them to begin with.
2486 Try to make your bug report self-contained. If we have to ask you for
2487 more information, it is best if you include all the previous information
2488 in your response, as well as the information that was missing.
2490 Please report each bug in a separate message. This makes it easier for
2491 us to track which bugs have been fixed and to forward your bugs reports
2492 to the appropriate maintainer.
2494 To enable someone to investigate the bug, you should include all these
2499 The version of GCC. You can get this by running it with the
2502 Without this, we won't know whether there is any point in looking for
2503 the bug in the current version of GCC.
2506 A complete input file that will reproduce the bug. If the bug is in the
2507 C preprocessor, send a source file and any header files that it
2508 requires. If the bug is in the compiler proper (@file{cc1}), send the
2509 preprocessor output generated by adding @samp{-save-temps} to the
2510 compilation command (@pxref{Debugging Options}). When you do this, use
2511 the same @samp{-I}, @samp{-D} or @samp{-U} options that you used in
2512 actual compilation. Then send the @var{input}.i or @var{input}.ii files
2515 A single statement is not enough of an example. In order to compile it,
2516 it must be embedded in a complete file of compiler input; and the bug
2517 might depend on the details of how this is done.
2519 Without a real example one can compile, all anyone can do about your bug
2520 report is wish you luck. It would be futile to try to guess how to
2521 provoke the bug. For example, bugs in register allocation and reloading
2522 frequently depend on every little detail of the function they happen in.
2524 Even if the input file that fails comes from a GNU program, you should
2525 still send the complete test case. Don't ask the GCC maintainers to
2526 do the extra work of obtaining the program in question---they are all
2527 overworked as it is. Also, the problem may depend on what is in the
2528 header files on your system; it is unreliable for the GCC maintainers
2529 to try the problem with the header files available to them. By sending
2530 CPP output, you can eliminate this source of uncertainty and save us
2531 a certain percentage of wild goose chases.
2534 The command arguments you gave GCC to compile that example
2535 and observe the bug. For example, did you use @samp{-O}? To guarantee
2536 you won't omit something important, list all the options.
2538 If we were to try to guess the arguments, we would probably guess wrong
2539 and then we would not encounter the bug.
2542 The type of machine you are using, and the operating system name and
2546 The operands you gave to the @code{configure} command when you installed
2550 A complete list of any modifications you have made to the compiler
2551 source. (We don't promise to investigate the bug unless it happens in
2552 an unmodified compiler. But if you've made modifications and don't tell
2553 us, then you are sending us on a wild goose chase.)
2555 Be precise about these changes. A description in English is not
2556 enough---send a context diff for them.
2558 Adding files of your own (such as a machine description for a machine we
2559 don't support) is a modification of the compiler source.
2562 Details of any other deviations from the standard procedure for installing
2566 A description of what behavior you observe that you believe is
2567 incorrect. For example, ``The compiler gets a fatal signal,'' or,
2568 ``The assembler instruction at line 208 in the output is incorrect.''
2570 Of course, if the bug is that the compiler gets a fatal signal, then one
2571 can't miss it. But if the bug is incorrect output, the maintainer might
2572 not notice unless it is glaringly wrong. None of us has time to study
2573 all the assembler code from a 50-line C program just on the chance that
2574 one instruction might be wrong. We need @emph{you} to do this part!
2576 Even if the problem you experience is a fatal signal, you should still
2577 say so explicitly. Suppose something strange is going on, such as, your
2578 copy of the compiler is out of synch, or you have encountered a bug in
2579 the C library on your system. (This has happened!) Your copy might
2580 crash and the copy here would not. If you @i{said} to expect a crash,
2581 then when the compiler here fails to crash, we would know that the bug
2582 was not happening. If you don't say to expect a crash, then we would
2583 not know whether the bug was happening. We would not be able to draw
2584 any conclusion from our observations.
2586 If the problem is a diagnostic when compiling GCC with some other
2587 compiler, say whether it is a warning or an error.
2589 Often the observed symptom is incorrect output when your program is run.
2590 Sad to say, this is not enough information unless the program is short
2591 and simple. None of us has time to study a large program to figure out
2592 how it would work if compiled correctly, much less which line of it was
2593 compiled wrong. So you will have to do that. Tell us which source line
2594 it is, and what incorrect result happens when that line is executed. A
2595 person who understands the program can find this as easily as finding a
2596 bug in the program itself.
2599 If you send examples of assembler code output from GCC,
2600 please use @samp{-g} when you make them. The debugging information
2601 includes source line numbers which are essential for correlating the
2602 output with the input.
2605 If you wish to mention something in the GCC source, refer to it by
2606 context, not by line number.
2608 The line numbers in the development sources don't match those in your
2609 sources. Your line numbers would convey no useful information to the
2613 Additional information from a debugger might enable someone to find a
2614 problem on a machine which he does not have available. However, you
2615 need to think when you collect this information if you want it to have
2616 any chance of being useful.
2618 @cindex backtrace for bug reports
2619 For example, many people send just a backtrace, but that is never
2620 useful by itself. A simple backtrace with arguments conveys little
2621 about GCC because the compiler is largely data-driven; the same
2622 functions are called over and over for different RTL insns, doing
2623 different things depending on the details of the insn.
2625 Most of the arguments listed in the backtrace are useless because they
2626 are pointers to RTL list structure. The numeric values of the
2627 pointers, which the debugger prints in the backtrace, have no
2628 significance whatever; all that matters is the contents of the objects
2629 they point to (and most of the contents are other such pointers).
2631 In addition, most compiler passes consist of one or more loops that
2632 scan the RTL insn sequence. The most vital piece of information about
2633 such a loop---which insn it has reached---is usually in a local variable,
2637 What you need to provide in addition to a backtrace are the values of
2638 the local variables for several stack frames up. When a local
2639 variable or an argument is an RTX, first print its value and then use
2640 the GDB command @code{pr} to print the RTL expression that it points
2641 to. (If GDB doesn't run on your machine, use your debugger to call
2642 the function @code{debug_rtx} with the RTX as an argument.) In
2643 general, whenever a variable is a pointer, its value is no use
2644 without the data it points to.
2647 Here are some things that are not necessary:
2651 A description of the envelope of the bug.
2653 Often people who encounter a bug spend a lot of time investigating
2654 which changes to the input file will make the bug go away and which
2655 changes will not affect it.
2657 This is often time consuming and not very useful, because the way we
2658 will find the bug is by running a single example under the debugger with
2659 breakpoints, not by pure deduction from a series of examples. You might
2660 as well save your time for something else.
2662 Of course, if you can find a simpler example to report @emph{instead} of
2663 the original one, that is a convenience. Errors in the output will be
2664 easier to spot, running under the debugger will take less time, etc.
2665 Most GCC bugs involve just one function, so the most straightforward
2666 way to simplify an example is to delete all the function definitions
2667 except the one where the bug occurs. Those earlier in the file may be
2668 replaced by external declarations if the crucial function depends on
2669 them. (Exception: inline functions may affect compilation of functions
2670 defined later in the file.)
2672 However, simplification is not vital; if you don't want to do this,
2673 report the bug anyway and send the entire test case you used.
2676 In particular, some people insert conditionals @samp{#ifdef BUG} around
2677 a statement which, if removed, makes the bug not happen. These are just
2678 clutter; we won't pay any attention to them anyway. Besides, you should
2679 send us cpp output, and that can't have conditionals.
2682 A patch for the bug.
2684 A patch for the bug is useful if it is a good one. But don't omit the
2685 necessary information, such as the test case, on the assumption that a
2686 patch is all we need. We might see problems with your patch and decide
2687 to fix the problem another way, or we might not understand it at all.
2689 Sometimes with a program as complicated as GCC it is very hard to
2690 construct an example that will make the program follow a certain path
2691 through the code. If you don't send the example, we won't be able to
2692 construct one, so we won't be able to verify that the bug is fixed.
2694 And if we can't understand what bug you are trying to fix, or why your
2695 patch should be an improvement, we won't install it. A test case will
2696 help us to understand.
2698 @xref{Sending Patches}, for guidelines on how to make it easy for us to
2699 understand and install your patches.
2702 A guess about what the bug is or what it depends on.
2704 Such guesses are usually wrong. Even I can't guess right about such
2705 things without first using the debugger to find the facts.
2710 We have no way of examining a core dump for your type of machine
2711 unless we have an identical system---and if we do have one,
2712 we should be able to reproduce the crash ourselves.
2715 @node gccbug,Sending Patches, Bug Reporting, Bugs
2716 @section The gccbug script
2717 @cindex gccbug script
2719 To simplify creation of bug reports, and to allow better tracking of
2720 reports, we use the GNATS bug tracking system. Part of that system is
2721 the @code{gccbug} script. This is a Unix shell script, so you need a
2722 shell to run it. It is normally installed in the same directory where
2723 @code{gcc} is installed.
2725 The gccbug script is derived from send-pr, @pxref{using
2726 send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
2727 invoked, it starts a text editor so you can fill out the various fields
2728 of the report. When the you quit the editor, the report is automatically
2729 send to the bug reporting address.
2731 A number of fields in this bug report form are specific to GCC, and are
2736 @cindex @code{Category} field
2737 @cindex @code{>Category:}
2739 The category of a GCC problem can be one of the following:
2743 A problem with the C compiler proper.
2747 A problem with the C++ compiler.
2751 A problem with the Fortran 77.
2754 A problem with the Java compiler.
2757 A problem with the Objective C compiler.
2760 A problem with the C++ standard library.
2763 A problem with the Fortran 77 library.
2766 A problem with the Objective C library.
2769 The problem occurs only when generating optimized code.
2772 The problem occurs only when generating code for debugging.
2775 The problem is specific to the target architecture.
2778 The problem is independent from target architecture and programming
2782 It is a problem in some other part of the GCC software.
2785 There is a problem with the GCC home page.
2789 @cindex @code{Class} field
2790 @cindex @code{>Class:}
2792 The class of a problem can be one of the following:
2795 @cindex @emph{doc-bug} class
2797 A problem with the documentation.
2799 @cindex @emph{accepts-illegal} class
2800 @item accepts-illegal
2801 GCC fails to reject erroneous code.
2803 @cindex @emph{rejects-legal} class
2805 GCC gives an error message for correct code.
2807 @cindex @emph{wrong-code} class
2809 The machine code generated by gcc is incorrect.
2811 @cindex @emph{ice-on-legal-code} class
2812 @item ice-on-legal-code
2813 GCC gives an Internal Compiler Error (ICE) for correct code.
2815 @cindex @emph{ice-on-illegal-code} class
2816 @item ice-on-illegal-code
2817 GCC gives an ICE instead of reporting an error
2819 @cindex @emph{pessimizes-code} class
2820 @item pessimizes-code
2821 GCC misses an important optimization opportunity.
2823 @cindex @emph{sw-bug} class
2825 A general product problem. (@samp{sw} stands for ``software''.)
2827 @cindex @emph{change-request} class
2828 @item change-request
2829 A request for a change in behavior, etc.
2831 @cindex @emph{support} class
2833 A support problem or question.
2835 @cindex @emph{duplicate} class
2836 @item duplicate (@var{pr-number})
2837 Duplicate PR. @var{pr-number} should be the number of the original PR.
2840 The default is @samp{sw-bug}.
2846 @node Sending Patches,, gccbug, Bugs
2847 @section Sending Patches for GCC
2849 If you would like to write bug fixes or improvements for the GNU C
2850 compiler, that is very helpful. Send suggested fixes to the patches
2851 mailing list, @email{gcc-patches@@gcc.gnu.org}.
2853 Please follow these guidelines so we can study your patches efficiently.
2854 If you don't follow these guidelines, your information might still be
2855 useful, but using it will take extra work. Maintaining GNU C is a lot
2856 of work in the best of circumstances, and we can't keep up unless you do
2861 Send an explanation with your changes of what problem they fix or what
2862 improvement they bring about. For a bug fix, just include a copy of the
2863 bug report, and explain why the change fixes the bug.
2865 (Referring to a bug report is not as good as including it, because then
2866 we will have to look it up, and we have probably already deleted it if
2867 we've already fixed the bug.)
2870 Always include a proper bug report for the problem you think you have
2871 fixed. We need to convince ourselves that the change is right before
2872 installing it. Even if it is right, we might have trouble judging it if
2873 we don't have a way to reproduce the problem.
2876 Include all the comments that are appropriate to help people reading the
2877 source in the future understand why this change was needed.
2880 Don't mix together changes made for different reasons.
2881 Send them @emph{individually}.
2883 If you make two changes for separate reasons, then we might not want to
2884 install them both. We might want to install just one. If you send them
2885 all jumbled together in a single set of diffs, we have to do extra work
2886 to disentangle them---to figure out which parts of the change serve
2887 which purpose. If we don't have time for this, we might have to ignore
2888 your changes entirely.
2890 If you send each change as soon as you have written it, with its own
2891 explanation, then the two changes never get tangled up, and we can
2892 consider each one properly without any extra work to disentangle them.
2894 Ideally, each change you send should be impossible to subdivide into
2895 parts that we might want to consider separately, because each of its
2896 parts gets its motivation from the other parts.
2899 Send each change as soon as that change is finished. Sometimes people
2900 think they are helping us by accumulating many changes to send them all
2901 together. As explained above, this is absolutely the worst thing you
2904 Since you should send each change separately, you might as well send it
2905 right away. That gives us the option of installing it immediately if it
2909 Use @samp{diff -c} to make your diffs. Diffs without context are hard
2910 for us to install reliably. More than that, they make it hard for us to
2911 study the diffs to decide whether we want to install them. Unidiff
2912 format is better than contextless diffs, but not as easy to read as
2915 If you have GNU diff, use @samp{diff -cp}, which shows the name of the
2916 function that each change occurs in.
2919 Write the change log entries for your changes. We get lots of changes,
2920 and we don't have time to do all the change log writing ourselves.
2922 Read the @file{ChangeLog} file to see what sorts of information to put
2923 in, and to learn the style that we use. The purpose of the change log
2924 is to show people where to find what was changed. So you need to be
2925 specific about what functions you changed; in large functions, it's
2926 often helpful to indicate where within the function the change was.
2928 On the other hand, once you have shown people where to find the change,
2929 you need not explain its purpose. Thus, if you add a new function, all
2930 you need to say about it is that it is new. If you feel that the
2931 purpose needs explaining, it probably does---but the explanation will be
2932 much more useful if you put it in comments in the code.
2934 If you would like your name to appear in the header line for who made
2935 the change, send us the header line.
2938 When you write the fix, keep in mind that we can't install a change that
2939 would break other systems.
2941 People often suggest fixing a problem by changing machine-independent
2942 files such as @file{toplev.c} to do something special that a particular
2943 system needs. Sometimes it is totally obvious that such changes would
2944 break GCC for almost all users. We can't possibly make a change like
2945 that. At best it might tell us how to write another patch that would
2946 solve the problem acceptably.
2948 Sometimes people send fixes that @emph{might} be an improvement in
2949 general---but it is hard to be sure of this. It's hard to install
2950 such changes because we have to study them very carefully. Of course,
2951 a good explanation of the reasoning by which you concluded the change
2952 was correct can help convince us.
2954 The safest changes are changes to the configuration files for a
2955 particular machine. These are safe because they can't create new bugs
2958 Please help us keep up with the workload by designing the patch in a
2959 form that is good to install.
2963 @chapter How To Get Help with GCC
2965 If you need help installing, using or changing GCC, there are two
2970 Send a message to a suitable network mailing list. First try
2971 @email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
2972 that brings no response, try @email{gcc@@gcc.gnu.org}. For help
2973 changing GCC, ask @email{gcc@@gcc.gnu.org}. If you think you have found
2974 a bug in GCC, please report it following the instructions at
2975 @pxref{Bug Reporting}.
2978 Look in the service directory for someone who might help you for a fee.
2979 The service directory is found at
2980 @uref{http://www.gnu.org/prep/service.html}.
2983 @c For further information, see
2984 @c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}.
2985 @c FIXME: this URL may be too volatile, this FAQ entry needs to move to
2986 @c the regular web pages before we can uncomment the reference.
2989 @chapter Contributing to GCC Development
2991 If you would like to help pretest GCC releases to assure they work well,
2992 our current development sources are available by CVS (see
2993 @uref{http://gcc.gnu.org/cvs.html}). Source and binary snapshots are
2994 also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
2996 If you would like to work on improvements to GCC, please read
2997 @uref{http://gcc.gnu.org/contribute.html} and
2998 @uref{http://gcc.gnu.org/contributewhy.html} for information on how to
2999 make useful contributions and avoid duplication of effort. Suggested
3000 projects are listed at @uref{http://gcc.gnu.org/projects/}.
3003 @chapter Using GCC on VMS
3005 @c prevent bad page break with this line
3006 Here is how to use GCC on VMS.
3009 * Include Files and VMS:: Where the preprocessor looks for the include files.
3010 * Global Declarations:: How to do globaldef, globalref and globalvalue with
3012 * VMS Misc:: Misc information.
3015 @node Include Files and VMS
3016 @section Include Files and VMS
3018 @cindex include files and VMS
3019 @cindex VMS and include files
3020 @cindex header files and VMS
3021 Due to the differences between the filesystems of Unix and VMS, GCC
3022 attempts to translate file names in @samp{#include} into names that VMS
3023 will understand. The basic strategy is to prepend a prefix to the
3024 specification of the include file, convert the whole filename to a VMS
3025 filename, and then try to open the file. GCC tries various prefixes
3026 one by one until one of them succeeds:
3030 The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
3031 where GNU C header files are traditionally stored. If you wish to store
3032 header files in non-standard locations, then you can assign the logical
3033 @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
3034 list is suitable for use with a rooted logical.
3037 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where
3038 VAX-C header files are traditionally stored.
3041 If the include file specification by itself is a valid VMS filename, the
3042 preprocessor then uses this name with no prefix in an attempt to open
3046 If the file specification is not a valid VMS filename (i.e. does not
3047 contain a device or a directory specifier, and contains a @samp{/}
3048 character), the preprocessor tries to convert it from Unix syntax to
3051 Conversion works like this: the first directory name becomes a device,
3052 and the rest of the directories are converted into VMS-format directory
3053 names. For example, the name @file{X11/foobar.h} is
3054 translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
3055 whichever one can be opened. This strategy allows you to assign a
3056 logical name to point to the actual location of the header files.
3059 If none of these strategies succeeds, the @samp{#include} fails.
3062 Include directives of the form:
3069 are a common source of incompatibility between VAX-C and GCC. VAX-C
3070 treats this much like a standard @code{#include <foobar.h>} directive.
3071 That is incompatible with the ISO C behavior implemented by GCC: to
3072 expand the name @code{foobar} as a macro. Macro expansion should
3073 eventually yield one of the two standard formats for @code{#include}:
3076 #include "@var{file}"
3077 #include <@var{file}>
3080 If you have this problem, the best solution is to modify the source to
3081 convert the @code{#include} directives to one of the two standard forms.
3082 That will work with either compiler. If you want a quick and dirty fix,
3083 define the file names as macros with the proper expansion, like this:
3086 #define stdio <stdio.h>
3090 This will work, as long as the name doesn't conflict with anything else
3093 Another source of incompatibility is that VAX-C assumes that:
3100 is actually asking for the file @file{foobar.h}. GCC does not
3101 make this assumption, and instead takes what you ask for literally;
3102 it tries to read the file @file{foobar}. The best way to avoid this
3103 problem is to always specify the desired file extension in your include
3106 GCC for VMS is distributed with a set of include files that is
3107 sufficient to compile most general purpose programs. Even though the
3108 GCC distribution does not contain header files to define constants
3109 and structures for some VMS system-specific functions, there is no
3110 reason why you cannot use GCC with any of these functions. You first
3111 may have to generate or create header files, either by using the public
3112 domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
3113 extracting the relevant modules from one of the system macro libraries,
3114 and using an editor to construct a C header file.
3116 A @code{#include} file name cannot contain a DECNET node name. The
3117 preprocessor reports an I/O error if you attempt to use a node name,
3118 whether explicitly, or implicitly via a logical name.
3120 @node Global Declarations
3121 @section Global Declarations and VMS
3125 @findex GLOBALVALUEDEF
3126 @findex GLOBALVALUEREF
3127 GCC does not provide the @code{globalref}, @code{globaldef} and
3128 @code{globalvalue} keywords of VAX-C. You can get the same effect with
3129 an obscure feature of GAS, the GNU assembler. (This requires GAS
3130 version 1.39 or later.) The following macros allow you to use this
3131 feature in a fairly natural way:
3135 #define GLOBALREF(TYPE,NAME) \
3137 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
3138 #define GLOBALDEF(TYPE,NAME,VALUE) \
3140 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
3142 #define GLOBALVALUEREF(TYPE,NAME) \
3143 const TYPE NAME[1] \
3144 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
3145 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
3146 const TYPE NAME[1] \
3147 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \
3150 #define GLOBALREF(TYPE,NAME) \
3152 #define GLOBALDEF(TYPE,NAME,VALUE) \
3153 globaldef TYPE NAME = VALUE
3154 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
3155 globalvalue TYPE NAME = VALUE
3156 #define GLOBALVALUEREF(TYPE,NAME) \
3157 globalvalue TYPE NAME
3162 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
3163 name is removed by the assembler, after it has modified the attributes
3164 of the symbol). These macros are provided in the VMS binaries
3165 distribution in a header file @file{GNU_HACKS.H}. An example of the
3169 GLOBALREF (int, ijk);
3170 GLOBALDEF (int, jkl, 0);
3173 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
3174 straightforwardly for arrays, since there is no way to insert the array
3175 dimension into the declaration at the right place. However, you can
3176 declare an array with these macros if you first define a typedef for the
3177 array type, like this:
3180 typedef int intvector[10];
3181 GLOBALREF (intvector, foo);
3184 Array and structure initializers will also break the macros; you can
3185 define the initializer to be a macro of its own, or you can expand the
3186 @code{GLOBALDEF} macro by hand. You may find a case where you wish to
3187 use the @code{GLOBALDEF} macro with a large array, but you are not
3188 interested in explicitly initializing each element of the array. In
3189 such cases you can use an initializer like: @code{@{0,@}}, which will
3190 initialize the entire array to @code{0}.
3192 A shortcoming of this implementation is that a variable declared with
3193 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For
3194 example, the declaration:
3197 GLOBALVALUEREF(int, ijk);
3201 declares the variable @code{ijk} as an array of type @code{int [1]}.
3202 This is done because a globalvalue is actually a constant; its ``value''
3203 is what the linker would normally consider an address. That is not how
3204 an integer value works in C, but it is how an array works. So treating
3205 the symbol as an array name gives consistent results---with the
3206 exception that the value seems to have the wrong type. @strong{Don't
3207 try to access an element of the array.} It doesn't have any elements.
3208 The array ``address'' may not be the address of actual storage.
3210 The fact that the symbol is an array may lead to warnings where the
3211 variable is used. Insert type casts to avoid the warnings. Here is an
3212 example; it takes advantage of the ISO C feature allowing macros that
3213 expand to use the same name as the macro itself.
3216 GLOBALVALUEREF (int, ss$_normal);
3217 GLOBALVALUEDEF (int, xyzzy,123);
3219 #define ss$_normal ((int) ss$_normal)
3220 #define xyzzy ((int) xyzzy)
3224 Don't use @code{globaldef} or @code{globalref} with a variable whose
3225 type is an enumeration type; this is not implemented. Instead, make the
3226 variable an integer, and use a @code{globalvaluedef} for each of the
3227 enumeration values. An example of this would be:
3231 GLOBALDEF (int, color, 0);
3232 GLOBALVALUEDEF (int, RED, 0);
3233 GLOBALVALUEDEF (int, BLUE, 1);
3234 GLOBALVALUEDEF (int, GREEN, 3);
3236 enum globaldef color @{RED, BLUE, GREEN = 3@};
3241 @section Other VMS Issues
3243 @cindex exit status and VMS
3244 @cindex return value of @code{main}
3245 @cindex @code{main} and the exit status
3246 GCC automatically arranges for @code{main} to return 1 by default if
3247 you fail to specify an explicit return value. This will be interpreted
3248 by VMS as a status code indicating a normal successful completion.
3249 Version 1 of GCC did not provide this default.
3251 GCC on VMS works only with the GNU assembler, GAS. You need version
3252 1.37 or later of GAS in order to produce value debugging information for
3253 the VMS debugger. Use the ordinary VMS linker with the object files
3256 @cindex shared VMS run time system
3257 @cindex @file{VAXCRTL}
3258 Under previous versions of GCC, the generated code would occasionally
3259 give strange results when linked to the sharable @file{VAXCRTL} library.
3260 Now this should work.
3262 A caveat for use of @code{const} global variables: the @code{const}
3263 modifier must be specified in every external declaration of the variable
3264 in all of the source files that use that variable. Otherwise the linker
3265 will issue warnings about conflicting attributes for the variable. Your
3266 program will still work despite the warnings, but the variable will be
3267 placed in writable storage.
3269 @cindex name augmentation
3270 @cindex case sensitivity and VMS
3271 @cindex VMS and case sensitivity
3272 Although the VMS linker does distinguish between upper and lower case
3273 letters in global symbols, most VMS compilers convert all such symbols
3274 into upper case and most run-time library routines also have upper case
3275 names. To be able to reliably call such routines, GCC (by means of
3276 the assembler GAS) converts global symbols into upper case like other
3277 VMS compilers. However, since the usual practice in C is to distinguish
3278 case, GCC (via GAS) tries to preserve usual C behavior by augmenting
3279 each name that is not all lower case. This means truncating the name
3280 to at most 23 characters and then adding more characters at the end
3281 which encode the case pattern of those 23. Names which contain at
3282 least one dollar sign are an exception; they are converted directly into
3283 upper case without augmentation.
3285 Name augmentation yields bad results for programs that use precompiled
3286 libraries (such as Xlib) which were generated by another compiler. You
3287 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
3288 it makes external C functions and variables case-independent as is usual
3289 on VMS. Alternatively, you could write all references to the functions
3290 and variables in such libraries using lower case; this will work on VMS,
3291 but is not portable to other systems. The compiler option @samp{/NAMES}
3292 also provides control over global name handling.
3294 Function and variable names are handled somewhat differently with GNU
3295 C++. The GNU C++ compiler performs @dfn{name mangling} on function
3296 names, which means that it adds information to the function name to
3297 describe the data types of the arguments that the function takes. One
3298 result of this is that the name of a function can become very long.
3299 Since the VMS linker only recognizes the first 31 characters in a name,
3300 special action is taken to ensure that each function and variable has a
3301 unique name that can be represented in 31 characters.
3303 If the name (plus a name augmentation, if required) is less than 32
3304 characters in length, then no special action is performed. If the name
3305 is longer than 31 characters, the assembler (GAS) will generate a
3306 hash string based upon the function name, truncate the function name to
3307 23 characters, and append the hash string to the truncated name. If the
3308 @samp{/VERBOSE} compiler option is used, the assembler will print both
3309 the full and truncated names of each symbol that is truncated.
3311 The @samp{/NOCASE_HACK} compiler option should not be used when you are
3312 compiling programs that use libg++. libg++ has several instances of
3313 objects (i.e. @code{Filebuf} and @code{filebuf}) which become
3314 indistinguishable in a case-insensitive environment. This leads to
3315 cases where you need to inhibit augmentation selectively (if you were
3316 using libg++ and Xlib in the same program, for example). There is no
3317 special feature for doing this, but you can get the result by defining a
3318 macro for each mixed case symbol for which you wish to inhibit
3319 augmentation. The macro should expand into the lower case equivalent of
3320 itself. For example:
3323 #define StuDlyCapS studlycaps
3326 These macro definitions can be placed in a header file to minimize the
3327 number of changes to your source code.
3330 @chapter Makefile Targets
3331 @cindex makefile targets
3332 @cindex targets, makefile
3336 This is the default target. Depending on what your build/host/target
3337 configuration is, it coordinates all the things that need to be built.
3340 Produce info-formatted documentation. Also, @code{make dvi} is
3341 available for DVI-formatted documentation, and @code{make
3342 generated-manpages} to generate man pages.
3345 Delete the files made while building the compiler.
3348 That, and all the other files built by @code{make all}.
3351 That, and all the files created by @code{configure}.
3354 That, and any temporary or intermediate files, like emacs backup files.
3356 @item maintainer-clean
3357 Distclean plus any file that can be generated from other files. Note
3358 that additional tools may be required beyond what is normally needed to
3365 Deletes installed files.
3368 Run the testsuite. This creates a @file{testsuite} subdirectory that
3369 has various @file{.sum} and @file{.log} files containing the results of
3370 the testing. You can run subsets with, for example, @code{make check-gcc}.
3371 You can specify specific tests by setting RUNTESTFLAGS to be the name
3372 of the @file{.exp} file, optionally followed by (for some tests) an equals
3373 and a file wildcard, like:
3376 make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
3379 Note that running the testsuite may require additional tools be
3380 installed, such as TCL or dejagnu.
3383 Builds gcc three times - once with the native compiler, once with the
3384 native-built compiler it just built, and once with the compiler it built
3385 the second time. In theory, the last two should produce the same
3386 results, which @code{make compare} can check. Each step of this process
3387 is called a "stage", and the results of each stage N (N=1..3) are copied
3388 to a subdirectory @file{stageN/}.
3390 @item bootstrap-lean
3391 Like @code{bootstrap}, except that the various stages are removed once
3392 they're no longer needed. This saves disk space.
3395 Once bootstrapped, this incrementally rebuilds each of the three stages,
3396 one at a time. It does this by "bubbling" the stages up from their
3397 stubdirectories, rebuilding them, and copying them back to their
3398 subdirectories. This will allow you to, for example, quickly rebuild a
3399 bootstrapped compiler after changing the sources, without having to do a
3403 Rebuilds the most recently built stage. Since each stage requires
3404 special invocation, using this target means you don't have to keep track
3405 of which stage you're on or what invocation that stage needs.
3408 Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}).
3410 @item stageN (N=1..4)
3411 For each stage, moves the appropriate files to the stageN subdirectory.
3413 @item unstageN (N=1..4)
3414 Undoes the corresponding @code{stageN}.
3416 @item restageN (N=1..4)
3417 Undoes the corresponding @code{stageN} and rebuilds it with the
3421 Compares the results of stages 2 and 3. This ensures that the compiler
3422 is running properly, since it should produce the same object files
3423 regardless of how it itself was compiled.
3431 @chapter GCC and Portability
3433 @cindex GCC and portability
3435 The main goal of GCC was to make a good, fast compiler for machines in
3436 the class that the GNU system aims to run on: 32-bit machines that address
3437 8-bit bytes and have several general registers. Elegance, theoretical
3438 power and simplicity are only secondary.
3440 GCC gets most of the information about the target machine from a machine
3441 description which gives an algebraic formula for each of the machine's
3442 instructions. This is a very clean way to describe the target. But when
3443 the compiler needs information that is difficult to express in this
3444 fashion, I have not hesitated to define an ad-hoc parameter to the machine
3445 description. The purpose of portability is to reduce the total work needed
3446 on the compiler; it was not of interest for its own sake.
3449 @cindex autoincrement addressing, availability
3451 GCC does not contain machine dependent code, but it does contain code
3452 that depends on machine parameters such as endianness (whether the most
3453 significant byte has the highest or lowest address of the bytes in a word)
3454 and the availability of autoincrement addressing. In the RTL-generation
3455 pass, it is often necessary to have multiple strategies for generating code
3456 for a particular kind of syntax tree, strategies that are usable for different
3457 combinations of parameters. Often I have not tried to address all possible
3458 cases, but only the common ones or only the ones that I have encountered.
3459 As a result, a new target may require additional strategies. You will know
3460 if this happens because the compiler will call @code{abort}. Fortunately,
3461 the new strategies can be added in a machine-independent fashion, and will
3462 affect only the target machines that need them.
3467 @chapter Interfacing to GCC Output
3468 @cindex interfacing to GCC output
3469 @cindex run-time conventions
3470 @cindex function call conventions
3471 @cindex conventions, run-time
3473 GCC is normally configured to use the same function calling convention
3474 normally in use on the target system. This is done with the
3475 machine-description macros described (@pxref{Target Macros}).
3477 @cindex unions, returning
3478 @cindex structures, returning
3479 @cindex returning structures and unions
3480 However, returning of structure and union values is done differently on
3481 some target machines. As a result, functions compiled with PCC
3482 returning such types cannot be called from code compiled with GCC,
3483 and vice versa. This does not cause trouble often because few Unix
3484 library routines return structures or unions.
3486 GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
3487 long in the same registers used for @code{int} or @code{double} return
3488 values. (GCC typically allocates variables of such types in
3489 registers also.) Structures and unions of other sizes are returned by
3490 storing them into an address passed by the caller (usually in a
3491 register). The machine-description macros @code{STRUCT_VALUE} and
3492 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
3494 By contrast, PCC on most target machines returns structures and unions
3495 of any size by copying the data into an area of static storage, and then
3496 returning the address of that storage as if it were a pointer value.
3497 The caller must copy the data from that memory area to the place where
3498 the value is wanted. This is slower than the method used by GCC, and
3499 fails to be reentrant.
3501 On some target machines, such as RISC machines and the 80386, the
3502 standard system convention is to pass to the subroutine the address of
3503 where to return the value. On these machines, GCC has been
3504 configured to be compatible with the standard compiler, when this method
3505 is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3507 @cindex argument passing
3508 @cindex passing arguments
3509 GCC uses the system's standard convention for passing arguments. On
3510 some machines, the first few arguments are passed in registers; in
3511 others, all are passed on the stack. It would be possible to use
3512 registers for argument passing on any machine, and this would probably
3513 result in a significant speedup. But the result would be complete
3514 incompatibility with code that follows the standard convention. So this
3515 change is practical only if you are switching to GCC as the sole C
3516 compiler for the system. We may implement register argument passing on
3517 certain machines once we have a complete GNU system so that we can
3518 compile the libraries with GCC.
3520 On some machines (particularly the Sparc), certain types of arguments
3521 are passed ``by invisible reference''. This means that the value is
3522 stored in memory, and the address of the memory location is passed to
3525 @cindex @code{longjmp} and automatic variables
3526 If you use @code{longjmp}, beware of automatic variables. ISO C says that
3527 automatic variables that are not declared @code{volatile} have undefined
3528 values after a @code{longjmp}. And this is all GCC promises to do,
3529 because it is very difficult to restore register variables correctly, and
3530 one of GCC's features is that it can put variables in registers without
3533 If you want a variable to be unaltered by @code{longjmp}, and you don't
3534 want to write @code{volatile} because old C compilers don't accept it,
3535 just take the address of the variable. If a variable's address is ever
3536 taken, even if just to compute it and ignore it, then the variable cannot
3547 @cindex arithmetic libraries
3548 @cindex math libraries
3549 Code compiled with GCC may call certain library routines. Most of
3550 them handle arithmetic for which there are no instructions. This
3551 includes multiply and divide on some machines, and floating point
3552 operations on any machine for which floating point support is disabled
3553 with @samp{-msoft-float}. Some standard parts of the C library, such as
3554 @code{bcopy} or @code{memcpy}, are also called automatically. The usual
3555 function call interface is used for calling the library routines.
3557 These library routines should be defined in the library @file{libgcc.a},
3558 which GCC automatically searches whenever it links a program. On
3559 machines that have multiply and divide instructions, if hardware
3560 floating point is in use, normally @file{libgcc.a} is not needed, but it
3561 is searched just in case.
3563 Each arithmetic function is defined in @file{libgcc1.c} to use the
3564 corresponding C arithmetic operator. As long as the file is compiled
3565 with another C compiler, which supports all the C arithmetic operators,
3566 this file will work portably. However, @file{libgcc1.c} does not work if
3567 compiled with GCC, because each arithmetic function would compile
3568 into a call to itself!
3573 @chapter Passes and Files of the Compiler
3574 @cindex passes and files of the compiler
3575 @cindex files and passes of the compiler
3576 @cindex compiler passes and files
3578 @cindex top level of compiler
3579 The overall control structure of the compiler is in @file{toplev.c}. This
3580 file is responsible for initialization, decoding arguments, opening and
3581 closing files, and sequencing the passes.
3583 @cindex parsing pass
3584 The parsing pass is invoked only once, to parse the entire input. The RTL
3585 intermediate code for a function is generated as the function is parsed, a
3586 statement at a time. Each statement is read in as a syntax tree and then
3587 converted to RTL; then the storage for the tree for the statement is
3588 reclaimed. Storage for types (and the expressions for their sizes),
3589 declarations, and a representation of the binding contours and how they nest,
3590 remain until the function is finished being compiled; these are all needed
3591 to output the debugging information.
3593 @findex rest_of_compilation
3594 @findex rest_of_decl_compilation
3595 Each time the parsing pass reads a complete function definition or
3596 top-level declaration, it calls either the function
3597 @code{rest_of_compilation}, or the function
3598 @code{rest_of_decl_compilation} in @file{toplev.c}, which are
3599 responsible for all further processing necessary, ending with output of
3600 the assembler language. All other compiler passes run, in sequence,
3601 within @code{rest_of_compilation}. When that function returns from
3602 compiling a function definition, the storage used for that function
3603 definition's compilation is entirely freed, unless it is an inline
3606 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3609 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3612 Here is a list of all the passes of the compiler and their source files.
3613 Also included is a description of where debugging dumps can be requested
3614 with @samp{-d} options.
3618 Parsing. This pass reads the entire text of a function definition,
3619 constructing partial syntax trees. This and RTL generation are no longer
3620 truly separate passes (formerly they were), but it is easier to think
3621 of them as separate.
3623 The tree representation does not entirely follow C syntax, because it is
3624 intended to support other languages as well.
3626 Language-specific data type analysis is also done in this pass, and every
3627 tree node that represents an expression has a data type attached.
3628 Variables are represented as declaration nodes.
3630 @cindex constant folding
3631 @cindex arithmetic simplifications
3632 @cindex simplifications, arithmetic
3633 Constant folding and some arithmetic simplifications are also done
3636 The language-independent source files for parsing are
3637 @file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}.
3638 There are also header files @file{tree.h} and @file{tree.def}
3639 which define the format of the tree representation.@refill
3641 @c Avoiding overfull is tricky here.
3642 The source files to parse C are
3646 @file{c-aux-info.c},
3649 along with header files
3653 The source files for parsing C++ are in @file{cp/}.
3654 They are @file{parse.y},
3656 @file{cvt.c}, @file{decl.c}, @file{decl2.c},
3658 @file{expr.c}, @file{init.c}, @file{lex.c},
3659 @file{method.c}, @file{ptree.c},@*
3660 @file{search.c}, @file{tree.c},
3661 @file{typeck2.c}, and
3662 @file{typeck.c}, along with header files @file{cp-tree.def},
3663 @file{cp-tree.h}, and @file{decl.h}.
3665 The special source files for parsing Objective C are in @file{objc/}.
3666 They are @file{objc-parse.y}, @file{objc-act.c}, @file{objc-tree.def}, and
3667 @file{objc-act.h}. Certain C-specific files are used for this as
3670 The file @file{c-common.c} is also used for all of the above languages.
3672 @cindex RTL generation
3674 RTL generation. This is the conversion of syntax tree into RTL code.
3675 It is actually done statement-by-statement during parsing, but for
3676 most purposes it can be thought of as a separate pass.
3678 @cindex target-parameter-dependent code
3679 This is where the bulk of target-parameter-dependent code is found,
3680 since often it is necessary for strategies to apply only when certain
3681 standard kinds of instructions are available. The purpose of named
3682 instruction patterns is to provide this information to the RTL
3685 @cindex tail recursion optimization
3686 Optimization is done in this pass for @code{if}-conditions that are
3687 comparisons, boolean operations or conditional expressions. Tail
3688 recursion is detected at this time also. Decisions are made about how
3689 best to arrange loops and how to output @code{switch} statements.
3691 @c Avoiding overfull is tricky here.
3692 The source files for RTL generation include
3700 and @file{emit-rtl.c}.
3702 @file{insn-emit.c}, generated from the machine description by the
3703 program @code{genemit}, is used in this pass. The header file
3704 @file{expr.h} is used for communication within this pass.@refill
3708 The header files @file{insn-flags.h} and @file{insn-codes.h},
3709 generated from the machine description by the programs @code{genflags}
3710 and @code{gencodes}, tell this pass which standard names are available
3711 for use and which patterns correspond to them.@refill
3713 Aside from debugging information output, none of the following passes
3714 refers to the tree structure representation of the function (only
3715 part of which is saved).
3717 @cindex inline, automatic
3718 The decision of whether the function can and should be expanded inline
3719 in its subsequent callers is made at the end of rtl generation. The
3720 function must meet certain criteria, currently related to the size of
3721 the function and the types and number of parameters it has. Note that
3722 this function may contain loops, recursive calls to itself
3723 (tail-recursive functions can be inlined!), gotos, in short, all
3724 constructs supported by GCC. The file @file{integrate.c} contains
3725 the code to save a function's rtl for later inlining and to inline that
3726 rtl when the function is called. The header file @file{integrate.h}
3727 is also used for this purpose.
3729 The option @samp{-dr} causes a debugging dump of the RTL code after
3730 this pass. This dump file's name is made by appending @samp{.rtl} to
3731 the input file name.
3733 @cindex jump optimization
3734 @cindex unreachable code
3737 Jump optimization. This pass simplifies jumps to the following
3738 instruction, jumps across jumps, and jumps to jumps. It deletes
3739 unreferenced labels and unreachable code, except that unreachable code
3740 that contains a loop is not recognized as unreachable in this pass.
3741 (Such loops are deleted later in the basic block analysis.) It also
3742 converts some code originally written with jumps into sequences of
3743 instructions that directly set values from the results of comparisons,
3744 if the machine has such instructions.
3746 Jump optimization is performed two or three times. The first time is
3747 immediately following RTL generation. The second time is after CSE,
3748 but only if CSE says repeated jump optimization is needed. The
3749 last time is right before the final pass. That time, cross-jumping
3750 and deletion of no-op move instructions are done together with the
3751 optimizations described above.
3753 The source file of this pass is @file{jump.c}.
3755 The option @samp{-dj} causes a debugging dump of the RTL code after
3756 this pass is run for the first time. This dump file's name is made by
3757 appending @samp{.jump} to the input file name.
3759 @cindex register use analysis
3761 Register scan. This pass finds the first and last use of each
3762 register, as a guide for common subexpression elimination. Its source
3763 is in @file{regclass.c}.
3765 @cindex jump threading
3767 Jump threading. This pass detects a condition jump that branches to an
3768 identical or inverse test. Such jumps can be @samp{threaded} through
3769 the second conditional test. The source code for this pass is in
3770 @file{jump.c}. This optimization is only performed if
3771 @samp{-fthread-jumps} is enabled.
3773 @cindex common subexpression elimination
3774 @cindex constant propagation
3776 Common subexpression elimination. This pass also does constant
3777 propagation. Its source file is @file{cse.c}. If constant
3778 propagation causes conditional jumps to become unconditional or to
3779 become no-ops, jump optimization is run again when CSE is finished.
3781 The option @samp{-ds} causes a debugging dump of the RTL code after
3782 this pass. This dump file's name is made by appending @samp{.cse} to
3783 the input file name.
3785 @cindex global common subexpression elimination
3786 @cindex constant propagation
3787 @cindex copy propagation
3789 Global common subexpression elimination. This pass performs GCSE
3790 using Morel-Renvoise Partial Redundancy Elimination, with the exception
3791 that it does not try to move invariants out of loops - that is left to
3792 the loop optimization pass. This pass also performs global constant
3793 and copy propagation.
3795 The source file for this pass is gcse.c.
3797 The option @samp{-dG} causes a debugging dump of the RTL code after
3798 this pass. This dump file's name is made by appending @samp{.gcse} to
3799 the input file name.
3801 @cindex loop optimization
3803 @cindex strength-reduction
3805 Loop optimization. This pass moves constant expressions out of loops,
3806 and optionally does strength-reduction and loop unrolling as well.
3807 Its source files are @file{loop.c} and @file{unroll.c}, plus the header
3808 @file{loop.h} used for communication between them. Loop unrolling uses
3809 some functions in @file{integrate.c} and the header @file{integrate.h}.
3811 The option @samp{-dL} causes a debugging dump of the RTL code after
3812 this pass. This dump file's name is made by appending @samp{.loop} to
3813 the input file name.
3816 If @samp{-frerun-cse-after-loop} was enabled, a second common
3817 subexpression elimination pass is performed after the loop optimization
3818 pass. Jump threading is also done again at this time if it was specified.
3820 The option @samp{-dt} causes a debugging dump of the RTL code after
3821 this pass. This dump file's name is made by appending @samp{.cse2} to
3822 the input file name.
3824 @cindex data flow analysis
3825 @cindex analysis, data flow
3826 @cindex basic blocks
3828 Data flow analysis (@file{flow.c}). This pass divides the program
3829 into basic blocks (and in the process deletes unreachable loops); then
3830 it computes which pseudo-registers are live at each point in the
3831 program, and makes the first instruction that uses a value point at
3832 the instruction that computed the value.
3834 @cindex autoincrement/decrement analysis
3835 This pass also deletes computations whose results are never used, and
3836 combines memory references with add or subtract instructions to make
3837 autoincrement or autodecrement addressing.
3839 The option @samp{-df} causes a debugging dump of the RTL code after
3840 this pass. This dump file's name is made by appending @samp{.flow} to
3841 the input file name. If stupid register allocation is in use, this
3842 dump file reflects the full results of such allocation.
3844 @cindex instruction combination
3846 Instruction combination (@file{combine.c}). This pass attempts to
3847 combine groups of two or three instructions that are related by data
3848 flow into single instructions. It combines the RTL expressions for
3849 the instructions by substitution, simplifies the result using algebra,
3850 and then attempts to match the result against the machine description.
3852 The option @samp{-dc} causes a debugging dump of the RTL code after
3853 this pass. This dump file's name is made by appending @samp{.combine}
3854 to the input file name.
3856 @cindex register movement
3858 Register movement (@file{regmove.c}). This pass looks for cases where
3859 matching constraints would force an instruction to need a reload, and
3860 this reload would be a register to register move. It then attempts
3861 to change the registers used by the instruction to avoid the move
3864 The option @samp{-dN} causes a debugging dump of the RTL code after
3865 this pass. This dump file's name is made by appending @samp{.regmove}
3866 to the input file name.
3868 @cindex instruction scheduling
3869 @cindex scheduling, instruction
3871 Instruction scheduling (@file{sched.c}). This pass looks for
3872 instructions whose output will not be available by the time that it is
3873 used in subsequent instructions. (Memory loads and floating point
3874 instructions often have this behavior on RISC machines). It re-orders
3875 instructions within a basic block to try to separate the definition and
3876 use of items that otherwise would cause pipeline stalls.
3878 Instruction scheduling is performed twice. The first time is immediately
3879 after instruction combination and the second is immediately after reload.
3881 The option @samp{-dS} causes a debugging dump of the RTL code after this
3882 pass is run for the first time. The dump file's name is made by
3883 appending @samp{.sched} to the input file name.
3885 @cindex register class preference pass
3887 Register class preferencing. The RTL code is scanned to find out
3888 which register class is best for each pseudo register. The source
3889 file is @file{regclass.c}.
3891 @cindex register allocation
3892 @cindex local register allocation
3894 Local register allocation (@file{local-alloc.c}). This pass allocates
3895 hard registers to pseudo registers that are used only within one basic
3896 block. Because the basic block is linear, it can use fast and
3897 powerful techniques to do a very good job.
3899 The option @samp{-dl} causes a debugging dump of the RTL code after
3900 this pass. This dump file's name is made by appending @samp{.lreg} to
3901 the input file name.
3903 @cindex global register allocation
3905 Global register allocation (@file{global.c}). This pass
3906 allocates hard registers for the remaining pseudo registers (those
3907 whose life spans are not contained in one basic block).
3911 Reloading. This pass renumbers pseudo registers with the hardware
3912 registers numbers they were allocated. Pseudo registers that did not
3913 get hard registers are replaced with stack slots. Then it finds
3914 instructions that are invalid because a value has failed to end up in
3915 a register, or has ended up in a register of the wrong kind. It fixes
3916 up these instructions by reloading the problematical values
3917 temporarily into registers. Additional instructions are generated to
3920 The reload pass also optionally eliminates the frame pointer and inserts
3921 instructions to save and restore call-clobbered registers around calls.
3923 Source files are @file{reload.c} and @file{reload1.c}, plus the header
3924 @file{reload.h} used for communication between them.
3926 The option @samp{-dg} causes a debugging dump of the RTL code after
3927 this pass. This dump file's name is made by appending @samp{.greg} to
3928 the input file name.
3930 @cindex instruction scheduling
3931 @cindex scheduling, instruction
3933 Instruction scheduling is repeated here to try to avoid pipeline stalls
3934 due to memory loads generated for spilled pseudo registers.
3936 The option @samp{-dR} causes a debugging dump of the RTL code after
3937 this pass. This dump file's name is made by appending @samp{.sched2}
3938 to the input file name.
3940 @cindex cross-jumping
3941 @cindex no-op move instructions
3943 Jump optimization is repeated, this time including cross-jumping
3944 and deletion of no-op move instructions.
3946 The option @samp{-dJ} causes a debugging dump of the RTL code after
3947 this pass. This dump file's name is made by appending @samp{.jump2}
3948 to the input file name.
3950 @cindex delayed branch scheduling
3951 @cindex scheduling, delayed branch
3953 Delayed branch scheduling. This optional pass attempts to find
3954 instructions that can go into the delay slots of other instructions,
3955 usually jumps and calls. The source file name is @file{reorg.c}.
3957 The option @samp{-dd} causes a debugging dump of the RTL code after
3958 this pass. This dump file's name is made by appending @samp{.dbr}
3959 to the input file name.
3961 @cindex branch shortening
3963 Branch shortening. On many RISC machines, branch instructions have a
3964 limited range. Thus, longer sequences of instructions must be used for
3965 long branches. In this pass, the compiler figures out what how far each
3966 instruction will be from each other instruction, and therefore whether
3967 the usual instructions, or the longer sequences, must be used for each
3970 @cindex register-to-stack conversion
3972 Conversion from usage of some hard registers to usage of a register
3973 stack may be done at this point. Currently, this is supported only
3974 for the floating-point registers of the Intel 80387 coprocessor. The
3975 source file name is @file{reg-stack.c}.
3977 The options @samp{-dk} causes a debugging dump of the RTL code after
3978 this pass. This dump file's name is made by appending @samp{.stack}
3979 to the input file name.
3982 @cindex peephole optimization
3984 Final. This pass outputs the assembler code for the function. It is
3985 also responsible for identifying spurious test and compare
3986 instructions. Machine-specific peephole optimizations are performed
3987 at the same time. The function entry and exit sequences are generated
3988 directly as assembler code in this pass; they never exist as RTL.
3990 The source files are @file{final.c} plus @file{insn-output.c}; the
3991 latter is generated automatically from the machine description by the
3992 tool @file{genoutput}. The header file @file{conditions.h} is used
3993 for communication between these files.
3995 @cindex debugging information generation
3997 Debugging information output. This is run after final because it must
3998 output the stack slot offsets for pseudo registers that did not get
3999 hard registers. Source files are @file{dbxout.c} for DBX symbol table
4000 format, @file{sdbout.c} for SDB symbol table format, and
4001 @file{dwarfout.c} for DWARF symbol table format.
4004 Some additional files are used by all or many passes:
4008 Every pass uses @file{machmode.def} and @file{machmode.h} which define
4012 Several passes use @file{real.h}, which defines the default
4013 representation of floating point constants and how to operate on them.
4016 All the passes that work with RTL use the header files @file{rtl.h}
4017 and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
4018 @code{gen*} also use these files to read and work with the machine
4023 Several passes refer to the header file @file{insn-config.h} which
4024 contains a few parameters (C macro definitions) generated
4025 automatically from the machine description RTL by the tool
4028 @cindex instruction recognizer
4030 Several passes use the instruction recognizer, which consists of
4031 @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
4032 and @file{insn-extract.c} that are generated automatically from the
4033 machine description by the tools @file{genrecog} and
4034 @file{genextract}.@refill
4037 Several passes use the header files @file{regs.h} which defines the
4038 information recorded about pseudo register usage, and @file{basic-block.h}
4039 which defines the information recorded about basic blocks.
4042 @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
4043 with a bit for each hard register, and some macros to manipulate it.
4044 This type is just @code{int} if the machine has few enough hard registers;
4045 otherwise it is an array of @code{int} and some of the macros expand
4049 Several passes use instruction attributes. A definition of the
4050 attributes defined for a particular machine is in file
4051 @file{insn-attr.h}, which is generated from the machine description by
4052 the program @file{genattr}. The file @file{insn-attrtab.c} contains
4053 subroutines to obtain the attribute values for insns. It is generated
4054 from the machine description by the program @file{genattrtab}.@refill
4066 @chapter The Configuration File
4067 @cindex configuration file
4068 @cindex @file{xm-@var{machine}.h}
4070 The configuration file @file{xm-@var{machine}.h} contains macro
4071 definitions that describe the machine and system on which the compiler
4072 is running, unlike the definitions in @file{@var{machine}.h}, which
4073 describe the machine for which the compiler is producing output. Most
4074 of the values in @file{xm-@var{machine}.h} are actually the same on all
4075 machines that GCC runs on, so large parts of all configuration files
4076 are identical. But there are some macros that vary:
4081 Define this macro if the host system is System V.
4085 Define this macro if the host system is VMS.
4087 @findex FATAL_EXIT_CODE
4088 @item FATAL_EXIT_CODE
4089 A C expression for the status code to be returned when the compiler
4090 exits after serious errors.
4092 @findex SUCCESS_EXIT_CODE
4093 @item SUCCESS_EXIT_CODE
4094 A C expression for the status code to be returned when the compiler
4095 exits without serious errors.
4097 @findex HOST_WORDS_BIG_ENDIAN
4098 @item HOST_WORDS_BIG_ENDIAN
4099 Defined if the host machine stores words of multi-word values in
4100 big-endian order. (GCC does not depend on the host byte ordering
4103 @findex HOST_FLOAT_WORDS_BIG_ENDIAN
4104 @item HOST_FLOAT_WORDS_BIG_ENDIAN
4105 Define this macro to be 1 if the host machine stores @code{DFmode},
4106 @code{XFmode} or @code{TFmode} floating point numbers in memory with the
4107 word containing the sign bit at the lowest address; otherwise, define it
4110 This macro need not be defined if the ordering is the same as for
4111 multi-word integers.
4113 @findex HOST_FLOAT_FORMAT
4114 @item HOST_FLOAT_FORMAT
4115 A numeric code distinguishing the floating point format for the host
4116 machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
4117 alternatives and default.
4119 @findex HOST_BITS_PER_CHAR
4120 @item HOST_BITS_PER_CHAR
4121 A C expression for the number of bits in @code{char} on the host
4124 @findex HOST_BITS_PER_SHORT
4125 @item HOST_BITS_PER_SHORT
4126 A C expression for the number of bits in @code{short} on the host
4129 @findex HOST_BITS_PER_INT
4130 @item HOST_BITS_PER_INT
4131 A C expression for the number of bits in @code{int} on the host
4134 @findex HOST_BITS_PER_LONG
4135 @item HOST_BITS_PER_LONG
4136 A C expression for the number of bits in @code{long} on the host
4139 @findex ONLY_INT_FIELDS
4140 @item ONLY_INT_FIELDS
4141 Define this macro to indicate that the host compiler only supports
4142 @code{int} bit fields, rather than other integral types, including
4143 @code{enum}, as do most C compilers.
4145 @findex OBSTACK_CHUNK_SIZE
4146 @item OBSTACK_CHUNK_SIZE
4147 A C expression for the size of ordinary obstack chunks.
4148 If you don't define this, a usually-reasonable default is used.
4150 @findex OBSTACK_CHUNK_ALLOC
4151 @item OBSTACK_CHUNK_ALLOC
4152 The function used to allocate obstack chunks.
4153 If you don't define this, @code{xmalloc} is used.
4155 @findex OBSTACK_CHUNK_FREE
4156 @item OBSTACK_CHUNK_FREE
4157 The function used to free obstack chunks.
4158 If you don't define this, @code{free} is used.
4160 @findex USE_C_ALLOCA
4162 Define this macro to indicate that the compiler is running with the
4163 @code{alloca} implemented in C. This version of @code{alloca} can be
4164 found in the file @file{alloca.c}; to use it, you must also alter the
4165 @file{Makefile} variable @code{ALLOCA}. (This is done automatically
4166 for the systems on which we know it is needed.)
4168 If you do define this macro, you should probably do it as follows:
4172 #define USE_C_ALLOCA
4174 #define alloca __builtin_alloca
4179 so that when the compiler is compiled with GCC it uses the more
4180 efficient built-in @code{alloca} function.
4182 @item FUNCTION_CONVERSION_BUG
4183 @findex FUNCTION_CONVERSION_BUG
4184 Define this macro to indicate that the host compiler does not properly
4185 handle converting a function value to a pointer-to-function when it is
4186 used in an expression.
4188 @findex MULTIBYTE_CHARS
4189 @item MULTIBYTE_CHARS
4190 Define this macro to enable support for multibyte characters in the
4191 input to GCC. This requires that the host system support the ISO C
4192 library functions for converting multibyte characters to wide
4197 Define this if your system is POSIX.1 compliant.
4199 @findex USE_PROTOTYPES
4200 @item USE_PROTOTYPES
4201 Define this to be 1 if you know that the host compiler supports
4202 prototypes, even if it doesn't define __STDC__, or define
4203 it to be 0 if you do not want any prototypes used in compiling
4204 GCC. If @samp{USE_PROTOTYPES} is not defined, it will be
4205 determined automatically whether your compiler supports
4206 prototypes by checking if @samp{__STDC__} is defined.
4208 @findex PATH_SEPARATOR
4209 @item PATH_SEPARATOR
4210 Define this macro to be a C character constant representing the
4211 character used to separate components in paths. The default value is
4214 @findex DIR_SEPARATOR
4216 If your system uses some character other than slash to separate
4217 directory names within a file specification, define this macro to be a C
4218 character constant specifying that character. When GCC displays file
4219 names, the character you specify will be used. GCC will test for
4220 both slash and the character you specify when parsing filenames.
4222 @findex OBJECT_SUFFIX
4224 Define this macro to be a C string representing the suffix for object
4225 files on your machine. If you do not define this macro, GCC will use
4226 @samp{.o} as the suffix for object files.
4228 @findex EXECUTABLE_SUFFIX
4229 @item EXECUTABLE_SUFFIX
4230 Define this macro to be a C string representing the suffix for executable
4231 files on your machine. If you do not define this macro, GCC will use
4232 the null string as the suffix for object files.
4234 @findex HOST_BIT_BUCKET
4235 @item HOST_BIT_BUCKET
4236 The name of a file or file-like object on the host system which acts as
4237 a ``bit bucket''. If you do not define this macro, GCC will use
4238 @samp{/dev/null} as the bit bucket. If the target does not support a
4239 bit bucket, this should be defined to the null string, or some other
4240 illegal filename. If the bit bucket is not writable, GCC will use a
4241 temporary file instead.
4243 @findex COLLECT_EXPORT_LIST
4244 @item COLLECT_EXPORT_LIST
4245 If defined, @code{collect2} will scan the individual object files
4246 specified on its command line and create an export list for the linker.
4247 Define this macro for systems like AIX, where the linker discards
4248 object files that are not referenced from @code{main} and uses export
4251 @findex COLLECT2_HOST_INITIALIZATION
4252 @item COLLECT2_HOST_INITIALIZATION
4253 If defined, a C statement (sans semicolon) that performs host-dependent
4254 initialization when @code{collect2} is being initialized.
4256 @findex GCC_DRIVER_HOST_INITIALIZATION
4257 @item GCC_DRIVER_HOST_INITIALIZATION
4258 If defined, a C statement (sans semicolon) that performs host-dependent
4259 initialization when a compilation driver is being initialized.
4261 @findex UPDATE_PATH_HOST_CANONICALIZE
4262 @item UPDATE_PATH_HOST_CANONICALIZE (@var{path}, @var{key})
4263 If defined, a C statement (sans semicolon) that performs host-dependent
4264 canonicalization when a path used in a compilation driver or preprocessor is
4265 canonicalized. @var{path} is the path to be canonicalized, and @var{key} is
4266 a translation prefix when its value isn't @code{NULL}. If the C statement
4267 does canonicalize @var{path}, the new path should be returned.
4272 In addition, configuration files for system V define @code{bcopy},
4273 @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
4274 as a macro when compiled with GCC, in order to take advantage of the
4275 benefit of GCC's built-in @code{alloca}.
4278 @chapter Makefile Fragments
4279 @cindex makefile fragment
4281 When you configure GCC using the @file{configure} script
4282 (@pxref{Installation}), it will construct the file @file{Makefile} from
4283 the template file @file{Makefile.in}. When it does this, it will
4284 incorporate makefile fragment files from the @file{config} directory,
4285 named @file{t-@var{target}} and @file{x-@var{host}}. If these files do
4286 not exist, it means nothing needs to be added for a given target or
4290 * Target Fragment:: Writing the @file{t-@var{target}} file.
4291 * Host Fragment:: Writing the @file{x-@var{host}} file.
4294 @node Target Fragment
4295 @section The Target Makefile Fragment
4296 @cindex target makefile fragment
4297 @cindex @file{t-@var{target}}
4299 The target makefile fragment, @file{t-@var{target}}, defines special
4300 target dependent variables and targets used in the @file{Makefile}:
4305 The rule to use to build @file{libgcc1.a}.
4306 If your target does not need to use the functions in @file{libgcc1.a},
4310 @findex CROSS_LIBGCC1
4312 The rule to use to build @file{libgcc1.a} when building a cross
4313 compiler. If your target does not need to use the functions in
4314 @file{libgcc1.a}, set this to empty. @xref{Cross Runtime}.
4316 @findex LIBGCC2_CFLAGS
4317 @item LIBGCC2_CFLAGS
4318 Compiler flags to use when compiling @file{libgcc2.c}.
4320 @findex LIB2FUNCS_EXTRA
4321 @item LIB2FUNCS_EXTRA
4322 A list of source file names to be compiled or assembled and inserted
4323 into @file{libgcc.a}.
4325 @findex Floating Point Emulation
4326 @item Floating Point Emulation
4327 To have GCC include software floating point libraries in @file{libgcc.a}
4328 define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
4330 # We want fine grained libraries, so use the new code to build the
4331 # floating point emulation libraries.
4336 fp-bit.c: $(srcdir)/config/fp-bit.c
4337 echo '#define FLOAT' > fp-bit.c
4338 cat $(srcdir)/config/fp-bit.c >> fp-bit.c
4340 dp-bit.c: $(srcdir)/config/fp-bit.c
4341 cat $(srcdir)/config/fp-bit.c > dp-bit.c
4344 You may need to provide additional #defines at the beginning of @file{fp-bit.c}
4345 and @file{dp-bit.c} to control target endianness and other options.
4348 @findex CRTSTUFF_T_CFLAGS
4349 @item CRTSTUFF_T_CFLAGS
4350 Special flags used when compiling @file{crtstuff.c}.
4351 @xref{Initialization}.
4353 @findex CRTSTUFF_T_CFLAGS_S
4354 @item CRTSTUFF_T_CFLAGS_S
4355 Special flags used when compiling @file{crtstuff.c} for shared
4356 linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
4357 in @code{EXTRA-PARTS}.
4358 @xref{Initialization}.
4360 @findex MULTILIB_OPTIONS
4361 @item MULTILIB_OPTIONS
4362 For some targets, invoking GCC in different ways produces objects
4363 that can not be linked together. For example, for some targets GCC
4364 produces both big and little endian code. For these targets, you must
4365 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
4366 each set of incompatible options. When GCC invokes the linker, it
4367 arranges to link in the right version of @file{libgcc.a}, based on
4368 the command line options used.
4370 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
4371 special versions of @file{libgcc.a} must be built. Write options that
4372 are mutually incompatible side by side, separated by a slash. Write
4373 options that may be used together separated by a space. The build
4374 procedure will build all combinations of compatible options.
4376 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
4377 msoft-float}, @file{Makefile} will build special versions of
4378 @file{libgcc.a} using the following sets of options: @samp{-m68000},
4379 @samp{-m68020}, @samp{-msoft-float}, @samp{-m68000 -msoft-float}, and
4380 @samp{-m68020 -msoft-float}.
4382 @findex MULTILIB_DIRNAMES
4383 @item MULTILIB_DIRNAMES
4384 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
4385 directory names that should be used to hold the various libraries.
4386 Write one element in @code{MULTILIB_DIRNAMES} for each element in
4387 @code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
4388 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
4391 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
4392 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
4393 @samp{m68000 m68020 msoft-float}. You may specify a different value if
4394 you desire a different set of directory names.
4396 @findex MULTILIB_MATCHES
4397 @item MULTILIB_MATCHES
4398 Sometimes the same option may be written in two different ways. If an
4399 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
4400 any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
4401 items of the form @samp{option=option} to describe all relevant
4402 synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
4404 @findex MULTILIB_EXCEPTIONS
4405 @item MULTILIB_EXCEPTIONS
4406 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
4407 specified, there are combinations that should not be built. In that
4408 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
4409 in shell case syntax that should not be built.
4411 For example, in the PowerPC embedded ABI support, it is not desirable
4412 to build libraries compiled with the @samp{-mcall-aix} option
4413 and either of the @samp{-fleading-underscore} or @samp{-mlittle} options
4414 at the same time. Therefore @code{MULTILIB_EXCEPTIONS} is set to
4415 @code{*mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*}.
4417 @findex MULTILIB_EXTRA_OPTS
4418 @item MULTILIB_EXTRA_OPTS
4419 Sometimes it is desirable that when building multiple versions of
4420 @file{libgcc.a} certain options should always be passed on to the
4421 compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
4422 of options to be used for all builds.
4426 @section The Host Makefile Fragment
4427 @cindex host makefile fragment
4428 @cindex @file{x-@var{host}}
4430 The host makefile fragment, @file{x-@var{host}}, defines special host
4431 dependent variables and targets used in the @file{Makefile}:
4436 The compiler to use when building the first stage.
4440 Additional host libraries to link with.
4444 The compiler to use when building @file{libgcc1.a} for a native
4449 The version of @code{ar} to use when building @file{libgcc1.a} for a native
4454 The install program to use.
4459 @unnumbered Funding Free Software
4461 If you want to have more free software a few years from now, it makes
4462 sense for you to help encourage people to contribute funds for its
4463 development. The most effective approach known is to encourage
4464 commercial redistributors to donate.
4466 Users of free software systems can boost the pace of development by
4467 encouraging for-a-fee distributors to donate part of their selling price
4468 to free software developers---the Free Software Foundation, and others.
4470 The way to convince distributors to do this is to demand it and expect
4471 it from them. So when you compare distributors, judge them partly by
4472 how much they give to free software development. Show distributors
4473 they must compete to be the one who gives the most.
4475 To make this approach work, you must insist on numbers that you can
4476 compare, such as, ``We will donate ten dollars to the Frobnitz project
4477 for each disk sold.'' Don't be satisfied with a vague promise, such as
4478 ``A portion of the profits are donated,'' since it doesn't give a basis
4481 Even a precise fraction ``of the profits from this disk'' is not very
4482 meaningful, since creative accounting and unrelated business decisions
4483 can greatly alter what fraction of the sales price counts as profit.
4484 If the price you pay is $50, ten percent of the profit is probably
4485 less than a dollar; it might be a few cents, or nothing at all.
4487 Some redistributors do development work themselves. This is useful too;
4488 but to keep everyone honest, you need to inquire how much they do, and
4489 what kind. Some kinds of development make much more long-term
4490 difference than others. For example, maintaining a separate version of
4491 a program contributes very little; maintaining the standard version of a
4492 program for the whole community contributes much. Easy new ports
4493 contribute little, since someone else would surely do them; difficult
4494 ports such as adding a new CPU to the GNU Compiler Collection contribute more;
4495 major new features or packages contribute the most.
4497 By establishing the idea that supporting further development is ``the
4498 proper thing to do'' when distributing free software for a fee, we can
4499 assure a steady flow of resources into making more free software.
4502 Copyright (C) 1994 Free Software Foundation, Inc.
4503 Verbatim copying and redistribution of this section is permitted
4504 without royalty; alteration is not permitted.
4508 @unnumbered Linux and the GNU Project
4510 Many computer users run a modified version of the GNU system every
4511 day, without realizing it. Through a peculiar turn of events, the
4512 version of GNU which is widely used today is more often known as
4513 ``Linux'', and many users are not aware of the extent of its
4514 connection with the GNU Project.
4516 There really is a Linux; it is a kernel, and these people are using
4517 it. But you can't use a kernel by itself; a kernel is useful only as
4518 part of a whole system. The system in which Linux is typically used
4519 is a modified variant of the GNU system---in other words, a Linux-based
4522 Many users are not fully aware of the distinction between the kernel,
4523 which is Linux, and the whole system, which they also call ``Linux''.
4524 The ambiguous use of the name doesn't promote understanding.
4526 Programmers generally know that Linux is a kernel. But since they
4527 have generally heard the whole system called ``Linux'' as well, they
4528 often envisage a history which fits that name. For example, many
4529 believe that once Linus Torvalds finished writing the kernel, his
4530 friends looked around for other free software, and for no particular
4531 reason most everything necessary to make a Unix-like system was
4534 What they found was no accident---it was the GNU system. The available
4535 free software added up to a complete system because the GNU Project
4536 had been working since 1984 to make one. The GNU Manifesto
4537 had set forth the goal of developing a free Unix-like system, called
4538 GNU. By the time Linux was written, the system was almost finished.
4540 Most free software projects have the goal of developing a particular
4541 program for a particular job. For example, Linus Torvalds set out to
4542 write a Unix-like kernel (Linux); Donald Knuth set out to write a text
4543 formatter (TeX); Bob Scheifler set out to develop a window system (X
4544 Windows). It's natural to measure the contribution of this kind of
4545 project by specific programs that came from the project.
4547 If we tried to measure the GNU Project's contribution in this way,
4548 what would we conclude? One CD-ROM vendor found that in their ``Linux
4549 distribution'', GNU software was the largest single contingent, around
4550 28% of the total source code, and this included some of the essential
4551 major components without which there could be no system. Linux itself
4552 was about 3%. So if you were going to pick a name for the system
4553 based on who wrote the programs in the system, the most appropriate
4554 single choice would be ``GNU''.
4556 But we don't think that is the right way to consider the question.
4557 The GNU Project was not, is not, a project to develop specific
4558 software packages. It was not a project to develop a C compiler,
4559 although we did. It was not a project to develop a text editor,
4560 although we developed one. The GNU Project's aim was to develop
4561 @emph{a complete free Unix-like system}.
4563 Many people have made major contributions to the free software in the
4564 system, and they all deserve credit. But the reason it is @emph{a
4565 system}---and not just a collection of useful programs---is because the
4566 GNU Project set out to make it one. We wrote the programs that were
4567 needed to make a @emph{complete} free system. We wrote essential but
4568 unexciting major components, such as the assembler and linker, because
4569 you can't have a system without them. A complete system needs more
4570 than just programming tools, so we wrote other components as well,
4571 such as the Bourne Again SHell, the PostScript interpreter
4572 Ghostscript, and the GNU C library.
4574 By the early 90s we had put together the whole system aside from the
4575 kernel (and we were also working on a kernel, the GNU Hurd, which runs
4576 on top of Mach). Developing this kernel has been a lot harder than we
4577 expected, and we are still working on finishing it.
4579 Fortunately, you don't have to wait for it, because Linux is working
4580 now. When Linus Torvalds wrote Linux, he filled the last major gap.
4581 People could then put Linux together with the GNU system to make a
4582 complete free system: a Linux-based GNU system (or GNU/Linux system,
4585 Putting them together sounds simple, but it was not a trivial job.
4586 The GNU C library (called glibc for short) needed substantial changes.
4587 Integrating a complete system as a distribution that would work ``out
4588 of the box'' was a big job, too. It required addressing the issue of
4589 how to install and boot the system---a problem we had not tackled,
4590 because we hadn't yet reached that point. The people who developed
4591 the various system distributions made a substantial contribution.
4593 The GNU Project supports GNU/Linux systems as well as @emph{the}
4594 GNU system---even with funds. We funded the rewriting of the
4595 Linux-related extensions to the GNU C library, so that now they are
4596 well integrated, and the newest GNU/Linux systems use the current
4597 library release with no changes. We also funded an early stage of the
4598 development of Debian GNU/Linux.
4600 We use Linux-based GNU systems today for most of our work, and we hope
4601 you use them too. But please don't confuse the public by using the
4602 name ``Linux'' ambiguously. Linux is the kernel, one of the essential
4603 major components of the system. The system as a whole is more or less
4607 @unnumbered GNU GENERAL PUBLIC LICENSE
4608 @center Version 2, June 1991
4611 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
4612 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
4614 Everyone is permitted to copy and distribute verbatim copies
4615 of this license document, but changing it is not allowed.
4618 @unnumberedsec Preamble
4620 The licenses for most software are designed to take away your
4621 freedom to share and change it. By contrast, the GNU General Public
4622 License is intended to guarantee your freedom to share and change free
4623 software---to make sure the software is free for all its users. This
4624 General Public License applies to most of the Free Software
4625 Foundation's software and to any other program whose authors commit to
4626 using it. (Some other Free Software Foundation software is covered by
4627 the GNU Library General Public License instead.) You can apply it to
4630 When we speak of free software, we are referring to freedom, not
4631 price. Our General Public Licenses are designed to make sure that you
4632 have the freedom to distribute copies of free software (and charge for
4633 this service if you wish), that you receive source code or can get it
4634 if you want it, that you can change the software or use pieces of it
4635 in new free programs; and that you know you can do these things.
4637 To protect your rights, we need to make restrictions that forbid
4638 anyone to deny you these rights or to ask you to surrender the rights.
4639 These restrictions translate to certain responsibilities for you if you
4640 distribute copies of the software, or if you modify it.
4642 For example, if you distribute copies of such a program, whether
4643 gratis or for a fee, you must give the recipients all the rights that
4644 you have. You must make sure that they, too, receive or can get the
4645 source code. And you must show them these terms so they know their
4648 We protect your rights with two steps: (1) copyright the software, and
4649 (2) offer you this license which gives you legal permission to copy,
4650 distribute and/or modify the software.
4652 Also, for each author's protection and ours, we want to make certain
4653 that everyone understands that there is no warranty for this free
4654 software. If the software is modified by someone else and passed on, we
4655 want its recipients to know that what they have is not the original, so
4656 that any problems introduced by others will not reflect on the original
4657 authors' reputations.
4659 Finally, any free program is threatened constantly by software
4660 patents. We wish to avoid the danger that redistributors of a free
4661 program will individually obtain patent licenses, in effect making the
4662 program proprietary. To prevent this, we have made it clear that any
4663 patent must be licensed for everyone's free use or not licensed at all.
4665 The precise terms and conditions for copying, distribution and
4666 modification follow.
4669 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4672 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4677 This License applies to any program or other work which contains
4678 a notice placed by the copyright holder saying it may be distributed
4679 under the terms of this General Public License. The ``Program'', below,
4680 refers to any such program or work, and a ``work based on the Program''
4681 means either the Program or any derivative work under copyright law:
4682 that is to say, a work containing the Program or a portion of it,
4683 either verbatim or with modifications and/or translated into another
4684 language. (Hereinafter, translation is included without limitation in
4685 the term ``modification''.) Each licensee is addressed as ``you''.
4687 Activities other than copying, distribution and modification are not
4688 covered by this License; they are outside its scope. The act of
4689 running the Program is not restricted, and the output from the Program
4690 is covered only if its contents constitute a work based on the
4691 Program (independent of having been made by running the Program).
4692 Whether that is true depends on what the Program does.
4695 You may copy and distribute verbatim copies of the Program's
4696 source code as you receive it, in any medium, provided that you
4697 conspicuously and appropriately publish on each copy an appropriate
4698 copyright notice and disclaimer of warranty; keep intact all the
4699 notices that refer to this License and to the absence of any warranty;
4700 and give any other recipients of the Program a copy of this License
4701 along with the Program.
4703 You may charge a fee for the physical act of transferring a copy, and
4704 you may at your option offer warranty protection in exchange for a fee.
4707 You may modify your copy or copies of the Program or any portion
4708 of it, thus forming a work based on the Program, and copy and
4709 distribute such modifications or work under the terms of Section 1
4710 above, provided that you also meet all of these conditions:
4714 You must cause the modified files to carry prominent notices
4715 stating that you changed the files and the date of any change.
4718 You must cause any work that you distribute or publish, that in
4719 whole or in part contains or is derived from the Program or any
4720 part thereof, to be licensed as a whole at no charge to all third
4721 parties under the terms of this License.
4724 If the modified program normally reads commands interactively
4725 when run, you must cause it, when started running for such
4726 interactive use in the most ordinary way, to print or display an
4727 announcement including an appropriate copyright notice and a
4728 notice that there is no warranty (or else, saying that you provide
4729 a warranty) and that users may redistribute the program under
4730 these conditions, and telling the user how to view a copy of this
4731 License. (Exception: if the Program itself is interactive but
4732 does not normally print such an announcement, your work based on
4733 the Program is not required to print an announcement.)
4736 These requirements apply to the modified work as a whole. If
4737 identifiable sections of that work are not derived from the Program,
4738 and can be reasonably considered independent and separate works in
4739 themselves, then this License, and its terms, do not apply to those
4740 sections when you distribute them as separate works. But when you
4741 distribute the same sections as part of a whole which is a work based
4742 on the Program, the distribution of the whole must be on the terms of
4743 this License, whose permissions for other licensees extend to the
4744 entire whole, and thus to each and every part regardless of who wrote it.
4746 Thus, it is not the intent of this section to claim rights or contest
4747 your rights to work written entirely by you; rather, the intent is to
4748 exercise the right to control the distribution of derivative or
4749 collective works based on the Program.
4751 In addition, mere aggregation of another work not based on the Program
4752 with the Program (or with a work based on the Program) on a volume of
4753 a storage or distribution medium does not bring the other work under
4754 the scope of this License.
4757 You may copy and distribute the Program (or a work based on it,
4758 under Section 2) in object code or executable form under the terms of
4759 Sections 1 and 2 above provided that you also do one of the following:
4763 Accompany it with the complete corresponding machine-readable
4764 source code, which must be distributed under the terms of Sections
4765 1 and 2 above on a medium customarily used for software interchange; or,
4768 Accompany it with a written offer, valid for at least three
4769 years, to give any third party, for a charge no more than your
4770 cost of physically performing source distribution, a complete
4771 machine-readable copy of the corresponding source code, to be
4772 distributed under the terms of Sections 1 and 2 above on a medium
4773 customarily used for software interchange; or,
4776 Accompany it with the information you received as to the offer
4777 to distribute corresponding source code. (This alternative is
4778 allowed only for noncommercial distribution and only if you
4779 received the program in object code or executable form with such
4780 an offer, in accord with Subsection b above.)
4783 The source code for a work means the preferred form of the work for
4784 making modifications to it. For an executable work, complete source
4785 code means all the source code for all modules it contains, plus any
4786 associated interface definition files, plus the scripts used to
4787 control compilation and installation of the executable. However, as a
4788 special exception, the source code distributed need not include
4789 anything that is normally distributed (in either source or binary
4790 form) with the major components (compiler, kernel, and so on) of the
4791 operating system on which the executable runs, unless that component
4792 itself accompanies the executable.
4794 If distribution of executable or object code is made by offering
4795 access to copy from a designated place, then offering equivalent
4796 access to copy the source code from the same place counts as
4797 distribution of the source code, even though third parties are not
4798 compelled to copy the source along with the object code.
4801 You may not copy, modify, sublicense, or distribute the Program
4802 except as expressly provided under this License. Any attempt
4803 otherwise to copy, modify, sublicense or distribute the Program is
4804 void, and will automatically terminate your rights under this License.
4805 However, parties who have received copies, or rights, from you under
4806 this License will not have their licenses terminated so long as such
4807 parties remain in full compliance.
4810 You are not required to accept this License, since you have not
4811 signed it. However, nothing else grants you permission to modify or
4812 distribute the Program or its derivative works. These actions are
4813 prohibited by law if you do not accept this License. Therefore, by
4814 modifying or distributing the Program (or any work based on the
4815 Program), you indicate your acceptance of this License to do so, and
4816 all its terms and conditions for copying, distributing or modifying
4817 the Program or works based on it.
4820 Each time you redistribute the Program (or any work based on the
4821 Program), the recipient automatically receives a license from the
4822 original licensor to copy, distribute or modify the Program subject to
4823 these terms and conditions. You may not impose any further
4824 restrictions on the recipients' exercise of the rights granted herein.
4825 You are not responsible for enforcing compliance by third parties to
4829 If, as a consequence of a court judgment or allegation of patent
4830 infringement or for any other reason (not limited to patent issues),
4831 conditions are imposed on you (whether by court order, agreement or
4832 otherwise) that contradict the conditions of this License, they do not
4833 excuse you from the conditions of this License. If you cannot
4834 distribute so as to satisfy simultaneously your obligations under this
4835 License and any other pertinent obligations, then as a consequence you
4836 may not distribute the Program at all. For example, if a patent
4837 license would not permit royalty-free redistribution of the Program by
4838 all those who receive copies directly or indirectly through you, then
4839 the only way you could satisfy both it and this License would be to
4840 refrain entirely from distribution of the Program.
4842 If any portion of this section is held invalid or unenforceable under
4843 any particular circumstance, the balance of the section is intended to
4844 apply and the section as a whole is intended to apply in other
4847 It is not the purpose of this section to induce you to infringe any
4848 patents or other property right claims or to contest validity of any
4849 such claims; this section has the sole purpose of protecting the
4850 integrity of the free software distribution system, which is
4851 implemented by public license practices. Many people have made
4852 generous contributions to the wide range of software distributed
4853 through that system in reliance on consistent application of that
4854 system; it is up to the author/donor to decide if he or she is willing
4855 to distribute software through any other system and a licensee cannot
4858 This section is intended to make thoroughly clear what is believed to
4859 be a consequence of the rest of this License.
4862 If the distribution and/or use of the Program is restricted in
4863 certain countries either by patents or by copyrighted interfaces, the
4864 original copyright holder who places the Program under this License
4865 may add an explicit geographical distribution limitation excluding
4866 those countries, so that distribution is permitted only in or among
4867 countries not thus excluded. In such case, this License incorporates
4868 the limitation as if written in the body of this License.
4871 The Free Software Foundation may publish revised and/or new versions
4872 of the General Public License from time to time. Such new versions will
4873 be similar in spirit to the present version, but may differ in detail to
4874 address new problems or concerns.
4876 Each version is given a distinguishing version number. If the Program
4877 specifies a version number of this License which applies to it and ``any
4878 later version'', you have the option of following the terms and conditions
4879 either of that version or of any later version published by the Free
4880 Software Foundation. If the Program does not specify a version number of
4881 this License, you may choose any version ever published by the Free Software
4885 If you wish to incorporate parts of the Program into other free
4886 programs whose distribution conditions are different, write to the author
4887 to ask for permission. For software which is copyrighted by the Free
4888 Software Foundation, write to the Free Software Foundation; we sometimes
4889 make exceptions for this. Our decision will be guided by the two goals
4890 of preserving the free status of all derivatives of our free software and
4891 of promoting the sharing and reuse of software generally.
4894 @heading NO WARRANTY
4901 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
4902 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
4903 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
4904 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
4905 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
4906 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
4907 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
4908 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
4909 REPAIR OR CORRECTION.
4912 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
4913 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
4914 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
4915 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
4916 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
4917 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
4918 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
4919 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
4920 POSSIBILITY OF SUCH DAMAGES.
4924 @heading END OF TERMS AND CONDITIONS
4927 @center END OF TERMS AND CONDITIONS
4931 @unnumberedsec How to Apply These Terms to Your New Programs
4933 If you develop a new program, and you want it to be of the greatest
4934 possible use to the public, the best way to achieve this is to make it
4935 free software which everyone can redistribute and change under these terms.
4937 To do so, attach the following notices to the program. It is safest
4938 to attach them to the start of each source file to most effectively
4939 convey the exclusion of warranty; and each file should have at least
4940 the ``copyright'' line and a pointer to where the full notice is found.
4943 @var{one line to give the program's name and a brief idea of what it does.}
4944 Copyright (C) @var{yyyy} @var{name of author}
4946 This program is free software; you can redistribute it and/or modify
4947 it under the terms of the GNU General Public License as published by
4948 the Free Software Foundation; either version 2 of the License, or
4949 (at your option) any later version.
4951 This program is distributed in the hope that it will be useful,
4952 but WITHOUT ANY WARRANTY; without even the implied warranty of
4953 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4954 GNU General Public License for more details.
4956 You should have received a copy of the GNU General Public License
4957 along with this program; if not, write to the Free Software
4958 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
4961 Also add information on how to contact you by electronic and paper mail.
4963 If the program is interactive, make it output a short notice like this
4964 when it starts in an interactive mode:
4967 Gnomovision version 69, Copyright (C) @var{yyyy} @var{name of author}
4968 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
4970 This is free software, and you are welcome to redistribute it
4971 under certain conditions; type `show c' for details.
4974 The hypothetical commands @samp{show w} and @samp{show c} should show
4975 the appropriate parts of the General Public License. Of course, the
4976 commands you use may be called something other than @samp{show w} and
4977 @samp{show c}; they could even be mouse-clicks or menu items---whatever
4980 You should also get your employer (if you work as a programmer) or your
4981 school, if any, to sign a ``copyright disclaimer'' for the program, if
4982 necessary. Here is a sample; alter the names:
4985 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
4986 `Gnomovision' (which makes passes at compilers) written by James Hacker.
4988 @var{signature of Ty Coon}, 1 April 1989
4989 Ty Coon, President of Vice
4992 This General Public License does not permit incorporating your program into
4993 proprietary programs. If your program is a subroutine library, you may
4994 consider it more useful to permit linking proprietary applications with the
4995 library. If this is what you want to do, use the GNU Library General
4996 Public License instead of this License.
4999 @unnumbered Contributors to GCC
5000 @cindex contributors
5001 @include contrib.texi