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
50 @settitle Using and Porting the GNU Compiler Collection (GCC)
53 @c seems reasonable to assume at least one of INTERNALS or USING is set...
55 @settitle Using the GNU Compiler Collection
58 @settitle Porting the GNU Compiler Collection
65 @c Use with @@smallbook.
67 @c Cause even numbered pages to be printed on the left hand side of
68 @c the page and odd numbered pages to be printed on the right hand
69 @c side of the page. Using this, you can print on both sides of a
70 @c sheet of paper and have the text on the same part of the sheet.
72 @c The text on right hand pages is pushed towards the right hand
73 @c margin and the text on left hand pages is pushed toward the left
75 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
78 @c \global\bindingoffset=0.75in
79 @c \global\normaloffset =0.75in
83 @dircategory Programming
85 * gcc: (gcc). The GNU Compiler Collection.
89 This file documents the use and the internals of the GNU compiler.
93 This file documents the internals of the GNU compiler.
96 This file documents the use of the GNU compiler.
99 Published by the Free Software Foundation
100 59 Temple Place - Suite 330
101 Boston, MA 02111-1307 USA
103 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
105 Permission is granted to make and distribute verbatim copies of
106 this manual provided the copyright notice and this permission notice
107 are preserved on all copies.
110 Permission is granted to process this file through Tex and print the
111 results, provided the printed document carries copying permission
112 notice identical to this one except for the removal of this paragraph
113 (this paragraph not being relevant to the printed manual).
116 Permission is granted to copy and distribute modified versions of this
117 manual under the conditions for verbatim copying, provided also that the
118 sections entitled ``GNU General Public License'' and ``Funding for Free
119 Software'' are included exactly as in the original, and provided that
120 the entire resulting derived work is distributed under the terms of a
121 permission notice identical to this one.
123 Permission is granted to copy and distribute translations of this manual
124 into another language, under the above conditions for modified versions,
125 except that the sections entitled ``GNU General Public License'' and
126 ``Funding for Free Software'', and this permission notice, may be
127 included in translations approved by the Free Software Foundation
128 instead of in the original English.
131 @setchapternewpage odd
136 @center @titlefont{Using and Porting the GNU Compiler Collection}
141 @title Using the GNU Compiler Collection
144 @title Porting the GNU Compiler Collection
147 @center Richard M. Stallman
149 @center Last updated 28 July 1999
151 @c The version number appears five times more in this file.
155 @vskip 0pt plus 1filll
156 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998, 1999 Free Software Foundation, Inc.
158 For GCC Version 2.95@*
160 Published by the Free Software Foundation @*
161 59 Temple Place - Suite 330@*
162 Boston, MA 02111-1307, USA@*
163 Last printed April, 1998.@*
164 Printed copies are available for $50 each.@*
167 Permission is granted to make and distribute verbatim copies of
168 this manual provided the copyright notice and this permission notice
169 are preserved on all copies.
171 Permission is granted to copy and distribute modified versions of this
172 manual under the conditions for verbatim copying, provided also that the
173 sections entitled ``GNU General Public License'' and ``Funding for Free
174 Software'' are included exactly as in the original, and provided that
175 the entire resulting derived work is distributed under the terms of a
176 permission notice identical to this one.
178 Permission is granted to copy and distribute translations of this manual
179 into another language, under the above conditions for modified versions,
180 except that the sections entitled ``GNU General Public License'' and
181 ``Funding for Free Software'', and this permission notice, may be
182 included in translations approved by the Free Software Foundation
183 instead of in the original English.
189 @node Top, G++ and GCC,, (DIR)
195 This manual documents how to run, install and port the GNU
196 compiler, as well as its new features and incompatibilities, and how to
197 report bugs. It corresponds to GCC version 2.95.
202 This manual documents how to run and install the GNU compiler,
203 as well as its new features and incompatibilities, and how to report
204 bugs. It corresponds to GCC version 2.95.
207 This manual documents how to port the GNU compiler,
208 as well as its new features and incompatibilities, and how to report
209 bugs. It corresponds to GCC version 2.95.
215 * G++ and GCC:: You can compile C or C++ programs.
216 * Invoking GCC:: Command options supported by @samp{gcc}.
217 * Installation:: How to configure, compile and install GCC.
218 * C Extensions:: GNU extensions to the C language family.
219 * C++ Extensions:: GNU extensions to the C++ language.
220 * Gcov:: gcov: a GCC test coverage program.
221 * Trouble:: If you have trouble installing GCC.
222 * Bugs:: How, why and where to report bugs.
223 * Service:: How to find suppliers of support for GCC.
224 * Contributing:: How to contribute to testing and developing GCC.
225 * VMS:: Using GCC on VMS.
228 * Portability:: Goals of GCC's portability features.
229 * Interface:: Function-call interface of GCC output.
230 * Passes:: Order of passes, what they do, and what each file is for.
231 * RTL:: The intermediate representation that most passes work on.
232 * Machine Desc:: How to write machine description instruction patterns.
233 * Target Macros:: How to write the machine description C macros.
234 * Config:: Writing the @file{xm-@var{machine}.h} file.
235 * Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
238 * Funding:: How to help assure funding for free software.
239 * GNU/Linux:: Linux and the GNU Project
241 * Copying:: GNU General Public License says
242 how you can copy and share GCC.
243 * Contributors:: People who have contributed to GCC.
245 * Index:: Index of concepts and symbol names.
250 @chapter Compile C, C++, Objective C, or Fortran
253 The C, C++, and Objective C, and Fortran versions of the compiler are
254 integrated; this is why we use the name ``GNU Compiler Collection''.
255 GCC can compile programs written in C, C++, Objective C, or Fortran.
256 The Fortran compiler is described in a separate manual.
259 ``GCC'' is a common shorthand term for the GNU Compiler Collection. This is both
260 the most general name for the compiler, and the name used when the
261 emphasis is on compiling C programs (as the abbreviation formerly
262 stood for ``GNU C Compiler'').
266 When referring to C++ compilation, it is usual to call the compiler
267 ``G++''. Since there is only one compiler, it is also accurate to call
268 it ``GCC'' no matter what the language context; however, the term
269 ``G++'' is more useful when the emphasis is on compiling C++ programs.
271 We use the name ``GCC'' to refer to the compilation system as a
272 whole, and more specifically to the language-independent part of the
273 compiler. For example, we refer to the optimization options as
274 affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
276 Front ends for other languages, such as Ada 9X, Fortran, Modula-3, and
277 Pascal, are under development. These front-ends, like that for C++, are
278 built in subdirectories of GCC and link to it. The result is an
279 integrated compiler that can compile programs written in C, C++,
280 Objective C, or any of the languages for which you have installed front
283 In this manual, we only discuss the options for the C, Objective-C, and
284 C++ compilers and those of the GCC core. Consult the documentation
285 of the other front ends for the options to use when compiling programs
286 written in other languages.
288 @cindex compiler compared to C++ preprocessor
289 @cindex intermediate C version, nonexistent
290 @cindex C intermediate output, nonexistent
291 G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object
292 code directly from your C++ program source. There is no intermediate C
293 version of the program. (By contrast, for example, some other
294 implementations use a program that generates a C program from your C++
295 source.) Avoiding an intermediate C representation of the program means
296 that you get better object code, and better debugging information. The
297 GNU debugger, GDB, works with this information in the object code to
298 give you comprehensive C++ source-level editing capabilities
299 (@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
301 @c FIXME! Someone who knows something about Objective C ought to put in
302 @c a paragraph or two about it here, and move the index entry down when
303 @c there is more to point to than the general mention in the 1st par.
307 @include install.texi
314 @chapter Known Causes of Trouble with GCC
316 @cindex installation trouble
317 @cindex known causes of trouble
319 This section describes known problems that affect users of GCC. Most
320 of these are not GCC bugs per se---if they were, we would fix them.
321 But the result for a user may be like the result of a bug.
323 Some of these problems are due to bugs in other software, some are
324 missing features that are too much work to add, and some are places
325 where people's opinions differ as to what is best.
328 * Actual Bugs:: Bugs we will fix later.
329 * Installation Problems:: Problems that manifest when you install GCC.
330 * Cross-Compiler Problems:: Common problems of cross compiling with GCC.
331 * Interoperation:: Problems using GCC with other compilers,
332 and with certain linkers, assemblers and debuggers.
333 * External Bugs:: Problems compiling certain programs.
334 * Incompatibilities:: GCC is incompatible with traditional C.
335 * Fixed Headers:: GNU C uses corrected versions of system header files.
336 This is necessary, but doesn't always work smoothly.
337 * Standard Libraries:: GNU C uses the system C library, which might not be
338 compliant with the ISO/ANSI C standard.
339 * Disappointments:: Regrettable things we can't change, but not quite bugs.
340 * C++ Misunderstandings:: Common misunderstandings with GNU C++.
341 * Protoize Caveats:: Things to watch out for when using @code{protoize}.
342 * Non-bugs:: Things we think are right, but some others disagree.
343 * Warnings and Errors:: Which problems in your code get warnings,
344 and which get errors.
348 @section Actual Bugs We Haven't Fixed Yet
352 The @code{fixincludes} script interacts badly with automounters; if the
353 directory of system header files is automounted, it tends to be
354 unmounted while @code{fixincludes} is running. This would seem to be a
355 bug in the automounter. We don't know any good way to work around it.
358 The @code{fixproto} script will sometimes add prototypes for the
359 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
360 @code{jmp_buf} type before that type is defined. To work around this,
361 edit the offending file and place the typedef in front of the
365 There are several obscure case of mis-using struct, union, and
366 enum tags that are not detected as errors by the compiler.
369 When @samp{-pedantic-errors} is specified, GCC will incorrectly give
370 an error message when a function name is specified in an expression
371 involving the comma operator.
374 Loop unrolling doesn't work properly for certain C++ programs. This is
375 a bug in the C++ front end. It sometimes emits incorrect debug info, and
376 the loop unrolling code is unable to recover from this error.
379 @node Installation Problems
380 @section Installation Problems
382 This is a list of problems (and some apparent problems which don't
383 really mean anything is wrong) that show up during installation of GNU
388 On certain systems, defining certain environment variables such as
389 @code{CC} can interfere with the functioning of @code{make}.
392 If you encounter seemingly strange errors when trying to build the
393 compiler in a directory other than the source directory, it could be
394 because you have previously configured the compiler in the source
395 directory. Make sure you have done all the necessary preparations.
399 If you build GCC on a BSD system using a directory stored in a System
400 V file system, problems may occur in running @code{fixincludes} if the
401 System V file system doesn't support symbolic links. These problems
402 result in a failure to fix the declaration of @code{size_t} in
403 @file{sys/types.h}. If you find that @code{size_t} is a signed type and
404 that type mismatches occur, this could be the cause.
406 The solution is not to use such a directory for building GCC.
409 In previous versions of GCC, the @code{gcc} driver program looked for
410 @code{as} and @code{ld} in various places; for example, in files
411 beginning with @file{/usr/local/lib/gcc-}. GCC version 2 looks for
412 them in the directory
413 @file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}.
415 Thus, to use a version of @code{as} or @code{ld} that is not the system
416 default, for example @code{gas} or GNU @code{ld}, you must put them in
417 that directory (or make links to them from that directory).
420 Some commands executed when making the compiler may fail (return a
421 non-zero status) and be ignored by @code{make}. These failures, which
422 are often due to files that were not found, are expected, and can safely
426 It is normal to have warnings in compiling certain files about
427 unreachable code and about enumeration type clashes. These files' names
428 begin with @samp{insn-}. Also, @file{real.c} may get some warnings that
432 Sometimes @code{make} recompiles parts of the compiler when installing
433 the compiler. In one case, this was traced down to a bug in
434 @code{make}. Either ignore the problem or switch to GNU Make.
437 If you have installed a program known as purify, you may find that it
438 causes errors while linking @code{enquire}, which is part of building
439 GCC. The fix is to get rid of the file @code{real-ld} which purify
440 installs---so that GCC won't try to use it.
443 On GNU/Linux SLS 1.01, there is a problem with @file{libc.a}: it does not
444 contain the obstack functions. However, GCC assumes that the obstack
445 functions are in @file{libc.a} when it is the GNU C library. To work
446 around this problem, change the @code{__GNU_LIBRARY__} conditional
447 around line 31 to @samp{#if 1}.
450 On some 386 systems, building the compiler never finishes because
451 @code{enquire} hangs due to a hardware problem in the motherboard---it
452 reports floating point exceptions to the kernel incorrectly. You can
453 install GCC except for @file{float.h} by patching out the command to
454 run @code{enquire}. You may also be able to fix the problem for real by
455 getting a replacement motherboard. This problem was observed in
456 Revision E of the Micronics motherboard, and is fixed in Revision F.
457 It has also been observed in the MYLEX MXA-33 motherboard.
459 If you encounter this problem, you may also want to consider removing
460 the FPU from the socket during the compilation. Alternatively, if you
461 are running SCO Unix, you can reboot and force the FPU to be ignored.
462 To do this, type @samp{hd(40)unix auto ignorefpu}.
465 On some 386 systems, GCC crashes trying to compile @file{enquire.c}.
466 This happens on machines that don't have a 387 FPU chip. On 386
467 machines, the system kernel is supposed to emulate the 387 when you
468 don't have one. The crash is due to a bug in the emulator.
470 One of these systems is the Unix from Interactive Systems: 386/ix.
471 On this system, an alternate emulator is provided, and it does work.
472 To use it, execute this command as super-user:
475 ln /etc/emulator.rel1 /etc/emulator
479 and then reboot the system. (The default emulator file remains present
480 under the name @file{emulator.dflt}.)
482 Try using @file{/etc/emulator.att}, if you have such a problem on the
485 Another system which has this problem is Esix. We don't know whether it
486 has an alternate emulator that works.
488 On NetBSD 0.8, a similar problem manifests itself as these error messages:
491 enquire.c: In function `fprop':
492 enquire.c:2328: floating overflow
496 On SCO systems, when compiling GCC with the system's compiler,
497 do not use @samp{-O}. Some versions of the system's compiler miscompile
500 @cindex @code{genflags}, crash on Sun 4
502 Sometimes on a Sun 4 you may observe a crash in the program
503 @code{genflags} or @code{genoutput} while building GCC. This is said to
504 be due to a bug in @code{sh}. You can probably get around it by running
505 @code{genflags} or @code{genoutput} manually and then retrying the
509 On Solaris 2, executables of GCC version 2.0.2 are commonly
510 available, but they have a bug that shows up when compiling current
511 versions of GCC: undefined symbol errors occur during assembly if you
514 The solution is to compile the current version of GCC without
515 @samp{-g}. That makes a working compiler which you can use to recompile
519 Solaris 2 comes with a number of optional OS packages. Some of these
520 packages are needed to use GCC fully. If you did not install all
521 optional packages when installing Solaris, you will need to verify that
522 the packages that GCC needs are installed.
524 To check whether an optional package is installed, use
525 the @code{pkginfo} command. To add an optional package, use the
526 @code{pkgadd} command. For further details, see the Solaris
529 For Solaris 2.0 and 2.1, GCC needs six packages: @samp{SUNWarc},
530 @samp{SUNWbtool}, @samp{SUNWesu}, @samp{SUNWhea}, @samp{SUNWlibm}, and
533 For Solaris 2.2, GCC needs an additional seventh package: @samp{SUNWsprot}.
536 On Solaris 2, trying to use the linker and other tools in
537 @file{/usr/ucb} to install GCC has been observed to cause trouble.
538 For example, the linker may hang indefinitely. The fix is to remove
539 @file{/usr/ucb} from your @code{PATH}.
542 If you use the 1.31 version of the MIPS assembler (such as was shipped
543 with Ultrix 3.1), you will need to use the -fno-delayed-branch switch
544 when optimizing floating point code. Otherwise, the assembler will
545 complain when the GCC compiler fills a branch delay slot with a
546 floating point instruction, such as @code{add.d}.
549 If on a MIPS system you get an error message saying ``does not have gp
550 sections for all it's [sic] sectons [sic]'', don't worry about it. This
551 happens whenever you use GAS with the MIPS linker, but there is not
552 really anything wrong, and it is okay to use the output file. You can
553 stop such warnings by installing the GNU linker.
555 It would be nice to extend GAS to produce the gp tables, but they are
556 optional, and there should not be a warning about their absence.
559 In Ultrix 4.0 on the MIPS machine, @file{stdio.h} does not work with GNU
560 CC at all unless it has been fixed with @code{fixincludes}. This causes
561 problems in building GCC. Once GCC is installed, the problems go
564 To work around this problem, when making the stage 1 compiler, specify
568 GCC_FOR_TARGET="./xgcc -B./ -I./include"
571 When making stage 2 and stage 3, specify this option:
574 CFLAGS="-g -I./include"
578 Users have reported some problems with version 2.0 of the MIPS
579 compiler tools that were shipped with Ultrix 4.1. Version 2.10
580 which came with Ultrix 4.2 seems to work fine.
582 Users have also reported some problems with version 2.20 of the
583 MIPS compiler tools that were shipped with RISC/os 4.x. The earlier
584 version 2.11 seems to work fine.
587 Some versions of the MIPS linker will issue an assertion failure
588 when linking code that uses @code{alloca} against shared
589 libraries on RISC-OS 5.0, and DEC's OSF/1 systems. This is a bug
590 in the linker, that is supposed to be fixed in future revisions.
591 To protect against this, GCC passes @samp{-non_shared} to the
592 linker unless you pass an explicit @samp{-shared} or
593 @samp{-call_shared} switch.
596 On System V release 3, you may get this error message
600 ld fatal: failed to write symbol name @var{something}
601 in strings table for file @var{whatever}
604 This probably indicates that the disk is full or your ULIMIT won't allow
605 the file to be as large as it needs to be.
607 This problem can also result because the kernel parameter @code{MAXUMEM}
608 is too small. If so, you must regenerate the kernel and make the value
609 much larger. The default value is reported to be 1024; a value of 32768
610 is said to work. Smaller values may also work.
613 On System V, if you get an error like this,
616 /usr/local/lib/bison.simple: In function `yyparse':
617 /usr/local/lib/bison.simple:625: virtual memory exhausted
621 that too indicates a problem with disk space, ULIMIT, or @code{MAXUMEM}.
624 Current GCC versions probably do not work on version 2 of the NeXT
628 On NeXTStep 3.0, the Objective C compiler does not work, due,
629 apparently, to a kernel bug that it happens to trigger. This problem
630 does not happen on 3.1.
633 On the Tower models 4@var{n}0 and 6@var{n}0, by default a process is not
634 allowed to have more than one megabyte of memory. GCC cannot compile
635 itself (or many other programs) with @samp{-O} in that much memory.
637 To solve this problem, reconfigure the kernel adding the following line
638 to the configuration file:
645 On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a bug
646 in the assembler that must be fixed before GCC can be built. This
647 bug manifests itself during the first stage of compilation, while
648 building @file{libgcc2.a}:
652 cc1: warning: `-g' option not supported on this version of GCC
653 cc1: warning: `-g1' option not supported on this version of GCC
654 ./xgcc: Internal compiler error: program as got fatal signal 11
657 A patched version of the assembler is available by anonymous ftp from
658 @code{altdorf.ai.mit.edu} as the file
659 @file{archive/cph/hpux-8.0-assembler}. If you have HP software support,
660 the patch can also be obtained directly from HP, as described in the
664 This is the patched assembler, to patch SR#1653-010439, where the
665 assembler aborts on floating point constants.
667 The bug is not really in the assembler, but in the shared library
668 version of the function ``cvtnum(3c)''. The bug on ``cvtnum(3c)'' is
669 SR#4701-078451. Anyway, the attached assembler uses the archive
670 library version of ``cvtnum(3c)'' and thus does not exhibit the bug.
673 This patch is also known as PHCO_4484.
676 On HP-UX version 8.05, but not on 8.07 or more recent versions,
677 the @code{fixproto} shell script triggers a bug in the system shell.
678 If you encounter this problem, upgrade your operating system or
679 use BASH (the GNU shell) to run @code{fixproto}.
682 Some versions of the Pyramid C compiler are reported to be unable to
683 compile GCC. You must use an older version of GCC for
684 bootstrapping. One indication of this problem is if you get a crash
685 when GCC compiles the function @code{muldi3} in file @file{libgcc2.c}.
687 You may be able to succeed by getting GCC version 1, installing it,
688 and using it to compile GCC version 2. The bug in the Pyramid C
689 compiler does not seem to affect GCC version 1.
692 There may be similar problems on System V Release 3.1 on 386 systems.
695 On the Intel Paragon (an i860 machine), if you are using operating
696 system version 1.0, you will get warnings or errors about redefinition
697 of @code{va_arg} when you build GCC.
699 If this happens, then you need to link most programs with the library
700 @file{iclib.a}. You must also modify @file{stdio.h} as follows: before
704 #if defined(__i860__) && !defined(_VA_LIST)
719 extern int vprintf(const char *, va_list );
720 extern int vsprintf(char *, const char *, va_list );
731 These problems don't exist in operating system version 1.1.
734 On the Altos 3068, programs compiled with GCC won't work unless you
735 fix a kernel bug. This happens using system versions V.2.2 1.0gT1 and
736 V.2.2 1.0e and perhaps later versions as well. See the file
740 You will get several sorts of compilation and linking errors on the
741 we32k if you don't follow the special instructions. @xref{Configurations}.
744 A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto
745 program to report an error of the form:
748 ./fixproto: sh internal 1K buffer overflow
751 To fix this, change the first line of the fixproto script to look like:
758 @node Cross-Compiler Problems
759 @section Cross-Compiler Problems
761 You may run into problems with cross compilation on certain machines,
766 Cross compilation can run into trouble for certain machines because
767 some target machines' assemblers require floating point numbers to be
768 written as @emph{integer} constants in certain contexts.
770 The compiler writes these integer constants by examining the floating
771 point value as an integer and printing that integer, because this is
772 simple to write and independent of the details of the floating point
773 representation. But this does not work if the compiler is running on
774 a different machine with an incompatible floating point format, or
775 even a different byte-ordering.
777 In addition, correct constant folding of floating point values
778 requires representing them in the target machine's format.
779 (The C standard does not quite require this, but in practice
780 it is the only way to win.)
782 It is now possible to overcome these problems by defining macros such
783 as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
784 work for each target machine.
786 @xref{Cross-compilation}.
789 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
790 gcc.info, Using and Porting GCC}.
794 At present, the program @file{mips-tfile} which adds debug
795 support to object files on MIPS systems does not work in a cross
800 @section Interoperation
802 This section lists various difficulties encountered in using GNU C or
803 GNU C++ together with other compilers or with the assemblers, linkers,
804 libraries and debuggers on certain systems.
808 Objective C does not work on the RS/6000.
811 GNU C++ does not do name mangling in the same way as other C++
812 compilers. This means that object files compiled with one compiler
813 cannot be used with another.
815 This effect is intentional, to protect you from more subtle problems.
816 Compilers differ as to many internal details of C++ implementation,
817 including: how class instances are laid out, how multiple inheritance is
818 implemented, and how virtual function calls are handled. If the name
819 encoding were made the same, your programs would link against libraries
820 provided from other compilers---but the programs would then crash when
821 run. Incompatible libraries are then detected at link time, rather than
825 Older GDB versions sometimes fail to read the output of GCC version
826 2. If you have trouble, get GDB version 4.4 or later.
830 DBX rejects some files produced by GCC, though it accepts similar
831 constructs in output from PCC. Until someone can supply a coherent
832 description of what is valid DBX input and what is not, there is
833 nothing I can do about these problems. You are on your own.
836 The GNU assembler (GAS) does not support PIC. To generate PIC code, you
837 must use some other assembler, such as @file{/bin/as}.
840 On some BSD systems, including some versions of Ultrix, use of profiling
841 causes static variable destructors (currently used only in C++) not to
845 Use of @samp{-I/usr/include} may cause trouble.
847 Many systems come with header files that won't work with GCC unless
848 corrected by @code{fixincludes}. The corrected header files go in a new
849 directory; GCC searches this directory before @file{/usr/include}.
850 If you use @samp{-I/usr/include}, this tells GCC to search
851 @file{/usr/include} earlier on, before the corrected headers. The
852 result is that you get the uncorrected header files.
854 Instead, you should use these options (when compiling C programs):
857 -I/usr/local/lib/gcc-lib/@var{target}/@var{version}/include -I/usr/include
860 For C++ programs, GCC also uses a special directory that defines C++
861 interfaces to standard C subroutines. This directory is meant to be
862 searched @emph{before} other standard include directories, so that it
863 takes precedence. If you are compiling C++ programs and specifying
864 include directories explicitly, use this option first, then the two
868 -I/usr/local/lib/g++-include
872 @cindex @code{vfork}, for the Sun-4
874 There is a bug in @code{vfork} on the Sun-4 which causes the registers
875 of the child process to clobber those of the parent. Because of this,
876 programs that call @code{vfork} are likely to lose when compiled
877 optimized with GCC when the child code alters registers which contain
878 C variables in the parent. This affects variables which are live in the
879 parent across the call to @code{vfork}.
881 If you encounter this, you can work around the problem by declaring
882 variables @code{volatile} in the function that calls @code{vfork}, until
883 the problem goes away, or by not declaring them @code{register} and not
884 using @samp{-O} for those source files.
888 On some SGI systems, when you use @samp{-lgl_s} as an option,
889 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
890 Naturally, this does not happen when you use GCC.
891 You must specify all three options explicitly.
894 On a Sparc, GCC aligns all values of type @code{double} on an 8-byte
895 boundary, and it expects every @code{double} to be so aligned. The Sun
896 compiler usually gives @code{double} values 8-byte alignment, with one
897 exception: function arguments of type @code{double} may not be aligned.
899 As a result, if a function compiled with Sun CC takes the address of an
900 argument of type @code{double} and passes this pointer of type
901 @code{double *} to a function compiled with GCC, dereferencing the
902 pointer may cause a fatal signal.
904 One way to solve this problem is to compile your entire program with GNU
905 CC. Another solution is to modify the function that is compiled with
906 Sun CC to copy the argument into a local variable; local variables
907 are always properly aligned. A third solution is to modify the function
908 that uses the pointer to dereference it via the following function
909 @code{access_double} instead of directly with @samp{*}:
913 access_double (double *unaligned_ptr)
915 union d2i @{ double d; int i[2]; @};
917 union d2i *p = (union d2i *) unaligned_ptr;
928 Storing into the pointer can be done likewise with the same union.
931 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
932 may allocate memory that is only 4 byte aligned. Since GCC on the
933 Sparc assumes that doubles are 8 byte aligned, this may result in a
934 fatal signal if doubles are stored in memory allocated by the
935 @file{libmalloc.a} library.
937 The solution is to not use the @file{libmalloc.a} library. Use instead
938 @code{malloc} and related functions from @file{libc.a}; they do not have
942 Sun forgot to include a static version of @file{libdl.a} with some
943 versions of SunOS (mainly 4.1). This results in undefined symbols when
944 linking static binaries (that is, if you use @samp{-static}). If you
945 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
946 when linking, compile and link against the file
947 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
950 The 128-bit long double format that the Sparc port supports currently
951 works by using the architecturally defined quad-word floating point
952 instructions. Since there is no hardware that supports these
953 instructions they must be emulated by the operating system. Long
954 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
955 kernel emulator uses an obsolete and incompatible format. Long doubles
956 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
957 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
958 does not enable them by default. Long doubles appear to work in Sun OS
962 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
963 compile GCC correctly. We do not yet know why. However, GCC
964 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
965 compile itself properly on 9.01.
968 On the HP PA machine, ADB sometimes fails to work on functions compiled
969 with GCC. Specifically, it fails to work on functions that use
970 @code{alloca} or variable-size arrays. This is because GCC doesn't
971 generate HP-UX unwind descriptors for such functions. It may even be
972 impossible to generate them.
975 Debugging (@samp{-g}) is not supported on the HP PA machine, unless you use
976 the preliminary GNU tools (@pxref{Installation}).
979 Taking the address of a label may generate errors from the HP-UX
980 PA assembler. GAS for the PA does not have this problem.
983 Using floating point parameters for indirect calls to static functions
984 will not work when using the HP assembler. There simply is no way for GCC
985 to specify what registers hold arguments for static functions when using
986 the HP assembler. GAS for the PA does not have this problem.
989 In extremely rare cases involving some very large functions you may
990 receive errors from the HP linker complaining about an out of bounds
991 unconditional branch offset. This used to occur more often in previous
992 versions of GCC, but is now exceptionally rare. If you should run
993 into it, you can work around by making your function smaller.
996 GCC compiled code sometimes emits warnings from the HP-UX assembler of
1000 (warning) Use of GR3 when
1001 frame >= 8192 may cause conflict.
1004 These warnings are harmless and can be safely ignored.
1007 The current version of the assembler (@file{/bin/as}) for the RS/6000
1008 has certain problems that prevent the @samp{-g} option in GCC from
1009 working. Note that @file{Makefile.in} uses @samp{-g} by default when
1010 compiling @file{libgcc2.c}.
1012 IBM has produced a fixed version of the assembler. The upgraded
1013 assembler unfortunately was not included in any of the AIX 3.2 update
1014 PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request
1015 PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
1016 See the file @file{README.RS6000} for more details on these updates.
1018 You can test for the presense of a fixed assembler by using the
1026 If the command exits normally, the assembler fix already is installed.
1027 If the assembler complains that "-u" is an unknown flag, you need to
1031 On the IBM RS/6000, compiling code of the form
1042 will cause the linker to report an undefined symbol @code{foo}.
1043 Although this behavior differs from most other systems, it is not a
1044 bug because redefining an @code{extern} variable as @code{static}
1045 is undefined in ANSI C.
1048 AIX on the RS/6000 provides support (NLS) for environments outside of
1049 the United States. Compilers and assemblers use NLS to support
1050 locale-specific representations of various objects including
1051 floating-point numbers ("." vs "," for separating decimal fractions).
1052 There have been problems reported where the library linked with GCC does
1053 not produce the same floating-point formats that the assembler accepts.
1054 If you have this problem, set the LANG environment variable to "C" or
1058 Even if you specify @samp{-fdollars-in-identifiers},
1059 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
1060 to a restriction in the IBM assembler. GAS supports these
1064 On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC
1065 version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2
1066 by requesting PTF 421749 from IBM.
1069 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
1070 occurs when the @samp{fldcr} instruction is used. GCC uses
1071 @samp{fldcr} on the 88100 to serialize volatile memory references. Use
1072 the option @samp{-mno-serialize-volatile} if your version of the
1073 assembler has this bug.
1076 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
1077 messages from the linker. These warning messages complain of mismatched
1078 psect attributes. You can ignore them. @xref{VMS Install}.
1081 On NewsOS version 3, if you include both of the files @file{stddef.h}
1082 and @file{sys/types.h}, you get an error because there are two typedefs
1083 of @code{size_t}. You should change @file{sys/types.h} by adding these
1084 lines around the definition of @code{size_t}:
1089 @var{actual typedef here}
1095 On the Alliant, the system's own convention for returning structures
1096 and unions is unusual, and is not compatible with GCC no matter
1097 what options are used.
1102 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
1103 convention for structure and union returning. Use the option
1104 @samp{-mhc-struct-return} to tell GCC to use a convention compatible
1107 @cindex Vax calling convention
1108 @cindex Ultrix calling convention
1110 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
1111 by function calls. However, the C compiler uses conventions compatible
1112 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
1114 GCC uses the same convention as the Ultrix C compiler. You can use
1115 these options to produce code compatible with the Fortran compiler:
1118 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
1122 On the WE32k, you may find that programs compiled with GCC do not
1123 work with the standard shared C library. You may need to link with
1124 the ordinary C compiler. If you do so, you must specify the following
1128 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
1131 The first specifies where to find the library @file{libgcc.a}
1132 specified with the @samp{-lgcc} option.
1134 GCC does linking by invoking @code{ld}, just as @code{cc} does, and
1135 there is no reason why it @emph{should} matter which compilation program
1136 you use to invoke @code{ld}. If someone tracks this problem down,
1137 it can probably be fixed easily.
1140 On the Alpha, you may get assembler errors about invalid syntax as a
1141 result of floating point constants. This is due to a bug in the C
1142 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid
1143 floating point numbers, they sometimes print @samp{NaN}.
1146 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
1147 sometimes reorders instructions incorrectly when optimization is turned
1148 on. If you think this may be happening to you, try using the GNU
1149 assembler; GAS version 2.1 supports ECOFF on Irix.
1151 Or use the @samp{-noasmopt} option when you compile GCC with itself,
1152 and then again when you compile your program. (This is a temporary
1153 kludge to turn off assembler optimization on Irix.) If this proves to
1154 be what you need, edit the assembler spec in the file @file{specs} so
1155 that it unconditionally passes @samp{-O0} to the assembler, and never
1156 passes @samp{-O2} or @samp{-O3}.
1160 @section Problems Compiling Certain Programs
1162 @c prevent bad page break with this line
1163 Certain programs have problems compiling.
1167 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
1168 because of problems in DEC's versions of the X11 header files
1169 @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
1170 @samp{-I/usr/include/mit} to use the MIT versions of the header files,
1171 using the @samp{-traditional} switch to turn off ANSI C, or fixing the
1172 header files by adding this:
1176 #define NeedFunctionPrototypes 0
1181 If you have trouble compiling Perl on a SunOS 4 system, it may be
1182 because Perl specifies @samp{-I/usr/ucbinclude}. This accesses the
1183 unfixed header files. Perl specifies the options
1186 -traditional -Dvolatile=__volatile__
1187 -I/usr/include/sun -I/usr/ucbinclude
1192 most of which are unnecessary with GCC 2.4.5 and newer versions. You
1193 can make a properly working Perl by setting @code{ccflags} to
1194 @samp{-fwritable-strings} (implied by the @samp{-traditional} in the
1195 original options) and @code{cppflags} to empty in @file{config.sh}, then
1196 typing @samp{./doSH; make depend; make}.
1199 On various 386 Unix systems derived from System V, including SCO, ISC,
1200 and ESIX, you may get error messages about running out of virtual memory
1201 while compiling certain programs.
1203 You can prevent this problem by linking GCC with the GNU malloc
1204 (which thus replaces the malloc that comes with the system). GNU malloc
1205 is available as a separate package, and also in the file
1206 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
1208 If you have installed GNU malloc as a separate library package, use this
1209 option when you relink GCC:
1212 MALLOC=/usr/local/lib/libgmalloc.a
1215 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
1216 the object file to @file{gmalloc.o} and use this option when you relink
1224 @node Incompatibilities
1225 @section Incompatibilities of GCC
1226 @cindex incompatibilities of GCC
1228 There are several noteworthy incompatibilities between GNU C and most
1229 existing (non-ANSI) versions of C. The @samp{-traditional} option
1230 eliminates many of these incompatibilities, @emph{but not all}, by
1231 telling GNU C to behave like the other C compilers.
1234 @cindex string constants
1235 @cindex read-only strings
1236 @cindex shared strings
1238 GCC normally makes string constants read-only. If several
1239 identical-looking string constants are used, GCC stores only one
1242 @cindex @code{mktemp}, and constant strings
1243 One consequence is that you cannot call @code{mktemp} with a string
1244 constant argument. The function @code{mktemp} always alters the
1245 string its argument points to.
1247 @cindex @code{sscanf}, and constant strings
1248 @cindex @code{fscanf}, and constant strings
1249 @cindex @code{scanf}, and constant strings
1250 Another consequence is that @code{sscanf} does not work on some systems
1251 when passed a string constant as its format control string or input.
1252 This is because @code{sscanf} incorrectly tries to write into the string
1253 constant. Likewise @code{fscanf} and @code{scanf}.
1255 The best solution to these problems is to change the program to use
1256 @code{char}-array variables with initialization strings for these
1257 purposes instead of string constants. But if this is not possible,
1258 you can use the @samp{-fwritable-strings} flag, which directs GCC
1259 to handle string constants the same way most C compilers do.
1260 @samp{-traditional} also has this effect, among others.
1263 @code{-2147483648} is positive.
1265 This is because 2147483648 cannot fit in the type @code{int}, so
1266 (following the ANSI C rules) its data type is @code{unsigned long int}.
1267 Negating this value yields 2147483648 again.
1270 GCC does not substitute macro arguments when they appear inside of
1271 string constants. For example, the following macro in GCC
1278 will produce output @code{"a"} regardless of what the argument @var{a} is.
1280 The @samp{-traditional} option directs GCC to handle such cases
1281 (among others) in the old-fashioned (non-ANSI) fashion.
1283 @cindex @code{setjmp} incompatibilities
1284 @cindex @code{longjmp} incompatibilities
1286 When you use @code{setjmp} and @code{longjmp}, the only automatic
1287 variables guaranteed to remain valid are those declared
1288 @code{volatile}. This is a consequence of automatic register
1289 allocation. Consider this function:
1303 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
1308 Here @code{a} may or may not be restored to its first value when the
1309 @code{longjmp} occurs. If @code{a} is allocated in a register, then
1310 its first value is restored; otherwise, it keeps the last value stored
1313 If you use the @samp{-W} option with the @samp{-O} option, you will
1314 get a warning when GCC thinks such a problem might be possible.
1316 The @samp{-traditional} option directs GNU C to put variables in
1317 the stack by default, rather than in registers, in functions that
1318 call @code{setjmp}. This results in the behavior found in
1319 traditional C compilers.
1322 Programs that use preprocessing directives in the middle of macro
1323 arguments do not work with GCC. For example, a program like this
1332 ANSI C does not permit such a construct. It would make sense to support
1333 it when @samp{-traditional} is used, but it is too much work to
1336 @cindex external declaration scope
1337 @cindex scope of external declarations
1338 @cindex declaration scope
1340 Declarations of external variables and functions within a block apply
1341 only to the block containing the declaration. In other words, they
1342 have the same scope as any other declaration in the same place.
1344 In some other C compilers, a @code{extern} declaration affects all the
1345 rest of the file even if it happens within a block.
1347 The @samp{-traditional} option directs GNU C to treat all @code{extern}
1348 declarations as global, like traditional compilers.
1351 In traditional C, you can combine @code{long}, etc., with a typedef name,
1356 typedef long foo bar;
1359 In ANSI C, this is not allowed: @code{long} and other type modifiers
1360 require an explicit @code{int}. Because this criterion is expressed
1361 by Bison grammar rules rather than C code, the @samp{-traditional}
1362 flag cannot alter it.
1364 @cindex typedef names as function parameters
1366 PCC allows typedef names to be used as function parameters. The
1367 difficulty described immediately above applies here too.
1371 PCC allows whitespace in the middle of compound assignment operators
1372 such as @samp{+=}. GCC, following the ANSI standard, does not
1373 allow this. The difficulty described immediately above applies here
1379 GCC complains about unterminated character constants inside of
1380 preprocessing conditionals that fail. Some programs have English
1381 comments enclosed in conditionals that are guaranteed to fail; if these
1382 comments contain apostrophes, GCC will probably report an error. For
1383 example, this code would produce an error:
1387 You can't expect this to work.
1391 The best solution to such a problem is to put the text into an actual
1392 C comment delimited by @samp{/*@dots{}*/}. However,
1393 @samp{-traditional} suppresses these error messages.
1396 Many user programs contain the declaration @samp{long time ();}. In the
1397 past, the system header files on many systems did not actually declare
1398 @code{time}, so it did not matter what type your program declared it to
1399 return. But in systems with ANSI C headers, @code{time} is declared to
1400 return @code{time_t}, and if that is not the same as @code{long}, then
1401 @samp{long time ();} is erroneous.
1403 The solution is to change your program to use @code{time_t} as the return
1404 type of @code{time}.
1406 @cindex @code{float} as function value type
1408 When compiling functions that return @code{float}, PCC converts it to
1409 a double. GCC actually returns a @code{float}. If you are concerned
1410 with PCC compatibility, you should declare your functions to return
1411 @code{double}; you might as well say what you mean.
1416 When compiling functions that return structures or unions, GCC
1417 output code normally uses a method different from that used on most
1418 versions of Unix. As a result, code compiled with GCC cannot call
1419 a structure-returning function compiled with PCC, and vice versa.
1421 The method used by GCC is as follows: a structure or union which is
1422 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
1423 with any other size is stored into an address supplied by the caller
1424 (usually in a special, fixed register, but on some machines it is passed
1425 on the stack). The machine-description macros @code{STRUCT_VALUE} and
1426 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
1428 By contrast, PCC on most target machines returns structures and unions
1429 of any size by copying the data into an area of static storage, and then
1430 returning the address of that storage as if it were a pointer value.
1431 The caller must copy the data from that memory area to the place where
1432 the value is wanted. GCC does not use this method because it is
1433 slower and nonreentrant.
1435 On some newer machines, PCC uses a reentrant convention for all
1436 structure and union returning. GCC on most of these machines uses a
1437 compatible convention when returning structures and unions in memory,
1438 but still returns small structures and unions in registers.
1440 You can tell GCC to use a compatible convention for all structure and
1441 union returning with the option @samp{-fpcc-struct-return}.
1443 @cindex preprocessing tokens
1444 @cindex preprocessing numbers
1446 GNU C complains about program fragments such as @samp{0x74ae-0x4000}
1447 which appear to be two hexadecimal constants separated by the minus
1448 operator. Actually, this string is a single @dfn{preprocessing token}.
1449 Each such token must correspond to one token in C. Since this does not,
1450 GNU C prints an error message. Although it may appear obvious that what
1451 is meant is an operator and two values, the ANSI C standard specifically
1452 requires that this be treated as erroneous.
1454 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
1455 begins with a digit and is followed by letters, underscores, digits,
1456 periods and @samp{e+}, @samp{e-}, @samp{E+}, or @samp{E-} character
1459 To make the above program fragment valid, place whitespace in front of
1460 the minus sign. This whitespace will end the preprocessing number.
1464 @section Fixed Header Files
1466 GCC needs to install corrected versions of some system header files.
1467 This is because most target systems have some header files that won't
1468 work with GCC unless they are changed. Some have bugs, some are
1469 incompatible with ANSI C, and some depend on special features of other
1472 Installing GCC automatically creates and installs the fixed header
1473 files, by running a program called @code{fixincludes} (or for certain
1474 targets an alternative such as @code{fixinc.svr4}). Normally, you
1475 don't need to pay attention to this. But there are cases where it
1476 doesn't do the right thing automatically.
1480 If you update the system's header files, such as by installing a new
1481 system version, the fixed header files of GCC are not automatically
1482 updated. The easiest way to update them is to reinstall GCC. (If
1483 you want to be clever, look in the makefile and you can find a
1487 On some systems, in particular SunOS 4, header file directories contain
1488 machine-specific symbolic links in certain places. This makes it
1489 possible to share most of the header files among hosts running the
1490 same version of SunOS 4 on different machine models.
1492 The programs that fix the header files do not understand this special
1493 way of using symbolic links; therefore, the directory of fixed header
1494 files is good only for the machine model used to build it.
1496 In SunOS 4, only programs that look inside the kernel will notice the
1497 difference between machine models. Therefore, for most purposes, you
1498 need not be concerned about this.
1500 It is possible to make separate sets of fixed header files for the
1501 different machine models, and arrange a structure of symbolic links so
1502 as to use the proper set, but you'll have to do this by hand.
1505 On Lynxos, GCC by default does not fix the header files. This is
1506 because bugs in the shell cause the @code{fixincludes} script to fail.
1508 This means you will encounter problems due to bugs in the system header
1509 files. It may be no comfort that they aren't GCC's fault, but it
1510 does mean that there's nothing for us to do about them.
1513 @node Standard Libraries
1514 @section Standard Libraries
1516 GCC by itself attempts to be what the ISO/ANSI C standard calls a
1517 @dfn{conforming freestanding implementation}. This means all ANSI
1518 C language features are available, as well as the contents of
1519 @file{float.h}, @file{limits.h}, @file{stdarg.h}, and
1520 @file{stddef.h}. The rest of the C library is supplied by the
1521 vendor of the operating system. If that C library doesn't conform to
1522 the C standards, then your programs might get warnings (especially when
1523 using @samp{-Wall}) that you don't expect.
1525 For example, the @code{sprintf} function on SunOS 4.1.3 returns
1526 @code{char *} while the C standard says that @code{sprintf} returns an
1527 @code{int}. The @code{fixincludes} program could make the prototype for
1528 this function match the Standard, but that would be wrong, since the
1529 function will still return @code{char *}.
1531 If you need a Standard compliant library, then you need to find one, as
1532 GCC does not provide one. The GNU C library (called @code{glibc})
1533 has been ported to a number of operating systems, and provides ANSI/ISO,
1534 POSIX, BSD and SystemV compatibility. You could also ask your operating
1535 system vendor if newer libraries are available.
1537 @node Disappointments
1538 @section Disappointments and Misunderstandings
1540 These problems are perhaps regrettable, but we don't know any practical
1545 Certain local variables aren't recognized by debuggers when you compile
1548 This occurs because sometimes GCC optimizes the variable out of
1549 existence. There is no way to tell the debugger how to compute the
1550 value such a variable ``would have had'', and it is not clear that would
1551 be desirable anyway. So GCC simply does not mention the eliminated
1552 variable when it writes debugging information.
1554 You have to expect a certain amount of disagreement between the
1555 executable and your source code, when you use optimization.
1557 @cindex conflicting types
1558 @cindex scope of declaration
1560 Users often think it is a bug when GCC reports an error for code
1564 int foo (struct mumble *);
1566 struct mumble @{ @dots{} @};
1568 int foo (struct mumble *x)
1572 This code really is erroneous, because the scope of @code{struct
1573 mumble} in the prototype is limited to the argument list containing it.
1574 It does not refer to the @code{struct mumble} defined with file scope
1575 immediately below---they are two unrelated types with similar names in
1578 But in the definition of @code{foo}, the file-scope type is used
1579 because that is available to be inherited. Thus, the definition and
1580 the prototype do not match, and you get an error.
1582 This behavior may seem silly, but it's what the ANSI standard specifies.
1583 It is easy enough for you to make your code work by moving the
1584 definition of @code{struct mumble} above the prototype. It's not worth
1585 being incompatible with ANSI C just to avoid an error for the example
1589 Accesses to bitfields even in volatile objects works by accessing larger
1590 objects, such as a byte or a word. You cannot rely on what size of
1591 object is accessed in order to read or write the bitfield; it may even
1592 vary for a given bitfield according to the precise usage.
1594 If you care about controlling the amount of memory that is accessed, use
1595 volatile but do not use bitfields.
1598 GCC comes with shell scripts to fix certain known problems in system
1599 header files. They install corrected copies of various header files in
1600 a special directory where only GCC will normally look for them. The
1601 scripts adapt to various systems by searching all the system header
1602 files for the problem cases that we know about.
1604 If new system header files are installed, nothing automatically arranges
1605 to update the corrected header files. You will have to reinstall GCC
1606 to fix the new header files. More specifically, go to the build
1607 directory and delete the files @file{stmp-fixinc} and
1608 @file{stmp-headers}, and the subdirectory @code{include}; then do
1609 @samp{make install} again.
1612 @cindex floating point precision
1613 On 68000 and x86 systems, for instance, you can get paradoxical results
1614 if you test the precise values of floating point numbers. For example,
1615 you can find that a floating point value which is not a NaN is not equal
1616 to itself. This results from the fact that the floating point registers
1617 hold a few more bits of precision than fit in a @code{double} in memory.
1618 Compiled code moves values between memory and floating point registers
1619 at its convenience, and moving them into memory truncates them.
1621 You can partially avoid this problem by using the @samp{-ffloat-store}
1622 option (@pxref{Optimize Options}).
1625 On the MIPS, variable argument functions using @file{varargs.h}
1626 cannot have a floating point value for the first argument. The
1627 reason for this is that in the absence of a prototype in scope,
1628 if the first argument is a floating point, it is passed in a
1629 floating point register, rather than an integer register.
1631 If the code is rewritten to use the ANSI standard @file{stdarg.h}
1632 method of variable arguments, and the prototype is in scope at
1633 the time of the call, everything will work fine.
1636 On the H8/300 and H8/300H, variable argument functions must be
1637 implemented using the ANSI standard @file{stdarg.h} method of
1638 variable arguments. Furthermore, calls to functions using @file{stdarg.h}
1639 variable arguments must have a prototype for the called function
1640 in scope at the time of the call.
1643 @node C++ Misunderstandings
1644 @section Common Misunderstandings with GNU C++
1646 @cindex misunderstandings in C++
1647 @cindex surprises in C++
1648 @cindex C++ misunderstandings
1649 C++ is a complex language and an evolving one, and its standard
1650 definition (the ISO C++ standard) was only recently completed. As a
1651 result, your C++ compiler may occasionally surprise you, even when its
1652 behavior is correct. This section discusses some areas that frequently
1653 give rise to questions of this sort.
1656 * Static Definitions:: Static member declarations are not definitions
1657 * Temporaries:: Temporaries may vanish before you expect
1658 * Copy Assignment:: Copy Assignment operators copy virtual bases twice
1661 @node Static Definitions
1662 @subsection Declare @emph{and} Define Static Members
1664 @cindex C++ static data, declaring and defining
1665 @cindex static data in C++, declaring and defining
1666 @cindex declaring static data in C++
1667 @cindex defining static data in C++
1668 When a class has static data members, it is not enough to @emph{declare}
1669 the static member; you must also @emph{define} it. For example:
1680 This declaration only establishes that the class @code{Foo} has an
1681 @code{int} named @code{Foo::bar}, and a member function named
1682 @code{Foo::method}. But you still need to define @emph{both}
1683 @code{method} and @code{bar} elsewhere. According to the draft ANSI
1684 standard, you must supply an initializer in one (and only one) source
1691 Other C++ compilers may not correctly implement the standard behavior.
1692 As a result, when you switch to @code{g++} from one of these compilers,
1693 you may discover that a program that appeared to work correctly in fact
1694 does not conform to the standard: @code{g++} reports as undefined
1695 symbols any static data members that lack definitions.
1698 @subsection Temporaries May Vanish Before You Expect
1700 @cindex temporaries, lifetime of
1701 @cindex portions of temporary objects, pointers to
1702 It is dangerous to use pointers or references to @emph{portions} of a
1703 temporary object. The compiler may very well delete the object before
1704 you expect it to, leaving a pointer to garbage. The most common place
1705 where this problem crops up is in classes like string classes,
1706 especially ones that define a conversion function to type @code{char *}
1707 or @code{const char *} -- which is one reason why the standard
1708 @code{string} class requires you to call the @code{c_str} member
1709 function. However, any class that returns a pointer to some internal
1710 structure is potentially subject to this problem.
1712 For example, a program may use a function @code{strfunc} that returns
1713 @code{string} objects, and another function @code{charfunc} that
1714 operates on pointers to @code{char}:
1718 void charfunc (const char *);
1723 const char *p = strfunc().c_str();
1732 In this situation, it may seem reasonable to save a pointer to the C
1733 string returned by the @code{c_str} member function and use that rather
1734 than call @code{c_str} repeatedly. However, the temporary string
1735 created by the call to @code{strfunc} is destroyed after @code{p} is
1736 initialized, at which point @code{p} is left pointing to freed memory.
1738 Code like this may run successfully under some other compilers,
1739 particularly obsolete cfront-based compilers that delete temporaries
1740 along with normal local variables. However, the GNU C++ behavior is
1741 standard-conforming, so if your program depends on late destruction of
1742 temporaries it is not portable.
1744 The safe way to write such code is to give the temporary a name, which
1745 forces it to remain until the end of the scope of the name. For
1749 string& tmp = strfunc ();
1750 charfunc (tmp.c_str ());
1753 @node Copy Assignment
1754 @subsection Implicit Copy-Assignment for Virtual Bases
1756 When a base class is virtual, only one subobject of the base class
1757 belongs to each full object. Also, the constructors and destructors are
1758 invoked only once, and called from the most-derived class. However, such
1759 objects behave unspecified when being assigned. For example:
1764 Base(char *n) : name(strdup(n))@{@}
1765 Base& operator= (const Base& other)@{
1767 name = strdup (other.name);
1771 struct A:virtual Base@{
1776 struct B:virtual Base@{
1781 struct Derived:public A, public B@{
1782 Derived():Base("Derived")@{@}
1785 void func(Derived &d1, Derived &d2)
1791 The C++ standard specifies that @samp{Base::Base} is only called once
1792 when constructing or copy-constructing a Derived object. It is
1793 unspecified whether @samp{Base::operator=} is called more than once when
1794 the implicit copy-assignment for Derived objects is invoked (as it is
1795 inside @samp{func} in the example).
1797 g++ implements the "intuitive" algorithm for copy-assignment: assign all
1798 direct bases, then assign all members. In that algorithm, the virtual
1799 base subobject can be encountered many times. In the example, copying
1800 proceeds in the following order: @samp{val}, @samp{name} (via
1801 @code{strdup}), @samp{bval}, and @samp{name} again.
1803 If application code relies on copy-assignment, a user-defined
1804 copy-assignment operator removes any uncertainties. With such an
1805 operator, the application can define whether and how the virtual base
1806 subobject is assigned.
1808 @node Protoize Caveats
1809 @section Caveats of using @code{protoize}
1811 The conversion programs @code{protoize} and @code{unprotoize} can
1812 sometimes change a source file in a way that won't work unless you
1817 @code{protoize} can insert references to a type name or type tag before
1818 the definition, or in a file where they are not defined.
1820 If this happens, compiler error messages should show you where the new
1821 references are, so fixing the file by hand is straightforward.
1824 There are some C constructs which @code{protoize} cannot figure out.
1825 For example, it can't determine argument types for declaring a
1826 pointer-to-function variable; this you must do by hand. @code{protoize}
1827 inserts a comment containing @samp{???} each time it finds such a
1828 variable; so you can find all such variables by searching for this
1829 string. ANSI C does not require declaring the argument types of
1830 pointer-to-function types.
1833 Using @code{unprotoize} can easily introduce bugs. If the program
1834 relied on prototypes to bring about conversion of arguments, these
1835 conversions will not take place in the program without prototypes.
1836 One case in which you can be sure @code{unprotoize} is safe is when
1837 you are removing prototypes that were made with @code{protoize}; if
1838 the program worked before without any prototypes, it will work again
1841 You can find all the places where this problem might occur by compiling
1842 the program with the @samp{-Wconversion} option. It prints a warning
1843 whenever an argument is converted.
1846 Both conversion programs can be confused if there are macro calls in and
1847 around the text to be converted. In other words, the standard syntax
1848 for a declaration or definition must not result from expanding a macro.
1849 This problem is inherent in the design of C and cannot be fixed. If
1850 only a few functions have confusing macro calls, you can easily convert
1854 @code{protoize} cannot get the argument types for a function whose
1855 definition was not actually compiled due to preprocessing conditionals.
1856 When this happens, @code{protoize} changes nothing in regard to such
1857 a function. @code{protoize} tries to detect such instances and warn
1860 You can generally work around this problem by using @code{protoize} step
1861 by step, each time specifying a different set of @samp{-D} options for
1862 compilation, until all of the functions have been converted. There is
1863 no automatic way to verify that you have got them all, however.
1866 Confusion may result if there is an occasion to convert a function
1867 declaration or definition in a region of source code where there is more
1868 than one formal parameter list present. Thus, attempts to convert code
1869 containing multiple (conditionally compiled) versions of a single
1870 function header (in the same vicinity) may not produce the desired (or
1873 If you plan on converting source files which contain such code, it is
1874 recommended that you first make sure that each conditionally compiled
1875 region of source code which contains an alternative function header also
1876 contains at least one additional follower token (past the final right
1877 parenthesis of the function header). This should circumvent the
1881 @code{unprotoize} can become confused when trying to convert a function
1882 definition or declaration which contains a declaration for a
1883 pointer-to-function formal argument which has the same name as the
1884 function being defined or declared. We recommand you avoid such choices
1885 of formal parameter names.
1888 You might also want to correct some of the indentation by hand and break
1889 long lines. (The conversion programs don't write lines longer than
1890 eighty characters in any case.)
1894 @section Certain Changes We Don't Want to Make
1896 This section lists changes that people frequently request, but which
1897 we do not make because we think GCC is better without them.
1901 Checking the number and type of arguments to a function which has an
1902 old-fashioned definition and no prototype.
1904 Such a feature would work only occasionally---only for calls that appear
1905 in the same file as the called function, following the definition. The
1906 only way to check all calls reliably is to add a prototype for the
1907 function. But adding a prototype eliminates the motivation for this
1908 feature. So the feature is not worthwhile.
1911 Warning about using an expression whose type is signed as a shift count.
1913 Shift count operands are probably signed more often than unsigned.
1914 Warning about this would cause far more annoyance than good.
1917 Warning about assigning a signed value to an unsigned variable.
1919 Such assignments must be very common; warning about them would cause
1920 more annoyance than good.
1923 Warning about unreachable code.
1925 It's very common to have unreachable code in machine-generated
1926 programs. For example, this happens normally in some files of GNU C
1930 Warning when a non-void function value is ignored.
1932 Coming as I do from a Lisp background, I balk at the idea that there is
1933 something dangerous about discarding a value. There are functions that
1934 return values which some callers may find useful; it makes no sense to
1935 clutter the program with a cast to @code{void} whenever the value isn't
1939 Assuming (for optimization) that the address of an external symbol is
1942 This assumption is false on certain systems when @samp{#pragma weak} is
1946 Making @samp{-fshort-enums} the default.
1948 This would cause storage layout to be incompatible with most other C
1949 compilers. And it doesn't seem very important, given that you can get
1950 the same result in other ways. The case where it matters most is when
1951 the enumeration-valued object is inside a structure, and in that case
1952 you can specify a field width explicitly.
1955 Making bitfields unsigned by default on particular machines where ``the
1956 ABI standard'' says to do so.
1958 The ANSI C standard leaves it up to the implementation whether a bitfield
1959 declared plain @code{int} is signed or not. This in effect creates two
1960 alternative dialects of C.
1962 The GNU C compiler supports both dialects; you can specify the signed
1963 dialect with @samp{-fsigned-bitfields} and the unsigned dialect with
1964 @samp{-funsigned-bitfields}. However, this leaves open the question of
1965 which dialect to use by default.
1967 Currently, the preferred dialect makes plain bitfields signed, because
1968 this is simplest. Since @code{int} is the same as @code{signed int} in
1969 every other context, it is cleanest for them to be the same in bitfields
1972 Some computer manufacturers have published Application Binary Interface
1973 standards which specify that plain bitfields should be unsigned. It is
1974 a mistake, however, to say anything about this issue in an ABI. This is
1975 because the handling of plain bitfields distinguishes two dialects of C.
1976 Both dialects are meaningful on every type of machine. Whether a
1977 particular object file was compiled using signed bitfields or unsigned
1978 is of no concern to other object files, even if they access the same
1979 bitfields in the same data structures.
1981 A given program is written in one or the other of these two dialects.
1982 The program stands a chance to work on most any machine if it is
1983 compiled with the proper dialect. It is unlikely to work at all if
1984 compiled with the wrong dialect.
1986 Many users appreciate the GNU C compiler because it provides an
1987 environment that is uniform across machines. These users would be
1988 inconvenienced if the compiler treated plain bitfields differently on
1991 Occasionally users write programs intended only for a particular machine
1992 type. On these occasions, the users would benefit if the GNU C compiler
1993 were to support by default the same dialect as the other compilers on
1994 that machine. But such applications are rare. And users writing a
1995 program to run on more than one type of machine cannot possibly benefit
1996 from this kind of compatibility.
1998 This is why GCC does and will treat plain bitfields in the same
1999 fashion on all types of machines (by default).
2001 There are some arguments for making bitfields unsigned by default on all
2002 machines. If, for example, this becomes a universal de facto standard,
2003 it would make sense for GCC to go along with it. This is something
2004 to be considered in the future.
2006 (Of course, users strongly concerned about portability should indicate
2007 explicitly in each bitfield whether it is signed or not. In this way,
2008 they write programs which have the same meaning in both C dialects.)
2011 Undefining @code{__STDC__} when @samp{-ansi} is not used.
2013 Currently, GCC defines @code{__STDC__} as long as you don't use
2014 @samp{-traditional}. This provides good results in practice.
2016 Programmers normally use conditionals on @code{__STDC__} to ask whether
2017 it is safe to use certain features of ANSI C, such as function
2018 prototypes or ANSI token concatenation. Since plain @samp{gcc} supports
2019 all the features of ANSI C, the correct answer to these questions is
2022 Some users try to use @code{__STDC__} to check for the availability of
2023 certain library facilities. This is actually incorrect usage in an ANSI
2024 C program, because the ANSI C standard says that a conforming
2025 freestanding implementation should define @code{__STDC__} even though it
2026 does not have the library facilities. @samp{gcc -ansi -pedantic} is a
2027 conforming freestanding implementation, and it is therefore required to
2028 define @code{__STDC__}, even though it does not come with an ANSI C
2031 Sometimes people say that defining @code{__STDC__} in a compiler that
2032 does not completely conform to the ANSI C standard somehow violates the
2033 standard. This is illogical. The standard is a standard for compilers
2034 that claim to support ANSI C, such as @samp{gcc -ansi}---not for other
2035 compilers such as plain @samp{gcc}. Whatever the ANSI C standard says
2036 is relevant to the design of plain @samp{gcc} without @samp{-ansi} only
2037 for pragmatic reasons, not as a requirement.
2039 GCC normally defines @code{__STDC__} to be 1, and in addition
2040 defines @code{__STRICT_ANSI__} if you specify the @samp{-ansi} option.
2041 On some hosts, system include files use a different convention, where
2042 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
2043 conformance to the C Standard. GCC follows the host convention when
2044 processing system include files, but when processing user files it follows
2045 the usual GNU C convention.
2048 Undefining @code{__STDC__} in C++.
2050 Programs written to compile with C++-to-C translators get the
2051 value of @code{__STDC__} that goes with the C compiler that is
2052 subsequently used. These programs must test @code{__STDC__}
2053 to determine what kind of C preprocessor that compiler uses:
2054 whether they should concatenate tokens in the ANSI C fashion
2055 or in the traditional fashion.
2057 These programs work properly with GNU C++ if @code{__STDC__} is defined.
2058 They would not work otherwise.
2060 In addition, many header files are written to provide prototypes in ANSI
2061 C but not in traditional C. Many of these header files can work without
2062 change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
2063 is not defined, they will all fail, and will all need to be changed to
2064 test explicitly for C++ as well.
2067 Deleting ``empty'' loops.
2069 Historically, GCC has not deleted ``empty'' loops under the
2070 assumption that the most likely reason you would put one in a program is
2071 to have a delay, so deleting them will not make real programs run any
2074 However, the rationale here is that optimization of a nonempty loop
2075 cannot produce an empty one, which holds for C but is not always the
2078 Moreover, with @samp{-funroll-loops} small ``empty'' loops are already
2079 removed, so the current behavior is both sub-optimal and inconsistent
2080 and will change in the future.
2083 Making side effects happen in the same order as in some other compiler.
2085 @cindex side effects, order of evaluation
2086 @cindex order of evaluation, side effects
2087 It is never safe to depend on the order of evaluation of side effects.
2088 For example, a function call like this may very well behave differently
2089 from one compiler to another:
2092 void func (int, int);
2098 There is no guarantee (in either the C or the C++ standard language
2099 definitions) that the increments will be evaluated in any particular
2100 order. Either increment might happen first. @code{func} might get the
2101 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
2104 Not allowing structures with volatile fields in registers.
2106 Strictly speaking, there is no prohibition in the ANSI C standard
2107 against allowing structures with volatile fields in registers, but
2108 it does not seem to make any sense and is probably not what you wanted
2109 to do. So the compiler will give an error message in this case.
2112 @node Warnings and Errors
2113 @section Warning Messages and Error Messages
2115 @cindex error messages
2116 @cindex warnings vs errors
2117 @cindex messages, warning and error
2118 The GNU compiler can produce two kinds of diagnostics: errors and
2119 warnings. Each kind has a different purpose:
2123 @emph{Errors} report problems that make it impossible to compile your
2124 program. GCC reports errors with the source file name and line
2125 number where the problem is apparent.
2128 @emph{Warnings} report other unusual conditions in your code that
2129 @emph{may} indicate a problem, although compilation can (and does)
2130 proceed. Warning messages also report the source file name and line
2131 number, but include the text @samp{warning:} to distinguish them
2132 from error messages.
2135 Warnings may indicate danger points where you should check to make sure
2136 that your program really does what you intend; or the use of obsolete
2137 features; or the use of nonstandard features of GNU C or C++. Many
2138 warnings are issued only if you ask for them, with one of the @samp{-W}
2139 options (for instance, @samp{-Wall} requests a variety of useful
2142 GCC always tries to compile your program if possible; it never
2143 gratuitously rejects a program whose meaning is clear merely because
2144 (for instance) it fails to conform to a standard. In some cases,
2145 however, the C and C++ standards specify that certain extensions are
2146 forbidden, and a diagnostic @emph{must} be issued by a conforming
2147 compiler. The @samp{-pedantic} option tells GCC to issue warnings in
2148 such cases; @samp{-pedantic-errors} says to make them errors instead.
2149 This does not mean that @emph{all} non-ANSI constructs get warnings
2152 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
2153 more detail on these and related command-line options.
2156 @chapter Reporting Bugs
2158 @cindex reporting bugs
2160 Your bug reports play an essential role in making GCC reliable.
2162 When you encounter a problem, the first thing to do is to see if it is
2163 already known. @xref{Trouble}. If it isn't known, then you should
2166 Reporting a bug may help you by bringing a solution to your problem, or
2167 it may not. (If it does not, look in the service directory; see
2168 @ref{Service}.) In any case, the principal function of a bug report is
2169 to help the entire community by making the next version of GCC work
2170 better. Bug reports are your contribution to the maintenance of GCC.
2172 Since the maintainers are very overloaded, we cannot respond to every
2173 bug report. However, if the bug has not been fixed, we are likely to
2174 send you a patch and ask you to tell us whether it works.
2176 In order for a bug report to serve its purpose, you must include the
2177 information that makes for fixing the bug.
2180 * Criteria: Bug Criteria. Have you really found a bug?
2181 * Where: Bug Lists. Where to send your bug report.
2182 * Reporting: Bug Reporting. How to report a bug effectively.
2183 * Patches: Sending Patches. How to send a patch for GCC.
2184 * Known: Trouble. Known problems.
2185 * Help: Service. Where to ask for help.
2189 @section Have You Found a Bug?
2190 @cindex bug criteria
2192 If you are not sure whether you have found a bug, here are some guidelines:
2195 @cindex fatal signal
2198 If the compiler gets a fatal signal, for any input whatever, that is a
2199 compiler bug. Reliable compilers never crash.
2201 @cindex invalid assembly code
2202 @cindex assembly code, invalid
2204 If the compiler produces invalid assembly code, for any input whatever
2205 (except an @code{asm} statement), that is a compiler bug, unless the
2206 compiler reports errors (not just warnings) which would ordinarily
2207 prevent the assembler from being run.
2209 @cindex undefined behavior
2210 @cindex undefined function value
2211 @cindex increment operators
2213 If the compiler produces valid assembly code that does not correctly
2214 execute the input source code, that is a compiler bug.
2216 However, you must double-check to make sure, because you may have run
2217 into an incompatibility between GNU C and traditional C
2218 (@pxref{Incompatibilities}). These incompatibilities might be considered
2219 bugs, but they are inescapable consequences of valuable features.
2221 Or you may have a program whose behavior is undefined, which happened
2222 by chance to give the desired results with another C or C++ compiler.
2224 For example, in many nonoptimizing compilers, you can write @samp{x;}
2225 at the end of a function instead of @samp{return x;}, with the same
2226 results. But the value of the function is undefined if @code{return}
2227 is omitted; it is not a bug when GCC produces different results.
2229 Problems often result from expressions with two increment operators,
2230 as in @code{f (*p++, *p++)}. Your previous compiler might have
2231 interpreted that expression the way you intended; GCC might
2232 interpret it another way. Neither compiler is wrong. The bug is
2235 After you have localized the error to a single source line, it should
2236 be easy to check for these things. If your program is correct and
2237 well defined, you have found a compiler bug.
2240 If the compiler produces an error message for valid input, that is a
2243 @cindex invalid input
2245 If the compiler does not produce an error message for invalid input,
2246 that is a compiler bug. However, you should note that your idea of
2247 ``invalid input'' might be my idea of ``an extension'' or ``support
2248 for traditional practice''.
2251 If you are an experienced user of C or C++ (or Fortran or Objective-C)
2252 compilers, your suggestions
2253 for improvement of GCC are welcome in any case.
2257 @section Where to Report Bugs
2258 @cindex bug report mailing lists
2259 @kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
2260 Send bug reports for the GNU Compiler Collection to
2261 @samp{gcc-bugs@@gcc.gnu.org}. In accordance with the GNU-wide
2262 convention, in which bug reports for tool ``foo'' are sent
2263 to @samp{bug-foo@@gnu.org}, the address @samp{bug-gcc@@gnu.org}
2264 may also be used; it will forward to the address given above.
2266 Please read @samp{<URL:http://www.gnu.org/software/gcc/bugs.html>} for
2267 bug reporting instructions before you post a bug report.
2269 Often people think of posting bug reports to the newsgroup instead of
2270 mailing them. This appears to work, but it has one problem which can be
2271 crucial: a newsgroup posting does not contain a mail path back to the
2272 sender. Thus, if maintainers need more information, they may be unable
2273 to reach you. For this reason, you should always send bug reports by
2274 mail to the proper mailing list.
2276 As a last resort, send bug reports on paper to:
2280 Free Software Foundation
2281 59 Temple Place - Suite 330
2282 Boston, MA 02111-1307, USA
2286 @section How to Report Bugs
2287 @cindex compiler bugs, reporting
2289 You may find additional and/or more up-to-date instructions at
2290 @samp{<URL:http://www.gnu.org/software/gcc/bugs.html>}.
2292 The fundamental principle of reporting bugs usefully is this:
2293 @strong{report all the facts}. If you are not sure whether to state a
2294 fact or leave it out, state it!
2296 Often people omit facts because they think they know what causes the
2297 problem and they conclude that some details don't matter. Thus, you might
2298 assume that the name of the variable you use in an example does not matter.
2299 Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
2300 stray memory reference which happens to fetch from the location where that
2301 name is stored in memory; perhaps, if the name were different, the contents
2302 of that location would fool the compiler into doing the right thing despite
2303 the bug. Play it safe and give a specific, complete example. That is the
2304 easiest thing for you to do, and the most helpful.
2306 Keep in mind that the purpose of a bug report is to enable someone to
2307 fix the bug if it is not known. It isn't very important what happens if
2308 the bug is already known. Therefore, always write your bug reports on
2309 the assumption that the bug is not known.
2311 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2312 bell?'' This cannot help us fix a bug, so it is basically useless. We
2313 respond by asking for enough details to enable us to investigate.
2314 You might as well expedite matters by sending them to begin with.
2316 Try to make your bug report self-contained. If we have to ask you for
2317 more information, it is best if you include all the previous information
2318 in your response, as well as the information that was missing.
2320 Please report each bug in a separate message. This makes it easier for
2321 us to track which bugs have been fixed and to forward your bugs reports
2322 to the appropriate maintainer.
2324 To enable someone to investigate the bug, you should include all these
2329 The version of GCC. You can get this by running it with the
2332 Without this, we won't know whether there is any point in looking for
2333 the bug in the current version of GCC.
2336 A complete input file that will reproduce the bug. If the bug is in the
2337 C preprocessor, send a source file and any header files that it
2338 requires. If the bug is in the compiler proper (@file{cc1}), send the
2339 preprocessor output generated by adding @samp{-save-temps} to the
2340 compilation command (@pxref{Debugging Options}). When you do this, use
2341 the same @samp{-I}, @samp{-D} or @samp{-U} options that you used in
2342 actual compilation. Then send the @var{input}.i or @var{input}.ii files
2345 A single statement is not enough of an example. In order to compile it,
2346 it must be embedded in a complete file of compiler input; and the bug
2347 might depend on the details of how this is done.
2349 Without a real example one can compile, all anyone can do about your bug
2350 report is wish you luck. It would be futile to try to guess how to
2351 provoke the bug. For example, bugs in register allocation and reloading
2352 frequently depend on every little detail of the function they happen in.
2354 Even if the input file that fails comes from a GNU program, you should
2355 still send the complete test case. Don't ask the GCC maintainers to
2356 do the extra work of obtaining the program in question---they are all
2357 overworked as it is. Also, the problem may depend on what is in the
2358 header files on your system; it is unreliable for the GCC maintainers
2359 to try the problem with the header files available to them. By sending
2360 CPP output, you can eliminate this source of uncertainty and save us
2361 a certain percentage of wild goose chases.
2364 The command arguments you gave GCC to compile that example
2365 and observe the bug. For example, did you use @samp{-O}? To guarantee
2366 you won't omit something important, list all the options.
2368 If we were to try to guess the arguments, we would probably guess wrong
2369 and then we would not encounter the bug.
2372 The type of machine you are using, and the operating system name and
2376 The operands you gave to the @code{configure} command when you installed
2380 A complete list of any modifications you have made to the compiler
2381 source. (We don't promise to investigate the bug unless it happens in
2382 an unmodified compiler. But if you've made modifications and don't tell
2383 us, then you are sending us on a wild goose chase.)
2385 Be precise about these changes. A description in English is not
2386 enough---send a context diff for them.
2388 Adding files of your own (such as a machine description for a machine we
2389 don't support) is a modification of the compiler source.
2392 Details of any other deviations from the standard procedure for installing
2396 A description of what behavior you observe that you believe is
2397 incorrect. For example, ``The compiler gets a fatal signal,'' or,
2398 ``The assembler instruction at line 208 in the output is incorrect.''
2400 Of course, if the bug is that the compiler gets a fatal signal, then one
2401 can't miss it. But if the bug is incorrect output, the maintainer might
2402 not notice unless it is glaringly wrong. None of us has time to study
2403 all the assembler code from a 50-line C program just on the chance that
2404 one instruction might be wrong. We need @emph{you} to do this part!
2406 Even if the problem you experience is a fatal signal, you should still
2407 say so explicitly. Suppose something strange is going on, such as, your
2408 copy of the compiler is out of synch, or you have encountered a bug in
2409 the C library on your system. (This has happened!) Your copy might
2410 crash and the copy here would not. If you @i{said} to expect a crash,
2411 then when the compiler here fails to crash, we would know that the bug
2412 was not happening. If you don't say to expect a crash, then we would
2413 not know whether the bug was happening. We would not be able to draw
2414 any conclusion from our observations.
2416 If the problem is a diagnostic when compiling GCC with some other
2417 compiler, say whether it is a warning or an error.
2419 Often the observed symptom is incorrect output when your program is run.
2420 Sad to say, this is not enough information unless the program is short
2421 and simple. None of us has time to study a large program to figure out
2422 how it would work if compiled correctly, much less which line of it was
2423 compiled wrong. So you will have to do that. Tell us which source line
2424 it is, and what incorrect result happens when that line is executed. A
2425 person who understands the program can find this as easily as finding a
2426 bug in the program itself.
2429 If you send examples of assembler code output from GCC,
2430 please use @samp{-g} when you make them. The debugging information
2431 includes source line numbers which are essential for correlating the
2432 output with the input.
2435 If you wish to mention something in the GCC source, refer to it by
2436 context, not by line number.
2438 The line numbers in the development sources don't match those in your
2439 sources. Your line numbers would convey no useful information to the
2443 Additional information from a debugger might enable someone to find a
2444 problem on a machine which he does not have available. However, you
2445 need to think when you collect this information if you want it to have
2446 any chance of being useful.
2448 @cindex backtrace for bug reports
2449 For example, many people send just a backtrace, but that is never
2450 useful by itself. A simple backtrace with arguments conveys little
2451 about GCC because the compiler is largely data-driven; the same
2452 functions are called over and over for different RTL insns, doing
2453 different things depending on the details of the insn.
2455 Most of the arguments listed in the backtrace are useless because they
2456 are pointers to RTL list structure. The numeric values of the
2457 pointers, which the debugger prints in the backtrace, have no
2458 significance whatever; all that matters is the contents of the objects
2459 they point to (and most of the contents are other such pointers).
2461 In addition, most compiler passes consist of one or more loops that
2462 scan the RTL insn sequence. The most vital piece of information about
2463 such a loop---which insn it has reached---is usually in a local variable,
2467 What you need to provide in addition to a backtrace are the values of
2468 the local variables for several stack frames up. When a local
2469 variable or an argument is an RTX, first print its value and then use
2470 the GDB command @code{pr} to print the RTL expression that it points
2471 to. (If GDB doesn't run on your machine, use your debugger to call
2472 the function @code{debug_rtx} with the RTX as an argument.) In
2473 general, whenever a variable is a pointer, its value is no use
2474 without the data it points to.
2477 Here are some things that are not necessary:
2481 A description of the envelope of the bug.
2483 Often people who encounter a bug spend a lot of time investigating
2484 which changes to the input file will make the bug go away and which
2485 changes will not affect it.
2487 This is often time consuming and not very useful, because the way we
2488 will find the bug is by running a single example under the debugger with
2489 breakpoints, not by pure deduction from a series of examples. You might
2490 as well save your time for something else.
2492 Of course, if you can find a simpler example to report @emph{instead} of
2493 the original one, that is a convenience. Errors in the output will be
2494 easier to spot, running under the debugger will take less time, etc.
2495 Most GCC bugs involve just one function, so the most straightforward
2496 way to simplify an example is to delete all the function definitions
2497 except the one where the bug occurs. Those earlier in the file may be
2498 replaced by external declarations if the crucial function depends on
2499 them. (Exception: inline functions may affect compilation of functions
2500 defined later in the file.)
2502 However, simplification is not vital; if you don't want to do this,
2503 report the bug anyway and send the entire test case you used.
2506 In particular, some people insert conditionals @samp{#ifdef BUG} around
2507 a statement which, if removed, makes the bug not happen. These are just
2508 clutter; we won't pay any attention to them anyway. Besides, you should
2509 send us cpp output, and that can't have conditionals.
2512 A patch for the bug.
2514 A patch for the bug is useful if it is a good one. But don't omit the
2515 necessary information, such as the test case, on the assumption that a
2516 patch is all we need. We might see problems with your patch and decide
2517 to fix the problem another way, or we might not understand it at all.
2519 Sometimes with a program as complicated as GCC it is very hard to
2520 construct an example that will make the program follow a certain path
2521 through the code. If you don't send the example, we won't be able to
2522 construct one, so we won't be able to verify that the bug is fixed.
2524 And if we can't understand what bug you are trying to fix, or why your
2525 patch should be an improvement, we won't install it. A test case will
2526 help us to understand.
2528 @xref{Sending Patches}, for guidelines on how to make it easy for us to
2529 understand and install your patches.
2532 A guess about what the bug is or what it depends on.
2534 Such guesses are usually wrong. Even I can't guess right about such
2535 things without first using the debugger to find the facts.
2540 We have no way of examining a core dump for your type of machine
2541 unless we have an identical system---and if we do have one,
2542 we should be able to reproduce the crash ourselves.
2545 @node Sending Patches,, Bug Reporting, Bugs
2546 @section Sending Patches for GCC
2548 If you would like to write bug fixes or improvements for the GNU C
2549 compiler, that is very helpful. Send suggested fixes to the patches
2550 mailing list, @code{gcc-patches@@gcc.gnu.org}.
2552 Please follow these guidelines so we can study your patches efficiently.
2553 If you don't follow these guidelines, your information might still be
2554 useful, but using it will take extra work. Maintaining GNU C is a lot
2555 of work in the best of circumstances, and we can't keep up unless you do
2560 Send an explanation with your changes of what problem they fix or what
2561 improvement they bring about. For a bug fix, just include a copy of the
2562 bug report, and explain why the change fixes the bug.
2564 (Referring to a bug report is not as good as including it, because then
2565 we will have to look it up, and we have probably already deleted it if
2566 we've already fixed the bug.)
2569 Always include a proper bug report for the problem you think you have
2570 fixed. We need to convince ourselves that the change is right before
2571 installing it. Even if it is right, we might have trouble judging it if
2572 we don't have a way to reproduce the problem.
2575 Include all the comments that are appropriate to help people reading the
2576 source in the future understand why this change was needed.
2579 Don't mix together changes made for different reasons.
2580 Send them @emph{individually}.
2582 If you make two changes for separate reasons, then we might not want to
2583 install them both. We might want to install just one. If you send them
2584 all jumbled together in a single set of diffs, we have to do extra work
2585 to disentangle them---to figure out which parts of the change serve
2586 which purpose. If we don't have time for this, we might have to ignore
2587 your changes entirely.
2589 If you send each change as soon as you have written it, with its own
2590 explanation, then the two changes never get tangled up, and we can
2591 consider each one properly without any extra work to disentangle them.
2593 Ideally, each change you send should be impossible to subdivide into
2594 parts that we might want to consider separately, because each of its
2595 parts gets its motivation from the other parts.
2598 Send each change as soon as that change is finished. Sometimes people
2599 think they are helping us by accumulating many changes to send them all
2600 together. As explained above, this is absolutely the worst thing you
2603 Since you should send each change separately, you might as well send it
2604 right away. That gives us the option of installing it immediately if it
2608 Use @samp{diff -c} to make your diffs. Diffs without context are hard
2609 for us to install reliably. More than that, they make it hard for us to
2610 study the diffs to decide whether we want to install them. Unidiff
2611 format is better than contextless diffs, but not as easy to read as
2614 If you have GNU diff, use @samp{diff -cp}, which shows the name of the
2615 function that each change occurs in.
2618 Write the change log entries for your changes. We get lots of changes,
2619 and we don't have time to do all the change log writing ourselves.
2621 Read the @file{ChangeLog} file to see what sorts of information to put
2622 in, and to learn the style that we use. The purpose of the change log
2623 is to show people where to find what was changed. So you need to be
2624 specific about what functions you changed; in large functions, it's
2625 often helpful to indicate where within the function the change was.
2627 On the other hand, once you have shown people where to find the change,
2628 you need not explain its purpose. Thus, if you add a new function, all
2629 you need to say about it is that it is new. If you feel that the
2630 purpose needs explaining, it probably does---but the explanation will be
2631 much more useful if you put it in comments in the code.
2633 If you would like your name to appear in the header line for who made
2634 the change, send us the header line.
2637 When you write the fix, keep in mind that we can't install a change that
2638 would break other systems.
2640 People often suggest fixing a problem by changing machine-independent
2641 files such as @file{toplev.c} to do something special that a particular
2642 system needs. Sometimes it is totally obvious that such changes would
2643 break GCC for almost all users. We can't possibly make a change like
2644 that. At best it might tell us how to write another patch that would
2645 solve the problem acceptably.
2647 Sometimes people send fixes that @emph{might} be an improvement in
2648 general---but it is hard to be sure of this. It's hard to install
2649 such changes because we have to study them very carefully. Of course,
2650 a good explanation of the reasoning by which you concluded the change
2651 was correct can help convince us.
2653 The safest changes are changes to the configuration files for a
2654 particular machine. These are safe because they can't create new bugs
2657 Please help us keep up with the workload by designing the patch in a
2658 form that is good to install.
2662 @chapter How To Get Help with GCC
2664 If you need help installing, using or changing GCC, there are two
2669 Send a message to a suitable network mailing list. First try
2670 @code{gcc-bugs@@gcc.gnu.org} or @code{bug-gcc@@gnu.org}, and if that
2671 brings no response, try @code{gcc@@gcc.gnu.org}.
2674 Look in the service directory for someone who might help you for a fee.
2675 The service directory is found in the file named @file{SERVICE} in the
2680 @chapter Contributing to GCC Development
2682 If you would like to help pretest GCC releases to assure they work
2683 well, or if you would like to work on improving GCC, please contact
2684 the maintainers at @code{gcc@@gcc.gnu.org}. A pretester should
2685 be willing to try to investigate bugs as well as report them.
2687 If you'd like to work on improvements, please ask for suggested projects
2688 or suggest your own ideas. If you have already written an improvement,
2689 please tell us about it. If you have not yet started work, it is useful
2690 to contact @code{gcc@@gcc.gnu.org} before you start; the
2691 maintainers may be able to suggest ways to make your extension fit in
2692 better with the rest of GCC and with other development plans.
2695 @chapter Using GCC on VMS
2697 @c prevent bad page break with this line
2698 Here is how to use GCC on VMS.
2701 * Include Files and VMS:: Where the preprocessor looks for the include files.
2702 * Global Declarations:: How to do globaldef, globalref and globalvalue with
2704 * VMS Misc:: Misc information.
2707 @node Include Files and VMS
2708 @section Include Files and VMS
2710 @cindex include files and VMS
2711 @cindex VMS and include files
2712 @cindex header files and VMS
2713 Due to the differences between the filesystems of Unix and VMS, GCC
2714 attempts to translate file names in @samp{#include} into names that VMS
2715 will understand. The basic strategy is to prepend a prefix to the
2716 specification of the include file, convert the whole filename to a VMS
2717 filename, and then try to open the file. GCC tries various prefixes
2718 one by one until one of them succeeds:
2722 The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
2723 where GNU C header files are traditionally stored. If you wish to store
2724 header files in non-standard locations, then you can assign the logical
2725 @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
2726 list is suitable for use with a rooted logical.
2729 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where
2730 VAX-C header files are traditionally stored.
2733 If the include file specification by itself is a valid VMS filename, the
2734 preprocessor then uses this name with no prefix in an attempt to open
2738 If the file specification is not a valid VMS filename (i.e. does not
2739 contain a device or a directory specifier, and contains a @samp{/}
2740 character), the preprocessor tries to convert it from Unix syntax to
2743 Conversion works like this: the first directory name becomes a device,
2744 and the rest of the directories are converted into VMS-format directory
2745 names. For example, the name @file{X11/foobar.h} is
2746 translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
2747 whichever one can be opened. This strategy allows you to assign a
2748 logical name to point to the actual location of the header files.
2751 If none of these strategies succeeds, the @samp{#include} fails.
2754 Include directives of the form:
2761 are a common source of incompatibility between VAX-C and GCC. VAX-C
2762 treats this much like a standard @code{#include <foobar.h>} directive.
2763 That is incompatible with the ANSI C behavior implemented by GCC: to
2764 expand the name @code{foobar} as a macro. Macro expansion should
2765 eventually yield one of the two standard formats for @code{#include}:
2768 #include "@var{file}"
2769 #include <@var{file}>
2772 If you have this problem, the best solution is to modify the source to
2773 convert the @code{#include} directives to one of the two standard forms.
2774 That will work with either compiler. If you want a quick and dirty fix,
2775 define the file names as macros with the proper expansion, like this:
2778 #define stdio <stdio.h>
2782 This will work, as long as the name doesn't conflict with anything else
2785 Another source of incompatibility is that VAX-C assumes that:
2792 is actually asking for the file @file{foobar.h}. GCC does not
2793 make this assumption, and instead takes what you ask for literally;
2794 it tries to read the file @file{foobar}. The best way to avoid this
2795 problem is to always specify the desired file extension in your include
2798 GCC for VMS is distributed with a set of include files that is
2799 sufficient to compile most general purpose programs. Even though the
2800 GCC distribution does not contain header files to define constants
2801 and structures for some VMS system-specific functions, there is no
2802 reason why you cannot use GCC with any of these functions. You first
2803 may have to generate or create header files, either by using the public
2804 domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
2805 extracting the relevant modules from one of the system macro libraries,
2806 and using an editor to construct a C header file.
2808 A @code{#include} file name cannot contain a DECNET node name. The
2809 preprocessor reports an I/O error if you attempt to use a node name,
2810 whether explicitly, or implicitly via a logical name.
2812 @node Global Declarations
2813 @section Global Declarations and VMS
2817 @findex GLOBALVALUEDEF
2818 @findex GLOBALVALUEREF
2819 GCC does not provide the @code{globalref}, @code{globaldef} and
2820 @code{globalvalue} keywords of VAX-C. You can get the same effect with
2821 an obscure feature of GAS, the GNU assembler. (This requires GAS
2822 version 1.39 or later.) The following macros allow you to use this
2823 feature in a fairly natural way:
2827 #define GLOBALREF(TYPE,NAME) \
2829 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
2830 #define GLOBALDEF(TYPE,NAME,VALUE) \
2832 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
2834 #define GLOBALVALUEREF(TYPE,NAME) \
2835 const TYPE NAME[1] \
2836 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
2837 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2838 const TYPE NAME[1] \
2839 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \
2842 #define GLOBALREF(TYPE,NAME) \
2844 #define GLOBALDEF(TYPE,NAME,VALUE) \
2845 globaldef TYPE NAME = VALUE
2846 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2847 globalvalue TYPE NAME = VALUE
2848 #define GLOBALVALUEREF(TYPE,NAME) \
2849 globalvalue TYPE NAME
2854 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
2855 name is removed by the assembler, after it has modified the attributes
2856 of the symbol). These macros are provided in the VMS binaries
2857 distribution in a header file @file{GNU_HACKS.H}. An example of the
2861 GLOBALREF (int, ijk);
2862 GLOBALDEF (int, jkl, 0);
2865 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
2866 straightforwardly for arrays, since there is no way to insert the array
2867 dimension into the declaration at the right place. However, you can
2868 declare an array with these macros if you first define a typedef for the
2869 array type, like this:
2872 typedef int intvector[10];
2873 GLOBALREF (intvector, foo);
2876 Array and structure initializers will also break the macros; you can
2877 define the initializer to be a macro of its own, or you can expand the
2878 @code{GLOBALDEF} macro by hand. You may find a case where you wish to
2879 use the @code{GLOBALDEF} macro with a large array, but you are not
2880 interested in explicitly initializing each element of the array. In
2881 such cases you can use an initializer like: @code{@{0,@}}, which will
2882 initialize the entire array to @code{0}.
2884 A shortcoming of this implementation is that a variable declared with
2885 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For
2886 example, the declaration:
2889 GLOBALVALUEREF(int, ijk);
2893 declares the variable @code{ijk} as an array of type @code{int [1]}.
2894 This is done because a globalvalue is actually a constant; its ``value''
2895 is what the linker would normally consider an address. That is not how
2896 an integer value works in C, but it is how an array works. So treating
2897 the symbol as an array name gives consistent results---with the
2898 exception that the value seems to have the wrong type. @strong{Don't
2899 try to access an element of the array.} It doesn't have any elements.
2900 The array ``address'' may not be the address of actual storage.
2902 The fact that the symbol is an array may lead to warnings where the
2903 variable is used. Insert type casts to avoid the warnings. Here is an
2904 example; it takes advantage of the ANSI C feature allowing macros that
2905 expand to use the same name as the macro itself.
2908 GLOBALVALUEREF (int, ss$_normal);
2909 GLOBALVALUEDEF (int, xyzzy,123);
2911 #define ss$_normal ((int) ss$_normal)
2912 #define xyzzy ((int) xyzzy)
2916 Don't use @code{globaldef} or @code{globalref} with a variable whose
2917 type is an enumeration type; this is not implemented. Instead, make the
2918 variable an integer, and use a @code{globalvaluedef} for each of the
2919 enumeration values. An example of this would be:
2923 GLOBALDEF (int, color, 0);
2924 GLOBALVALUEDEF (int, RED, 0);
2925 GLOBALVALUEDEF (int, BLUE, 1);
2926 GLOBALVALUEDEF (int, GREEN, 3);
2928 enum globaldef color @{RED, BLUE, GREEN = 3@};
2933 @section Other VMS Issues
2935 @cindex exit status and VMS
2936 @cindex return value of @code{main}
2937 @cindex @code{main} and the exit status
2938 GCC automatically arranges for @code{main} to return 1 by default if
2939 you fail to specify an explicit return value. This will be interpreted
2940 by VMS as a status code indicating a normal successful completion.
2941 Version 1 of GCC did not provide this default.
2943 GCC on VMS works only with the GNU assembler, GAS. You need version
2944 1.37 or later of GAS in order to produce value debugging information for
2945 the VMS debugger. Use the ordinary VMS linker with the object files
2948 @cindex shared VMS run time system
2949 @cindex @file{VAXCRTL}
2950 Under previous versions of GCC, the generated code would occasionally
2951 give strange results when linked to the sharable @file{VAXCRTL} library.
2952 Now this should work.
2954 A caveat for use of @code{const} global variables: the @code{const}
2955 modifier must be specified in every external declaration of the variable
2956 in all of the source files that use that variable. Otherwise the linker
2957 will issue warnings about conflicting attributes for the variable. Your
2958 program will still work despite the warnings, but the variable will be
2959 placed in writable storage.
2961 @cindex name augmentation
2962 @cindex case sensitivity and VMS
2963 @cindex VMS and case sensitivity
2964 Although the VMS linker does distinguish between upper and lower case
2965 letters in global symbols, most VMS compilers convert all such symbols
2966 into upper case and most run-time library routines also have upper case
2967 names. To be able to reliably call such routines, GCC (by means of
2968 the assembler GAS) converts global symbols into upper case like other
2969 VMS compilers. However, since the usual practice in C is to distinguish
2970 case, GCC (via GAS) tries to preserve usual C behavior by augmenting
2971 each name that is not all lower case. This means truncating the name
2972 to at most 23 characters and then adding more characters at the end
2973 which encode the case pattern of those 23. Names which contain at
2974 least one dollar sign are an exception; they are converted directly into
2975 upper case without augmentation.
2977 Name augmentation yields bad results for programs that use precompiled
2978 libraries (such as Xlib) which were generated by another compiler. You
2979 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
2980 it makes external C functions and variables case-independent as is usual
2981 on VMS. Alternatively, you could write all references to the functions
2982 and variables in such libraries using lower case; this will work on VMS,
2983 but is not portable to other systems. The compiler option @samp{/NAMES}
2984 also provides control over global name handling.
2986 Function and variable names are handled somewhat differently with GNU
2987 C++. The GNU C++ compiler performs @dfn{name mangling} on function
2988 names, which means that it adds information to the function name to
2989 describe the data types of the arguments that the function takes. One
2990 result of this is that the name of a function can become very long.
2991 Since the VMS linker only recognizes the first 31 characters in a name,
2992 special action is taken to ensure that each function and variable has a
2993 unique name that can be represented in 31 characters.
2995 If the name (plus a name augmentation, if required) is less than 32
2996 characters in length, then no special action is performed. If the name
2997 is longer than 31 characters, the assembler (GAS) will generate a
2998 hash string based upon the function name, truncate the function name to
2999 23 characters, and append the hash string to the truncated name. If the
3000 @samp{/VERBOSE} compiler option is used, the assembler will print both
3001 the full and truncated names of each symbol that is truncated.
3003 The @samp{/NOCASE_HACK} compiler option should not be used when you are
3004 compiling programs that use libg++. libg++ has several instances of
3005 objects (i.e. @code{Filebuf} and @code{filebuf}) which become
3006 indistinguishable in a case-insensitive environment. This leads to
3007 cases where you need to inhibit augmentation selectively (if you were
3008 using libg++ and Xlib in the same program, for example). There is no
3009 special feature for doing this, but you can get the result by defining a
3010 macro for each mixed case symbol for which you wish to inhibit
3011 augmentation. The macro should expand into the lower case equivalent of
3012 itself. For example:
3015 #define StuDlyCapS studlycaps
3018 These macro definitions can be placed in a header file to minimize the
3019 number of changes to your source code.
3024 @chapter GCC and Portability
3026 @cindex GCC and portability
3028 The main goal of GCC was to make a good, fast compiler for machines in
3029 the class that the GNU system aims to run on: 32-bit machines that address
3030 8-bit bytes and have several general registers. Elegance, theoretical
3031 power and simplicity are only secondary.
3033 GCC gets most of the information about the target machine from a machine
3034 description which gives an algebraic formula for each of the machine's
3035 instructions. This is a very clean way to describe the target. But when
3036 the compiler needs information that is difficult to express in this
3037 fashion, I have not hesitated to define an ad-hoc parameter to the machine
3038 description. The purpose of portability is to reduce the total work needed
3039 on the compiler; it was not of interest for its own sake.
3042 @cindex autoincrement addressing, availability
3044 GCC does not contain machine dependent code, but it does contain code
3045 that depends on machine parameters such as endianness (whether the most
3046 significant byte has the highest or lowest address of the bytes in a word)
3047 and the availability of autoincrement addressing. In the RTL-generation
3048 pass, it is often necessary to have multiple strategies for generating code
3049 for a particular kind of syntax tree, strategies that are usable for different
3050 combinations of parameters. Often I have not tried to address all possible
3051 cases, but only the common ones or only the ones that I have encountered.
3052 As a result, a new target may require additional strategies. You will know
3053 if this happens because the compiler will call @code{abort}. Fortunately,
3054 the new strategies can be added in a machine-independent fashion, and will
3055 affect only the target machines that need them.
3060 @chapter Interfacing to GCC Output
3061 @cindex interfacing to GCC output
3062 @cindex run-time conventions
3063 @cindex function call conventions
3064 @cindex conventions, run-time
3066 GCC is normally configured to use the same function calling convention
3067 normally in use on the target system. This is done with the
3068 machine-description macros described (@pxref{Target Macros}).
3070 @cindex unions, returning
3071 @cindex structures, returning
3072 @cindex returning structures and unions
3073 However, returning of structure and union values is done differently on
3074 some target machines. As a result, functions compiled with PCC
3075 returning such types cannot be called from code compiled with GCC,
3076 and vice versa. This does not cause trouble often because few Unix
3077 library routines return structures or unions.
3079 GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
3080 long in the same registers used for @code{int} or @code{double} return
3081 values. (GCC typically allocates variables of such types in
3082 registers also.) Structures and unions of other sizes are returned by
3083 storing them into an address passed by the caller (usually in a
3084 register). The machine-description macros @code{STRUCT_VALUE} and
3085 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
3087 By contrast, PCC on most target machines returns structures and unions
3088 of any size by copying the data into an area of static storage, and then
3089 returning the address of that storage as if it were a pointer value.
3090 The caller must copy the data from that memory area to the place where
3091 the value is wanted. This is slower than the method used by GCC, and
3092 fails to be reentrant.
3094 On some target machines, such as RISC machines and the 80386, the
3095 standard system convention is to pass to the subroutine the address of
3096 where to return the value. On these machines, GCC has been
3097 configured to be compatible with the standard compiler, when this method
3098 is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3100 @cindex argument passing
3101 @cindex passing arguments
3102 GCC uses the system's standard convention for passing arguments. On
3103 some machines, the first few arguments are passed in registers; in
3104 others, all are passed on the stack. It would be possible to use
3105 registers for argument passing on any machine, and this would probably
3106 result in a significant speedup. But the result would be complete
3107 incompatibility with code that follows the standard convention. So this
3108 change is practical only if you are switching to GCC as the sole C
3109 compiler for the system. We may implement register argument passing on
3110 certain machines once we have a complete GNU system so that we can
3111 compile the libraries with GCC.
3113 On some machines (particularly the Sparc), certain types of arguments
3114 are passed ``by invisible reference''. This means that the value is
3115 stored in memory, and the address of the memory location is passed to
3118 @cindex @code{longjmp} and automatic variables
3119 If you use @code{longjmp}, beware of automatic variables. ANSI C says that
3120 automatic variables that are not declared @code{volatile} have undefined
3121 values after a @code{longjmp}. And this is all GCC promises to do,
3122 because it is very difficult to restore register variables correctly, and
3123 one of GCC's features is that it can put variables in registers without
3126 If you want a variable to be unaltered by @code{longjmp}, and you don't
3127 want to write @code{volatile} because old C compilers don't accept it,
3128 just take the address of the variable. If a variable's address is ever
3129 taken, even if just to compute it and ignore it, then the variable cannot
3140 @cindex arithmetic libraries
3141 @cindex math libraries
3142 Code compiled with GCC may call certain library routines. Most of
3143 them handle arithmetic for which there are no instructions. This
3144 includes multiply and divide on some machines, and floating point
3145 operations on any machine for which floating point support is disabled
3146 with @samp{-msoft-float}. Some standard parts of the C library, such as
3147 @code{bcopy} or @code{memcpy}, are also called automatically. The usual
3148 function call interface is used for calling the library routines.
3150 These library routines should be defined in the library @file{libgcc.a},
3151 which GCC automatically searches whenever it links a program. On
3152 machines that have multiply and divide instructions, if hardware
3153 floating point is in use, normally @file{libgcc.a} is not needed, but it
3154 is searched just in case.
3156 Each arithmetic function is defined in @file{libgcc1.c} to use the
3157 corresponding C arithmetic operator. As long as the file is compiled
3158 with another C compiler, which supports all the C arithmetic operators,
3159 this file will work portably. However, @file{libgcc1.c} does not work if
3160 compiled with GCC, because each arithmetic function would compile
3161 into a call to itself!
3166 @chapter Passes and Files of the Compiler
3167 @cindex passes and files of the compiler
3168 @cindex files and passes of the compiler
3169 @cindex compiler passes and files
3171 @cindex top level of compiler
3172 The overall control structure of the compiler is in @file{toplev.c}. This
3173 file is responsible for initialization, decoding arguments, opening and
3174 closing files, and sequencing the passes.
3176 @cindex parsing pass
3177 The parsing pass is invoked only once, to parse the entire input. The RTL
3178 intermediate code for a function is generated as the function is parsed, a
3179 statement at a time. Each statement is read in as a syntax tree and then
3180 converted to RTL; then the storage for the tree for the statement is
3181 reclaimed. Storage for types (and the expressions for their sizes),
3182 declarations, and a representation of the binding contours and how they nest,
3183 remain until the function is finished being compiled; these are all needed
3184 to output the debugging information.
3186 @findex rest_of_compilation
3187 @findex rest_of_decl_compilation
3188 Each time the parsing pass reads a complete function definition or
3189 top-level declaration, it calls either the function
3190 @code{rest_of_compilation}, or the function
3191 @code{rest_of_decl_compilation} in @file{toplev.c}, which are
3192 responsible for all further processing necessary, ending with output of
3193 the assembler language. All other compiler passes run, in sequence,
3194 within @code{rest_of_compilation}. When that function returns from
3195 compiling a function definition, the storage used for that function
3196 definition's compilation is entirely freed, unless it is an inline
3199 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3202 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3205 Here is a list of all the passes of the compiler and their source files.
3206 Also included is a description of where debugging dumps can be requested
3207 with @samp{-d} options.
3211 Parsing. This pass reads the entire text of a function definition,
3212 constructing partial syntax trees. This and RTL generation are no longer
3213 truly separate passes (formerly they were), but it is easier to think
3214 of them as separate.
3216 The tree representation does not entirely follow C syntax, because it is
3217 intended to support other languages as well.
3219 Language-specific data type analysis is also done in this pass, and every
3220 tree node that represents an expression has a data type attached.
3221 Variables are represented as declaration nodes.
3223 @cindex constant folding
3224 @cindex arithmetic simplifications
3225 @cindex simplifications, arithmetic
3226 Constant folding and some arithmetic simplifications are also done
3229 The language-independent source files for parsing are
3230 @file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}.
3231 There are also header files @file{tree.h} and @file{tree.def}
3232 which define the format of the tree representation.@refill
3234 @c Avoiding overfull is tricky here.
3235 The source files to parse C are
3239 @file{c-aux-info.c},
3242 along with header files
3246 The source files for parsing C++ are @file{cp-parse.y},
3247 @file{cp-class.c},@*
3248 @file{cp-cvt.c}, @file{cp-decl.c}, @file{cp-decl2.c},
3249 @file{cp-dem.c}, @file{cp-except.c},@*
3250 @file{cp-expr.c}, @file{cp-init.c}, @file{cp-lex.c},
3251 @file{cp-method.c}, @file{cp-ptree.c},@*
3252 @file{cp-search.c}, @file{cp-tree.c}, @file{cp-type2.c}, and
3253 @file{cp-typeck.c}, along with header files @file{cp-tree.def},
3254 @file{cp-tree.h}, and @file{cp-decl.h}.
3256 The special source files for parsing Objective C are
3257 @file{objc-parse.y}, @file{objc-actions.c}, @file{objc-tree.def}, and
3258 @file{objc-actions.h}. Certain C-specific files are used for this as
3261 The file @file{c-common.c} is also used for all of the above languages.
3263 @cindex RTL generation
3265 RTL generation. This is the conversion of syntax tree into RTL code.
3266 It is actually done statement-by-statement during parsing, but for
3267 most purposes it can be thought of as a separate pass.
3269 @cindex target-parameter-dependent code
3270 This is where the bulk of target-parameter-dependent code is found,
3271 since often it is necessary for strategies to apply only when certain
3272 standard kinds of instructions are available. The purpose of named
3273 instruction patterns is to provide this information to the RTL
3276 @cindex tail recursion optimization
3277 Optimization is done in this pass for @code{if}-conditions that are
3278 comparisons, boolean operations or conditional expressions. Tail
3279 recursion is detected at this time also. Decisions are made about how
3280 best to arrange loops and how to output @code{switch} statements.
3282 @c Avoiding overfull is tricky here.
3283 The source files for RTL generation include
3291 and @file{emit-rtl.c}.
3293 @file{insn-emit.c}, generated from the machine description by the
3294 program @code{genemit}, is used in this pass. The header file
3295 @file{expr.h} is used for communication within this pass.@refill
3299 The header files @file{insn-flags.h} and @file{insn-codes.h},
3300 generated from the machine description by the programs @code{genflags}
3301 and @code{gencodes}, tell this pass which standard names are available
3302 for use and which patterns correspond to them.@refill
3304 Aside from debugging information output, none of the following passes
3305 refers to the tree structure representation of the function (only
3306 part of which is saved).
3308 @cindex inline, automatic
3309 The decision of whether the function can and should be expanded inline
3310 in its subsequent callers is made at the end of rtl generation. The
3311 function must meet certain criteria, currently related to the size of
3312 the function and the types and number of parameters it has. Note that
3313 this function may contain loops, recursive calls to itself
3314 (tail-recursive functions can be inlined!), gotos, in short, all
3315 constructs supported by GCC. The file @file{integrate.c} contains
3316 the code to save a function's rtl for later inlining and to inline that
3317 rtl when the function is called. The header file @file{integrate.h}
3318 is also used for this purpose.
3320 The option @samp{-dr} causes a debugging dump of the RTL code after
3321 this pass. This dump file's name is made by appending @samp{.rtl} to
3322 the input file name.
3324 @cindex jump optimization
3325 @cindex unreachable code
3328 Jump optimization. This pass simplifies jumps to the following
3329 instruction, jumps across jumps, and jumps to jumps. It deletes
3330 unreferenced labels and unreachable code, except that unreachable code
3331 that contains a loop is not recognized as unreachable in this pass.
3332 (Such loops are deleted later in the basic block analysis.) It also
3333 converts some code originally written with jumps into sequences of
3334 instructions that directly set values from the results of comparisons,
3335 if the machine has such instructions.
3337 Jump optimization is performed two or three times. The first time is
3338 immediately following RTL generation. The second time is after CSE,
3339 but only if CSE says repeated jump optimization is needed. The
3340 last time is right before the final pass. That time, cross-jumping
3341 and deletion of no-op move instructions are done together with the
3342 optimizations described above.
3344 The source file of this pass is @file{jump.c}.
3346 The option @samp{-dj} causes a debugging dump of the RTL code after
3347 this pass is run for the first time. This dump file's name is made by
3348 appending @samp{.jump} to the input file name.
3350 @cindex register use analysis
3352 Register scan. This pass finds the first and last use of each
3353 register, as a guide for common subexpression elimination. Its source
3354 is in @file{regclass.c}.
3356 @cindex jump threading
3358 Jump threading. This pass detects a condition jump that branches to an
3359 identical or inverse test. Such jumps can be @samp{threaded} through
3360 the second conditional test. The source code for this pass is in
3361 @file{jump.c}. This optimization is only performed if
3362 @samp{-fthread-jumps} is enabled.
3364 @cindex common subexpression elimination
3365 @cindex constant propagation
3367 Common subexpression elimination. This pass also does constant
3368 propagation. Its source file is @file{cse.c}. If constant
3369 propagation causes conditional jumps to become unconditional or to
3370 become no-ops, jump optimization is run again when CSE is finished.
3372 The option @samp{-ds} causes a debugging dump of the RTL code after
3373 this pass. This dump file's name is made by appending @samp{.cse} to
3374 the input file name.
3376 @cindex global common subexpression elimination
3377 @cindex constant propagation
3378 @cindex copy propagation
3380 Global common subexpression elimination. This pass performs GCSE
3381 using Morel-Renvoise Partial Redundancy Elimination, with the exception
3382 that it does not try to move invariants out of loops - that is left to
3383 the loop optimization pass. This pass also performs global constant
3384 and copy propagation.
3386 The source file for this pass is gcse.c.
3388 The option @samp{-dG} causes a debugging dump of the RTL code after
3389 this pass. This dump file's name is made by appending @samp{.gcse} to
3390 the input file name.
3392 @cindex loop optimization
3394 @cindex strength-reduction
3396 Loop optimization. This pass moves constant expressions out of loops,
3397 and optionally does strength-reduction and loop unrolling as well.
3398 Its source files are @file{loop.c} and @file{unroll.c}, plus the header
3399 @file{loop.h} used for communication between them. Loop unrolling uses
3400 some functions in @file{integrate.c} and the header @file{integrate.h}.
3402 The option @samp{-dL} causes a debugging dump of the RTL code after
3403 this pass. This dump file's name is made by appending @samp{.loop} to
3404 the input file name.
3407 If @samp{-frerun-cse-after-loop} was enabled, a second common
3408 subexpression elimination pass is performed after the loop optimization
3409 pass. Jump threading is also done again at this time if it was specified.
3411 The option @samp{-dt} causes a debugging dump of the RTL code after
3412 this pass. This dump file's name is made by appending @samp{.cse2} to
3413 the input file name.
3415 @cindex register allocation, stupid
3416 @cindex stupid register allocation
3418 Stupid register allocation is performed at this point in a
3419 nonoptimizing compilation. It does a little data flow analysis as
3420 well. When stupid register allocation is in use, the next pass
3421 executed is the reloading pass; the others in between are skipped.
3422 The source file is @file{stupid.c}.
3424 @cindex data flow analysis
3425 @cindex analysis, data flow
3426 @cindex basic blocks
3428 Data flow analysis (@file{flow.c}). This pass divides the program
3429 into basic blocks (and in the process deletes unreachable loops); then
3430 it computes which pseudo-registers are live at each point in the
3431 program, and makes the first instruction that uses a value point at
3432 the instruction that computed the value.
3434 @cindex autoincrement/decrement analysis
3435 This pass also deletes computations whose results are never used, and
3436 combines memory references with add or subtract instructions to make
3437 autoincrement or autodecrement addressing.
3439 The option @samp{-df} causes a debugging dump of the RTL code after
3440 this pass. This dump file's name is made by appending @samp{.flow} to
3441 the input file name. If stupid register allocation is in use, this
3442 dump file reflects the full results of such allocation.
3444 @cindex instruction combination
3446 Instruction combination (@file{combine.c}). This pass attempts to
3447 combine groups of two or three instructions that are related by data
3448 flow into single instructions. It combines the RTL expressions for
3449 the instructions by substitution, simplifies the result using algebra,
3450 and then attempts to match the result against the machine description.
3452 The option @samp{-dc} causes a debugging dump of the RTL code after
3453 this pass. This dump file's name is made by appending @samp{.combine}
3454 to the input file name.
3456 @cindex register movement
3458 Register movement (@file{regmove.c}). This pass looks for cases where
3459 matching constraints would force an instruction to need a reload, and
3460 this reload would be a register to register move. It them attempts
3461 to change the registers used by the instruction to avoid the move
3464 The option @samp{-dN} causes a debugging dump of the RTL code after
3465 this pass. This dump file's name is made by appending @samp{.regmove}
3466 to the input file name.
3468 @cindex instruction scheduling
3469 @cindex scheduling, instruction
3471 Instruction scheduling (@file{sched.c}). This pass looks for
3472 instructions whose output will not be available by the time that it is
3473 used in subsequent instructions. (Memory loads and floating point
3474 instructions often have this behavior on RISC machines). It re-orders
3475 instructions within a basic block to try to separate the definition and
3476 use of items that otherwise would cause pipeline stalls.
3478 Instruction scheduling is performed twice. The first time is immediately
3479 after instruction combination and the second is immediately after reload.
3481 The option @samp{-dS} causes a debugging dump of the RTL code after this
3482 pass is run for the first time. The dump file's name is made by
3483 appending @samp{.sched} to the input file name.
3485 @cindex register class preference pass
3487 Register class preferencing. The RTL code is scanned to find out
3488 which register class is best for each pseudo register. The source
3489 file is @file{regclass.c}.
3491 @cindex register allocation
3492 @cindex local register allocation
3494 Local register allocation (@file{local-alloc.c}). This pass allocates
3495 hard registers to pseudo registers that are used only within one basic
3496 block. Because the basic block is linear, it can use fast and
3497 powerful techniques to do a very good job.
3499 The option @samp{-dl} causes a debugging dump of the RTL code after
3500 this pass. This dump file's name is made by appending @samp{.lreg} to
3501 the input file name.
3503 @cindex global register allocation
3505 Global register allocation (@file{global.c}). This pass
3506 allocates hard registers for the remaining pseudo registers (those
3507 whose life spans are not contained in one basic block).
3511 Reloading. This pass renumbers pseudo registers with the hardware
3512 registers numbers they were allocated. Pseudo registers that did not
3513 get hard registers are replaced with stack slots. Then it finds
3514 instructions that are invalid because a value has failed to end up in
3515 a register, or has ended up in a register of the wrong kind. It fixes
3516 up these instructions by reloading the problematical values
3517 temporarily into registers. Additional instructions are generated to
3520 The reload pass also optionally eliminates the frame pointer and inserts
3521 instructions to save and restore call-clobbered registers around calls.
3523 Source files are @file{reload.c} and @file{reload1.c}, plus the header
3524 @file{reload.h} used for communication between them.
3526 The option @samp{-dg} causes a debugging dump of the RTL code after
3527 this pass. This dump file's name is made by appending @samp{.greg} to
3528 the input file name.
3530 @cindex instruction scheduling
3531 @cindex scheduling, instruction
3533 Instruction scheduling is repeated here to try to avoid pipeline stalls
3534 due to memory loads generated for spilled pseudo registers.
3536 The option @samp{-dR} causes a debugging dump of the RTL code after
3537 this pass. This dump file's name is made by appending @samp{.sched2}
3538 to the input file name.
3540 @cindex cross-jumping
3541 @cindex no-op move instructions
3543 Jump optimization is repeated, this time including cross-jumping
3544 and deletion of no-op move instructions.
3546 The option @samp{-dJ} causes a debugging dump of the RTL code after
3547 this pass. This dump file's name is made by appending @samp{.jump2}
3548 to the input file name.
3550 @cindex delayed branch scheduling
3551 @cindex scheduling, delayed branch
3553 Delayed branch scheduling. This optional pass attempts to find
3554 instructions that can go into the delay slots of other instructions,
3555 usually jumps and calls. The source file name is @file{reorg.c}.
3557 The option @samp{-dd} causes a debugging dump of the RTL code after
3558 this pass. This dump file's name is made by appending @samp{.dbr}
3559 to the input file name.
3561 @cindex register-to-stack conversion
3563 Conversion from usage of some hard registers to usage of a register
3564 stack may be done at this point. Currently, this is supported only
3565 for the floating-point registers of the Intel 80387 coprocessor. The
3566 source file name is @file{reg-stack.c}.
3568 The options @samp{-dk} causes a debugging dump of the RTL code after
3569 this pass. This dump file's name is made by appending @samp{.stack}
3570 to the input file name.
3573 @cindex peephole optimization
3575 Final. This pass outputs the assembler code for the function. It is
3576 also responsible for identifying spurious test and compare
3577 instructions. Machine-specific peephole optimizations are performed
3578 at the same time. The function entry and exit sequences are generated
3579 directly as assembler code in this pass; they never exist as RTL.
3581 The source files are @file{final.c} plus @file{insn-output.c}; the
3582 latter is generated automatically from the machine description by the
3583 tool @file{genoutput}. The header file @file{conditions.h} is used
3584 for communication between these files.
3586 @cindex debugging information generation
3588 Debugging information output. This is run after final because it must
3589 output the stack slot offsets for pseudo registers that did not get
3590 hard registers. Source files are @file{dbxout.c} for DBX symbol table
3591 format, @file{sdbout.c} for SDB symbol table format, and
3592 @file{dwarfout.c} for DWARF symbol table format.
3595 Some additional files are used by all or many passes:
3599 Every pass uses @file{machmode.def} and @file{machmode.h} which define
3603 Several passes use @file{real.h}, which defines the default
3604 representation of floating point constants and how to operate on them.
3607 All the passes that work with RTL use the header files @file{rtl.h}
3608 and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
3609 @code{gen*} also use these files to read and work with the machine
3614 Several passes refer to the header file @file{insn-config.h} which
3615 contains a few parameters (C macro definitions) generated
3616 automatically from the machine description RTL by the tool
3619 @cindex instruction recognizer
3621 Several passes use the instruction recognizer, which consists of
3622 @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
3623 and @file{insn-extract.c} that are generated automatically from the
3624 machine description by the tools @file{genrecog} and
3625 @file{genextract}.@refill
3628 Several passes use the header files @file{regs.h} which defines the
3629 information recorded about pseudo register usage, and @file{basic-block.h}
3630 which defines the information recorded about basic blocks.
3633 @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
3634 with a bit for each hard register, and some macros to manipulate it.
3635 This type is just @code{int} if the machine has few enough hard registers;
3636 otherwise it is an array of @code{int} and some of the macros expand
3640 Several passes use instruction attributes. A definition of the
3641 attributes defined for a particular machine is in file
3642 @file{insn-attr.h}, which is generated from the machine description by
3643 the program @file{genattr}. The file @file{insn-attrtab.c} contains
3644 subroutines to obtain the attribute values for insns. It is generated
3645 from the machine description by the program @file{genattrtab}.@refill
3657 @chapter The Configuration File
3658 @cindex configuration file
3659 @cindex @file{xm-@var{machine}.h}
3661 The configuration file @file{xm-@var{machine}.h} contains macro
3662 definitions that describe the machine and system on which the compiler
3663 is running, unlike the definitions in @file{@var{machine}.h}, which
3664 describe the machine for which the compiler is producing output. Most
3665 of the values in @file{xm-@var{machine}.h} are actually the same on all
3666 machines that GCC runs on, so large parts of all configuration files
3667 are identical. But there are some macros that vary:
3672 Define this macro if the host system is System V.
3676 Define this macro if the host system is VMS.
3678 @findex FATAL_EXIT_CODE
3679 @item FATAL_EXIT_CODE
3680 A C expression for the status code to be returned when the compiler
3681 exits after serious errors.
3683 @findex SUCCESS_EXIT_CODE
3684 @item SUCCESS_EXIT_CODE
3685 A C expression for the status code to be returned when the compiler
3686 exits without serious errors.
3688 @findex HOST_WORDS_BIG_ENDIAN
3689 @item HOST_WORDS_BIG_ENDIAN
3690 Defined if the host machine stores words of multi-word values in
3691 big-endian order. (GCC does not depend on the host byte ordering
3694 @findex HOST_FLOAT_WORDS_BIG_ENDIAN
3695 @item HOST_FLOAT_WORDS_BIG_ENDIAN
3696 Define this macro to be 1 if the host machine stores @code{DFmode},
3697 @code{XFmode} or @code{TFmode} floating point numbers in memory with the
3698 word containing the sign bit at the lowest address; otherwise, define it
3701 This macro need not be defined if the ordering is the same as for
3702 multi-word integers.
3704 @findex HOST_FLOAT_FORMAT
3705 @item HOST_FLOAT_FORMAT
3706 A numeric code distinguishing the floating point format for the host
3707 machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
3708 alternatives and default.
3710 @findex HOST_BITS_PER_CHAR
3711 @item HOST_BITS_PER_CHAR
3712 A C expression for the number of bits in @code{char} on the host
3715 @findex HOST_BITS_PER_SHORT
3716 @item HOST_BITS_PER_SHORT
3717 A C expression for the number of bits in @code{short} on the host
3720 @findex HOST_BITS_PER_INT
3721 @item HOST_BITS_PER_INT
3722 A C expression for the number of bits in @code{int} on the host
3725 @findex HOST_BITS_PER_LONG
3726 @item HOST_BITS_PER_LONG
3727 A C expression for the number of bits in @code{long} on the host
3730 @findex ONLY_INT_FIELDS
3731 @item ONLY_INT_FIELDS
3732 Define this macro to indicate that the host compiler only supports
3733 @code{int} bit fields, rather than other integral types, including
3734 @code{enum}, as do most C compilers.
3736 @findex OBSTACK_CHUNK_SIZE
3737 @item OBSTACK_CHUNK_SIZE
3738 A C expression for the size of ordinary obstack chunks.
3739 If you don't define this, a usually-reasonable default is used.
3741 @findex OBSTACK_CHUNK_ALLOC
3742 @item OBSTACK_CHUNK_ALLOC
3743 The function used to allocate obstack chunks.
3744 If you don't define this, @code{xmalloc} is used.
3746 @findex OBSTACK_CHUNK_FREE
3747 @item OBSTACK_CHUNK_FREE
3748 The function used to free obstack chunks.
3749 If you don't define this, @code{free} is used.
3751 @findex USE_C_ALLOCA
3753 Define this macro to indicate that the compiler is running with the
3754 @code{alloca} implemented in C. This version of @code{alloca} can be
3755 found in the file @file{alloca.c}; to use it, you must also alter the
3756 @file{Makefile} variable @code{ALLOCA}. (This is done automatically
3757 for the systems on which we know it is needed.)
3759 If you do define this macro, you should probably do it as follows:
3763 #define USE_C_ALLOCA
3765 #define alloca __builtin_alloca
3770 so that when the compiler is compiled with GCC it uses the more
3771 efficient built-in @code{alloca} function.
3773 @item FUNCTION_CONVERSION_BUG
3774 @findex FUNCTION_CONVERSION_BUG
3775 Define this macro to indicate that the host compiler does not properly
3776 handle converting a function value to a pointer-to-function when it is
3777 used in an expression.
3779 @findex MULTIBYTE_CHARS
3780 @item MULTIBYTE_CHARS
3781 Define this macro to enable support for multibyte characters in the
3782 input to GCC. This requires that the host system support the ANSI C
3783 library functions for converting multibyte characters to wide
3788 Define this if your system is POSIX.1 compliant.
3790 @findex NO_SYS_SIGLIST
3791 @item NO_SYS_SIGLIST
3792 Define this if your system @emph{does not} provide the variable
3796 Some systems do provide this variable, but with a different name such
3797 as @code{_sys_siglist}. On these systems, you can define
3798 @code{sys_siglist} as a macro which expands into the name actually
3801 Autoconf normally defines @code{SYS_SIGLIST_DECLARED} when it finds a
3802 declaration of @code{sys_siglist} in the system header files.
3803 However, when you define @code{sys_siglist} to a different name
3804 autoconf will not automatically define @code{SYS_SIGLIST_DECLARED}.
3805 Therefore, if you define @code{sys_siglist}, you should also define
3806 @code{SYS_SIGLIST_DECLARED}.
3808 @findex USE_PROTOTYPES
3809 @item USE_PROTOTYPES
3810 Define this to be 1 if you know that the host compiler supports
3811 prototypes, even if it doesn't define __STDC__, or define
3812 it to be 0 if you do not want any prototypes used in compiling
3813 GCC. If @samp{USE_PROTOTYPES} is not defined, it will be
3814 determined automatically whether your compiler supports
3815 prototypes by checking if @samp{__STDC__} is defined.
3817 @findex NO_MD_PROTOTYPES
3818 @item NO_MD_PROTOTYPES
3819 Define this if you wish suppression of prototypes generated from
3820 the machine description file, but to use other prototypes within
3821 GCC. If @samp{USE_PROTOTYPES} is defined to be 0, or the
3822 host compiler does not support prototypes, this macro has no
3825 @findex MD_CALL_PROTOTYPES
3826 @item MD_CALL_PROTOTYPES
3827 Define this if you wish to generate prototypes for the
3828 @code{gen_call} or @code{gen_call_value} functions generated from
3829 the machine description file. If @samp{USE_PROTOTYPES} is
3830 defined to be 0, or the host compiler does not support
3831 prototypes, or @samp{NO_MD_PROTOTYPES} is defined, this macro has
3832 no effect. As soon as all of the machine descriptions are
3833 modified to have the appropriate number of arguments, this macro
3836 @findex PATH_SEPARATOR
3837 @item PATH_SEPARATOR
3838 Define this macro to be a C character constant representing the
3839 character used to separate components in paths. The default value is
3842 @findex DIR_SEPARATOR
3844 If your system uses some character other than slash to separate
3845 directory names within a file specification, define this macro to be a C
3846 character constant specifying that character. When GCC displays file
3847 names, the character you specify will be used. GCC will test for
3848 both slash and the character you specify when parsing filenames.
3850 @findex OBJECT_SUFFIX
3852 Define this macro to be a C string representing the suffix for object
3853 files on your machine. If you do not define this macro, GCC will use
3854 @samp{.o} as the suffix for object files.
3856 @findex EXECUTABLE_SUFFIX
3857 @item EXECUTABLE_SUFFIX
3858 Define this macro to be a C string representing the suffix for executable
3859 files on your machine. If you do not define this macro, GCC will use
3860 the null string as the suffix for object files.
3862 @findex COLLECT_EXPORT_LIST
3863 @item COLLECT_EXPORT_LIST
3864 If defined, @code{collect2} will scan the individual object files
3865 specified on its command line and create an export list for the linker.
3866 Define this macro for systems like AIX, where the linker discards
3867 object files that are not referenced from @code{main} and uses export
3873 In addition, configuration files for system V define @code{bcopy},
3874 @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
3875 as a macro when compiled with GCC, in order to take advantage of the
3876 benefit of GCC's built-in @code{alloca}.
3879 @chapter Makefile Fragments
3880 @cindex makefile fragment
3882 When you configure GCC using the @file{configure} script
3883 (@pxref{Installation}), it will construct the file @file{Makefile} from
3884 the template file @file{Makefile.in}. When it does this, it will
3885 incorporate makefile fragment files from the @file{config} directory,
3886 named @file{t-@var{target}} and @file{x-@var{host}}. If these files do
3887 not exist, it means nothing needs to be added for a given target or
3891 * Target Fragment:: Writing the @file{t-@var{target}} file.
3892 * Host Fragment:: Writing the @file{x-@var{host}} file.
3895 @node Target Fragment
3896 @section The Target Makefile Fragment
3897 @cindex target makefile fragment
3898 @cindex @file{t-@var{target}}
3900 The target makefile fragment, @file{t-@var{target}}, defines special
3901 target dependent variables and targets used in the @file{Makefile}:
3906 The rule to use to build @file{libgcc1.a}.
3907 If your target does not need to use the functions in @file{libgcc1.a},
3911 @findex CROSS_LIBGCC1
3913 The rule to use to build @file{libgcc1.a} when building a cross
3914 compiler. If your target does not need to use the functions in
3915 @file{libgcc1.a}, set this to empty. @xref{Cross Runtime}.
3917 @findex LIBGCC2_CFLAGS
3918 @item LIBGCC2_CFLAGS
3919 Compiler flags to use when compiling @file{libgcc2.c}.
3921 @findex LIB2FUNCS_EXTRA
3922 @item LIB2FUNCS_EXTRA
3923 A list of source file names to be compiled or assembled and inserted
3924 into @file{libgcc.a}.
3926 @findex CRTSTUFF_T_CFLAGS
3927 @item CRTSTUFF_T_CFLAGS
3928 Special flags used when compiling @file{crtstuff.c}.
3929 @xref{Initialization}.
3931 @findex CRTSTUFF_T_CFLAGS_S
3932 @item CRTSTUFF_T_CFLAGS_S
3933 Special flags used when compiling @file{crtstuff.c} for shared
3934 linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
3935 in @code{EXTRA-PARTS}.
3936 @xref{Initialization}.
3938 @findex MULTILIB_OPTIONS
3939 @item MULTILIB_OPTIONS
3940 For some targets, invoking GCC in different ways produces objects
3941 that can not be linked together. For example, for some targets GCC
3942 produces both big and little endian code. For these targets, you must
3943 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
3944 each set of incompatible options. When GCC invokes the linker, it
3945 arranges to link in the right version of @file{libgcc.a}, based on
3946 the command line options used.
3948 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
3949 special versions of @file{libgcc.a} must be built. Write options that
3950 are mutually incompatible side by side, separated by a slash. Write
3951 options that may be used together separated by a space. The build
3952 procedure will build all combinations of compatible options.
3954 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
3955 msoft-float}, @file{Makefile} will build special versions of
3956 @file{libgcc.a} using the following sets of options: @samp{-m68000},
3957 @samp{-m68020}, @samp{-msoft-float}, @samp{-m68000 -msoft-float}, and
3958 @samp{-m68020 -msoft-float}.
3960 @findex MULTILIB_DIRNAMES
3961 @item MULTILIB_DIRNAMES
3962 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
3963 directory names that should be used to hold the various libraries.
3964 Write one element in @code{MULTILIB_DIRNAMES} for each element in
3965 @code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
3966 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
3969 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
3970 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
3971 @samp{m68000 m68020 msoft-float}. You may specify a different value if
3972 you desire a different set of directory names.
3974 @findex MULTILIB_MATCHES
3975 @item MULTILIB_MATCHES
3976 Sometimes the same option may be written in two different ways. If an
3977 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
3978 any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
3979 items of the form @samp{option=option} to describe all relevant
3980 synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
3982 @findex MULTILIB_EXCEPTIONS
3983 @item MULTILIB_EXCEPTIONS
3984 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
3985 specified, there are combinations that should not be built. In that
3986 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
3987 in shell case syntax that should not be built.
3989 For example, in the PowerPC embedded ABI support, it was not desirable
3990 to build libraries that compiled with the @samp{-mcall-aixdesc} option
3991 and either of the @samp{-mcall-aixdesc} or @samp{-mlittle} options at
3992 the same time, and therefore @code{MULTILIB_EXCEPTIONS} is set to
3993 @code{*mrelocatable/*mcall-aixdesc* *mlittle/*mcall-aixdesc*}.
3995 @findex MULTILIB_EXTRA_OPTS
3996 @item MULTILIB_EXTRA_OPTS
3997 Sometimes it is desirable that when building multiple versions of
3998 @file{libgcc.a} certain options should always be passed on to the
3999 compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
4000 of options to be used for all builds.
4004 @section The Host Makefile Fragment
4005 @cindex host makefile fragment
4006 @cindex @file{x-@var{host}}
4008 The host makefile fragment, @file{x-@var{host}}, defines special host
4009 dependent variables and targets used in the @file{Makefile}:
4014 The compiler to use when building the first stage.
4018 Additional host libraries to link with.
4022 The compiler to use when building @file{libgcc1.a} for a native
4027 The version of @code{ar} to use when building @file{libgcc1.a} for a native
4032 The install program to use.
4036 @unnumbered Funding Free Software
4038 If you want to have more free software a few years from now, it makes
4039 sense for you to help encourage people to contribute funds for its
4040 development. The most effective approach known is to encourage
4041 commercial redistributors to donate.
4043 Users of free software systems can boost the pace of development by
4044 encouraging for-a-fee distributors to donate part of their selling price
4045 to free software developers---the Free Software Foundation, and others.
4047 The way to convince distributors to do this is to demand it and expect
4048 it from them. So when you compare distributors, judge them partly by
4049 how much they give to free software development. Show distributors
4050 they must compete to be the one who gives the most.
4052 To make this approach work, you must insist on numbers that you can
4053 compare, such as, ``We will donate ten dollars to the Frobnitz project
4054 for each disk sold.'' Don't be satisfied with a vague promise, such as
4055 ``A portion of the profits are donated,'' since it doesn't give a basis
4058 Even a precise fraction ``of the profits from this disk'' is not very
4059 meaningful, since creative accounting and unrelated business decisions
4060 can greatly alter what fraction of the sales price counts as profit.
4061 If the price you pay is $50, ten percent of the profit is probably
4062 less than a dollar; it might be a few cents, or nothing at all.
4064 Some redistributors do development work themselves. This is useful too;
4065 but to keep everyone honest, you need to inquire how much they do, and
4066 what kind. Some kinds of development make much more long-term
4067 difference than others. For example, maintaining a separate version of
4068 a program contributes very little; maintaining the standard version of a
4069 program for the whole community contributes much. Easy new ports
4070 contribute little, since someone else would surely do them; difficult
4071 ports such as adding a new CPU to the GNU Compiler Collection contribute more;
4072 major new features or packages contribute the most.
4074 By establishing the idea that supporting further development is ``the
4075 proper thing to do'' when distributing free software for a fee, we can
4076 assure a steady flow of resources into making more free software.
4079 Copyright (C) 1994 Free Software Foundation, Inc.
4080 Verbatim copying and redistribution of this section is permitted
4081 without royalty; alteration is not permitted.
4085 @unnumbered Linux and the GNU Project
4087 Many computer users run a modified version of the GNU system every
4088 day, without realizing it. Through a peculiar turn of events, the
4089 version of GNU which is widely used today is more often known as
4090 ``Linux'', and many users are not aware of the extent of its
4091 connection with the GNU Project.
4093 There really is a Linux; it is a kernel, and these people are using
4094 it. But you can't use a kernel by itself; a kernel is useful only as
4095 part of a whole system. The system in which Linux is typically used
4096 is a modified variant of the GNU system---in other words, a Linux-based
4099 Many users are not fully aware of the distinction between the kernel,
4100 which is Linux, and the whole system, which they also call ``Linux''.
4101 The ambiguous use of the name doesn't promote understanding.
4103 Programmers generally know that Linux is a kernel. But since they
4104 have generally heard the whole system called ``Linux'' as well, they
4105 often envisage a history which fits that name. For example, many
4106 believe that once Linus Torvalds finished writing the kernel, his
4107 friends looked around for other free software, and for no particular
4108 reason most everything necessary to make a Unix-like system was
4111 What they found was no accident---it was the GNU system. The available
4112 free software added up to a complete system because the GNU Project
4113 had been working since 1984 to make one. The GNU Manifesto
4114 had set forth the goal of developing a free Unix-like system, called
4115 GNU. By the time Linux was written, the system was almost finished.
4117 Most free software projects have the goal of developing a particular
4118 program for a particular job. For example, Linus Torvalds set out to
4119 write a Unix-like kernel (Linux); Donald Knuth set out to write a text
4120 formatter (TeX); Bob Scheifler set out to develop a window system (X
4121 Windows). It's natural to measure the contribution of this kind of
4122 project by specific programs that came from the project.
4124 If we tried to measure the GNU Project's contribution in this way,
4125 what would we conclude? One CD-ROM vendor found that in their ``Linux
4126 distribution'', GNU software was the largest single contingent, around
4127 28% of the total source code, and this included some of the essential
4128 major components without which there could be no system. Linux itself
4129 was about 3%. So if you were going to pick a name for the system
4130 based on who wrote the programs in the system, the most appropriate
4131 single choice would be ``GNU''.
4133 But we don't think that is the right way to consider the question.
4134 The GNU Project was not, is not, a project to develop specific
4135 software packages. It was not a project to develop a C compiler,
4136 although we did. It was not a project to develop a text editor,
4137 although we developed one. The GNU Project's aim was to develop
4138 @emph{a complete free Unix-like system}.
4140 Many people have made major contributions to the free software in the
4141 system, and they all deserve credit. But the reason it is @emph{a
4142 system}---and not just a collection of useful programs---is because the
4143 GNU Project set out to make it one. We wrote the programs that were
4144 needed to make a @emph{complete} free system. We wrote essential but
4145 unexciting major components, such as the assembler and linker, because
4146 you can't have a system without them. A complete system needs more
4147 than just programming tools, so we wrote other components as well,
4148 such as the Bourne Again SHell, the PostScript interpreter
4149 Ghostscript, and the GNU C library.
4151 By the early 90s we had put together the whole system aside from the
4152 kernel (and we were also working on a kernel, the GNU Hurd, which runs
4153 on top of Mach). Developing this kernel has been a lot harder than we
4154 expected, and we are still working on finishing it.
4156 Fortunately, you don't have to wait for it, because Linux is working
4157 now. When Linus Torvalds wrote Linux, he filled the last major gap.
4158 People could then put Linux together with the GNU system to make a
4159 complete free system: a Linux-based GNU system (or GNU/Linux system,
4162 Putting them together sounds simple, but it was not a trivial job.
4163 The GNU C library (called glibc for short) needed substantial changes.
4164 Integrating a complete system as a distribution that would work ``out
4165 of the box'' was a big job, too. It required addressing the issue of
4166 how to install and boot the system---a problem we had not tackled,
4167 because we hadn't yet reached that point. The people who developed
4168 the various system distributions made a substantial contribution.
4170 The GNU Project supports GNU/Linux systems as well as @emph{the}
4171 GNU system---even with funds. We funded the rewriting of the
4172 Linux-related extensions to the GNU C library, so that now they are
4173 well integrated, and the newest GNU/Linux systems use the current
4174 library release with no changes. We also funded an early stage of the
4175 development of Debian GNU/Linux.
4177 We use Linux-based GNU systems today for most of our work, and we hope
4178 you use them too. But please don't confuse the public by using the
4179 name ``Linux'' ambiguously. Linux is the kernel, one of the essential
4180 major components of the system. The system as a whole is more or less
4184 @unnumbered GNU GENERAL PUBLIC LICENSE
4185 @center Version 2, June 1991
4188 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
4189 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
4191 Everyone is permitted to copy and distribute verbatim copies
4192 of this license document, but changing it is not allowed.
4195 @unnumberedsec Preamble
4197 The licenses for most software are designed to take away your
4198 freedom to share and change it. By contrast, the GNU General Public
4199 License is intended to guarantee your freedom to share and change free
4200 software---to make sure the software is free for all its users. This
4201 General Public License applies to most of the Free Software
4202 Foundation's software and to any other program whose authors commit to
4203 using it. (Some other Free Software Foundation software is covered by
4204 the GNU Library General Public License instead.) You can apply it to
4207 When we speak of free software, we are referring to freedom, not
4208 price. Our General Public Licenses are designed to make sure that you
4209 have the freedom to distribute copies of free software (and charge for
4210 this service if you wish), that you receive source code or can get it
4211 if you want it, that you can change the software or use pieces of it
4212 in new free programs; and that you know you can do these things.
4214 To protect your rights, we need to make restrictions that forbid
4215 anyone to deny you these rights or to ask you to surrender the rights.
4216 These restrictions translate to certain responsibilities for you if you
4217 distribute copies of the software, or if you modify it.
4219 For example, if you distribute copies of such a program, whether
4220 gratis or for a fee, you must give the recipients all the rights that
4221 you have. You must make sure that they, too, receive or can get the
4222 source code. And you must show them these terms so they know their
4225 We protect your rights with two steps: (1) copyright the software, and
4226 (2) offer you this license which gives you legal permission to copy,
4227 distribute and/or modify the software.
4229 Also, for each author's protection and ours, we want to make certain
4230 that everyone understands that there is no warranty for this free
4231 software. If the software is modified by someone else and passed on, we
4232 want its recipients to know that what they have is not the original, so
4233 that any problems introduced by others will not reflect on the original
4234 authors' reputations.
4236 Finally, any free program is threatened constantly by software
4237 patents. We wish to avoid the danger that redistributors of a free
4238 program will individually obtain patent licenses, in effect making the
4239 program proprietary. To prevent this, we have made it clear that any
4240 patent must be licensed for everyone's free use or not licensed at all.
4242 The precise terms and conditions for copying, distribution and
4243 modification follow.
4246 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4249 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4254 This License applies to any program or other work which contains
4255 a notice placed by the copyright holder saying it may be distributed
4256 under the terms of this General Public License. The ``Program'', below,
4257 refers to any such program or work, and a ``work based on the Program''
4258 means either the Program or any derivative work under copyright law:
4259 that is to say, a work containing the Program or a portion of it,
4260 either verbatim or with modifications and/or translated into another
4261 language. (Hereinafter, translation is included without limitation in
4262 the term ``modification''.) Each licensee is addressed as ``you''.
4264 Activities other than copying, distribution and modification are not
4265 covered by this License; they are outside its scope. The act of
4266 running the Program is not restricted, and the output from the Program
4267 is covered only if its contents constitute a work based on the
4268 Program (independent of having been made by running the Program).
4269 Whether that is true depends on what the Program does.
4272 You may copy and distribute verbatim copies of the Program's
4273 source code as you receive it, in any medium, provided that you
4274 conspicuously and appropriately publish on each copy an appropriate
4275 copyright notice and disclaimer of warranty; keep intact all the
4276 notices that refer to this License and to the absence of any warranty;
4277 and give any other recipients of the Program a copy of this License
4278 along with the Program.
4280 You may charge a fee for the physical act of transferring a copy, and
4281 you may at your option offer warranty protection in exchange for a fee.
4284 You may modify your copy or copies of the Program or any portion
4285 of it, thus forming a work based on the Program, and copy and
4286 distribute such modifications or work under the terms of Section 1
4287 above, provided that you also meet all of these conditions:
4291 You must cause the modified files to carry prominent notices
4292 stating that you changed the files and the date of any change.
4295 You must cause any work that you distribute or publish, that in
4296 whole or in part contains or is derived from the Program or any
4297 part thereof, to be licensed as a whole at no charge to all third
4298 parties under the terms of this License.
4301 If the modified program normally reads commands interactively
4302 when run, you must cause it, when started running for such
4303 interactive use in the most ordinary way, to print or display an
4304 announcement including an appropriate copyright notice and a
4305 notice that there is no warranty (or else, saying that you provide
4306 a warranty) and that users may redistribute the program under
4307 these conditions, and telling the user how to view a copy of this
4308 License. (Exception: if the Program itself is interactive but
4309 does not normally print such an announcement, your work based on
4310 the Program is not required to print an announcement.)
4313 These requirements apply to the modified work as a whole. If
4314 identifiable sections of that work are not derived from the Program,
4315 and can be reasonably considered independent and separate works in
4316 themselves, then this License, and its terms, do not apply to those
4317 sections when you distribute them as separate works. But when you
4318 distribute the same sections as part of a whole which is a work based
4319 on the Program, the distribution of the whole must be on the terms of
4320 this License, whose permissions for other licensees extend to the
4321 entire whole, and thus to each and every part regardless of who wrote it.
4323 Thus, it is not the intent of this section to claim rights or contest
4324 your rights to work written entirely by you; rather, the intent is to
4325 exercise the right to control the distribution of derivative or
4326 collective works based on the Program.
4328 In addition, mere aggregation of another work not based on the Program
4329 with the Program (or with a work based on the Program) on a volume of
4330 a storage or distribution medium does not bring the other work under
4331 the scope of this License.
4334 You may copy and distribute the Program (or a work based on it,
4335 under Section 2) in object code or executable form under the terms of
4336 Sections 1 and 2 above provided that you also do one of the following:
4340 Accompany it with the complete corresponding machine-readable
4341 source code, which must be distributed under the terms of Sections
4342 1 and 2 above on a medium customarily used for software interchange; or,
4345 Accompany it with a written offer, valid for at least three
4346 years, to give any third party, for a charge no more than your
4347 cost of physically performing source distribution, a complete
4348 machine-readable copy of the corresponding source code, to be
4349 distributed under the terms of Sections 1 and 2 above on a medium
4350 customarily used for software interchange; or,
4353 Accompany it with the information you received as to the offer
4354 to distribute corresponding source code. (This alternative is
4355 allowed only for noncommercial distribution and only if you
4356 received the program in object code or executable form with such
4357 an offer, in accord with Subsection b above.)
4360 The source code for a work means the preferred form of the work for
4361 making modifications to it. For an executable work, complete source
4362 code means all the source code for all modules it contains, plus any
4363 associated interface definition files, plus the scripts used to
4364 control compilation and installation of the executable. However, as a
4365 special exception, the source code distributed need not include
4366 anything that is normally distributed (in either source or binary
4367 form) with the major components (compiler, kernel, and so on) of the
4368 operating system on which the executable runs, unless that component
4369 itself accompanies the executable.
4371 If distribution of executable or object code is made by offering
4372 access to copy from a designated place, then offering equivalent
4373 access to copy the source code from the same place counts as
4374 distribution of the source code, even though third parties are not
4375 compelled to copy the source along with the object code.
4378 You may not copy, modify, sublicense, or distribute the Program
4379 except as expressly provided under this License. Any attempt
4380 otherwise to copy, modify, sublicense or distribute the Program is
4381 void, and will automatically terminate your rights under this License.
4382 However, parties who have received copies, or rights, from you under
4383 this License will not have their licenses terminated so long as such
4384 parties remain in full compliance.
4387 You are not required to accept this License, since you have not
4388 signed it. However, nothing else grants you permission to modify or
4389 distribute the Program or its derivative works. These actions are
4390 prohibited by law if you do not accept this License. Therefore, by
4391 modifying or distributing the Program (or any work based on the
4392 Program), you indicate your acceptance of this License to do so, and
4393 all its terms and conditions for copying, distributing or modifying
4394 the Program or works based on it.
4397 Each time you redistribute the Program (or any work based on the
4398 Program), the recipient automatically receives a license from the
4399 original licensor to copy, distribute or modify the Program subject to
4400 these terms and conditions. You may not impose any further
4401 restrictions on the recipients' exercise of the rights granted herein.
4402 You are not responsible for enforcing compliance by third parties to
4406 If, as a consequence of a court judgment or allegation of patent
4407 infringement or for any other reason (not limited to patent issues),
4408 conditions are imposed on you (whether by court order, agreement or
4409 otherwise) that contradict the conditions of this License, they do not
4410 excuse you from the conditions of this License. If you cannot
4411 distribute so as to satisfy simultaneously your obligations under this
4412 License and any other pertinent obligations, then as a consequence you
4413 may not distribute the Program at all. For example, if a patent
4414 license would not permit royalty-free redistribution of the Program by
4415 all those who receive copies directly or indirectly through you, then
4416 the only way you could satisfy both it and this License would be to
4417 refrain entirely from distribution of the Program.
4419 If any portion of this section is held invalid or unenforceable under
4420 any particular circumstance, the balance of the section is intended to
4421 apply and the section as a whole is intended to apply in other
4424 It is not the purpose of this section to induce you to infringe any
4425 patents or other property right claims or to contest validity of any
4426 such claims; this section has the sole purpose of protecting the
4427 integrity of the free software distribution system, which is
4428 implemented by public license practices. Many people have made
4429 generous contributions to the wide range of software distributed
4430 through that system in reliance on consistent application of that
4431 system; it is up to the author/donor to decide if he or she is willing
4432 to distribute software through any other system and a licensee cannot
4435 This section is intended to make thoroughly clear what is believed to
4436 be a consequence of the rest of this License.
4439 If the distribution and/or use of the Program is restricted in
4440 certain countries either by patents or by copyrighted interfaces, the
4441 original copyright holder who places the Program under this License
4442 may add an explicit geographical distribution limitation excluding
4443 those countries, so that distribution is permitted only in or among
4444 countries not thus excluded. In such case, this License incorporates
4445 the limitation as if written in the body of this License.
4448 The Free Software Foundation may publish revised and/or new versions
4449 of the General Public License from time to time. Such new versions will
4450 be similar in spirit to the present version, but may differ in detail to
4451 address new problems or concerns.
4453 Each version is given a distinguishing version number. If the Program
4454 specifies a version number of this License which applies to it and ``any
4455 later version'', you have the option of following the terms and conditions
4456 either of that version or of any later version published by the Free
4457 Software Foundation. If the Program does not specify a version number of
4458 this License, you may choose any version ever published by the Free Software
4462 If you wish to incorporate parts of the Program into other free
4463 programs whose distribution conditions are different, write to the author
4464 to ask for permission. For software which is copyrighted by the Free
4465 Software Foundation, write to the Free Software Foundation; we sometimes
4466 make exceptions for this. Our decision will be guided by the two goals
4467 of preserving the free status of all derivatives of our free software and
4468 of promoting the sharing and reuse of software generally.
4471 @heading NO WARRANTY
4478 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
4479 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
4480 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
4481 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
4482 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
4483 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
4484 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
4485 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
4486 REPAIR OR CORRECTION.
4489 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
4490 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
4491 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
4492 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
4493 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
4494 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
4495 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
4496 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
4497 POSSIBILITY OF SUCH DAMAGES.
4501 @heading END OF TERMS AND CONDITIONS
4504 @center END OF TERMS AND CONDITIONS
4508 @unnumberedsec How to Apply These Terms to Your New Programs
4510 If you develop a new program, and you want it to be of the greatest
4511 possible use to the public, the best way to achieve this is to make it
4512 free software which everyone can redistribute and change under these terms.
4514 To do so, attach the following notices to the program. It is safest
4515 to attach them to the start of each source file to most effectively
4516 convey the exclusion of warranty; and each file should have at least
4517 the ``copyright'' line and a pointer to where the full notice is found.
4520 @var{one line to give the program's name and a brief idea of what it does.}
4521 Copyright (C) @var{yyyy} @var{name of author}
4523 This program is free software; you can redistribute it and/or modify
4524 it under the terms of the GNU General Public License as published by
4525 the Free Software Foundation; either version 2 of the License, or
4526 (at your option) any later version.
4528 This program is distributed in the hope that it will be useful,
4529 but WITHOUT ANY WARRANTY; without even the implied warranty of
4530 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4531 GNU General Public License for more details.
4533 You should have received a copy of the GNU General Public License
4534 along with this program; if not, write to the Free Software
4535 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
4538 Also add information on how to contact you by electronic and paper mail.
4540 If the program is interactive, make it output a short notice like this
4541 when it starts in an interactive mode:
4544 Gnomovision version 69, Copyright (C) @var{yyyy} @var{name of author}
4545 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
4547 This is free software, and you are welcome to redistribute it
4548 under certain conditions; type `show c' for details.
4551 The hypothetical commands @samp{show w} and @samp{show c} should show
4552 the appropriate parts of the General Public License. Of course, the
4553 commands you use may be called something other than @samp{show w} and
4554 @samp{show c}; they could even be mouse-clicks or menu items---whatever
4557 You should also get your employer (if you work as a programmer) or your
4558 school, if any, to sign a ``copyright disclaimer'' for the program, if
4559 necessary. Here is a sample; alter the names:
4562 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
4563 `Gnomovision' (which makes passes at compilers) written by James Hacker.
4565 @var{signature of Ty Coon}, 1 April 1989
4566 Ty Coon, President of Vice
4569 This General Public License does not permit incorporating your program into
4570 proprietary programs. If your program is a subroutine library, you may
4571 consider it more useful to permit linking proprietary applications with the
4572 library. If this is what you want to do, use the GNU Library General
4573 Public License instead of this License.
4576 @unnumbered Contributors to GCC
4577 @cindex contributors
4579 In addition to Richard Stallman, several people have written parts
4584 The idea of using RTL and some of the optimization ideas came from the
4585 program PO written at the University of Arizona by Jack Davidson and
4586 Christopher Fraser. See ``Register Allocation and Exhaustive Peephole
4587 Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
4591 Paul Rubin wrote most of the preprocessor.
4594 Leonard Tower wrote parts of the parser, RTL generator, and RTL
4595 definitions, and of the Vax machine description.
4598 Ted Lemon wrote parts of the RTL reader and printer.
4601 Jim Wilson implemented loop strength reduction and some other
4605 Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
4606 the support for the Sony NEWS machine.
4609 Charles LaBrec contributed the support for the Integrated Solutions
4613 Michael Tiemann of Cygnus Support wrote the front end for C++, as well
4614 as the support for inline functions and instruction scheduling. Also
4615 the descriptions of the National Semiconductor 32000 series cpu, the
4616 SPARC cpu and part of the Motorola 88000 cpu.
4619 Gerald Baumgartner added the signature extension to the C++ front-end.
4622 Jan Stein of the Chalmers Computer Society provided support for
4623 Genix, as well as part of the 32000 machine description.
4626 Randy Smith finished the Sun FPA support.
4629 Robert Brown implemented the support for Encore 32000 systems.
4632 David Kashtan of SRI adapted GCC to VMS.
4635 Alex Crain provided changes for the 3b1.
4638 Greg Satz and Chris Hanson assisted in making GCC work on HP-UX for
4639 the 9000 series 300.
4642 William Schelter did most of the work on the Intel 80386 support.
4645 Christopher Smith did the port for Convex machines.
4648 Paul Petersen wrote the machine description for the Alliant FX/8.
4651 Dario Dariol contributed the four varieties of sample programs
4652 that print a copy of their source.
4655 Alain Lichnewsky ported GCC to the Mips cpu.
4658 Devon Bowen, Dale Wiles and Kevin Zachmann ported GCC to the Tahoe.
4661 Jonathan Stone wrote the machine description for the Pyramid computer.
4664 Gary Miller ported GCC to Charles River Data Systems machines.
4667 Richard Kenner of the New York University Ultracomputer Research
4668 Laboratory wrote the machine descriptions for the AMD 29000, the DEC
4669 Alpha, the IBM RT PC, and the IBM RS/6000 as well as the support for
4670 instruction attributes. He also made changes to better support RISC
4671 processors including changes to common subexpression elimination,
4672 strength reduction, function calling sequence handling, and condition
4673 code support, in addition to generalizing the code for frame pointer
4677 Richard Kenner and Michael Tiemann jointly developed reorg.c, the delay
4681 Mike Meissner and Tom Wood of Data General finished the port to the
4685 Masanobu Yuhara of Fujitsu Laboratories implemented the machine
4686 description for the Tron architecture (specifically, the Gmicro).
4689 NeXT, Inc.@: donated the front end that supports the Objective C
4691 @c We need to be careful to make it clear that "Objective C"
4692 @c is the name of a language, not that of a program or product.
4695 James van Artsdalen wrote the code that makes efficient use of
4696 the Intel 80387 register stack.
4699 Mike Meissner at the Open Software Foundation finished the port to the
4700 MIPS cpu, including adding ECOFF debug support, and worked on the
4701 Intel port for the Intel 80386 cpu. Later at Cygnus Support, he worked
4702 on the rs6000 and PowerPC ports.
4705 Ron Guilmette implemented the @code{protoize} and @code{unprotoize}
4706 tools, the support for Dwarf symbolic debugging information, and much of
4707 the support for System V Release 4. He has also worked heavily on the
4708 Intel 386 and 860 support.
4711 Torbjorn Granlund implemented multiply- and divide-by-constant
4712 optimization, improved long long support, and improved leaf function
4713 register allocation.
4716 Mike Stump implemented the support for Elxsi 64 bit CPU.
4719 John Wehle added the machine description for the Western Electric 32000
4720 processor used in several 3b series machines (no relation to the
4721 National Semiconductor 32000 processor).
4723 @ignore @c These features aren't advertised yet, since they don't fully work.
4725 Analog Devices helped implement the support for complex data types
4730 Holger Teutsch provided the support for the Clipper cpu.
4733 Kresten Krab Thorup wrote the run time support for the Objective C
4737 Stephen Moshier contributed the floating point emulator that assists in
4738 cross-compilation and permits support for floating point numbers wider
4742 David Edelsohn contributed the changes to RS/6000 port to make it
4743 support the PowerPC and POWER2 architectures.
4746 Steve Chamberlain wrote the support for the Hitachi SH processor.
4749 Peter Schauer wrote the code to allow debugging to work on the Alpha.
4752 Oliver M. Kellogg of Deutsche Aerospace contributed the port to the
4756 Michael K. Gschwind contributed the port to the PDP-11.
4759 David Reese of Sun Microsystems contributed to the Solaris on PowerPC