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 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.96@*
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.96.
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.96.
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.96.
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} or @samp{bug-gcc@@gnu.org}.
2263 Please read @samp{<URL:http://www.gnu.org/software/gcc/faq.html#bugreport>} for
2264 bug reporting instructions before you post a bug report.
2266 Often people think of posting bug reports to the newsgroup instead of
2267 mailing them. This appears to work, but it has one problem which can be
2268 crucial: a newsgroup posting does not contain a mail path back to the
2269 sender. Thus, if maintainers need more information, they may be unable
2270 to reach you. For this reason, you should always send bug reports by
2271 mail to the proper mailing list.
2273 As a last resort, send bug reports on paper to:
2277 Free Software Foundation
2278 59 Temple Place - Suite 330
2279 Boston, MA 02111-1307, USA
2283 @section How to Report Bugs
2284 @cindex compiler bugs, reporting
2286 You may find additional and/or more up-to-date instructions at
2287 @samp{<URL:http://www.gnu.org/software/gcc/faq.html#bugreport>}.
2289 The fundamental principle of reporting bugs usefully is this:
2290 @strong{report all the facts}. If you are not sure whether to state a
2291 fact or leave it out, state it!
2293 Often people omit facts because they think they know what causes the
2294 problem and they conclude that some details don't matter. Thus, you might
2295 assume that the name of the variable you use in an example does not matter.
2296 Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
2297 stray memory reference which happens to fetch from the location where that
2298 name is stored in memory; perhaps, if the name were different, the contents
2299 of that location would fool the compiler into doing the right thing despite
2300 the bug. Play it safe and give a specific, complete example. That is the
2301 easiest thing for you to do, and the most helpful.
2303 Keep in mind that the purpose of a bug report is to enable someone to
2304 fix the bug if it is not known. It isn't very important what happens if
2305 the bug is already known. Therefore, always write your bug reports on
2306 the assumption that the bug is not known.
2308 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2309 bell?'' This cannot help us fix a bug, so it is basically useless. We
2310 respond by asking for enough details to enable us to investigate.
2311 You might as well expedite matters by sending them to begin with.
2313 Try to make your bug report self-contained. If we have to ask you for
2314 more information, it is best if you include all the previous information
2315 in your response, as well as the information that was missing.
2317 Please report each bug in a separate message. This makes it easier for
2318 us to track which bugs have been fixed and to forward your bugs reports
2319 to the appropriate maintainer.
2321 To enable someone to investigate the bug, you should include all these
2326 The version of GCC. You can get this by running it with the
2329 Without this, we won't know whether there is any point in looking for
2330 the bug in the current version of GCC.
2333 A complete input file that will reproduce the bug. If the bug is in the
2334 C preprocessor, send a source file and any header files that it
2335 requires. If the bug is in the compiler proper (@file{cc1}), send the
2336 preprocessor output generated by adding @samp{-save-temps} to the
2337 compilation command (@pxref{Debugging Options}). When you do this, use
2338 the same @samp{-I}, @samp{-D} or @samp{-U} options that you used in
2339 actual compilation. Then send the @var{input}.i or @var{input}.ii files
2342 A single statement is not enough of an example. In order to compile it,
2343 it must be embedded in a complete file of compiler input; and the bug
2344 might depend on the details of how this is done.
2346 Without a real example one can compile, all anyone can do about your bug
2347 report is wish you luck. It would be futile to try to guess how to
2348 provoke the bug. For example, bugs in register allocation and reloading
2349 frequently depend on every little detail of the function they happen in.
2351 Even if the input file that fails comes from a GNU program, you should
2352 still send the complete test case. Don't ask the GCC maintainers to
2353 do the extra work of obtaining the program in question---they are all
2354 overworked as it is. Also, the problem may depend on what is in the
2355 header files on your system; it is unreliable for the GCC maintainers
2356 to try the problem with the header files available to them. By sending
2357 CPP output, you can eliminate this source of uncertainty and save us
2358 a certain percentage of wild goose chases.
2361 The command arguments you gave GCC to compile that example
2362 and observe the bug. For example, did you use @samp{-O}? To guarantee
2363 you won't omit something important, list all the options.
2365 If we were to try to guess the arguments, we would probably guess wrong
2366 and then we would not encounter the bug.
2369 The type of machine you are using, and the operating system name and
2373 The operands you gave to the @code{configure} command when you installed
2377 A complete list of any modifications you have made to the compiler
2378 source. (We don't promise to investigate the bug unless it happens in
2379 an unmodified compiler. But if you've made modifications and don't tell
2380 us, then you are sending us on a wild goose chase.)
2382 Be precise about these changes. A description in English is not
2383 enough---send a context diff for them.
2385 Adding files of your own (such as a machine description for a machine we
2386 don't support) is a modification of the compiler source.
2389 Details of any other deviations from the standard procedure for installing
2393 A description of what behavior you observe that you believe is
2394 incorrect. For example, ``The compiler gets a fatal signal,'' or,
2395 ``The assembler instruction at line 208 in the output is incorrect.''
2397 Of course, if the bug is that the compiler gets a fatal signal, then one
2398 can't miss it. But if the bug is incorrect output, the maintainer might
2399 not notice unless it is glaringly wrong. None of us has time to study
2400 all the assembler code from a 50-line C program just on the chance that
2401 one instruction might be wrong. We need @emph{you} to do this part!
2403 Even if the problem you experience is a fatal signal, you should still
2404 say so explicitly. Suppose something strange is going on, such as, your
2405 copy of the compiler is out of synch, or you have encountered a bug in
2406 the C library on your system. (This has happened!) Your copy might
2407 crash and the copy here would not. If you @i{said} to expect a crash,
2408 then when the compiler here fails to crash, we would know that the bug
2409 was not happening. If you don't say to expect a crash, then we would
2410 not know whether the bug was happening. We would not be able to draw
2411 any conclusion from our observations.
2413 If the problem is a diagnostic when compiling GCC with some other
2414 compiler, say whether it is a warning or an error.
2416 Often the observed symptom is incorrect output when your program is run.
2417 Sad to say, this is not enough information unless the program is short
2418 and simple. None of us has time to study a large program to figure out
2419 how it would work if compiled correctly, much less which line of it was
2420 compiled wrong. So you will have to do that. Tell us which source line
2421 it is, and what incorrect result happens when that line is executed. A
2422 person who understands the program can find this as easily as finding a
2423 bug in the program itself.
2426 If you send examples of assembler code output from GCC,
2427 please use @samp{-g} when you make them. The debugging information
2428 includes source line numbers which are essential for correlating the
2429 output with the input.
2432 If you wish to mention something in the GCC source, refer to it by
2433 context, not by line number.
2435 The line numbers in the development sources don't match those in your
2436 sources. Your line numbers would convey no useful information to the
2440 Additional information from a debugger might enable someone to find a
2441 problem on a machine which he does not have available. However, you
2442 need to think when you collect this information if you want it to have
2443 any chance of being useful.
2445 @cindex backtrace for bug reports
2446 For example, many people send just a backtrace, but that is never
2447 useful by itself. A simple backtrace with arguments conveys little
2448 about GCC because the compiler is largely data-driven; the same
2449 functions are called over and over for different RTL insns, doing
2450 different things depending on the details of the insn.
2452 Most of the arguments listed in the backtrace are useless because they
2453 are pointers to RTL list structure. The numeric values of the
2454 pointers, which the debugger prints in the backtrace, have no
2455 significance whatever; all that matters is the contents of the objects
2456 they point to (and most of the contents are other such pointers).
2458 In addition, most compiler passes consist of one or more loops that
2459 scan the RTL insn sequence. The most vital piece of information about
2460 such a loop---which insn it has reached---is usually in a local variable,
2464 What you need to provide in addition to a backtrace are the values of
2465 the local variables for several stack frames up. When a local
2466 variable or an argument is an RTX, first print its value and then use
2467 the GDB command @code{pr} to print the RTL expression that it points
2468 to. (If GDB doesn't run on your machine, use your debugger to call
2469 the function @code{debug_rtx} with the RTX as an argument.) In
2470 general, whenever a variable is a pointer, its value is no use
2471 without the data it points to.
2474 Here are some things that are not necessary:
2478 A description of the envelope of the bug.
2480 Often people who encounter a bug spend a lot of time investigating
2481 which changes to the input file will make the bug go away and which
2482 changes will not affect it.
2484 This is often time consuming and not very useful, because the way we
2485 will find the bug is by running a single example under the debugger with
2486 breakpoints, not by pure deduction from a series of examples. You might
2487 as well save your time for something else.
2489 Of course, if you can find a simpler example to report @emph{instead} of
2490 the original one, that is a convenience. Errors in the output will be
2491 easier to spot, running under the debugger will take less time, etc.
2492 Most GCC bugs involve just one function, so the most straightforward
2493 way to simplify an example is to delete all the function definitions
2494 except the one where the bug occurs. Those earlier in the file may be
2495 replaced by external declarations if the crucial function depends on
2496 them. (Exception: inline functions may affect compilation of functions
2497 defined later in the file.)
2499 However, simplification is not vital; if you don't want to do this,
2500 report the bug anyway and send the entire test case you used.
2503 In particular, some people insert conditionals @samp{#ifdef BUG} around
2504 a statement which, if removed, makes the bug not happen. These are just
2505 clutter; we won't pay any attention to them anyway. Besides, you should
2506 send us cpp output, and that can't have conditionals.
2509 A patch for the bug.
2511 A patch for the bug is useful if it is a good one. But don't omit the
2512 necessary information, such as the test case, on the assumption that a
2513 patch is all we need. We might see problems with your patch and decide
2514 to fix the problem another way, or we might not understand it at all.
2516 Sometimes with a program as complicated as GCC it is very hard to
2517 construct an example that will make the program follow a certain path
2518 through the code. If you don't send the example, we won't be able to
2519 construct one, so we won't be able to verify that the bug is fixed.
2521 And if we can't understand what bug you are trying to fix, or why your
2522 patch should be an improvement, we won't install it. A test case will
2523 help us to understand.
2525 @xref{Sending Patches}, for guidelines on how to make it easy for us to
2526 understand and install your patches.
2529 A guess about what the bug is or what it depends on.
2531 Such guesses are usually wrong. Even I can't guess right about such
2532 things without first using the debugger to find the facts.
2537 We have no way of examining a core dump for your type of machine
2538 unless we have an identical system---and if we do have one,
2539 we should be able to reproduce the crash ourselves.
2542 @node Sending Patches,, Bug Reporting, Bugs
2543 @section Sending Patches for GCC
2545 If you would like to write bug fixes or improvements for the GNU C
2546 compiler, that is very helpful. Send suggested fixes to the patches
2547 mailing list, @code{gcc-patches@@gcc.gnu.org}.
2549 Please follow these guidelines so we can study your patches efficiently.
2550 If you don't follow these guidelines, your information might still be
2551 useful, but using it will take extra work. Maintaining GNU C is a lot
2552 of work in the best of circumstances, and we can't keep up unless you do
2557 Send an explanation with your changes of what problem they fix or what
2558 improvement they bring about. For a bug fix, just include a copy of the
2559 bug report, and explain why the change fixes the bug.
2561 (Referring to a bug report is not as good as including it, because then
2562 we will have to look it up, and we have probably already deleted it if
2563 we've already fixed the bug.)
2566 Always include a proper bug report for the problem you think you have
2567 fixed. We need to convince ourselves that the change is right before
2568 installing it. Even if it is right, we might have trouble judging it if
2569 we don't have a way to reproduce the problem.
2572 Include all the comments that are appropriate to help people reading the
2573 source in the future understand why this change was needed.
2576 Don't mix together changes made for different reasons.
2577 Send them @emph{individually}.
2579 If you make two changes for separate reasons, then we might not want to
2580 install them both. We might want to install just one. If you send them
2581 all jumbled together in a single set of diffs, we have to do extra work
2582 to disentangle them---to figure out which parts of the change serve
2583 which purpose. If we don't have time for this, we might have to ignore
2584 your changes entirely.
2586 If you send each change as soon as you have written it, with its own
2587 explanation, then the two changes never get tangled up, and we can
2588 consider each one properly without any extra work to disentangle them.
2590 Ideally, each change you send should be impossible to subdivide into
2591 parts that we might want to consider separately, because each of its
2592 parts gets its motivation from the other parts.
2595 Send each change as soon as that change is finished. Sometimes people
2596 think they are helping us by accumulating many changes to send them all
2597 together. As explained above, this is absolutely the worst thing you
2600 Since you should send each change separately, you might as well send it
2601 right away. That gives us the option of installing it immediately if it
2605 Use @samp{diff -c} to make your diffs. Diffs without context are hard
2606 for us to install reliably. More than that, they make it hard for us to
2607 study the diffs to decide whether we want to install them. Unidiff
2608 format is better than contextless diffs, but not as easy to read as
2611 If you have GNU diff, use @samp{diff -cp}, which shows the name of the
2612 function that each change occurs in.
2615 Write the change log entries for your changes. We get lots of changes,
2616 and we don't have time to do all the change log writing ourselves.
2618 Read the @file{ChangeLog} file to see what sorts of information to put
2619 in, and to learn the style that we use. The purpose of the change log
2620 is to show people where to find what was changed. So you need to be
2621 specific about what functions you changed; in large functions, it's
2622 often helpful to indicate where within the function the change was.
2624 On the other hand, once you have shown people where to find the change,
2625 you need not explain its purpose. Thus, if you add a new function, all
2626 you need to say about it is that it is new. If you feel that the
2627 purpose needs explaining, it probably does---but the explanation will be
2628 much more useful if you put it in comments in the code.
2630 If you would like your name to appear in the header line for who made
2631 the change, send us the header line.
2634 When you write the fix, keep in mind that we can't install a change that
2635 would break other systems.
2637 People often suggest fixing a problem by changing machine-independent
2638 files such as @file{toplev.c} to do something special that a particular
2639 system needs. Sometimes it is totally obvious that such changes would
2640 break GCC for almost all users. We can't possibly make a change like
2641 that. At best it might tell us how to write another patch that would
2642 solve the problem acceptably.
2644 Sometimes people send fixes that @emph{might} be an improvement in
2645 general---but it is hard to be sure of this. It's hard to install
2646 such changes because we have to study them very carefully. Of course,
2647 a good explanation of the reasoning by which you concluded the change
2648 was correct can help convince us.
2650 The safest changes are changes to the configuration files for a
2651 particular machine. These are safe because they can't create new bugs
2654 Please help us keep up with the workload by designing the patch in a
2655 form that is good to install.
2659 @chapter How To Get Help with GCC
2661 If you need help installing, using or changing GCC, there are two
2666 Send a message to a suitable network mailing list. First try
2667 @code{gcc-bugs@@gcc.gnu.org} or @code{bug-gcc@@gnu.org}, and if that
2668 brings no response, try @code{gcc@@gcc.gnu.org}.
2671 Look in the service directory for someone who might help you for a fee.
2672 The service directory is found in the file named @file{SERVICE} in the
2677 @chapter Contributing to GCC Development
2679 If you would like to help pretest GCC releases to assure they work
2680 well, or if you would like to work on improving GCC, please contact
2681 the maintainers at @code{egcs@@egcs.cygnus.com}. A pretester should
2682 be willing to try to investigate bugs as well as report them.
2684 If you'd like to work on improvements, please ask for suggested projects
2685 or suggest your own ideas. If you have already written an improvement,
2686 please tell us about it. If you have not yet started work, it is useful
2687 to contact @code{egcs@@egcs.cygnus.com} before you start; the
2688 maintainers may be able to suggest ways to make your extension fit in
2689 better with the rest of GCC and with other development plans.
2692 @chapter Using GCC on VMS
2694 @c prevent bad page break with this line
2695 Here is how to use GCC on VMS.
2698 * Include Files and VMS:: Where the preprocessor looks for the include files.
2699 * Global Declarations:: How to do globaldef, globalref and globalvalue with
2701 * VMS Misc:: Misc information.
2704 @node Include Files and VMS
2705 @section Include Files and VMS
2707 @cindex include files and VMS
2708 @cindex VMS and include files
2709 @cindex header files and VMS
2710 Due to the differences between the filesystems of Unix and VMS, GCC
2711 attempts to translate file names in @samp{#include} into names that VMS
2712 will understand. The basic strategy is to prepend a prefix to the
2713 specification of the include file, convert the whole filename to a VMS
2714 filename, and then try to open the file. GCC tries various prefixes
2715 one by one until one of them succeeds:
2719 The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
2720 where GNU C header files are traditionally stored. If you wish to store
2721 header files in non-standard locations, then you can assign the logical
2722 @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
2723 list is suitable for use with a rooted logical.
2726 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where
2727 VAX-C header files are traditionally stored.
2730 If the include file specification by itself is a valid VMS filename, the
2731 preprocessor then uses this name with no prefix in an attempt to open
2735 If the file specification is not a valid VMS filename (i.e. does not
2736 contain a device or a directory specifier, and contains a @samp{/}
2737 character), the preprocessor tries to convert it from Unix syntax to
2740 Conversion works like this: the first directory name becomes a device,
2741 and the rest of the directories are converted into VMS-format directory
2742 names. For example, the name @file{X11/foobar.h} is
2743 translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
2744 whichever one can be opened. This strategy allows you to assign a
2745 logical name to point to the actual location of the header files.
2748 If none of these strategies succeeds, the @samp{#include} fails.
2751 Include directives of the form:
2758 are a common source of incompatibility between VAX-C and GCC. VAX-C
2759 treats this much like a standard @code{#include <foobar.h>} directive.
2760 That is incompatible with the ANSI C behavior implemented by GCC: to
2761 expand the name @code{foobar} as a macro. Macro expansion should
2762 eventually yield one of the two standard formats for @code{#include}:
2765 #include "@var{file}"
2766 #include <@var{file}>
2769 If you have this problem, the best solution is to modify the source to
2770 convert the @code{#include} directives to one of the two standard forms.
2771 That will work with either compiler. If you want a quick and dirty fix,
2772 define the file names as macros with the proper expansion, like this:
2775 #define stdio <stdio.h>
2779 This will work, as long as the name doesn't conflict with anything else
2782 Another source of incompatibility is that VAX-C assumes that:
2789 is actually asking for the file @file{foobar.h}. GCC does not
2790 make this assumption, and instead takes what you ask for literally;
2791 it tries to read the file @file{foobar}. The best way to avoid this
2792 problem is to always specify the desired file extension in your include
2795 GCC for VMS is distributed with a set of include files that is
2796 sufficient to compile most general purpose programs. Even though the
2797 GCC distribution does not contain header files to define constants
2798 and structures for some VMS system-specific functions, there is no
2799 reason why you cannot use GCC with any of these functions. You first
2800 may have to generate or create header files, either by using the public
2801 domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
2802 extracting the relevant modules from one of the system macro libraries,
2803 and using an editor to construct a C header file.
2805 A @code{#include} file name cannot contain a DECNET node name. The
2806 preprocessor reports an I/O error if you attempt to use a node name,
2807 whether explicitly, or implicitly via a logical name.
2809 @node Global Declarations
2810 @section Global Declarations and VMS
2814 @findex GLOBALVALUEDEF
2815 @findex GLOBALVALUEREF
2816 GCC does not provide the @code{globalref}, @code{globaldef} and
2817 @code{globalvalue} keywords of VAX-C. You can get the same effect with
2818 an obscure feature of GAS, the GNU assembler. (This requires GAS
2819 version 1.39 or later.) The following macros allow you to use this
2820 feature in a fairly natural way:
2824 #define GLOBALREF(TYPE,NAME) \
2826 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
2827 #define GLOBALDEF(TYPE,NAME,VALUE) \
2829 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
2831 #define GLOBALVALUEREF(TYPE,NAME) \
2832 const TYPE NAME[1] \
2833 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
2834 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2835 const TYPE NAME[1] \
2836 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \
2839 #define GLOBALREF(TYPE,NAME) \
2841 #define GLOBALDEF(TYPE,NAME,VALUE) \
2842 globaldef TYPE NAME = VALUE
2843 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2844 globalvalue TYPE NAME = VALUE
2845 #define GLOBALVALUEREF(TYPE,NAME) \
2846 globalvalue TYPE NAME
2851 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
2852 name is removed by the assembler, after it has modified the attributes
2853 of the symbol). These macros are provided in the VMS binaries
2854 distribution in a header file @file{GNU_HACKS.H}. An example of the
2858 GLOBALREF (int, ijk);
2859 GLOBALDEF (int, jkl, 0);
2862 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
2863 straightforwardly for arrays, since there is no way to insert the array
2864 dimension into the declaration at the right place. However, you can
2865 declare an array with these macros if you first define a typedef for the
2866 array type, like this:
2869 typedef int intvector[10];
2870 GLOBALREF (intvector, foo);
2873 Array and structure initializers will also break the macros; you can
2874 define the initializer to be a macro of its own, or you can expand the
2875 @code{GLOBALDEF} macro by hand. You may find a case where you wish to
2876 use the @code{GLOBALDEF} macro with a large array, but you are not
2877 interested in explicitly initializing each element of the array. In
2878 such cases you can use an initializer like: @code{@{0,@}}, which will
2879 initialize the entire array to @code{0}.
2881 A shortcoming of this implementation is that a variable declared with
2882 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For
2883 example, the declaration:
2886 GLOBALVALUEREF(int, ijk);
2890 declares the variable @code{ijk} as an array of type @code{int [1]}.
2891 This is done because a globalvalue is actually a constant; its ``value''
2892 is what the linker would normally consider an address. That is not how
2893 an integer value works in C, but it is how an array works. So treating
2894 the symbol as an array name gives consistent results---with the
2895 exception that the value seems to have the wrong type. @strong{Don't
2896 try to access an element of the array.} It doesn't have any elements.
2897 The array ``address'' may not be the address of actual storage.
2899 The fact that the symbol is an array may lead to warnings where the
2900 variable is used. Insert type casts to avoid the warnings. Here is an
2901 example; it takes advantage of the ANSI C feature allowing macros that
2902 expand to use the same name as the macro itself.
2905 GLOBALVALUEREF (int, ss$_normal);
2906 GLOBALVALUEDEF (int, xyzzy,123);
2908 #define ss$_normal ((int) ss$_normal)
2909 #define xyzzy ((int) xyzzy)
2913 Don't use @code{globaldef} or @code{globalref} with a variable whose
2914 type is an enumeration type; this is not implemented. Instead, make the
2915 variable an integer, and use a @code{globalvaluedef} for each of the
2916 enumeration values. An example of this would be:
2920 GLOBALDEF (int, color, 0);
2921 GLOBALVALUEDEF (int, RED, 0);
2922 GLOBALVALUEDEF (int, BLUE, 1);
2923 GLOBALVALUEDEF (int, GREEN, 3);
2925 enum globaldef color @{RED, BLUE, GREEN = 3@};
2930 @section Other VMS Issues
2932 @cindex exit status and VMS
2933 @cindex return value of @code{main}
2934 @cindex @code{main} and the exit status
2935 GCC automatically arranges for @code{main} to return 1 by default if
2936 you fail to specify an explicit return value. This will be interpreted
2937 by VMS as a status code indicating a normal successful completion.
2938 Version 1 of GCC did not provide this default.
2940 GCC on VMS works only with the GNU assembler, GAS. You need version
2941 1.37 or later of GAS in order to produce value debugging information for
2942 the VMS debugger. Use the ordinary VMS linker with the object files
2945 @cindex shared VMS run time system
2946 @cindex @file{VAXCRTL}
2947 Under previous versions of GCC, the generated code would occasionally
2948 give strange results when linked to the sharable @file{VAXCRTL} library.
2949 Now this should work.
2951 A caveat for use of @code{const} global variables: the @code{const}
2952 modifier must be specified in every external declaration of the variable
2953 in all of the source files that use that variable. Otherwise the linker
2954 will issue warnings about conflicting attributes for the variable. Your
2955 program will still work despite the warnings, but the variable will be
2956 placed in writable storage.
2958 @cindex name augmentation
2959 @cindex case sensitivity and VMS
2960 @cindex VMS and case sensitivity
2961 Although the VMS linker does distinguish between upper and lower case
2962 letters in global symbols, most VMS compilers convert all such symbols
2963 into upper case and most run-time library routines also have upper case
2964 names. To be able to reliably call such routines, GCC (by means of
2965 the assembler GAS) converts global symbols into upper case like other
2966 VMS compilers. However, since the usual practice in C is to distinguish
2967 case, GCC (via GAS) tries to preserve usual C behavior by augmenting
2968 each name that is not all lower case. This means truncating the name
2969 to at most 23 characters and then adding more characters at the end
2970 which encode the case pattern of those 23. Names which contain at
2971 least one dollar sign are an exception; they are converted directly into
2972 upper case without augmentation.
2974 Name augmentation yields bad results for programs that use precompiled
2975 libraries (such as Xlib) which were generated by another compiler. You
2976 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
2977 it makes external C functions and variables case-independent as is usual
2978 on VMS. Alternatively, you could write all references to the functions
2979 and variables in such libraries using lower case; this will work on VMS,
2980 but is not portable to other systems. The compiler option @samp{/NAMES}
2981 also provides control over global name handling.
2983 Function and variable names are handled somewhat differently with GNU
2984 C++. The GNU C++ compiler performs @dfn{name mangling} on function
2985 names, which means that it adds information to the function name to
2986 describe the data types of the arguments that the function takes. One
2987 result of this is that the name of a function can become very long.
2988 Since the VMS linker only recognizes the first 31 characters in a name,
2989 special action is taken to ensure that each function and variable has a
2990 unique name that can be represented in 31 characters.
2992 If the name (plus a name augmentation, if required) is less than 32
2993 characters in length, then no special action is performed. If the name
2994 is longer than 31 characters, the assembler (GAS) will generate a
2995 hash string based upon the function name, truncate the function name to
2996 23 characters, and append the hash string to the truncated name. If the
2997 @samp{/VERBOSE} compiler option is used, the assembler will print both
2998 the full and truncated names of each symbol that is truncated.
3000 The @samp{/NOCASE_HACK} compiler option should not be used when you are
3001 compiling programs that use libg++. libg++ has several instances of
3002 objects (i.e. @code{Filebuf} and @code{filebuf}) which become
3003 indistinguishable in a case-insensitive environment. This leads to
3004 cases where you need to inhibit augmentation selectively (if you were
3005 using libg++ and Xlib in the same program, for example). There is no
3006 special feature for doing this, but you can get the result by defining a
3007 macro for each mixed case symbol for which you wish to inhibit
3008 augmentation. The macro should expand into the lower case equivalent of
3009 itself. For example:
3012 #define StuDlyCapS studlycaps
3015 These macro definitions can be placed in a header file to minimize the
3016 number of changes to your source code.
3021 @chapter GCC and Portability
3023 @cindex GCC and portability
3025 The main goal of GCC was to make a good, fast compiler for machines in
3026 the class that the GNU system aims to run on: 32-bit machines that address
3027 8-bit bytes and have several general registers. Elegance, theoretical
3028 power and simplicity are only secondary.
3030 GCC gets most of the information about the target machine from a machine
3031 description which gives an algebraic formula for each of the machine's
3032 instructions. This is a very clean way to describe the target. But when
3033 the compiler needs information that is difficult to express in this
3034 fashion, I have not hesitated to define an ad-hoc parameter to the machine
3035 description. The purpose of portability is to reduce the total work needed
3036 on the compiler; it was not of interest for its own sake.
3039 @cindex autoincrement addressing, availability
3041 GCC does not contain machine dependent code, but it does contain code
3042 that depends on machine parameters such as endianness (whether the most
3043 significant byte has the highest or lowest address of the bytes in a word)
3044 and the availability of autoincrement addressing. In the RTL-generation
3045 pass, it is often necessary to have multiple strategies for generating code
3046 for a particular kind of syntax tree, strategies that are usable for different
3047 combinations of parameters. Often I have not tried to address all possible
3048 cases, but only the common ones or only the ones that I have encountered.
3049 As a result, a new target may require additional strategies. You will know
3050 if this happens because the compiler will call @code{abort}. Fortunately,
3051 the new strategies can be added in a machine-independent fashion, and will
3052 affect only the target machines that need them.
3057 @chapter Interfacing to GCC Output
3058 @cindex interfacing to GCC output
3059 @cindex run-time conventions
3060 @cindex function call conventions
3061 @cindex conventions, run-time
3063 GCC is normally configured to use the same function calling convention
3064 normally in use on the target system. This is done with the
3065 machine-description macros described (@pxref{Target Macros}).
3067 @cindex unions, returning
3068 @cindex structures, returning
3069 @cindex returning structures and unions
3070 However, returning of structure and union values is done differently on
3071 some target machines. As a result, functions compiled with PCC
3072 returning such types cannot be called from code compiled with GCC,
3073 and vice versa. This does not cause trouble often because few Unix
3074 library routines return structures or unions.
3076 GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
3077 long in the same registers used for @code{int} or @code{double} return
3078 values. (GCC typically allocates variables of such types in
3079 registers also.) Structures and unions of other sizes are returned by
3080 storing them into an address passed by the caller (usually in a
3081 register). The machine-description macros @code{STRUCT_VALUE} and
3082 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
3084 By contrast, PCC on most target machines returns structures and unions
3085 of any size by copying the data into an area of static storage, and then
3086 returning the address of that storage as if it were a pointer value.
3087 The caller must copy the data from that memory area to the place where
3088 the value is wanted. This is slower than the method used by GCC, and
3089 fails to be reentrant.
3091 On some target machines, such as RISC machines and the 80386, the
3092 standard system convention is to pass to the subroutine the address of
3093 where to return the value. On these machines, GCC has been
3094 configured to be compatible with the standard compiler, when this method
3095 is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3097 @cindex argument passing
3098 @cindex passing arguments
3099 GCC uses the system's standard convention for passing arguments. On
3100 some machines, the first few arguments are passed in registers; in
3101 others, all are passed on the stack. It would be possible to use
3102 registers for argument passing on any machine, and this would probably
3103 result in a significant speedup. But the result would be complete
3104 incompatibility with code that follows the standard convention. So this
3105 change is practical only if you are switching to GCC as the sole C
3106 compiler for the system. We may implement register argument passing on
3107 certain machines once we have a complete GNU system so that we can
3108 compile the libraries with GCC.
3110 On some machines (particularly the Sparc), certain types of arguments
3111 are passed ``by invisible reference''. This means that the value is
3112 stored in memory, and the address of the memory location is passed to
3115 @cindex @code{longjmp} and automatic variables
3116 If you use @code{longjmp}, beware of automatic variables. ANSI C says that
3117 automatic variables that are not declared @code{volatile} have undefined
3118 values after a @code{longjmp}. And this is all GCC promises to do,
3119 because it is very difficult to restore register variables correctly, and
3120 one of GCC's features is that it can put variables in registers without
3123 If you want a variable to be unaltered by @code{longjmp}, and you don't
3124 want to write @code{volatile} because old C compilers don't accept it,
3125 just take the address of the variable. If a variable's address is ever
3126 taken, even if just to compute it and ignore it, then the variable cannot
3137 @cindex arithmetic libraries
3138 @cindex math libraries
3139 Code compiled with GCC may call certain library routines. Most of
3140 them handle arithmetic for which there are no instructions. This
3141 includes multiply and divide on some machines, and floating point
3142 operations on any machine for which floating point support is disabled
3143 with @samp{-msoft-float}. Some standard parts of the C library, such as
3144 @code{bcopy} or @code{memcpy}, are also called automatically. The usual
3145 function call interface is used for calling the library routines.
3147 These library routines should be defined in the library @file{libgcc.a},
3148 which GCC automatically searches whenever it links a program. On
3149 machines that have multiply and divide instructions, if hardware
3150 floating point is in use, normally @file{libgcc.a} is not needed, but it
3151 is searched just in case.
3153 Each arithmetic function is defined in @file{libgcc1.c} to use the
3154 corresponding C arithmetic operator. As long as the file is compiled
3155 with another C compiler, which supports all the C arithmetic operators,
3156 this file will work portably. However, @file{libgcc1.c} does not work if
3157 compiled with GCC, because each arithmetic function would compile
3158 into a call to itself!
3163 @chapter Passes and Files of the Compiler
3164 @cindex passes and files of the compiler
3165 @cindex files and passes of the compiler
3166 @cindex compiler passes and files
3168 @cindex top level of compiler
3169 The overall control structure of the compiler is in @file{toplev.c}. This
3170 file is responsible for initialization, decoding arguments, opening and
3171 closing files, and sequencing the passes.
3173 @cindex parsing pass
3174 The parsing pass is invoked only once, to parse the entire input. The RTL
3175 intermediate code for a function is generated as the function is parsed, a
3176 statement at a time. Each statement is read in as a syntax tree and then
3177 converted to RTL; then the storage for the tree for the statement is
3178 reclaimed. Storage for types (and the expressions for their sizes),
3179 declarations, and a representation of the binding contours and how they nest,
3180 remain until the function is finished being compiled; these are all needed
3181 to output the debugging information.
3183 @findex rest_of_compilation
3184 @findex rest_of_decl_compilation
3185 Each time the parsing pass reads a complete function definition or
3186 top-level declaration, it calls either the function
3187 @code{rest_of_compilation}, or the function
3188 @code{rest_of_decl_compilation} in @file{toplev.c}, which are
3189 responsible for all further processing necessary, ending with output of
3190 the assembler language. All other compiler passes run, in sequence,
3191 within @code{rest_of_compilation}. When that function returns from
3192 compiling a function definition, the storage used for that function
3193 definition's compilation is entirely freed, unless it is an inline
3196 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3199 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3202 Here is a list of all the passes of the compiler and their source files.
3203 Also included is a description of where debugging dumps can be requested
3204 with @samp{-d} options.
3208 Parsing. This pass reads the entire text of a function definition,
3209 constructing partial syntax trees. This and RTL generation are no longer
3210 truly separate passes (formerly they were), but it is easier to think
3211 of them as separate.
3213 The tree representation does not entirely follow C syntax, because it is
3214 intended to support other languages as well.
3216 Language-specific data type analysis is also done in this pass, and every
3217 tree node that represents an expression has a data type attached.
3218 Variables are represented as declaration nodes.
3220 @cindex constant folding
3221 @cindex arithmetic simplifications
3222 @cindex simplifications, arithmetic
3223 Constant folding and some arithmetic simplifications are also done
3226 The language-independent source files for parsing are
3227 @file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}.
3228 There are also header files @file{tree.h} and @file{tree.def}
3229 which define the format of the tree representation.@refill
3231 @c Avoiding overfull is tricky here.
3232 The source files to parse C are
3236 @file{c-aux-info.c},
3239 along with header files
3243 The source files for parsing C++ are @file{cp-parse.y},
3244 @file{cp-class.c},@*
3245 @file{cp-cvt.c}, @file{cp-decl.c}, @file{cp-decl2.c},
3246 @file{cp-dem.c}, @file{cp-except.c},@*
3247 @file{cp-expr.c}, @file{cp-init.c}, @file{cp-lex.c},
3248 @file{cp-method.c}, @file{cp-ptree.c},@*
3249 @file{cp-search.c}, @file{cp-tree.c}, @file{cp-type2.c}, and
3250 @file{cp-typeck.c}, along with header files @file{cp-tree.def},
3251 @file{cp-tree.h}, and @file{cp-decl.h}.
3253 The special source files for parsing Objective C are
3254 @file{objc-parse.y}, @file{objc-actions.c}, @file{objc-tree.def}, and
3255 @file{objc-actions.h}. Certain C-specific files are used for this as
3258 The file @file{c-common.c} is also used for all of the above languages.
3260 @cindex RTL generation
3262 RTL generation. This is the conversion of syntax tree into RTL code.
3263 It is actually done statement-by-statement during parsing, but for
3264 most purposes it can be thought of as a separate pass.
3266 @cindex target-parameter-dependent code
3267 This is where the bulk of target-parameter-dependent code is found,
3268 since often it is necessary for strategies to apply only when certain
3269 standard kinds of instructions are available. The purpose of named
3270 instruction patterns is to provide this information to the RTL
3273 @cindex tail recursion optimization
3274 Optimization is done in this pass for @code{if}-conditions that are
3275 comparisons, boolean operations or conditional expressions. Tail
3276 recursion is detected at this time also. Decisions are made about how
3277 best to arrange loops and how to output @code{switch} statements.
3279 @c Avoiding overfull is tricky here.
3280 The source files for RTL generation include
3288 and @file{emit-rtl.c}.
3290 @file{insn-emit.c}, generated from the machine description by the
3291 program @code{genemit}, is used in this pass. The header file
3292 @file{expr.h} is used for communication within this pass.@refill
3296 The header files @file{insn-flags.h} and @file{insn-codes.h},
3297 generated from the machine description by the programs @code{genflags}
3298 and @code{gencodes}, tell this pass which standard names are available
3299 for use and which patterns correspond to them.@refill
3301 Aside from debugging information output, none of the following passes
3302 refers to the tree structure representation of the function (only
3303 part of which is saved).
3305 @cindex inline, automatic
3306 The decision of whether the function can and should be expanded inline
3307 in its subsequent callers is made at the end of rtl generation. The
3308 function must meet certain criteria, currently related to the size of
3309 the function and the types and number of parameters it has. Note that
3310 this function may contain loops, recursive calls to itself
3311 (tail-recursive functions can be inlined!), gotos, in short, all
3312 constructs supported by GCC. The file @file{integrate.c} contains
3313 the code to save a function's rtl for later inlining and to inline that
3314 rtl when the function is called. The header file @file{integrate.h}
3315 is also used for this purpose.
3317 The option @samp{-dr} causes a debugging dump of the RTL code after
3318 this pass. This dump file's name is made by appending @samp{.rtl} to
3319 the input file name.
3321 @cindex jump optimization
3322 @cindex unreachable code
3325 Jump optimization. This pass simplifies jumps to the following
3326 instruction, jumps across jumps, and jumps to jumps. It deletes
3327 unreferenced labels and unreachable code, except that unreachable code
3328 that contains a loop is not recognized as unreachable in this pass.
3329 (Such loops are deleted later in the basic block analysis.) It also
3330 converts some code originally written with jumps into sequences of
3331 instructions that directly set values from the results of comparisons,
3332 if the machine has such instructions.
3334 Jump optimization is performed two or three times. The first time is
3335 immediately following RTL generation. The second time is after CSE,
3336 but only if CSE says repeated jump optimization is needed. The
3337 last time is right before the final pass. That time, cross-jumping
3338 and deletion of no-op move instructions are done together with the
3339 optimizations described above.
3341 The source file of this pass is @file{jump.c}.
3343 The option @samp{-dj} causes a debugging dump of the RTL code after
3344 this pass is run for the first time. This dump file's name is made by
3345 appending @samp{.jump} to the input file name.
3347 @cindex register use analysis
3349 Register scan. This pass finds the first and last use of each
3350 register, as a guide for common subexpression elimination. Its source
3351 is in @file{regclass.c}.
3353 @cindex jump threading
3355 Jump threading. This pass detects a condition jump that branches to an
3356 identical or inverse test. Such jumps can be @samp{threaded} through
3357 the second conditional test. The source code for this pass is in
3358 @file{jump.c}. This optimization is only performed if
3359 @samp{-fthread-jumps} is enabled.
3361 @cindex common subexpression elimination
3362 @cindex constant propagation
3364 Common subexpression elimination. This pass also does constant
3365 propagation. Its source file is @file{cse.c}. If constant
3366 propagation causes conditional jumps to become unconditional or to
3367 become no-ops, jump optimization is run again when CSE is finished.
3369 The option @samp{-ds} causes a debugging dump of the RTL code after
3370 this pass. This dump file's name is made by appending @samp{.cse} to
3371 the input file name.
3373 @cindex global common subexpression elimination
3374 @cindex constant propagation
3375 @cindex copy propagation
3377 Global common subexpression elimination. This pass performs GCSE
3378 using Morel-Renvoise Partial Redundancy Elimination, with the exception
3379 that it does not try to move invariants out of loops - that is left to
3380 the loop optimization pass. This pass also performs global constant
3381 and copy propagation.
3383 The source file for this pass is gcse.c.
3385 The option @samp{-dG} causes a debugging dump of the RTL code after
3386 this pass. This dump file's name is made by appending @samp{.gcse} to
3387 the input file name.
3389 @cindex loop optimization
3391 @cindex strength-reduction
3393 Loop optimization. This pass moves constant expressions out of loops,
3394 and optionally does strength-reduction and loop unrolling as well.
3395 Its source files are @file{loop.c} and @file{unroll.c}, plus the header
3396 @file{loop.h} used for communication between them. Loop unrolling uses
3397 some functions in @file{integrate.c} and the header @file{integrate.h}.
3399 The option @samp{-dL} causes a debugging dump of the RTL code after
3400 this pass. This dump file's name is made by appending @samp{.loop} to
3401 the input file name.
3404 If @samp{-frerun-cse-after-loop} was enabled, a second common
3405 subexpression elimination pass is performed after the loop optimization
3406 pass. Jump threading is also done again at this time if it was specified.
3408 The option @samp{-dt} causes a debugging dump of the RTL code after
3409 this pass. This dump file's name is made by appending @samp{.cse2} to
3410 the input file name.
3412 @cindex register allocation, stupid
3413 @cindex stupid register allocation
3415 Stupid register allocation is performed at this point in a
3416 nonoptimizing compilation. It does a little data flow analysis as
3417 well. When stupid register allocation is in use, the next pass
3418 executed is the reloading pass; the others in between are skipped.
3419 The source file is @file{stupid.c}.
3421 @cindex data flow analysis
3422 @cindex analysis, data flow
3423 @cindex basic blocks
3425 Data flow analysis (@file{flow.c}). This pass divides the program
3426 into basic blocks (and in the process deletes unreachable loops); then
3427 it computes which pseudo-registers are live at each point in the
3428 program, and makes the first instruction that uses a value point at
3429 the instruction that computed the value.
3431 @cindex autoincrement/decrement analysis
3432 This pass also deletes computations whose results are never used, and
3433 combines memory references with add or subtract instructions to make
3434 autoincrement or autodecrement addressing.
3436 The option @samp{-df} causes a debugging dump of the RTL code after
3437 this pass. This dump file's name is made by appending @samp{.flow} to
3438 the input file name. If stupid register allocation is in use, this
3439 dump file reflects the full results of such allocation.
3441 @cindex instruction combination
3443 Instruction combination (@file{combine.c}). This pass attempts to
3444 combine groups of two or three instructions that are related by data
3445 flow into single instructions. It combines the RTL expressions for
3446 the instructions by substitution, simplifies the result using algebra,
3447 and then attempts to match the result against the machine description.
3449 The option @samp{-dc} causes a debugging dump of the RTL code after
3450 this pass. This dump file's name is made by appending @samp{.combine}
3451 to the input file name.
3453 @cindex register movement
3455 Register movement (@file{regmove.c}). This pass looks for cases where
3456 matching constraints would force an instruction to need a reload, and
3457 this reload would be a register to register move. It them attempts
3458 to change the registers used by the instruction to avoid the move
3461 The option @samp{-dN} causes a debugging dump of the RTL code after
3462 this pass. This dump file's name is made by appending @samp{.regmove}
3463 to the input file name.
3465 @cindex instruction scheduling
3466 @cindex scheduling, instruction
3468 Instruction scheduling (@file{sched.c}). This pass looks for
3469 instructions whose output will not be available by the time that it is
3470 used in subsequent instructions. (Memory loads and floating point
3471 instructions often have this behavior on RISC machines). It re-orders
3472 instructions within a basic block to try to separate the definition and
3473 use of items that otherwise would cause pipeline stalls.
3475 Instruction scheduling is performed twice. The first time is immediately
3476 after instruction combination and the second is immediately after reload.
3478 The option @samp{-dS} causes a debugging dump of the RTL code after this
3479 pass is run for the first time. The dump file's name is made by
3480 appending @samp{.sched} to the input file name.
3482 @cindex register class preference pass
3484 Register class preferencing. The RTL code is scanned to find out
3485 which register class is best for each pseudo register. The source
3486 file is @file{regclass.c}.
3488 @cindex register allocation
3489 @cindex local register allocation
3491 Local register allocation (@file{local-alloc.c}). This pass allocates
3492 hard registers to pseudo registers that are used only within one basic
3493 block. Because the basic block is linear, it can use fast and
3494 powerful techniques to do a very good job.
3496 The option @samp{-dl} causes a debugging dump of the RTL code after
3497 this pass. This dump file's name is made by appending @samp{.lreg} to
3498 the input file name.
3500 @cindex global register allocation
3502 Global register allocation (@file{global.c}). This pass
3503 allocates hard registers for the remaining pseudo registers (those
3504 whose life spans are not contained in one basic block).
3508 Reloading. This pass renumbers pseudo registers with the hardware
3509 registers numbers they were allocated. Pseudo registers that did not
3510 get hard registers are replaced with stack slots. Then it finds
3511 instructions that are invalid because a value has failed to end up in
3512 a register, or has ended up in a register of the wrong kind. It fixes
3513 up these instructions by reloading the problematical values
3514 temporarily into registers. Additional instructions are generated to
3517 The reload pass also optionally eliminates the frame pointer and inserts
3518 instructions to save and restore call-clobbered registers around calls.
3520 Source files are @file{reload.c} and @file{reload1.c}, plus the header
3521 @file{reload.h} used for communication between them.
3523 The option @samp{-dg} causes a debugging dump of the RTL code after
3524 this pass. This dump file's name is made by appending @samp{.greg} to
3525 the input file name.
3527 @cindex instruction scheduling
3528 @cindex scheduling, instruction
3530 Instruction scheduling is repeated here to try to avoid pipeline stalls
3531 due to memory loads generated for spilled pseudo registers.
3533 The option @samp{-dR} causes a debugging dump of the RTL code after
3534 this pass. This dump file's name is made by appending @samp{.sched2}
3535 to the input file name.
3537 @cindex cross-jumping
3538 @cindex no-op move instructions
3540 Jump optimization is repeated, this time including cross-jumping
3541 and deletion of no-op move instructions.
3543 The option @samp{-dJ} causes a debugging dump of the RTL code after
3544 this pass. This dump file's name is made by appending @samp{.jump2}
3545 to the input file name.
3547 @cindex delayed branch scheduling
3548 @cindex scheduling, delayed branch
3550 Delayed branch scheduling. This optional pass attempts to find
3551 instructions that can go into the delay slots of other instructions,
3552 usually jumps and calls. The source file name is @file{reorg.c}.
3554 The option @samp{-dd} causes a debugging dump of the RTL code after
3555 this pass. This dump file's name is made by appending @samp{.dbr}
3556 to the input file name.
3558 @cindex branch shortening
3560 Branch shortening. On many RISC machines, branch instructions have a
3561 limited range. Thus, longer sequences of instructions must be used for
3562 long branches. In this pass, the compiler figures out what how far each
3563 instruction will be from each other instruction, and therefore whether
3564 the usual instructions, or the longer sequences, must be used for each
3567 @cindex register-to-stack conversion
3569 Conversion from usage of some hard registers to usage of a register
3570 stack may be done at this point. Currently, this is supported only
3571 for the floating-point registers of the Intel 80387 coprocessor. The
3572 source file name is @file{reg-stack.c}.
3574 The options @samp{-dk} causes a debugging dump of the RTL code after
3575 this pass. This dump file's name is made by appending @samp{.stack}
3576 to the input file name.
3579 @cindex peephole optimization
3581 Final. This pass outputs the assembler code for the function. It is
3582 also responsible for identifying spurious test and compare
3583 instructions. Machine-specific peephole optimizations are performed
3584 at the same time. The function entry and exit sequences are generated
3585 directly as assembler code in this pass; they never exist as RTL.
3587 The source files are @file{final.c} plus @file{insn-output.c}; the
3588 latter is generated automatically from the machine description by the
3589 tool @file{genoutput}. The header file @file{conditions.h} is used
3590 for communication between these files.
3592 @cindex debugging information generation
3594 Debugging information output. This is run after final because it must
3595 output the stack slot offsets for pseudo registers that did not get
3596 hard registers. Source files are @file{dbxout.c} for DBX symbol table
3597 format, @file{sdbout.c} for SDB symbol table format, and
3598 @file{dwarfout.c} for DWARF symbol table format.
3601 Some additional files are used by all or many passes:
3605 Every pass uses @file{machmode.def} and @file{machmode.h} which define
3609 Several passes use @file{real.h}, which defines the default
3610 representation of floating point constants and how to operate on them.
3613 All the passes that work with RTL use the header files @file{rtl.h}
3614 and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
3615 @code{gen*} also use these files to read and work with the machine
3620 Several passes refer to the header file @file{insn-config.h} which
3621 contains a few parameters (C macro definitions) generated
3622 automatically from the machine description RTL by the tool
3625 @cindex instruction recognizer
3627 Several passes use the instruction recognizer, which consists of
3628 @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
3629 and @file{insn-extract.c} that are generated automatically from the
3630 machine description by the tools @file{genrecog} and
3631 @file{genextract}.@refill
3634 Several passes use the header files @file{regs.h} which defines the
3635 information recorded about pseudo register usage, and @file{basic-block.h}
3636 which defines the information recorded about basic blocks.
3639 @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
3640 with a bit for each hard register, and some macros to manipulate it.
3641 This type is just @code{int} if the machine has few enough hard registers;
3642 otherwise it is an array of @code{int} and some of the macros expand
3646 Several passes use instruction attributes. A definition of the
3647 attributes defined for a particular machine is in file
3648 @file{insn-attr.h}, which is generated from the machine description by
3649 the program @file{genattr}. The file @file{insn-attrtab.c} contains
3650 subroutines to obtain the attribute values for insns. It is generated
3651 from the machine description by the program @file{genattrtab}.@refill
3663 @chapter The Configuration File
3664 @cindex configuration file
3665 @cindex @file{xm-@var{machine}.h}
3667 The configuration file @file{xm-@var{machine}.h} contains macro
3668 definitions that describe the machine and system on which the compiler
3669 is running, unlike the definitions in @file{@var{machine}.h}, which
3670 describe the machine for which the compiler is producing output. Most
3671 of the values in @file{xm-@var{machine}.h} are actually the same on all
3672 machines that GCC runs on, so large parts of all configuration files
3673 are identical. But there are some macros that vary:
3678 Define this macro if the host system is System V.
3682 Define this macro if the host system is VMS.
3684 @findex FATAL_EXIT_CODE
3685 @item FATAL_EXIT_CODE
3686 A C expression for the status code to be returned when the compiler
3687 exits after serious errors.
3689 @findex SUCCESS_EXIT_CODE
3690 @item SUCCESS_EXIT_CODE
3691 A C expression for the status code to be returned when the compiler
3692 exits without serious errors.
3694 @findex HOST_WORDS_BIG_ENDIAN
3695 @item HOST_WORDS_BIG_ENDIAN
3696 Defined if the host machine stores words of multi-word values in
3697 big-endian order. (GCC does not depend on the host byte ordering
3700 @findex HOST_FLOAT_WORDS_BIG_ENDIAN
3701 @item HOST_FLOAT_WORDS_BIG_ENDIAN
3702 Define this macro to be 1 if the host machine stores @code{DFmode},
3703 @code{XFmode} or @code{TFmode} floating point numbers in memory with the
3704 word containing the sign bit at the lowest address; otherwise, define it
3707 This macro need not be defined if the ordering is the same as for
3708 multi-word integers.
3710 @findex HOST_FLOAT_FORMAT
3711 @item HOST_FLOAT_FORMAT
3712 A numeric code distinguishing the floating point format for the host
3713 machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
3714 alternatives and default.
3716 @findex HOST_BITS_PER_CHAR
3717 @item HOST_BITS_PER_CHAR
3718 A C expression for the number of bits in @code{char} on the host
3721 @findex HOST_BITS_PER_SHORT
3722 @item HOST_BITS_PER_SHORT
3723 A C expression for the number of bits in @code{short} on the host
3726 @findex HOST_BITS_PER_INT
3727 @item HOST_BITS_PER_INT
3728 A C expression for the number of bits in @code{int} on the host
3731 @findex HOST_BITS_PER_LONG
3732 @item HOST_BITS_PER_LONG
3733 A C expression for the number of bits in @code{long} on the host
3736 @findex ONLY_INT_FIELDS
3737 @item ONLY_INT_FIELDS
3738 Define this macro to indicate that the host compiler only supports
3739 @code{int} bit fields, rather than other integral types, including
3740 @code{enum}, as do most C compilers.
3742 @findex OBSTACK_CHUNK_SIZE
3743 @item OBSTACK_CHUNK_SIZE
3744 A C expression for the size of ordinary obstack chunks.
3745 If you don't define this, a usually-reasonable default is used.
3747 @findex OBSTACK_CHUNK_ALLOC
3748 @item OBSTACK_CHUNK_ALLOC
3749 The function used to allocate obstack chunks.
3750 If you don't define this, @code{xmalloc} is used.
3752 @findex OBSTACK_CHUNK_FREE
3753 @item OBSTACK_CHUNK_FREE
3754 The function used to free obstack chunks.
3755 If you don't define this, @code{free} is used.
3757 @findex USE_C_ALLOCA
3759 Define this macro to indicate that the compiler is running with the
3760 @code{alloca} implemented in C. This version of @code{alloca} can be
3761 found in the file @file{alloca.c}; to use it, you must also alter the
3762 @file{Makefile} variable @code{ALLOCA}. (This is done automatically
3763 for the systems on which we know it is needed.)
3765 If you do define this macro, you should probably do it as follows:
3769 #define USE_C_ALLOCA
3771 #define alloca __builtin_alloca
3776 so that when the compiler is compiled with GCC it uses the more
3777 efficient built-in @code{alloca} function.
3779 @item FUNCTION_CONVERSION_BUG
3780 @findex FUNCTION_CONVERSION_BUG
3781 Define this macro to indicate that the host compiler does not properly
3782 handle converting a function value to a pointer-to-function when it is
3783 used in an expression.
3785 @findex MULTIBYTE_CHARS
3786 @item MULTIBYTE_CHARS
3787 Define this macro to enable support for multibyte characters in the
3788 input to GCC. This requires that the host system support the ANSI C
3789 library functions for converting multibyte characters to wide
3794 Define this if your system is POSIX.1 compliant.
3796 @findex NO_SYS_SIGLIST
3797 @item NO_SYS_SIGLIST
3798 Define this if your system @emph{does not} provide the variable
3802 Some systems do provide this variable, but with a different name such
3803 as @code{_sys_siglist}. On these systems, you can define
3804 @code{sys_siglist} as a macro which expands into the name actually
3807 Autoconf normally defines @code{SYS_SIGLIST_DECLARED} when it finds a
3808 declaration of @code{sys_siglist} in the system header files.
3809 However, when you define @code{sys_siglist} to a different name
3810 autoconf will not automatically define @code{SYS_SIGLIST_DECLARED}.
3811 Therefore, if you define @code{sys_siglist}, you should also define
3812 @code{SYS_SIGLIST_DECLARED}.
3814 @findex USE_PROTOTYPES
3815 @item USE_PROTOTYPES
3816 Define this to be 1 if you know that the host compiler supports
3817 prototypes, even if it doesn't define __STDC__, or define
3818 it to be 0 if you do not want any prototypes used in compiling
3819 GCC. If @samp{USE_PROTOTYPES} is not defined, it will be
3820 determined automatically whether your compiler supports
3821 prototypes by checking if @samp{__STDC__} is defined.
3823 @findex NO_MD_PROTOTYPES
3824 @item NO_MD_PROTOTYPES
3825 Define this if you wish suppression of prototypes generated from
3826 the machine description file, but to use other prototypes within
3827 GCC. If @samp{USE_PROTOTYPES} is defined to be 0, or the
3828 host compiler does not support prototypes, this macro has no
3831 @findex MD_CALL_PROTOTYPES
3832 @item MD_CALL_PROTOTYPES
3833 Define this if you wish to generate prototypes for the
3834 @code{gen_call} or @code{gen_call_value} functions generated from
3835 the machine description file. If @samp{USE_PROTOTYPES} is
3836 defined to be 0, or the host compiler does not support
3837 prototypes, or @samp{NO_MD_PROTOTYPES} is defined, this macro has
3838 no effect. As soon as all of the machine descriptions are
3839 modified to have the appropriate number of arguments, this macro
3842 @findex PATH_SEPARATOR
3843 @item PATH_SEPARATOR
3844 Define this macro to be a C character constant representing the
3845 character used to separate components in paths. The default value is
3848 @findex DIR_SEPARATOR
3850 If your system uses some character other than slash to separate
3851 directory names within a file specification, define this macro to be a C
3852 character constant specifying that character. When GCC displays file
3853 names, the character you specify will be used. GCC will test for
3854 both slash and the character you specify when parsing filenames.
3856 @findex OBJECT_SUFFIX
3858 Define this macro to be a C string representing the suffix for object
3859 files on your machine. If you do not define this macro, GCC will use
3860 @samp{.o} as the suffix for object files.
3862 @findex EXECUTABLE_SUFFIX
3863 @item EXECUTABLE_SUFFIX
3864 Define this macro to be a C string representing the suffix for executable
3865 files on your machine. If you do not define this macro, GCC will use
3866 the null string as the suffix for object files.
3868 @findex COLLECT_EXPORT_LIST
3869 @item COLLECT_EXPORT_LIST
3870 If defined, @code{collect2} will scan the individual object files
3871 specified on its command line and create an export list for the linker.
3872 Define this macro for systems like AIX, where the linker discards
3873 object files that are not referenced from @code{main} and uses export
3879 In addition, configuration files for system V define @code{bcopy},
3880 @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
3881 as a macro when compiled with GCC, in order to take advantage of the
3882 benefit of GCC's built-in @code{alloca}.
3885 @chapter Makefile Fragments
3886 @cindex makefile fragment
3888 When you configure GCC using the @file{configure} script
3889 (@pxref{Installation}), it will construct the file @file{Makefile} from
3890 the template file @file{Makefile.in}. When it does this, it will
3891 incorporate makefile fragment files from the @file{config} directory,
3892 named @file{t-@var{target}} and @file{x-@var{host}}. If these files do
3893 not exist, it means nothing needs to be added for a given target or
3897 * Target Fragment:: Writing the @file{t-@var{target}} file.
3898 * Host Fragment:: Writing the @file{x-@var{host}} file.
3901 @node Target Fragment
3902 @section The Target Makefile Fragment
3903 @cindex target makefile fragment
3904 @cindex @file{t-@var{target}}
3906 The target makefile fragment, @file{t-@var{target}}, defines special
3907 target dependent variables and targets used in the @file{Makefile}:
3912 The rule to use to build @file{libgcc1.a}.
3913 If your target does not need to use the functions in @file{libgcc1.a},
3917 @findex CROSS_LIBGCC1
3919 The rule to use to build @file{libgcc1.a} when building a cross
3920 compiler. If your target does not need to use the functions in
3921 @file{libgcc1.a}, set this to empty. @xref{Cross Runtime}.
3923 @findex LIBGCC2_CFLAGS
3924 @item LIBGCC2_CFLAGS
3925 Compiler flags to use when compiling @file{libgcc2.c}.
3927 @findex LIB2FUNCS_EXTRA
3928 @item LIB2FUNCS_EXTRA
3929 A list of source file names to be compiled or assembled and inserted
3930 into @file{libgcc.a}.
3932 @findex Floating Point Emulation
3933 @item Floating Point Emulation
3934 To have GCC include software floating point libraries in @file{libgcc.a}
3935 define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
3937 # We want fine grained libraries, so use the new code to build the
3938 # floating point emulation libraries.
3943 fp-bit.c: $(srcdir)/config/fp-bit.c
3944 echo '#define FLOAT' > fp-bit.c
3945 cat $(srcdir)/config/fp-bit.c >> fp-bit.c
3947 dp-bit.c: $(srcdir)/config/fp-bit.c
3948 cat $(srcdir)/config/fp-bit.c > dp-bit.c
3951 You may need to provide additional #defines at the beginning of @file{fp-bit.c}
3952 and @file{dp-bit.c} to control target endianness and other options.
3955 @findex CRTSTUFF_T_CFLAGS
3956 @item CRTSTUFF_T_CFLAGS
3957 Special flags used when compiling @file{crtstuff.c}.
3958 @xref{Initialization}.
3960 @findex CRTSTUFF_T_CFLAGS_S
3961 @item CRTSTUFF_T_CFLAGS_S
3962 Special flags used when compiling @file{crtstuff.c} for shared
3963 linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
3964 in @code{EXTRA-PARTS}.
3965 @xref{Initialization}.
3967 @findex MULTILIB_OPTIONS
3968 @item MULTILIB_OPTIONS
3969 For some targets, invoking GCC in different ways produces objects
3970 that can not be linked together. For example, for some targets GCC
3971 produces both big and little endian code. For these targets, you must
3972 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
3973 each set of incompatible options. When GCC invokes the linker, it
3974 arranges to link in the right version of @file{libgcc.a}, based on
3975 the command line options used.
3977 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
3978 special versions of @file{libgcc.a} must be built. Write options that
3979 are mutually incompatible side by side, separated by a slash. Write
3980 options that may be used together separated by a space. The build
3981 procedure will build all combinations of compatible options.
3983 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
3984 msoft-float}, @file{Makefile} will build special versions of
3985 @file{libgcc.a} using the following sets of options: @samp{-m68000},
3986 @samp{-m68020}, @samp{-msoft-float}, @samp{-m68000 -msoft-float}, and
3987 @samp{-m68020 -msoft-float}.
3989 @findex MULTILIB_DIRNAMES
3990 @item MULTILIB_DIRNAMES
3991 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
3992 directory names that should be used to hold the various libraries.
3993 Write one element in @code{MULTILIB_DIRNAMES} for each element in
3994 @code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
3995 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
3998 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
3999 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
4000 @samp{m68000 m68020 msoft-float}. You may specify a different value if
4001 you desire a different set of directory names.
4003 @findex MULTILIB_MATCHES
4004 @item MULTILIB_MATCHES
4005 Sometimes the same option may be written in two different ways. If an
4006 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
4007 any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
4008 items of the form @samp{option=option} to describe all relevant
4009 synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
4011 @findex MULTILIB_EXCEPTIONS
4012 @item MULTILIB_EXCEPTIONS
4013 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
4014 specified, there are combinations that should not be built. In that
4015 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
4016 in shell case syntax that should not be built.
4018 For example, in the PowerPC embedded ABI support, it was not desirable
4019 to build libraries that compiled with the @samp{-mcall-aixdesc} option
4020 and either of the @samp{-mcall-aixdesc} or @samp{-mlittle} options at
4021 the same time, and therefore @code{MULTILIB_EXCEPTIONS} is set to
4022 @code{*mrelocatable/*mcall-aixdesc* *mlittle/*mcall-aixdesc*}.
4024 @findex MULTILIB_EXTRA_OPTS
4025 @item MULTILIB_EXTRA_OPTS
4026 Sometimes it is desirable that when building multiple versions of
4027 @file{libgcc.a} certain options should always be passed on to the
4028 compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
4029 of options to be used for all builds.
4033 @section The Host Makefile Fragment
4034 @cindex host makefile fragment
4035 @cindex @file{x-@var{host}}
4037 The host makefile fragment, @file{x-@var{host}}, defines special host
4038 dependent variables and targets used in the @file{Makefile}:
4043 The compiler to use when building the first stage.
4047 Additional host libraries to link with.
4051 The compiler to use when building @file{libgcc1.a} for a native
4056 The version of @code{ar} to use when building @file{libgcc1.a} for a native
4061 The install program to use.
4065 @unnumbered Funding Free Software
4067 If you want to have more free software a few years from now, it makes
4068 sense for you to help encourage people to contribute funds for its
4069 development. The most effective approach known is to encourage
4070 commercial redistributors to donate.
4072 Users of free software systems can boost the pace of development by
4073 encouraging for-a-fee distributors to donate part of their selling price
4074 to free software developers---the Free Software Foundation, and others.
4076 The way to convince distributors to do this is to demand it and expect
4077 it from them. So when you compare distributors, judge them partly by
4078 how much they give to free software development. Show distributors
4079 they must compete to be the one who gives the most.
4081 To make this approach work, you must insist on numbers that you can
4082 compare, such as, ``We will donate ten dollars to the Frobnitz project
4083 for each disk sold.'' Don't be satisfied with a vague promise, such as
4084 ``A portion of the profits are donated,'' since it doesn't give a basis
4087 Even a precise fraction ``of the profits from this disk'' is not very
4088 meaningful, since creative accounting and unrelated business decisions
4089 can greatly alter what fraction of the sales price counts as profit.
4090 If the price you pay is $50, ten percent of the profit is probably
4091 less than a dollar; it might be a few cents, or nothing at all.
4093 Some redistributors do development work themselves. This is useful too;
4094 but to keep everyone honest, you need to inquire how much they do, and
4095 what kind. Some kinds of development make much more long-term
4096 difference than others. For example, maintaining a separate version of
4097 a program contributes very little; maintaining the standard version of a
4098 program for the whole community contributes much. Easy new ports
4099 contribute little, since someone else would surely do them; difficult
4100 ports such as adding a new CPU to the GNU Compiler Collection contribute more;
4101 major new features or packages contribute the most.
4103 By establishing the idea that supporting further development is ``the
4104 proper thing to do'' when distributing free software for a fee, we can
4105 assure a steady flow of resources into making more free software.
4108 Copyright (C) 1994 Free Software Foundation, Inc.
4109 Verbatim copying and redistribution of this section is permitted
4110 without royalty; alteration is not permitted.
4114 @unnumbered Linux and the GNU Project
4116 Many computer users run a modified version of the GNU system every
4117 day, without realizing it. Through a peculiar turn of events, the
4118 version of GNU which is widely used today is more often known as
4119 ``Linux'', and many users are not aware of the extent of its
4120 connection with the GNU Project.
4122 There really is a Linux; it is a kernel, and these people are using
4123 it. But you can't use a kernel by itself; a kernel is useful only as
4124 part of a whole system. The system in which Linux is typically used
4125 is a modified variant of the GNU system---in other words, a Linux-based
4128 Many users are not fully aware of the distinction between the kernel,
4129 which is Linux, and the whole system, which they also call ``Linux''.
4130 The ambiguous use of the name doesn't promote understanding.
4132 Programmers generally know that Linux is a kernel. But since they
4133 have generally heard the whole system called ``Linux'' as well, they
4134 often envisage a history which fits that name. For example, many
4135 believe that once Linus Torvalds finished writing the kernel, his
4136 friends looked around for other free software, and for no particular
4137 reason most everything necessary to make a Unix-like system was
4140 What they found was no accident---it was the GNU system. The available
4141 free software added up to a complete system because the GNU Project
4142 had been working since 1984 to make one. The GNU Manifesto
4143 had set forth the goal of developing a free Unix-like system, called
4144 GNU. By the time Linux was written, the system was almost finished.
4146 Most free software projects have the goal of developing a particular
4147 program for a particular job. For example, Linus Torvalds set out to
4148 write a Unix-like kernel (Linux); Donald Knuth set out to write a text
4149 formatter (TeX); Bob Scheifler set out to develop a window system (X
4150 Windows). It's natural to measure the contribution of this kind of
4151 project by specific programs that came from the project.
4153 If we tried to measure the GNU Project's contribution in this way,
4154 what would we conclude? One CD-ROM vendor found that in their ``Linux
4155 distribution'', GNU software was the largest single contingent, around
4156 28% of the total source code, and this included some of the essential
4157 major components without which there could be no system. Linux itself
4158 was about 3%. So if you were going to pick a name for the system
4159 based on who wrote the programs in the system, the most appropriate
4160 single choice would be ``GNU''.
4162 But we don't think that is the right way to consider the question.
4163 The GNU Project was not, is not, a project to develop specific
4164 software packages. It was not a project to develop a C compiler,
4165 although we did. It was not a project to develop a text editor,
4166 although we developed one. The GNU Project's aim was to develop
4167 @emph{a complete free Unix-like system}.
4169 Many people have made major contributions to the free software in the
4170 system, and they all deserve credit. But the reason it is @emph{a
4171 system}---and not just a collection of useful programs---is because the
4172 GNU Project set out to make it one. We wrote the programs that were
4173 needed to make a @emph{complete} free system. We wrote essential but
4174 unexciting major components, such as the assembler and linker, because
4175 you can't have a system without them. A complete system needs more
4176 than just programming tools, so we wrote other components as well,
4177 such as the Bourne Again SHell, the PostScript interpreter
4178 Ghostscript, and the GNU C library.
4180 By the early 90s we had put together the whole system aside from the
4181 kernel (and we were also working on a kernel, the GNU Hurd, which runs
4182 on top of Mach). Developing this kernel has been a lot harder than we
4183 expected, and we are still working on finishing it.
4185 Fortunately, you don't have to wait for it, because Linux is working
4186 now. When Linus Torvalds wrote Linux, he filled the last major gap.
4187 People could then put Linux together with the GNU system to make a
4188 complete free system: a Linux-based GNU system (or GNU/Linux system,
4191 Putting them together sounds simple, but it was not a trivial job.
4192 The GNU C library (called glibc for short) needed substantial changes.
4193 Integrating a complete system as a distribution that would work ``out
4194 of the box'' was a big job, too. It required addressing the issue of
4195 how to install and boot the system---a problem we had not tackled,
4196 because we hadn't yet reached that point. The people who developed
4197 the various system distributions made a substantial contribution.
4199 The GNU Project supports GNU/Linux systems as well as @emph{the}
4200 GNU system---even with funds. We funded the rewriting of the
4201 Linux-related extensions to the GNU C library, so that now they are
4202 well integrated, and the newest GNU/Linux systems use the current
4203 library release with no changes. We also funded an early stage of the
4204 development of Debian GNU/Linux.
4206 We use Linux-based GNU systems today for most of our work, and we hope
4207 you use them too. But please don't confuse the public by using the
4208 name ``Linux'' ambiguously. Linux is the kernel, one of the essential
4209 major components of the system. The system as a whole is more or less
4213 @unnumbered GNU GENERAL PUBLIC LICENSE
4214 @center Version 2, June 1991
4217 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
4218 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
4220 Everyone is permitted to copy and distribute verbatim copies
4221 of this license document, but changing it is not allowed.
4224 @unnumberedsec Preamble
4226 The licenses for most software are designed to take away your
4227 freedom to share and change it. By contrast, the GNU General Public
4228 License is intended to guarantee your freedom to share and change free
4229 software---to make sure the software is free for all its users. This
4230 General Public License applies to most of the Free Software
4231 Foundation's software and to any other program whose authors commit to
4232 using it. (Some other Free Software Foundation software is covered by
4233 the GNU Library General Public License instead.) You can apply it to
4236 When we speak of free software, we are referring to freedom, not
4237 price. Our General Public Licenses are designed to make sure that you
4238 have the freedom to distribute copies of free software (and charge for
4239 this service if you wish), that you receive source code or can get it
4240 if you want it, that you can change the software or use pieces of it
4241 in new free programs; and that you know you can do these things.
4243 To protect your rights, we need to make restrictions that forbid
4244 anyone to deny you these rights or to ask you to surrender the rights.
4245 These restrictions translate to certain responsibilities for you if you
4246 distribute copies of the software, or if you modify it.
4248 For example, if you distribute copies of such a program, whether
4249 gratis or for a fee, you must give the recipients all the rights that
4250 you have. You must make sure that they, too, receive or can get the
4251 source code. And you must show them these terms so they know their
4254 We protect your rights with two steps: (1) copyright the software, and
4255 (2) offer you this license which gives you legal permission to copy,
4256 distribute and/or modify the software.
4258 Also, for each author's protection and ours, we want to make certain
4259 that everyone understands that there is no warranty for this free
4260 software. If the software is modified by someone else and passed on, we
4261 want its recipients to know that what they have is not the original, so
4262 that any problems introduced by others will not reflect on the original
4263 authors' reputations.
4265 Finally, any free program is threatened constantly by software
4266 patents. We wish to avoid the danger that redistributors of a free
4267 program will individually obtain patent licenses, in effect making the
4268 program proprietary. To prevent this, we have made it clear that any
4269 patent must be licensed for everyone's free use or not licensed at all.
4271 The precise terms and conditions for copying, distribution and
4272 modification follow.
4275 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4278 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4283 This License applies to any program or other work which contains
4284 a notice placed by the copyright holder saying it may be distributed
4285 under the terms of this General Public License. The ``Program'', below,
4286 refers to any such program or work, and a ``work based on the Program''
4287 means either the Program or any derivative work under copyright law:
4288 that is to say, a work containing the Program or a portion of it,
4289 either verbatim or with modifications and/or translated into another
4290 language. (Hereinafter, translation is included without limitation in
4291 the term ``modification''.) Each licensee is addressed as ``you''.
4293 Activities other than copying, distribution and modification are not
4294 covered by this License; they are outside its scope. The act of
4295 running the Program is not restricted, and the output from the Program
4296 is covered only if its contents constitute a work based on the
4297 Program (independent of having been made by running the Program).
4298 Whether that is true depends on what the Program does.
4301 You may copy and distribute verbatim copies of the Program's
4302 source code as you receive it, in any medium, provided that you
4303 conspicuously and appropriately publish on each copy an appropriate
4304 copyright notice and disclaimer of warranty; keep intact all the
4305 notices that refer to this License and to the absence of any warranty;
4306 and give any other recipients of the Program a copy of this License
4307 along with the Program.
4309 You may charge a fee for the physical act of transferring a copy, and
4310 you may at your option offer warranty protection in exchange for a fee.
4313 You may modify your copy or copies of the Program or any portion
4314 of it, thus forming a work based on the Program, and copy and
4315 distribute such modifications or work under the terms of Section 1
4316 above, provided that you also meet all of these conditions:
4320 You must cause the modified files to carry prominent notices
4321 stating that you changed the files and the date of any change.
4324 You must cause any work that you distribute or publish, that in
4325 whole or in part contains or is derived from the Program or any
4326 part thereof, to be licensed as a whole at no charge to all third
4327 parties under the terms of this License.
4330 If the modified program normally reads commands interactively
4331 when run, you must cause it, when started running for such
4332 interactive use in the most ordinary way, to print or display an
4333 announcement including an appropriate copyright notice and a
4334 notice that there is no warranty (or else, saying that you provide
4335 a warranty) and that users may redistribute the program under
4336 these conditions, and telling the user how to view a copy of this
4337 License. (Exception: if the Program itself is interactive but
4338 does not normally print such an announcement, your work based on
4339 the Program is not required to print an announcement.)
4342 These requirements apply to the modified work as a whole. If
4343 identifiable sections of that work are not derived from the Program,
4344 and can be reasonably considered independent and separate works in
4345 themselves, then this License, and its terms, do not apply to those
4346 sections when you distribute them as separate works. But when you
4347 distribute the same sections as part of a whole which is a work based
4348 on the Program, the distribution of the whole must be on the terms of
4349 this License, whose permissions for other licensees extend to the
4350 entire whole, and thus to each and every part regardless of who wrote it.
4352 Thus, it is not the intent of this section to claim rights or contest
4353 your rights to work written entirely by you; rather, the intent is to
4354 exercise the right to control the distribution of derivative or
4355 collective works based on the Program.
4357 In addition, mere aggregation of another work not based on the Program
4358 with the Program (or with a work based on the Program) on a volume of
4359 a storage or distribution medium does not bring the other work under
4360 the scope of this License.
4363 You may copy and distribute the Program (or a work based on it,
4364 under Section 2) in object code or executable form under the terms of
4365 Sections 1 and 2 above provided that you also do one of the following:
4369 Accompany it with the complete corresponding machine-readable
4370 source code, which must be distributed under the terms of Sections
4371 1 and 2 above on a medium customarily used for software interchange; or,
4374 Accompany it with a written offer, valid for at least three
4375 years, to give any third party, for a charge no more than your
4376 cost of physically performing source distribution, a complete
4377 machine-readable copy of the corresponding source code, to be
4378 distributed under the terms of Sections 1 and 2 above on a medium
4379 customarily used for software interchange; or,
4382 Accompany it with the information you received as to the offer
4383 to distribute corresponding source code. (This alternative is
4384 allowed only for noncommercial distribution and only if you
4385 received the program in object code or executable form with such
4386 an offer, in accord with Subsection b above.)
4389 The source code for a work means the preferred form of the work for
4390 making modifications to it. For an executable work, complete source
4391 code means all the source code for all modules it contains, plus any
4392 associated interface definition files, plus the scripts used to
4393 control compilation and installation of the executable. However, as a
4394 special exception, the source code distributed need not include
4395 anything that is normally distributed (in either source or binary
4396 form) with the major components (compiler, kernel, and so on) of the
4397 operating system on which the executable runs, unless that component
4398 itself accompanies the executable.
4400 If distribution of executable or object code is made by offering
4401 access to copy from a designated place, then offering equivalent
4402 access to copy the source code from the same place counts as
4403 distribution of the source code, even though third parties are not
4404 compelled to copy the source along with the object code.
4407 You may not copy, modify, sublicense, or distribute the Program
4408 except as expressly provided under this License. Any attempt
4409 otherwise to copy, modify, sublicense or distribute the Program is
4410 void, and will automatically terminate your rights under this License.
4411 However, parties who have received copies, or rights, from you under
4412 this License will not have their licenses terminated so long as such
4413 parties remain in full compliance.
4416 You are not required to accept this License, since you have not
4417 signed it. However, nothing else grants you permission to modify or
4418 distribute the Program or its derivative works. These actions are
4419 prohibited by law if you do not accept this License. Therefore, by
4420 modifying or distributing the Program (or any work based on the
4421 Program), you indicate your acceptance of this License to do so, and
4422 all its terms and conditions for copying, distributing or modifying
4423 the Program or works based on it.
4426 Each time you redistribute the Program (or any work based on the
4427 Program), the recipient automatically receives a license from the
4428 original licensor to copy, distribute or modify the Program subject to
4429 these terms and conditions. You may not impose any further
4430 restrictions on the recipients' exercise of the rights granted herein.
4431 You are not responsible for enforcing compliance by third parties to
4435 If, as a consequence of a court judgment or allegation of patent
4436 infringement or for any other reason (not limited to patent issues),
4437 conditions are imposed on you (whether by court order, agreement or
4438 otherwise) that contradict the conditions of this License, they do not
4439 excuse you from the conditions of this License. If you cannot
4440 distribute so as to satisfy simultaneously your obligations under this
4441 License and any other pertinent obligations, then as a consequence you
4442 may not distribute the Program at all. For example, if a patent
4443 license would not permit royalty-free redistribution of the Program by
4444 all those who receive copies directly or indirectly through you, then
4445 the only way you could satisfy both it and this License would be to
4446 refrain entirely from distribution of the Program.
4448 If any portion of this section is held invalid or unenforceable under
4449 any particular circumstance, the balance of the section is intended to
4450 apply and the section as a whole is intended to apply in other
4453 It is not the purpose of this section to induce you to infringe any
4454 patents or other property right claims or to contest validity of any
4455 such claims; this section has the sole purpose of protecting the
4456 integrity of the free software distribution system, which is
4457 implemented by public license practices. Many people have made
4458 generous contributions to the wide range of software distributed
4459 through that system in reliance on consistent application of that
4460 system; it is up to the author/donor to decide if he or she is willing
4461 to distribute software through any other system and a licensee cannot
4464 This section is intended to make thoroughly clear what is believed to
4465 be a consequence of the rest of this License.
4468 If the distribution and/or use of the Program is restricted in
4469 certain countries either by patents or by copyrighted interfaces, the
4470 original copyright holder who places the Program under this License
4471 may add an explicit geographical distribution limitation excluding
4472 those countries, so that distribution is permitted only in or among
4473 countries not thus excluded. In such case, this License incorporates
4474 the limitation as if written in the body of this License.
4477 The Free Software Foundation may publish revised and/or new versions
4478 of the General Public License from time to time. Such new versions will
4479 be similar in spirit to the present version, but may differ in detail to
4480 address new problems or concerns.
4482 Each version is given a distinguishing version number. If the Program
4483 specifies a version number of this License which applies to it and ``any
4484 later version'', you have the option of following the terms and conditions
4485 either of that version or of any later version published by the Free
4486 Software Foundation. If the Program does not specify a version number of
4487 this License, you may choose any version ever published by the Free Software
4491 If you wish to incorporate parts of the Program into other free
4492 programs whose distribution conditions are different, write to the author
4493 to ask for permission. For software which is copyrighted by the Free
4494 Software Foundation, write to the Free Software Foundation; we sometimes
4495 make exceptions for this. Our decision will be guided by the two goals
4496 of preserving the free status of all derivatives of our free software and
4497 of promoting the sharing and reuse of software generally.
4500 @heading NO WARRANTY
4507 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
4508 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
4509 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
4510 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
4511 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
4512 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
4513 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
4514 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
4515 REPAIR OR CORRECTION.
4518 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
4519 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
4520 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
4521 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
4522 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
4523 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
4524 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
4525 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
4526 POSSIBILITY OF SUCH DAMAGES.
4530 @heading END OF TERMS AND CONDITIONS
4533 @center END OF TERMS AND CONDITIONS
4537 @unnumberedsec How to Apply These Terms to Your New Programs
4539 If you develop a new program, and you want it to be of the greatest
4540 possible use to the public, the best way to achieve this is to make it
4541 free software which everyone can redistribute and change under these terms.
4543 To do so, attach the following notices to the program. It is safest
4544 to attach them to the start of each source file to most effectively
4545 convey the exclusion of warranty; and each file should have at least
4546 the ``copyright'' line and a pointer to where the full notice is found.
4549 @var{one line to give the program's name and a brief idea of what it does.}
4550 Copyright (C) @var{yyyy} @var{name of author}
4552 This program is free software; you can redistribute it and/or modify
4553 it under the terms of the GNU General Public License as published by
4554 the Free Software Foundation; either version 2 of the License, or
4555 (at your option) any later version.
4557 This program is distributed in the hope that it will be useful,
4558 but WITHOUT ANY WARRANTY; without even the implied warranty of
4559 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4560 GNU General Public License for more details.
4562 You should have received a copy of the GNU General Public License
4563 along with this program; if not, write to the Free Software
4564 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
4567 Also add information on how to contact you by electronic and paper mail.
4569 If the program is interactive, make it output a short notice like this
4570 when it starts in an interactive mode:
4573 Gnomovision version 69, Copyright (C) @var{yyyy} @var{name of author}
4574 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
4576 This is free software, and you are welcome to redistribute it
4577 under certain conditions; type `show c' for details.
4580 The hypothetical commands @samp{show w} and @samp{show c} should show
4581 the appropriate parts of the General Public License. Of course, the
4582 commands you use may be called something other than @samp{show w} and
4583 @samp{show c}; they could even be mouse-clicks or menu items---whatever
4586 You should also get your employer (if you work as a programmer) or your
4587 school, if any, to sign a ``copyright disclaimer'' for the program, if
4588 necessary. Here is a sample; alter the names:
4591 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
4592 `Gnomovision' (which makes passes at compilers) written by James Hacker.
4594 @var{signature of Ty Coon}, 1 April 1989
4595 Ty Coon, President of Vice
4598 This General Public License does not permit incorporating your program into
4599 proprietary programs. If your program is a subroutine library, you may
4600 consider it more useful to permit linking proprietary applications with the
4601 library. If this is what you want to do, use the GNU Library General
4602 Public License instead of this License.
4605 @unnumbered Contributors to GCC
4606 @cindex contributors
4608 In addition to Richard Stallman, several people have written parts
4613 The idea of using RTL and some of the optimization ideas came from the
4614 program PO written at the University of Arizona by Jack Davidson and
4615 Christopher Fraser. See ``Register Allocation and Exhaustive Peephole
4616 Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
4620 Paul Rubin wrote most of the preprocessor.
4623 Leonard Tower wrote parts of the parser, RTL generator, and RTL
4624 definitions, and of the Vax machine description.
4627 Ted Lemon wrote parts of the RTL reader and printer.
4630 Jim Wilson implemented loop strength reduction and some other
4634 Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
4635 the support for the Sony NEWS machine.
4638 Charles LaBrec contributed the support for the Integrated Solutions
4642 Michael Tiemann of Cygnus Support wrote the front end for C++, as well
4643 as the support for inline functions and instruction scheduling. Also
4644 the descriptions of the National Semiconductor 32000 series cpu, the
4645 SPARC cpu and part of the Motorola 88000 cpu.
4648 Gerald Baumgartner added the signature extension to the C++ front-end.
4651 Jan Stein of the Chalmers Computer Society provided support for
4652 Genix, as well as part of the 32000 machine description.
4655 Randy Smith finished the Sun FPA support.
4658 Robert Brown implemented the support for Encore 32000 systems.
4661 David Kashtan of SRI adapted GCC to VMS.
4664 Alex Crain provided changes for the 3b1.
4667 Greg Satz and Chris Hanson assisted in making GCC work on HP-UX for
4668 the 9000 series 300.
4671 William Schelter did most of the work on the Intel 80386 support.
4674 Christopher Smith did the port for Convex machines.
4677 Paul Petersen wrote the machine description for the Alliant FX/8.
4680 Dario Dariol contributed the four varieties of sample programs
4681 that print a copy of their source.
4684 Alain Lichnewsky ported GCC to the Mips cpu.
4687 Devon Bowen, Dale Wiles and Kevin Zachmann ported GCC to the Tahoe.
4690 Jonathan Stone wrote the machine description for the Pyramid computer.
4693 Gary Miller ported GCC to Charles River Data Systems machines.
4696 Richard Kenner of the New York University Ultracomputer Research
4697 Laboratory wrote the machine descriptions for the AMD 29000, the DEC
4698 Alpha, the IBM RT PC, and the IBM RS/6000 as well as the support for
4699 instruction attributes. He also made changes to better support RISC
4700 processors including changes to common subexpression elimination,
4701 strength reduction, function calling sequence handling, and condition
4702 code support, in addition to generalizing the code for frame pointer
4706 Richard Kenner and Michael Tiemann jointly developed reorg.c, the delay
4710 Mike Meissner and Tom Wood of Data General finished the port to the
4714 Masanobu Yuhara of Fujitsu Laboratories implemented the machine
4715 description for the Tron architecture (specifically, the Gmicro).
4718 NeXT, Inc.@: donated the front end that supports the Objective C
4720 @c We need to be careful to make it clear that "Objective C"
4721 @c is the name of a language, not that of a program or product.
4724 James van Artsdalen wrote the code that makes efficient use of
4725 the Intel 80387 register stack.
4728 Mike Meissner at the Open Software Foundation finished the port to the
4729 MIPS cpu, including adding ECOFF debug support, and worked on the
4730 Intel port for the Intel 80386 cpu. Later at Cygnus Support, he worked
4731 on the rs6000 and PowerPC ports.
4734 Ron Guilmette implemented the @code{protoize} and @code{unprotoize}
4735 tools, the support for Dwarf symbolic debugging information, and much of
4736 the support for System V Release 4. He has also worked heavily on the
4737 Intel 386 and 860 support.
4740 Torbjorn Granlund implemented multiply- and divide-by-constant
4741 optimization, improved long long support, and improved leaf function
4742 register allocation.
4745 Mike Stump implemented the support for Elxsi 64 bit CPU.
4748 John Wehle added the machine description for the Western Electric 32000
4749 processor used in several 3b series machines (no relation to the
4750 National Semiconductor 32000 processor).
4752 @ignore @c These features aren't advertised yet, since they don't fully work.
4754 Analog Devices helped implement the support for complex data types
4759 Holger Teutsch provided the support for the Clipper cpu.
4762 Kresten Krab Thorup wrote the run time support for the Objective C
4766 Stephen Moshier contributed the floating point emulator that assists in
4767 cross-compilation and permits support for floating point numbers wider
4771 David Edelsohn contributed the changes to RS/6000 port to make it
4772 support the PowerPC and POWER2 architectures.
4775 Steve Chamberlain wrote the support for the Hitachi SH processor.
4778 Peter Schauer wrote the code to allow debugging to work on the Alpha.
4781 Oliver M. Kellogg of Deutsche Aerospace contributed the port to the
4785 Michael K. Gschwind contributed the port to the PDP-11.
4788 David Reese of Sun Microsystems contributed to the Solaris on PowerPC