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 GNU CC
53 @c seems reasonable to assume at least one of INTERNALS or USING is set...
55 @settitle Using GNU CC
58 @settitle Porting GNU CC
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 C compiler.
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 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 GNU CC}
144 @title Porting GNU CC
147 @center Richard M. Stallman
149 @center Last updated 16 March 1998
151 @c The version number appears five times more in this file.
155 @vskip 0pt plus 1filll
156 Copyright @copyright{} 1988, 89, 92, 93, 94, 95, 96, 98 Free Software Foundation, Inc.
158 For EGCS Version 1.0@*
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 EGCS version 1.0.
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 EGCS version 1.0.
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 EGCS version 1.0.
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 GNU CC.
218 * C Extensions:: GNU extensions to the C language family.
219 * C++ Extensions:: GNU extensions to the C++ language.
220 * Gcov:: gcov: a GNU CC test coverage program.
221 * Trouble:: If you have trouble installing GNU CC.
222 * Bugs:: How, why and where to report bugs.
223 * Service:: How to find suppliers of support for GNU CC.
224 * Contributing:: How to contribute to testing and developing GNU CC.
225 * VMS:: Using GNU CC on VMS.
228 * Portability:: Goals of GNU CC's portability features.
229 * Interface:: Function-call interface of GNU CC 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 GNU CC.
243 * Contributors:: People who have contributed to GNU CC.
245 * Index:: Index of concepts and symbol names.
250 @chapter Compile C, C++, or Objective C
253 The C, C++, and Objective C versions of the compiler are integrated; the
254 GNU C compiler can compile programs written in C, C++, or Objective C.
257 ``GCC'' is a common shorthand term for the GNU C compiler. This is both
258 the most general name for the compiler, and the name used when the
259 emphasis is on compiling C programs.
263 When referring to C++ compilation, it is usual to call the compiler
264 ``G++''. Since there is only one compiler, it is also accurate to call
265 it ``GCC'' no matter what the language context; however, the term
266 ``G++'' is more useful when the emphasis is on compiling C++ programs.
268 We use the name ``GNU CC'' to refer to the compilation system as a
269 whole, and more specifically to the language-independent part of the
270 compiler. For example, we refer to the optimization options as
271 affecting the behavior of ``GNU CC'' or sometimes just ``the compiler''.
273 Front ends for other languages, such as Ada 9X, Fortran, Modula-3, and
274 Pascal, are under development. These front-ends, like that for C++, are
275 built in subdirectories of GNU CC and link to it. The result is an
276 integrated compiler that can compile programs written in C, C++,
277 Objective C, or any of the languages for which you have installed front
280 In this manual, we only discuss the options for the C, Objective-C, and
281 C++ compilers and those of the GNU CC core. Consult the documentation
282 of the other front ends for the options to use when compiling programs
283 written in other languages.
285 @cindex compiler compared to C++ preprocessor
286 @cindex intermediate C version, nonexistent
287 @cindex C intermediate output, nonexistent
288 G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object
289 code directly from your C++ program source. There is no intermediate C
290 version of the program. (By contrast, for example, some other
291 implementations use a program that generates a C program from your C++
292 source.) Avoiding an intermediate C representation of the program means
293 that you get better object code, and better debugging information. The
294 GNU debugger, GDB, works with this information in the object code to
295 give you comprehensive C++ source-level editing capabilities
296 (@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
298 @c FIXME! Someone who knows something about Objective C ought to put in
299 @c a paragraph or two about it here, and move the index entry down when
300 @c there is more to point to than the general mention in the 1st par.
304 @include install.texi
311 @chapter Known Causes of Trouble with GNU CC
313 @cindex installation trouble
314 @cindex known causes of trouble
316 This section describes known problems that affect users of GNU CC. Most
317 of these are not GNU CC bugs per se---if they were, we would fix them.
318 But the result for a user may be like the result of a bug.
320 Some of these problems are due to bugs in other software, some are
321 missing features that are too much work to add, and some are places
322 where people's opinions differ as to what is best.
325 * Actual Bugs:: Bugs we will fix later.
326 * Installation Problems:: Problems that manifest when you install GNU CC.
327 * Cross-Compiler Problems:: Common problems of cross compiling with GNU CC.
328 * Interoperation:: Problems using GNU CC with other compilers,
329 and with certain linkers, assemblers and debuggers.
330 * External Bugs:: Problems compiling certain programs.
331 * Incompatibilities:: GNU CC is incompatible with traditional C.
332 * Fixed Headers:: GNU C uses corrected versions of system header files.
333 This is necessary, but doesn't always work smoothly.
334 * Standard Libraries:: GNU C uses the system C library, which might not be
335 compliant with the ISO/ANSI C standard.
336 * Disappointments:: Regrettable things we can't change, but not quite bugs.
337 * C++ Misunderstandings:: Common misunderstandings with GNU C++.
338 * Protoize Caveats:: Things to watch out for when using @code{protoize}.
339 * Non-bugs:: Things we think are right, but some others disagree.
340 * Warnings and Errors:: Which problems in your code get warnings,
341 and which get errors.
345 @section Actual Bugs We Haven't Fixed Yet
349 The @code{fixincludes} script interacts badly with automounters; if the
350 directory of system header files is automounted, it tends to be
351 unmounted while @code{fixincludes} is running. This would seem to be a
352 bug in the automounter. We don't know any good way to work around it.
355 The @code{fixproto} script will sometimes add prototypes for the
356 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
357 @code{jmp_buf} type before that type is defined. To work around this,
358 edit the offending file and place the typedef in front of the
362 There are several obscure case of mis-using struct, union, and
363 enum tags that are not detected as errors by the compiler.
366 When @samp{-pedantic-errors} is specified, GNU C will incorrectly give
367 an error message when a function name is specified in an expression
368 involving the comma operator.
371 Loop unrolling doesn't work properly for certain C++ programs. This is
372 a bug in the C++ front end. It sometimes emits incorrect debug info, and
373 the loop unrolling code is unable to recover from this error.
376 @node Installation Problems
377 @section Installation Problems
379 This is a list of problems (and some apparent problems which don't
380 really mean anything is wrong) that show up during installation of GNU
385 On certain systems, defining certain environment variables such as
386 @code{CC} can interfere with the functioning of @code{make}.
389 If you encounter seemingly strange errors when trying to build the
390 compiler in a directory other than the source directory, it could be
391 because you have previously configured the compiler in the source
392 directory. Make sure you have done all the necessary preparations.
396 If you build GNU CC on a BSD system using a directory stored in a System
397 V file system, problems may occur in running @code{fixincludes} if the
398 System V file system doesn't support symbolic links. These problems
399 result in a failure to fix the declaration of @code{size_t} in
400 @file{sys/types.h}. If you find that @code{size_t} is a signed type and
401 that type mismatches occur, this could be the cause.
403 The solution is not to use such a directory for building GNU CC.
406 In previous versions of GNU CC, the @code{gcc} driver program looked for
407 @code{as} and @code{ld} in various places; for example, in files
408 beginning with @file{/usr/local/lib/gcc-}. GNU CC version 2 looks for
409 them in the directory
410 @file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}.
412 Thus, to use a version of @code{as} or @code{ld} that is not the system
413 default, for example @code{gas} or GNU @code{ld}, you must put them in
414 that directory (or make links to them from that directory).
417 Some commands executed when making the compiler may fail (return a
418 non-zero status) and be ignored by @code{make}. These failures, which
419 are often due to files that were not found, are expected, and can safely
423 It is normal to have warnings in compiling certain files about
424 unreachable code and about enumeration type clashes. These files' names
425 begin with @samp{insn-}. Also, @file{real.c} may get some warnings that
429 Sometimes @code{make} recompiles parts of the compiler when installing
430 the compiler. In one case, this was traced down to a bug in
431 @code{make}. Either ignore the problem or switch to GNU Make.
434 If you have installed a program known as purify, you may find that it
435 causes errors while linking @code{enquire}, which is part of building
436 GNU CC. The fix is to get rid of the file @code{real-ld} which purify
437 installs---so that GNU CC won't try to use it.
440 On GNU/Linux SLS 1.01, there is a problem with @file{libc.a}: it does not
441 contain the obstack functions. However, GNU CC assumes that the obstack
442 functions are in @file{libc.a} when it is the GNU C library. To work
443 around this problem, change the @code{__GNU_LIBRARY__} conditional
444 around line 31 to @samp{#if 1}.
447 On some 386 systems, building the compiler never finishes because
448 @code{enquire} hangs due to a hardware problem in the motherboard---it
449 reports floating point exceptions to the kernel incorrectly. You can
450 install GNU CC except for @file{float.h} by patching out the command to
451 run @code{enquire}. You may also be able to fix the problem for real by
452 getting a replacement motherboard. This problem was observed in
453 Revision E of the Micronics motherboard, and is fixed in Revision F.
454 It has also been observed in the MYLEX MXA-33 motherboard.
456 If you encounter this problem, you may also want to consider removing
457 the FPU from the socket during the compilation. Alternatively, if you
458 are running SCO Unix, you can reboot and force the FPU to be ignored.
459 To do this, type @samp{hd(40)unix auto ignorefpu}.
462 On some 386 systems, GNU CC crashes trying to compile @file{enquire.c}.
463 This happens on machines that don't have a 387 FPU chip. On 386
464 machines, the system kernel is supposed to emulate the 387 when you
465 don't have one. The crash is due to a bug in the emulator.
467 One of these systems is the Unix from Interactive Systems: 386/ix.
468 On this system, an alternate emulator is provided, and it does work.
469 To use it, execute this command as super-user:
472 ln /etc/emulator.rel1 /etc/emulator
476 and then reboot the system. (The default emulator file remains present
477 under the name @file{emulator.dflt}.)
479 Try using @file{/etc/emulator.att}, if you have such a problem on the
482 Another system which has this problem is Esix. We don't know whether it
483 has an alternate emulator that works.
485 On NetBSD 0.8, a similar problem manifests itself as these error messages:
488 enquire.c: In function `fprop':
489 enquire.c:2328: floating overflow
493 On SCO systems, when compiling GNU CC with the system's compiler,
494 do not use @samp{-O}. Some versions of the system's compiler miscompile
495 GNU CC with @samp{-O}.
497 @cindex @code{genflags}, crash on Sun 4
499 Sometimes on a Sun 4 you may observe a crash in the program
500 @code{genflags} or @code{genoutput} while building GNU CC. This is said to
501 be due to a bug in @code{sh}. You can probably get around it by running
502 @code{genflags} or @code{genoutput} manually and then retrying the
506 On Solaris 2, executables of GNU CC version 2.0.2 are commonly
507 available, but they have a bug that shows up when compiling current
508 versions of GNU CC: undefined symbol errors occur during assembly if you
511 The solution is to compile the current version of GNU CC without
512 @samp{-g}. That makes a working compiler which you can use to recompile
516 Solaris 2 comes with a number of optional OS packages. Some of these
517 packages are needed to use GNU CC fully. If you did not install all
518 optional packages when installing Solaris, you will need to verify that
519 the packages that GNU CC needs are installed.
521 To check whether an optional package is installed, use
522 the @code{pkginfo} command. To add an optional package, use the
523 @code{pkgadd} command. For further details, see the Solaris
526 For Solaris 2.0 and 2.1, GNU CC needs six packages: @samp{SUNWarc},
527 @samp{SUNWbtool}, @samp{SUNWesu}, @samp{SUNWhea}, @samp{SUNWlibm}, and
530 For Solaris 2.2, GNU CC needs an additional seventh package: @samp{SUNWsprot}.
533 On Solaris 2, trying to use the linker and other tools in
534 @file{/usr/ucb} to install GNU CC has been observed to cause trouble.
535 For example, the linker may hang indefinitely. The fix is to remove
536 @file{/usr/ucb} from your @code{PATH}.
539 If you use the 1.31 version of the MIPS assembler (such as was shipped
540 with Ultrix 3.1), you will need to use the -fno-delayed-branch switch
541 when optimizing floating point code. Otherwise, the assembler will
542 complain when the GCC compiler fills a branch delay slot with a
543 floating point instruction, such as @code{add.d}.
546 If on a MIPS system you get an error message saying ``does not have gp
547 sections for all it's [sic] sectons [sic]'', don't worry about it. This
548 happens whenever you use GAS with the MIPS linker, but there is not
549 really anything wrong, and it is okay to use the output file. You can
550 stop such warnings by installing the GNU linker.
552 It would be nice to extend GAS to produce the gp tables, but they are
553 optional, and there should not be a warning about their absence.
556 In Ultrix 4.0 on the MIPS machine, @file{stdio.h} does not work with GNU
557 CC at all unless it has been fixed with @code{fixincludes}. This causes
558 problems in building GNU CC. Once GNU CC is installed, the problems go
561 To work around this problem, when making the stage 1 compiler, specify
565 GCC_FOR_TARGET="./xgcc -B./ -I./include"
568 When making stage 2 and stage 3, specify this option:
571 CFLAGS="-g -I./include"
575 Users have reported some problems with version 2.0 of the MIPS
576 compiler tools that were shipped with Ultrix 4.1. Version 2.10
577 which came with Ultrix 4.2 seems to work fine.
579 Users have also reported some problems with version 2.20 of the
580 MIPS compiler tools that were shipped with RISC/os 4.x. The earlier
581 version 2.11 seems to work fine.
584 Some versions of the MIPS linker will issue an assertion failure
585 when linking code that uses @code{alloca} against shared
586 libraries on RISC-OS 5.0, and DEC's OSF/1 systems. This is a bug
587 in the linker, that is supposed to be fixed in future revisions.
588 To protect against this, GNU CC passes @samp{-non_shared} to the
589 linker unless you pass an explicit @samp{-shared} or
590 @samp{-call_shared} switch.
593 On System V release 3, you may get this error message
597 ld fatal: failed to write symbol name @var{something}
598 in strings table for file @var{whatever}
601 This probably indicates that the disk is full or your ULIMIT won't allow
602 the file to be as large as it needs to be.
604 This problem can also result because the kernel parameter @code{MAXUMEM}
605 is too small. If so, you must regenerate the kernel and make the value
606 much larger. The default value is reported to be 1024; a value of 32768
607 is said to work. Smaller values may also work.
610 On System V, if you get an error like this,
613 /usr/local/lib/bison.simple: In function `yyparse':
614 /usr/local/lib/bison.simple:625: virtual memory exhausted
618 that too indicates a problem with disk space, ULIMIT, or @code{MAXUMEM}.
621 Current GNU CC versions probably do not work on version 2 of the NeXT
625 On NeXTStep 3.0, the Objective C compiler does not work, due,
626 apparently, to a kernel bug that it happens to trigger. This problem
627 does not happen on 3.1.
630 On the Tower models 4@var{n}0 and 6@var{n}0, by default a process is not
631 allowed to have more than one megabyte of memory. GNU CC cannot compile
632 itself (or many other programs) with @samp{-O} in that much memory.
634 To solve this problem, reconfigure the kernel adding the following line
635 to the configuration file:
642 On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a bug
643 in the assembler that must be fixed before GNU CC can be built. This
644 bug manifests itself during the first stage of compilation, while
645 building @file{libgcc2.a}:
649 cc1: warning: `-g' option not supported on this version of GCC
650 cc1: warning: `-g1' option not supported on this version of GCC
651 ./xgcc: Internal compiler error: program as got fatal signal 11
654 A patched version of the assembler is available by anonymous ftp from
655 @code{altdorf.ai.mit.edu} as the file
656 @file{archive/cph/hpux-8.0-assembler}. If you have HP software support,
657 the patch can also be obtained directly from HP, as described in the
661 This is the patched assembler, to patch SR#1653-010439, where the
662 assembler aborts on floating point constants.
664 The bug is not really in the assembler, but in the shared library
665 version of the function ``cvtnum(3c)''. The bug on ``cvtnum(3c)'' is
666 SR#4701-078451. Anyway, the attached assembler uses the archive
667 library version of ``cvtnum(3c)'' and thus does not exhibit the bug.
670 This patch is also known as PHCO_4484.
673 On HP-UX version 8.05, but not on 8.07 or more recent versions,
674 the @code{fixproto} shell script triggers a bug in the system shell.
675 If you encounter this problem, upgrade your operating system or
676 use BASH (the GNU shell) to run @code{fixproto}.
679 Some versions of the Pyramid C compiler are reported to be unable to
680 compile GNU CC. You must use an older version of GNU CC for
681 bootstrapping. One indication of this problem is if you get a crash
682 when GNU CC compiles the function @code{muldi3} in file @file{libgcc2.c}.
684 You may be able to succeed by getting GNU CC version 1, installing it,
685 and using it to compile GNU CC version 2. The bug in the Pyramid C
686 compiler does not seem to affect GNU CC version 1.
689 There may be similar problems on System V Release 3.1 on 386 systems.
692 On the Intel Paragon (an i860 machine), if you are using operating
693 system version 1.0, you will get warnings or errors about redefinition
694 of @code{va_arg} when you build GNU CC.
696 If this happens, then you need to link most programs with the library
697 @file{iclib.a}. You must also modify @file{stdio.h} as follows: before
701 #if defined(__i860__) && !defined(_VA_LIST)
716 extern int vprintf(const char *, va_list );
717 extern int vsprintf(char *, const char *, va_list );
728 These problems don't exist in operating system version 1.1.
731 On the Altos 3068, programs compiled with GNU CC won't work unless you
732 fix a kernel bug. This happens using system versions V.2.2 1.0gT1 and
733 V.2.2 1.0e and perhaps later versions as well. See the file
737 You will get several sorts of compilation and linking errors on the
738 we32k if you don't follow the special instructions. @xref{Configurations}.
741 A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto
742 program to report an error of the form:
745 ./fixproto: sh internal 1K buffer overflow
748 To fix this, change the first line of the fixproto script to look like:
755 @node Cross-Compiler Problems
756 @section Cross-Compiler Problems
758 You may run into problems with cross compilation on certain machines,
763 Cross compilation can run into trouble for certain machines because
764 some target machines' assemblers require floating point numbers to be
765 written as @emph{integer} constants in certain contexts.
767 The compiler writes these integer constants by examining the floating
768 point value as an integer and printing that integer, because this is
769 simple to write and independent of the details of the floating point
770 representation. But this does not work if the compiler is running on
771 a different machine with an incompatible floating point format, or
772 even a different byte-ordering.
774 In addition, correct constant folding of floating point values
775 requires representing them in the target machine's format.
776 (The C standard does not quite require this, but in practice
777 it is the only way to win.)
779 It is now possible to overcome these problems by defining macros such
780 as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
781 work for each target machine.
783 @xref{Cross-compilation}.
786 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
787 gcc.info, Using and Porting GCC}.
791 At present, the program @file{mips-tfile} which adds debug
792 support to object files on MIPS systems does not work in a cross
797 @section Interoperation
799 This section lists various difficulties encountered in using GNU C or
800 GNU C++ together with other compilers or with the assemblers, linkers,
801 libraries and debuggers on certain systems.
805 Objective C does not work on the RS/6000.
808 GNU C++ does not do name mangling in the same way as other C++
809 compilers. This means that object files compiled with one compiler
810 cannot be used with another.
812 This effect is intentional, to protect you from more subtle problems.
813 Compilers differ as to many internal details of C++ implementation,
814 including: how class instances are laid out, how multiple inheritance is
815 implemented, and how virtual function calls are handled. If the name
816 encoding were made the same, your programs would link against libraries
817 provided from other compilers---but the programs would then crash when
818 run. Incompatible libraries are then detected at link time, rather than
822 Older GDB versions sometimes fail to read the output of GNU CC version
823 2. If you have trouble, get GDB version 4.4 or later.
827 DBX rejects some files produced by GNU CC, though it accepts similar
828 constructs in output from PCC. Until someone can supply a coherent
829 description of what is valid DBX input and what is not, there is
830 nothing I can do about these problems. You are on your own.
833 The GNU assembler (GAS) does not support PIC. To generate PIC code, you
834 must use some other assembler, such as @file{/bin/as}.
837 On some BSD systems, including some versions of Ultrix, use of profiling
838 causes static variable destructors (currently used only in C++) not to
842 Use of @samp{-I/usr/include} may cause trouble.
844 Many systems come with header files that won't work with GNU CC unless
845 corrected by @code{fixincludes}. The corrected header files go in a new
846 directory; GNU CC searches this directory before @file{/usr/include}.
847 If you use @samp{-I/usr/include}, this tells GNU CC to search
848 @file{/usr/include} earlier on, before the corrected headers. The
849 result is that you get the uncorrected header files.
851 Instead, you should use these options (when compiling C programs):
854 -I/usr/local/lib/gcc-lib/@var{target}/@var{version}/include -I/usr/include
857 For C++ programs, GNU CC also uses a special directory that defines C++
858 interfaces to standard C subroutines. This directory is meant to be
859 searched @emph{before} other standard include directories, so that it
860 takes precedence. If you are compiling C++ programs and specifying
861 include directories explicitly, use this option first, then the two
865 -I/usr/local/lib/g++-include
869 @cindex @code{vfork}, for the Sun-4
871 There is a bug in @code{vfork} on the Sun-4 which causes the registers
872 of the child process to clobber those of the parent. Because of this,
873 programs that call @code{vfork} are likely to lose when compiled
874 optimized with GNU CC when the child code alters registers which contain
875 C variables in the parent. This affects variables which are live in the
876 parent across the call to @code{vfork}.
878 If you encounter this, you can work around the problem by declaring
879 variables @code{volatile} in the function that calls @code{vfork}, until
880 the problem goes away, or by not declaring them @code{register} and not
881 using @samp{-O} for those source files.
885 On some SGI systems, when you use @samp{-lgl_s} as an option,
886 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
887 Naturally, this does not happen when you use GNU CC.
888 You must specify all three options explicitly.
891 On a Sparc, GNU CC aligns all values of type @code{double} on an 8-byte
892 boundary, and it expects every @code{double} to be so aligned. The Sun
893 compiler usually gives @code{double} values 8-byte alignment, with one
894 exception: function arguments of type @code{double} may not be aligned.
896 As a result, if a function compiled with Sun CC takes the address of an
897 argument of type @code{double} and passes this pointer of type
898 @code{double *} to a function compiled with GNU CC, dereferencing the
899 pointer may cause a fatal signal.
901 One way to solve this problem is to compile your entire program with GNU
902 CC. Another solution is to modify the function that is compiled with
903 Sun CC to copy the argument into a local variable; local variables
904 are always properly aligned. A third solution is to modify the function
905 that uses the pointer to dereference it via the following function
906 @code{access_double} instead of directly with @samp{*}:
910 access_double (double *unaligned_ptr)
912 union d2i @{ double d; int i[2]; @};
914 union d2i *p = (union d2i *) unaligned_ptr;
925 Storing into the pointer can be done likewise with the same union.
928 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
929 may allocate memory that is only 4 byte aligned. Since GNU CC on the
930 Sparc assumes that doubles are 8 byte aligned, this may result in a
931 fatal signal if doubles are stored in memory allocated by the
932 @file{libmalloc.a} library.
934 The solution is to not use the @file{libmalloc.a} library. Use instead
935 @code{malloc} and related functions from @file{libc.a}; they do not have
939 Sun forgot to include a static version of @file{libdl.a} with some
940 versions of SunOS (mainly 4.1). This results in undefined symbols when
941 linking static binaries (that is, if you use @samp{-static}). If you
942 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
943 when linking, compile and link against the file
944 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
947 The 128-bit long double format that the Sparc port supports currently
948 works by using the architecturally defined quad-word floating point
949 instructions. Since there is no hardware that supports these
950 instructions they must be emulated by the operating system. Long
951 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
952 kernel emulator uses an obsolete and incompatible format. Long doubles
953 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
954 Long doubles do work on Sun OS versions 4.1.2 and higher, but GNU CC
955 does not enable them by default. Long doubles appear to work in Sun OS
959 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
960 compile GNU CC correctly. We do not yet know why. However, GNU CC
961 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
962 compile itself properly on 9.01.
965 On the HP PA machine, ADB sometimes fails to work on functions compiled
966 with GNU CC. Specifically, it fails to work on functions that use
967 @code{alloca} or variable-size arrays. This is because GNU CC doesn't
968 generate HP-UX unwind descriptors for such functions. It may even be
969 impossible to generate them.
972 Debugging (@samp{-g}) is not supported on the HP PA machine, unless you use
973 the preliminary GNU tools (@pxref{Installation}).
976 Taking the address of a label may generate errors from the HP-UX
977 PA assembler. GAS for the PA does not have this problem.
980 Using floating point parameters for indirect calls to static functions
981 will not work when using the HP assembler. There simply is no way for GCC
982 to specify what registers hold arguments for static functions when using
983 the HP assembler. GAS for the PA does not have this problem.
986 In extremely rare cases involving some very large functions you may
987 receive errors from the HP linker complaining about an out of bounds
988 unconditional branch offset. This used to occur more often in previous
989 versions of GNU CC, but is now exceptionally rare. If you should run
990 into it, you can work around by making your function smaller.
993 GNU CC compiled code sometimes emits warnings from the HP-UX assembler of
997 (warning) Use of GR3 when
998 frame >= 8192 may cause conflict.
1001 These warnings are harmless and can be safely ignored.
1004 The current version of the assembler (@file{/bin/as}) for the RS/6000
1005 has certain problems that prevent the @samp{-g} option in GCC from
1006 working. Note that @file{Makefile.in} uses @samp{-g} by default when
1007 compiling @file{libgcc2.c}.
1009 IBM has produced a fixed version of the assembler. The upgraded
1010 assembler unfortunately was not included in any of the AIX 3.2 update
1011 PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request
1012 PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
1013 See the file @file{README.RS6000} for more details on these updates.
1015 You can test for the presense of a fixed assembler by using the
1023 If the command exits normally, the assembler fix already is installed.
1024 If the assembler complains that "-u" is an unknown flag, you need to
1028 On the IBM RS/6000, compiling code of the form
1039 will cause the linker to report an undefined symbol @code{foo}.
1040 Although this behavior differs from most other systems, it is not a
1041 bug because redefining an @code{extern} variable as @code{static}
1042 is undefined in ANSI C.
1045 AIX on the RS/6000 provides support (NLS) for environments outside of
1046 the United States. Compilers and assemblers use NLS to support
1047 locale-specific representations of various objects including
1048 floating-point numbers ("." vs "," for separating decimal fractions).
1049 There have been problems reported where the library linked with GCC does
1050 not produce the same floating-point formats that the assembler accepts.
1051 If you have this problem, set the LANG environment variable to "C" or
1055 Even if you specify @samp{-fdollars-in-identifiers},
1056 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
1057 to a restriction in the IBM assembler. GAS supports these
1061 On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC
1062 version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2
1063 by requesting PTF 421749 from IBM.
1066 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
1067 occurs when the @samp{fldcr} instruction is used. GNU CC uses
1068 @samp{fldcr} on the 88100 to serialize volatile memory references. Use
1069 the option @samp{-mno-serialize-volatile} if your version of the
1070 assembler has this bug.
1073 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
1074 messages from the linker. These warning messages complain of mismatched
1075 psect attributes. You can ignore them. @xref{VMS Install}.
1078 On NewsOS version 3, if you include both of the files @file{stddef.h}
1079 and @file{sys/types.h}, you get an error because there are two typedefs
1080 of @code{size_t}. You should change @file{sys/types.h} by adding these
1081 lines around the definition of @code{size_t}:
1086 @var{actual typedef here}
1092 On the Alliant, the system's own convention for returning structures
1093 and unions is unusual, and is not compatible with GNU CC no matter
1094 what options are used.
1099 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
1100 convention for structure and union returning. Use the option
1101 @samp{-mhc-struct-return} to tell GNU CC to use a convention compatible
1104 @cindex Vax calling convention
1105 @cindex Ultrix calling convention
1107 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
1108 by function calls. However, the C compiler uses conventions compatible
1109 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
1111 GNU CC uses the same convention as the Ultrix C compiler. You can use
1112 these options to produce code compatible with the Fortran compiler:
1115 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
1119 On the WE32k, you may find that programs compiled with GNU CC do not
1120 work with the standard shared C library. You may need to link with
1121 the ordinary C compiler. If you do so, you must specify the following
1125 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
1128 The first specifies where to find the library @file{libgcc.a}
1129 specified with the @samp{-lgcc} option.
1131 GNU CC does linking by invoking @code{ld}, just as @code{cc} does, and
1132 there is no reason why it @emph{should} matter which compilation program
1133 you use to invoke @code{ld}. If someone tracks this problem down,
1134 it can probably be fixed easily.
1137 On the Alpha, you may get assembler errors about invalid syntax as a
1138 result of floating point constants. This is due to a bug in the C
1139 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid
1140 floating point numbers, they sometimes print @samp{NaN}.
1143 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
1144 sometimes reorders instructions incorrectly when optimization is turned
1145 on. If you think this may be happening to you, try using the GNU
1146 assembler; GAS version 2.1 supports ECOFF on Irix.
1148 Or use the @samp{-noasmopt} option when you compile GNU CC with itself,
1149 and then again when you compile your program. (This is a temporary
1150 kludge to turn off assembler optimization on Irix.) If this proves to
1151 be what you need, edit the assembler spec in the file @file{specs} so
1152 that it unconditionally passes @samp{-O0} to the assembler, and never
1153 passes @samp{-O2} or @samp{-O3}.
1157 @section Problems Compiling Certain Programs
1159 @c prevent bad page break with this line
1160 Certain programs have problems compiling.
1164 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
1165 because of problems in DEC's versions of the X11 header files
1166 @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
1167 @samp{-I/usr/include/mit} to use the MIT versions of the header files,
1168 using the @samp{-traditional} switch to turn off ANSI C, or fixing the
1169 header files by adding this:
1173 #define NeedFunctionPrototypes 0
1178 If you have trouble compiling Perl on a SunOS 4 system, it may be
1179 because Perl specifies @samp{-I/usr/ucbinclude}. This accesses the
1180 unfixed header files. Perl specifies the options
1183 -traditional -Dvolatile=__volatile__
1184 -I/usr/include/sun -I/usr/ucbinclude
1189 most of which are unnecessary with GCC 2.4.5 and newer versions. You
1190 can make a properly working Perl by setting @code{ccflags} to
1191 @samp{-fwritable-strings} (implied by the @samp{-traditional} in the
1192 original options) and @code{cppflags} to empty in @file{config.sh}, then
1193 typing @samp{./doSH; make depend; make}.
1196 On various 386 Unix systems derived from System V, including SCO, ISC,
1197 and ESIX, you may get error messages about running out of virtual memory
1198 while compiling certain programs.
1200 You can prevent this problem by linking GNU CC with the GNU malloc
1201 (which thus replaces the malloc that comes with the system). GNU malloc
1202 is available as a separate package, and also in the file
1203 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
1205 If you have installed GNU malloc as a separate library package, use this
1206 option when you relink GNU CC:
1209 MALLOC=/usr/local/lib/libgmalloc.a
1212 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
1213 the object file to @file{gmalloc.o} and use this option when you relink
1221 @node Incompatibilities
1222 @section Incompatibilities of GNU CC
1223 @cindex incompatibilities of GNU CC
1225 There are several noteworthy incompatibilities between GNU C and most
1226 existing (non-ANSI) versions of C. The @samp{-traditional} option
1227 eliminates many of these incompatibilities, @emph{but not all}, by
1228 telling GNU C to behave like the other C compilers.
1231 @cindex string constants
1232 @cindex read-only strings
1233 @cindex shared strings
1235 GNU CC normally makes string constants read-only. If several
1236 identical-looking string constants are used, GNU CC stores only one
1239 @cindex @code{mktemp}, and constant strings
1240 One consequence is that you cannot call @code{mktemp} with a string
1241 constant argument. The function @code{mktemp} always alters the
1242 string its argument points to.
1244 @cindex @code{sscanf}, and constant strings
1245 @cindex @code{fscanf}, and constant strings
1246 @cindex @code{scanf}, and constant strings
1247 Another consequence is that @code{sscanf} does not work on some systems
1248 when passed a string constant as its format control string or input.
1249 This is because @code{sscanf} incorrectly tries to write into the string
1250 constant. Likewise @code{fscanf} and @code{scanf}.
1252 The best solution to these problems is to change the program to use
1253 @code{char}-array variables with initialization strings for these
1254 purposes instead of string constants. But if this is not possible,
1255 you can use the @samp{-fwritable-strings} flag, which directs GNU CC
1256 to handle string constants the same way most C compilers do.
1257 @samp{-traditional} also has this effect, among others.
1260 @code{-2147483648} is positive.
1262 This is because 2147483648 cannot fit in the type @code{int}, so
1263 (following the ANSI C rules) its data type is @code{unsigned long int}.
1264 Negating this value yields 2147483648 again.
1267 GNU CC does not substitute macro arguments when they appear inside of
1268 string constants. For example, the following macro in GNU CC
1275 will produce output @code{"a"} regardless of what the argument @var{a} is.
1277 The @samp{-traditional} option directs GNU CC to handle such cases
1278 (among others) in the old-fashioned (non-ANSI) fashion.
1280 @cindex @code{setjmp} incompatibilities
1281 @cindex @code{longjmp} incompatibilities
1283 When you use @code{setjmp} and @code{longjmp}, the only automatic
1284 variables guaranteed to remain valid are those declared
1285 @code{volatile}. This is a consequence of automatic register
1286 allocation. Consider this function:
1300 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
1305 Here @code{a} may or may not be restored to its first value when the
1306 @code{longjmp} occurs. If @code{a} is allocated in a register, then
1307 its first value is restored; otherwise, it keeps the last value stored
1310 If you use the @samp{-W} option with the @samp{-O} option, you will
1311 get a warning when GNU CC thinks such a problem might be possible.
1313 The @samp{-traditional} option directs GNU C to put variables in
1314 the stack by default, rather than in registers, in functions that
1315 call @code{setjmp}. This results in the behavior found in
1316 traditional C compilers.
1319 Programs that use preprocessing directives in the middle of macro
1320 arguments do not work with GNU CC. For example, a program like this
1329 ANSI C does not permit such a construct. It would make sense to support
1330 it when @samp{-traditional} is used, but it is too much work to
1333 @cindex external declaration scope
1334 @cindex scope of external declarations
1335 @cindex declaration scope
1337 Declarations of external variables and functions within a block apply
1338 only to the block containing the declaration. In other words, they
1339 have the same scope as any other declaration in the same place.
1341 In some other C compilers, a @code{extern} declaration affects all the
1342 rest of the file even if it happens within a block.
1344 The @samp{-traditional} option directs GNU C to treat all @code{extern}
1345 declarations as global, like traditional compilers.
1348 In traditional C, you can combine @code{long}, etc., with a typedef name,
1353 typedef long foo bar;
1356 In ANSI C, this is not allowed: @code{long} and other type modifiers
1357 require an explicit @code{int}. Because this criterion is expressed
1358 by Bison grammar rules rather than C code, the @samp{-traditional}
1359 flag cannot alter it.
1361 @cindex typedef names as function parameters
1363 PCC allows typedef names to be used as function parameters. The
1364 difficulty described immediately above applies here too.
1368 PCC allows whitespace in the middle of compound assignment operators
1369 such as @samp{+=}. GNU CC, following the ANSI standard, does not
1370 allow this. The difficulty described immediately above applies here
1376 GNU CC complains about unterminated character constants inside of
1377 preprocessing conditionals that fail. Some programs have English
1378 comments enclosed in conditionals that are guaranteed to fail; if these
1379 comments contain apostrophes, GNU CC will probably report an error. For
1380 example, this code would produce an error:
1384 You can't expect this to work.
1388 The best solution to such a problem is to put the text into an actual
1389 C comment delimited by @samp{/*@dots{}*/}. However,
1390 @samp{-traditional} suppresses these error messages.
1393 Many user programs contain the declaration @samp{long time ();}. In the
1394 past, the system header files on many systems did not actually declare
1395 @code{time}, so it did not matter what type your program declared it to
1396 return. But in systems with ANSI C headers, @code{time} is declared to
1397 return @code{time_t}, and if that is not the same as @code{long}, then
1398 @samp{long time ();} is erroneous.
1400 The solution is to change your program to use @code{time_t} as the return
1401 type of @code{time}.
1403 @cindex @code{float} as function value type
1405 When compiling functions that return @code{float}, PCC converts it to
1406 a double. GNU CC actually returns a @code{float}. If you are concerned
1407 with PCC compatibility, you should declare your functions to return
1408 @code{double}; you might as well say what you mean.
1413 When compiling functions that return structures or unions, GNU CC
1414 output code normally uses a method different from that used on most
1415 versions of Unix. As a result, code compiled with GNU CC cannot call
1416 a structure-returning function compiled with PCC, and vice versa.
1418 The method used by GNU CC is as follows: a structure or union which is
1419 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
1420 with any other size is stored into an address supplied by the caller
1421 (usually in a special, fixed register, but on some machines it is passed
1422 on the stack). The machine-description macros @code{STRUCT_VALUE} and
1423 @code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address.
1425 By contrast, PCC on most target machines returns structures and unions
1426 of any size by copying the data into an area of static storage, and then
1427 returning the address of that storage as if it were a pointer value.
1428 The caller must copy the data from that memory area to the place where
1429 the value is wanted. GNU CC does not use this method because it is
1430 slower and nonreentrant.
1432 On some newer machines, PCC uses a reentrant convention for all
1433 structure and union returning. GNU CC on most of these machines uses a
1434 compatible convention when returning structures and unions in memory,
1435 but still returns small structures and unions in registers.
1437 You can tell GNU CC to use a compatible convention for all structure and
1438 union returning with the option @samp{-fpcc-struct-return}.
1440 @cindex preprocessing tokens
1441 @cindex preprocessing numbers
1443 GNU C complains about program fragments such as @samp{0x74ae-0x4000}
1444 which appear to be two hexadecimal constants separated by the minus
1445 operator. Actually, this string is a single @dfn{preprocessing token}.
1446 Each such token must correspond to one token in C. Since this does not,
1447 GNU C prints an error message. Although it may appear obvious that what
1448 is meant is an operator and two values, the ANSI C standard specifically
1449 requires that this be treated as erroneous.
1451 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
1452 begins with a digit and is followed by letters, underscores, digits,
1453 periods and @samp{e+}, @samp{e-}, @samp{E+}, or @samp{E-} character
1456 To make the above program fragment valid, place whitespace in front of
1457 the minus sign. This whitespace will end the preprocessing number.
1461 @section Fixed Header Files
1463 GNU CC needs to install corrected versions of some system header files.
1464 This is because most target systems have some header files that won't
1465 work with GNU CC unless they are changed. Some have bugs, some are
1466 incompatible with ANSI C, and some depend on special features of other
1469 Installing GNU CC automatically creates and installs the fixed header
1470 files, by running a program called @code{fixincludes} (or for certain
1471 targets an alternative such as @code{fixinc.svr4}). Normally, you
1472 don't need to pay attention to this. But there are cases where it
1473 doesn't do the right thing automatically.
1477 If you update the system's header files, such as by installing a new
1478 system version, the fixed header files of GNU CC are not automatically
1479 updated. The easiest way to update them is to reinstall GNU CC. (If
1480 you want to be clever, look in the makefile and you can find a
1484 On some systems, in particular SunOS 4, header file directories contain
1485 machine-specific symbolic links in certain places. This makes it
1486 possible to share most of the header files among hosts running the
1487 same version of SunOS 4 on different machine models.
1489 The programs that fix the header files do not understand this special
1490 way of using symbolic links; therefore, the directory of fixed header
1491 files is good only for the machine model used to build it.
1493 In SunOS 4, only programs that look inside the kernel will notice the
1494 difference between machine models. Therefore, for most purposes, you
1495 need not be concerned about this.
1497 It is possible to make separate sets of fixed header files for the
1498 different machine models, and arrange a structure of symbolic links so
1499 as to use the proper set, but you'll have to do this by hand.
1502 On Lynxos, GNU CC by default does not fix the header files. This is
1503 because bugs in the shell cause the @code{fixincludes} script to fail.
1505 This means you will encounter problems due to bugs in the system header
1506 files. It may be no comfort that they aren't GNU CC's fault, but it
1507 does mean that there's nothing for us to do about them.
1510 @node Standard Libraries
1511 @section Standard Libraries
1513 GNU CC by itself attempts to be what the ISO/ANSI C standard calls a
1514 @dfn{conforming freestanding implementation}. This means all ANSI
1515 C language features are available, as well as the contents of
1516 @file{float.h}, @file{limits.h}, @file{stdarg.h}, and
1517 @file{stddef.h}. The rest of the C library is supplied by the
1518 vendor of the operating system. If that C library doesn't conform to
1519 the C standards, then your programs might get warnings (especially when
1520 using @samp{-Wall}) that you don't expect.
1522 For example, the @code{sprintf} function on SunOS 4.1.3 returns
1523 @code{char *} while the C standard says that @code{sprintf} returns an
1524 @code{int}. The @code{fixincludes} program could make the prototype for
1525 this function match the Standard, but that would be wrong, since the
1526 function will still return @code{char *}.
1528 If you need a Standard compliant library, then you need to find one, as
1529 GNU CC does not provide one. The GNU C library (called @code{glibc})
1530 has been ported to a number of operating systems, and provides ANSI/ISO,
1531 POSIX, BSD and SystemV compatibility. You could also ask your operating
1532 system vendor if newer libraries are available.
1534 @node Disappointments
1535 @section Disappointments and Misunderstandings
1537 These problems are perhaps regrettable, but we don't know any practical
1542 Certain local variables aren't recognized by debuggers when you compile
1545 This occurs because sometimes GNU CC optimizes the variable out of
1546 existence. There is no way to tell the debugger how to compute the
1547 value such a variable ``would have had'', and it is not clear that would
1548 be desirable anyway. So GNU CC simply does not mention the eliminated
1549 variable when it writes debugging information.
1551 You have to expect a certain amount of disagreement between the
1552 executable and your source code, when you use optimization.
1554 @cindex conflicting types
1555 @cindex scope of declaration
1557 Users often think it is a bug when GNU CC reports an error for code
1561 int foo (struct mumble *);
1563 struct mumble @{ @dots{} @};
1565 int foo (struct mumble *x)
1569 This code really is erroneous, because the scope of @code{struct
1570 mumble} in the prototype is limited to the argument list containing it.
1571 It does not refer to the @code{struct mumble} defined with file scope
1572 immediately below---they are two unrelated types with similar names in
1575 But in the definition of @code{foo}, the file-scope type is used
1576 because that is available to be inherited. Thus, the definition and
1577 the prototype do not match, and you get an error.
1579 This behavior may seem silly, but it's what the ANSI standard specifies.
1580 It is easy enough for you to make your code work by moving the
1581 definition of @code{struct mumble} above the prototype. It's not worth
1582 being incompatible with ANSI C just to avoid an error for the example
1586 Accesses to bitfields even in volatile objects works by accessing larger
1587 objects, such as a byte or a word. You cannot rely on what size of
1588 object is accessed in order to read or write the bitfield; it may even
1589 vary for a given bitfield according to the precise usage.
1591 If you care about controlling the amount of memory that is accessed, use
1592 volatile but do not use bitfields.
1595 GNU CC comes with shell scripts to fix certain known problems in system
1596 header files. They install corrected copies of various header files in
1597 a special directory where only GNU CC will normally look for them. The
1598 scripts adapt to various systems by searching all the system header
1599 files for the problem cases that we know about.
1601 If new system header files are installed, nothing automatically arranges
1602 to update the corrected header files. You will have to reinstall GNU CC
1603 to fix the new header files. More specifically, go to the build
1604 directory and delete the files @file{stmp-fixinc} and
1605 @file{stmp-headers}, and the subdirectory @code{include}; then do
1606 @samp{make install} again.
1609 @cindex floating point precision
1610 On 68000 and x86 systems, for instance, you can get paradoxical results
1611 if you test the precise values of floating point numbers. For example,
1612 you can find that a floating point value which is not a NaN is not equal
1613 to itself. This results from the fact that the floating point registers
1614 hold a few more bits of precision than fit in a @code{double} in memory.
1615 Compiled code moves values between memory and floating point registers
1616 at its convenience, and moving them into memory truncates them.
1618 You can partially avoid this problem by using the @samp{-ffloat-store}
1619 option (@pxref{Optimize Options}).
1622 On the MIPS, variable argument functions using @file{varargs.h}
1623 cannot have a floating point value for the first argument. The
1624 reason for this is that in the absence of a prototype in scope,
1625 if the first argument is a floating point, it is passed in a
1626 floating point register, rather than an integer register.
1628 If the code is rewritten to use the ANSI standard @file{stdarg.h}
1629 method of variable arguments, and the prototype is in scope at
1630 the time of the call, everything will work fine.
1633 On the H8/300 and H8/300H, variable argument functions must be
1634 implemented using the ANSI standard @file{stdarg.h} method of
1635 variable arguments. Furthermore, calls to functions using @file{stdarg.h}
1636 variable arguments must have a prototype for the called function
1637 in scope at the time of the call.
1640 @node C++ Misunderstandings
1641 @section Common Misunderstandings with GNU C++
1643 @cindex misunderstandings in C++
1644 @cindex surprises in C++
1645 @cindex C++ misunderstandings
1646 C++ is a complex language and an evolving one, and its standard definition
1647 (the ANSI C++ draft standard) is also evolving. As a result,
1648 your C++ compiler may occasionally surprise you, even when its behavior is
1649 correct. This section discusses some areas that frequently give rise to
1650 questions of this sort.
1653 * Static Definitions:: Static member declarations are not definitions
1654 * Temporaries:: Temporaries may vanish before you expect
1657 @node Static Definitions
1658 @subsection Declare @emph{and} Define Static Members
1660 @cindex C++ static data, declaring and defining
1661 @cindex static data in C++, declaring and defining
1662 @cindex declaring static data in C++
1663 @cindex defining static data in C++
1664 When a class has static data members, it is not enough to @emph{declare}
1665 the static member; you must also @emph{define} it. For example:
1676 This declaration only establishes that the class @code{Foo} has an
1677 @code{int} named @code{Foo::bar}, and a member function named
1678 @code{Foo::method}. But you still need to define @emph{both}
1679 @code{method} and @code{bar} elsewhere. According to the draft ANSI
1680 standard, you must supply an initializer in one (and only one) source
1687 Other C++ compilers may not correctly implement the standard behavior.
1688 As a result, when you switch to @code{g++} from one of these compilers,
1689 you may discover that a program that appeared to work correctly in fact
1690 does not conform to the standard: @code{g++} reports as undefined
1691 symbols any static data members that lack definitions.
1694 @subsection Temporaries May Vanish Before You Expect
1696 @cindex temporaries, lifetime of
1697 @cindex portions of temporary objects, pointers to
1698 It is dangerous to use pointers or references to @emph{portions} of a
1699 temporary object. The compiler may very well delete the object before
1700 you expect it to, leaving a pointer to garbage. The most common place
1701 where this problem crops up is in classes like the libg++
1702 @code{String} class, that define a conversion function to type
1703 @code{char *} or @code{const char *}. However, any class that returns
1704 a pointer to some internal structure is potentially subject to this
1707 For example, a program may use a function @code{strfunc} that returns
1708 @code{String} objects, and another function @code{charfunc} that
1709 operates on pointers to @code{char}:
1713 void charfunc (const char *);
1717 In this situation, it may seem natural to write @w{@samp{charfunc
1718 (strfunc ());}} based on the knowledge that class @code{String} has an
1719 explicit conversion to @code{char} pointers. However, what really
1720 happens is akin to @samp{charfunc (@w{strfunc ()}.@w{convert ()});},
1721 where the @code{convert} method is a function to do the same data
1722 conversion normally performed by a cast. Since the last use of the
1723 temporary @code{String} object is the call to the conversion function,
1724 the compiler may delete that object before actually calling
1725 @code{charfunc}. The compiler has no way of knowing that deleting the
1726 @code{String} object will invalidate the pointer. The pointer then
1727 points to garbage, so that by the time @code{charfunc} is called, it
1728 gets an invalid argument.
1730 Code like this may run successfully under some other compilers,
1731 especially those that delete temporaries relatively late. However, the
1732 GNU C++ behavior is also standard-conforming, so if your program depends
1733 on late destruction of temporaries it is not portable.
1735 If you think this is surprising, you should be aware that the ANSI C++
1736 committee continues to debate the lifetime-of-temporaries problem.
1738 For now, at least, the safe way to write such code is to give the
1739 temporary a name, which forces it to remain until the end of the scope of
1740 the name. For example:
1743 String& tmp = strfunc ();
1747 @node Protoize Caveats
1748 @section Caveats of using @code{protoize}
1750 The conversion programs @code{protoize} and @code{unprotoize} can
1751 sometimes change a source file in a way that won't work unless you
1756 @code{protoize} can insert references to a type name or type tag before
1757 the definition, or in a file where they are not defined.
1759 If this happens, compiler error messages should show you where the new
1760 references are, so fixing the file by hand is straightforward.
1763 There are some C constructs which @code{protoize} cannot figure out.
1764 For example, it can't determine argument types for declaring a
1765 pointer-to-function variable; this you must do by hand. @code{protoize}
1766 inserts a comment containing @samp{???} each time it finds such a
1767 variable; so you can find all such variables by searching for this
1768 string. ANSI C does not require declaring the argument types of
1769 pointer-to-function types.
1772 Using @code{unprotoize} can easily introduce bugs. If the program
1773 relied on prototypes to bring about conversion of arguments, these
1774 conversions will not take place in the program without prototypes.
1775 One case in which you can be sure @code{unprotoize} is safe is when
1776 you are removing prototypes that were made with @code{protoize}; if
1777 the program worked before without any prototypes, it will work again
1780 You can find all the places where this problem might occur by compiling
1781 the program with the @samp{-Wconversion} option. It prints a warning
1782 whenever an argument is converted.
1785 Both conversion programs can be confused if there are macro calls in and
1786 around the text to be converted. In other words, the standard syntax
1787 for a declaration or definition must not result from expanding a macro.
1788 This problem is inherent in the design of C and cannot be fixed. If
1789 only a few functions have confusing macro calls, you can easily convert
1793 @code{protoize} cannot get the argument types for a function whose
1794 definition was not actually compiled due to preprocessing conditionals.
1795 When this happens, @code{protoize} changes nothing in regard to such
1796 a function. @code{protoize} tries to detect such instances and warn
1799 You can generally work around this problem by using @code{protoize} step
1800 by step, each time specifying a different set of @samp{-D} options for
1801 compilation, until all of the functions have been converted. There is
1802 no automatic way to verify that you have got them all, however.
1805 Confusion may result if there is an occasion to convert a function
1806 declaration or definition in a region of source code where there is more
1807 than one formal parameter list present. Thus, attempts to convert code
1808 containing multiple (conditionally compiled) versions of a single
1809 function header (in the same vicinity) may not produce the desired (or
1812 If you plan on converting source files which contain such code, it is
1813 recommended that you first make sure that each conditionally compiled
1814 region of source code which contains an alternative function header also
1815 contains at least one additional follower token (past the final right
1816 parenthesis of the function header). This should circumvent the
1820 @code{unprotoize} can become confused when trying to convert a function
1821 definition or declaration which contains a declaration for a
1822 pointer-to-function formal argument which has the same name as the
1823 function being defined or declared. We recommand you avoid such choices
1824 of formal parameter names.
1827 You might also want to correct some of the indentation by hand and break
1828 long lines. (The conversion programs don't write lines longer than
1829 eighty characters in any case.)
1833 @section Certain Changes We Don't Want to Make
1835 This section lists changes that people frequently request, but which
1836 we do not make because we think GNU CC is better without them.
1840 Checking the number and type of arguments to a function which has an
1841 old-fashioned definition and no prototype.
1843 Such a feature would work only occasionally---only for calls that appear
1844 in the same file as the called function, following the definition. The
1845 only way to check all calls reliably is to add a prototype for the
1846 function. But adding a prototype eliminates the motivation for this
1847 feature. So the feature is not worthwhile.
1850 Warning about using an expression whose type is signed as a shift count.
1852 Shift count operands are probably signed more often than unsigned.
1853 Warning about this would cause far more annoyance than good.
1856 Warning about assigning a signed value to an unsigned variable.
1858 Such assignments must be very common; warning about them would cause
1859 more annoyance than good.
1862 Warning about unreachable code.
1864 It's very common to have unreachable code in machine-generated
1865 programs. For example, this happens normally in some files of GNU C
1869 Warning when a non-void function value is ignored.
1871 Coming as I do from a Lisp background, I balk at the idea that there is
1872 something dangerous about discarding a value. There are functions that
1873 return values which some callers may find useful; it makes no sense to
1874 clutter the program with a cast to @code{void} whenever the value isn't
1878 Assuming (for optimization) that the address of an external symbol is
1881 This assumption is false on certain systems when @samp{#pragma weak} is
1885 Making @samp{-fshort-enums} the default.
1887 This would cause storage layout to be incompatible with most other C
1888 compilers. And it doesn't seem very important, given that you can get
1889 the same result in other ways. The case where it matters most is when
1890 the enumeration-valued object is inside a structure, and in that case
1891 you can specify a field width explicitly.
1894 Making bitfields unsigned by default on particular machines where ``the
1895 ABI standard'' says to do so.
1897 The ANSI C standard leaves it up to the implementation whether a bitfield
1898 declared plain @code{int} is signed or not. This in effect creates two
1899 alternative dialects of C.
1901 The GNU C compiler supports both dialects; you can specify the signed
1902 dialect with @samp{-fsigned-bitfields} and the unsigned dialect with
1903 @samp{-funsigned-bitfields}. However, this leaves open the question of
1904 which dialect to use by default.
1906 Currently, the preferred dialect makes plain bitfields signed, because
1907 this is simplest. Since @code{int} is the same as @code{signed int} in
1908 every other context, it is cleanest for them to be the same in bitfields
1911 Some computer manufacturers have published Application Binary Interface
1912 standards which specify that plain bitfields should be unsigned. It is
1913 a mistake, however, to say anything about this issue in an ABI. This is
1914 because the handling of plain bitfields distinguishes two dialects of C.
1915 Both dialects are meaningful on every type of machine. Whether a
1916 particular object file was compiled using signed bitfields or unsigned
1917 is of no concern to other object files, even if they access the same
1918 bitfields in the same data structures.
1920 A given program is written in one or the other of these two dialects.
1921 The program stands a chance to work on most any machine if it is
1922 compiled with the proper dialect. It is unlikely to work at all if
1923 compiled with the wrong dialect.
1925 Many users appreciate the GNU C compiler because it provides an
1926 environment that is uniform across machines. These users would be
1927 inconvenienced if the compiler treated plain bitfields differently on
1930 Occasionally users write programs intended only for a particular machine
1931 type. On these occasions, the users would benefit if the GNU C compiler
1932 were to support by default the same dialect as the other compilers on
1933 that machine. But such applications are rare. And users writing a
1934 program to run on more than one type of machine cannot possibly benefit
1935 from this kind of compatibility.
1937 This is why GNU CC does and will treat plain bitfields in the same
1938 fashion on all types of machines (by default).
1940 There are some arguments for making bitfields unsigned by default on all
1941 machines. If, for example, this becomes a universal de facto standard,
1942 it would make sense for GNU CC to go along with it. This is something
1943 to be considered in the future.
1945 (Of course, users strongly concerned about portability should indicate
1946 explicitly in each bitfield whether it is signed or not. In this way,
1947 they write programs which have the same meaning in both C dialects.)
1950 Undefining @code{__STDC__} when @samp{-ansi} is not used.
1952 Currently, GNU CC defines @code{__STDC__} as long as you don't use
1953 @samp{-traditional}. This provides good results in practice.
1955 Programmers normally use conditionals on @code{__STDC__} to ask whether
1956 it is safe to use certain features of ANSI C, such as function
1957 prototypes or ANSI token concatenation. Since plain @samp{gcc} supports
1958 all the features of ANSI C, the correct answer to these questions is
1961 Some users try to use @code{__STDC__} to check for the availability of
1962 certain library facilities. This is actually incorrect usage in an ANSI
1963 C program, because the ANSI C standard says that a conforming
1964 freestanding implementation should define @code{__STDC__} even though it
1965 does not have the library facilities. @samp{gcc -ansi -pedantic} is a
1966 conforming freestanding implementation, and it is therefore required to
1967 define @code{__STDC__}, even though it does not come with an ANSI C
1970 Sometimes people say that defining @code{__STDC__} in a compiler that
1971 does not completely conform to the ANSI C standard somehow violates the
1972 standard. This is illogical. The standard is a standard for compilers
1973 that claim to support ANSI C, such as @samp{gcc -ansi}---not for other
1974 compilers such as plain @samp{gcc}. Whatever the ANSI C standard says
1975 is relevant to the design of plain @samp{gcc} without @samp{-ansi} only
1976 for pragmatic reasons, not as a requirement.
1978 GNU CC normally defines @code{__STDC__} to be 1, and in addition
1979 defines @code{__STRICT_ANSI__} if you specify the @samp{-ansi} option.
1980 On some hosts, system include files use a different convention, where
1981 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
1982 conformance to the C Standard. GNU CC follows the host convention when
1983 processing system include files, but when processing user files it follows
1984 the usual GNU C convention.
1987 Undefining @code{__STDC__} in C++.
1989 Programs written to compile with C++-to-C translators get the
1990 value of @code{__STDC__} that goes with the C compiler that is
1991 subsequently used. These programs must test @code{__STDC__}
1992 to determine what kind of C preprocessor that compiler uses:
1993 whether they should concatenate tokens in the ANSI C fashion
1994 or in the traditional fashion.
1996 These programs work properly with GNU C++ if @code{__STDC__} is defined.
1997 They would not work otherwise.
1999 In addition, many header files are written to provide prototypes in ANSI
2000 C but not in traditional C. Many of these header files can work without
2001 change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
2002 is not defined, they will all fail, and will all need to be changed to
2003 test explicitly for C++ as well.
2006 Deleting ``empty'' loops.
2008 Historically, GNU CC has not deleted ``empty'' loops under the
2009 assumption that the most likely reason you would put one in a program is
2010 to have a delay, so deleting them will not make real programs run any
2013 However, the rationale here is that optimization of a nonempty loop
2014 cannot produce an empty one, which holds for C but is not always the
2017 Moreover, with @samp{-funroll-loops} small ``empty'' loops are already
2018 removed, so the current behavior is both sub-optimal and inconsistent
2019 and will change in the future.
2022 Making side effects happen in the same order as in some other compiler.
2024 @cindex side effects, order of evaluation
2025 @cindex order of evaluation, side effects
2026 It is never safe to depend on the order of evaluation of side effects.
2027 For example, a function call like this may very well behave differently
2028 from one compiler to another:
2031 void func (int, int);
2037 There is no guarantee (in either the C or the C++ standard language
2038 definitions) that the increments will be evaluated in any particular
2039 order. Either increment might happen first. @code{func} might get the
2040 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
2043 Not allowing structures with volatile fields in registers.
2045 Strictly speaking, there is no prohibition in the ANSI C standard
2046 against allowing structures with volatile fields in registers, but
2047 it does not seem to make any sense and is probably not what you wanted
2048 to do. So the compiler will give an error message in this case.
2051 @node Warnings and Errors
2052 @section Warning Messages and Error Messages
2054 @cindex error messages
2055 @cindex warnings vs errors
2056 @cindex messages, warning and error
2057 The GNU compiler can produce two kinds of diagnostics: errors and
2058 warnings. Each kind has a different purpose:
2062 @emph{Errors} report problems that make it impossible to compile your
2063 program. GNU CC reports errors with the source file name and line
2064 number where the problem is apparent.
2067 @emph{Warnings} report other unusual conditions in your code that
2068 @emph{may} indicate a problem, although compilation can (and does)
2069 proceed. Warning messages also report the source file name and line
2070 number, but include the text @samp{warning:} to distinguish them
2071 from error messages.
2074 Warnings may indicate danger points where you should check to make sure
2075 that your program really does what you intend; or the use of obsolete
2076 features; or the use of nonstandard features of GNU C or C++. Many
2077 warnings are issued only if you ask for them, with one of the @samp{-W}
2078 options (for instance, @samp{-Wall} requests a variety of useful
2081 GNU CC always tries to compile your program if possible; it never
2082 gratuitously rejects a program whose meaning is clear merely because
2083 (for instance) it fails to conform to a standard. In some cases,
2084 however, the C and C++ standards specify that certain extensions are
2085 forbidden, and a diagnostic @emph{must} be issued by a conforming
2086 compiler. The @samp{-pedantic} option tells GNU CC to issue warnings in
2087 such cases; @samp{-pedantic-errors} says to make them errors instead.
2088 This does not mean that @emph{all} non-ANSI constructs get warnings
2091 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
2092 more detail on these and related command-line options.
2095 @chapter Reporting Bugs
2097 @cindex reporting bugs
2099 Your bug reports play an essential role in making GNU CC reliable.
2101 When you encounter a problem, the first thing to do is to see if it is
2102 already known. @xref{Trouble}. If it isn't known, then you should
2105 Reporting a bug may help you by bringing a solution to your problem, or
2106 it may not. (If it does not, look in the service directory; see
2107 @ref{Service}.) In any case, the principal function of a bug report is
2108 to help the entire community by making the next version of GNU CC work
2109 better. Bug reports are your contribution to the maintenance of GNU CC.
2111 Since the maintainers are very overloaded, we cannot respond to every
2112 bug report. However, if the bug has not been fixed, we are likely to
2113 send you a patch and ask you to tell us whether it works.
2115 In order for a bug report to serve its purpose, you must include the
2116 information that makes for fixing the bug.
2119 * Criteria: Bug Criteria. Have you really found a bug?
2120 * Where: Bug Lists. Where to send your bug report.
2121 * Reporting: Bug Reporting. How to report a bug effectively.
2122 * Patches: Sending Patches. How to send a patch for GNU CC.
2123 * Known: Trouble. Known problems.
2124 * Help: Service. Where to ask for help.
2128 @section Have You Found a Bug?
2129 @cindex bug criteria
2131 If you are not sure whether you have found a bug, here are some guidelines:
2134 @cindex fatal signal
2137 If the compiler gets a fatal signal, for any input whatever, that is a
2138 compiler bug. Reliable compilers never crash.
2140 @cindex invalid assembly code
2141 @cindex assembly code, invalid
2143 If the compiler produces invalid assembly code, for any input whatever
2144 (except an @code{asm} statement), that is a compiler bug, unless the
2145 compiler reports errors (not just warnings) which would ordinarily
2146 prevent the assembler from being run.
2148 @cindex undefined behavior
2149 @cindex undefined function value
2150 @cindex increment operators
2152 If the compiler produces valid assembly code that does not correctly
2153 execute the input source code, that is a compiler bug.
2155 However, you must double-check to make sure, because you may have run
2156 into an incompatibility between GNU C and traditional C
2157 (@pxref{Incompatibilities}). These incompatibilities might be considered
2158 bugs, but they are inescapable consequences of valuable features.
2160 Or you may have a program whose behavior is undefined, which happened
2161 by chance to give the desired results with another C or C++ compiler.
2163 For example, in many nonoptimizing compilers, you can write @samp{x;}
2164 at the end of a function instead of @samp{return x;}, with the same
2165 results. But the value of the function is undefined if @code{return}
2166 is omitted; it is not a bug when GNU CC produces different results.
2168 Problems often result from expressions with two increment operators,
2169 as in @code{f (*p++, *p++)}. Your previous compiler might have
2170 interpreted that expression the way you intended; GNU CC might
2171 interpret it another way. Neither compiler is wrong. The bug is
2174 After you have localized the error to a single source line, it should
2175 be easy to check for these things. If your program is correct and
2176 well defined, you have found a compiler bug.
2179 If the compiler produces an error message for valid input, that is a
2182 @cindex invalid input
2184 If the compiler does not produce an error message for invalid input,
2185 that is a compiler bug. However, you should note that your idea of
2186 ``invalid input'' might be my idea of ``an extension'' or ``support
2187 for traditional practice''.
2190 If you are an experienced user of C or C++ compilers, your suggestions
2191 for improvement of GNU CC or GNU C++ are welcome in any case.
2195 @section Where to Report Bugs
2196 @cindex bug report mailing lists
2197 @kindex egcs-bugs@@cygnus.com
2198 Send bug reports for GNU C to @samp{egcs-bugs@@cygnus.com}.
2200 @kindex egcs-bugs@@cygnus.com
2201 @kindex egcs-bugs@@cygnus.com
2202 Send bug reports for GNU C++ and the C++ runtime libraries to
2203 @samp{egcs-bugs@@cygnus.com}.
2205 Often people think of posting bug reports to the newsgroup instead of
2206 mailing them. This appears to work, but it has one problem which can be
2207 crucial: a newsgroup posting does not contain a mail path back to the
2208 sender. Thus, if maintainers need more information, they may be unable
2209 to reach you. For this reason, you should always send bug reports by
2210 mail to the proper mailing list.
2212 As a last resort, send bug reports on paper to:
2216 Free Software Foundation
2217 59 Temple Place - Suite 330
2218 Boston, MA 02111-1307, USA
2222 @section How to Report Bugs
2223 @cindex compiler bugs, reporting
2225 The fundamental principle of reporting bugs usefully is this:
2226 @strong{report all the facts}. If you are not sure whether to state a
2227 fact or leave it out, state it!
2229 Often people omit facts because they think they know what causes the
2230 problem and they conclude that some details don't matter. Thus, you might
2231 assume that the name of the variable you use in an example does not matter.
2232 Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
2233 stray memory reference which happens to fetch from the location where that
2234 name is stored in memory; perhaps, if the name were different, the contents
2235 of that location would fool the compiler into doing the right thing despite
2236 the bug. Play it safe and give a specific, complete example. That is the
2237 easiest thing for you to do, and the most helpful.
2239 Keep in mind that the purpose of a bug report is to enable someone to
2240 fix the bug if it is not known. It isn't very important what happens if
2241 the bug is already known. Therefore, always write your bug reports on
2242 the assumption that the bug is not known.
2244 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2245 bell?'' This cannot help us fix a bug, so it is basically useless. We
2246 respond by asking for enough details to enable us to investigate.
2247 You might as well expedite matters by sending them to begin with.
2249 Try to make your bug report self-contained. If we have to ask you for
2250 more information, it is best if you include all the previous information
2251 in your response, as well as the information that was missing.
2253 Please report each bug in a separate message. This makes it easier for
2254 us to track which bugs have been fixed and to forward your bugs reports
2255 to the appropriate maintainer.
2257 If you include source code in your message, you can send it as clear
2258 text if it is small. If the message is larger, you may compress it using
2259 @file{gzip}, @file{bzip2}, or @file{pkzip}. Please be aware that sending
2260 compressed files needs an additional binary-safe mechanism such as
2261 @code{MIME} or @code{uuencode}. There is a 40k message soft limit on the
2262 @samp{egcs-bugs@@cygnus.com} mailing list at the time of this writing
2263 (August 1998). However, if you can't reduce a bug report to less than
2264 that, post it anyway; it will be manually approved as long as it is
2265 compressed. Don't think that posting a URL to the code is better, we do
2266 want to archive bug reports, and not all maintainers have good network
2267 connectivity to download large pieces of software when they need them;
2268 it's much easier for them to have them in their mailboxes.
2270 To enable someone to investigate the bug, you should include all these
2275 The version of GNU CC. You can get this by running it with the
2278 Without this, we won't know whether there is any point in looking for
2279 the bug in the current version of GNU CC.
2282 A complete input file that will reproduce the bug. If the bug is in the
2283 C preprocessor, send a source file and any header files that it
2284 requires. If the bug is in the compiler proper (@file{cc1}), send the
2285 preprocessor output generated by adding @samp{-save-temps} to the
2286 compilation command (@pxref{Debugging Options}). When you do this, use
2287 the same @samp{-I}, @samp{-D} or @samp{-U} options that you used in
2288 actual compilation. Then send the @var{input}.i or @var{input}.ii files
2291 A single statement is not enough of an example. In order to compile it,
2292 it must be embedded in a complete file of compiler input; and the bug
2293 might depend on the details of how this is done.
2295 Without a real example one can compile, all anyone can do about your bug
2296 report is wish you luck. It would be futile to try to guess how to
2297 provoke the bug. For example, bugs in register allocation and reloading
2298 frequently depend on every little detail of the function they happen in.
2300 Even if the input file that fails comes from a GNU program, you should
2301 still send the complete test case. Don't ask the GNU CC maintainers to
2302 do the extra work of obtaining the program in question---they are all
2303 overworked as it is. Also, the problem may depend on what is in the
2304 header files on your system; it is unreliable for the GNU CC maintainers
2305 to try the problem with the header files available to them. By sending
2306 CPP output, you can eliminate this source of uncertainty and save us
2307 a certain percentage of wild goose chases.
2310 The command arguments you gave GNU CC or GNU C++ to compile that example
2311 and observe the bug. For example, did you use @samp{-O}? To guarantee
2312 you won't omit something important, list all the options.
2314 If we were to try to guess the arguments, we would probably guess wrong
2315 and then we would not encounter the bug.
2318 The type of machine you are using, and the operating system name and
2322 The operands you gave to the @code{configure} command when you installed
2326 A complete list of any modifications you have made to the compiler
2327 source. (We don't promise to investigate the bug unless it happens in
2328 an unmodified compiler. But if you've made modifications and don't tell
2329 us, then you are sending us on a wild goose chase.)
2331 Be precise about these changes. A description in English is not
2332 enough---send a context diff for them.
2334 Adding files of your own (such as a machine description for a machine we
2335 don't support) is a modification of the compiler source.
2338 Details of any other deviations from the standard procedure for installing
2342 A description of what behavior you observe that you believe is
2343 incorrect. For example, ``The compiler gets a fatal signal,'' or,
2344 ``The assembler instruction at line 208 in the output is incorrect.''
2346 Of course, if the bug is that the compiler gets a fatal signal, then one
2347 can't miss it. But if the bug is incorrect output, the maintainer might
2348 not notice unless it is glaringly wrong. None of us has time to study
2349 all the assembler code from a 50-line C program just on the chance that
2350 one instruction might be wrong. We need @emph{you} to do this part!
2352 Even if the problem you experience is a fatal signal, you should still
2353 say so explicitly. Suppose something strange is going on, such as, your
2354 copy of the compiler is out of synch, or you have encountered a bug in
2355 the C library on your system. (This has happened!) Your copy might
2356 crash and the copy here would not. If you @i{said} to expect a crash,
2357 then when the compiler here fails to crash, we would know that the bug
2358 was not happening. If you don't say to expect a crash, then we would
2359 not know whether the bug was happening. We would not be able to draw
2360 any conclusion from our observations.
2362 If the problem is a diagnostic when compiling GNU CC with some other
2363 compiler, say whether it is a warning or an error.
2365 Often the observed symptom is incorrect output when your program is run.
2366 Sad to say, this is not enough information unless the program is short
2367 and simple. None of us has time to study a large program to figure out
2368 how it would work if compiled correctly, much less which line of it was
2369 compiled wrong. So you will have to do that. Tell us which source line
2370 it is, and what incorrect result happens when that line is executed. A
2371 person who understands the program can find this as easily as finding a
2372 bug in the program itself.
2375 If you send examples of assembler code output from GNU CC or GNU C++,
2376 please use @samp{-g} when you make them. The debugging information
2377 includes source line numbers which are essential for correlating the
2378 output with the input.
2381 If you wish to mention something in the GNU CC source, refer to it by
2382 context, not by line number.
2384 The line numbers in the development sources don't match those in your
2385 sources. Your line numbers would convey no useful information to the
2389 Additional information from a debugger might enable someone to find a
2390 problem on a machine which he does not have available. However, you
2391 need to think when you collect this information if you want it to have
2392 any chance of being useful.
2394 @cindex backtrace for bug reports
2395 For example, many people send just a backtrace, but that is never
2396 useful by itself. A simple backtrace with arguments conveys little
2397 about GNU CC because the compiler is largely data-driven; the same
2398 functions are called over and over for different RTL insns, doing
2399 different things depending on the details of the insn.
2401 Most of the arguments listed in the backtrace are useless because they
2402 are pointers to RTL list structure. The numeric values of the
2403 pointers, which the debugger prints in the backtrace, have no
2404 significance whatever; all that matters is the contents of the objects
2405 they point to (and most of the contents are other such pointers).
2407 In addition, most compiler passes consist of one or more loops that
2408 scan the RTL insn sequence. The most vital piece of information about
2409 such a loop---which insn it has reached---is usually in a local variable,
2413 What you need to provide in addition to a backtrace are the values of
2414 the local variables for several stack frames up. When a local
2415 variable or an argument is an RTX, first print its value and then use
2416 the GDB command @code{pr} to print the RTL expression that it points
2417 to. (If GDB doesn't run on your machine, use your debugger to call
2418 the function @code{debug_rtx} with the RTX as an argument.) In
2419 general, whenever a variable is a pointer, its value is no use
2420 without the data it points to.
2423 Here are some things that are not necessary:
2427 A description of the envelope of the bug.
2429 Often people who encounter a bug spend a lot of time investigating
2430 which changes to the input file will make the bug go away and which
2431 changes will not affect it.
2433 This is often time consuming and not very useful, because the way we
2434 will find the bug is by running a single example under the debugger with
2435 breakpoints, not by pure deduction from a series of examples. You might
2436 as well save your time for something else.
2438 Of course, if you can find a simpler example to report @emph{instead} of
2439 the original one, that is a convenience. Errors in the output will be
2440 easier to spot, running under the debugger will take less time, etc.
2441 Most GNU CC bugs involve just one function, so the most straightforward
2442 way to simplify an example is to delete all the function definitions
2443 except the one where the bug occurs. Those earlier in the file may be
2444 replaced by external declarations if the crucial function depends on
2445 them. (Exception: inline functions may affect compilation of functions
2446 defined later in the file.)
2448 However, simplification is not vital; if you don't want to do this,
2449 report the bug anyway and send the entire test case you used.
2452 In particular, some people insert conditionals @samp{#ifdef BUG} around
2453 a statement which, if removed, makes the bug not happen. These are just
2454 clutter; we won't pay any attention to them anyway. Besides, you should
2455 send us cpp output, and that can't have conditionals.
2458 A patch for the bug.
2460 A patch for the bug is useful if it is a good one. But don't omit the
2461 necessary information, such as the test case, on the assumption that a
2462 patch is all we need. We might see problems with your patch and decide
2463 to fix the problem another way, or we might not understand it at all.
2465 Sometimes with a program as complicated as GNU CC it is very hard to
2466 construct an example that will make the program follow a certain path
2467 through the code. If you don't send the example, we won't be able to
2468 construct one, so we won't be able to verify that the bug is fixed.
2470 And if we can't understand what bug you are trying to fix, or why your
2471 patch should be an improvement, we won't install it. A test case will
2472 help us to understand.
2474 @xref{Sending Patches}, for guidelines on how to make it easy for us to
2475 understand and install your patches.
2478 A guess about what the bug is or what it depends on.
2480 Such guesses are usually wrong. Even I can't guess right about such
2481 things without first using the debugger to find the facts.
2486 We have no way of examining a core dump for your type of machine
2487 unless we have an identical system---and if we do have one,
2488 we should be able to reproduce the crash ourselves.
2491 @node Sending Patches,, Bug Reporting, Bugs
2492 @section Sending Patches for GNU CC
2494 If you would like to write bug fixes or improvements for the GNU C
2495 compiler, that is very helpful. Send suggested fixes to the bug report
2496 mailing list, @code{egcs-bugs@@cygnus.com}.
2498 Please follow these guidelines so we can study your patches efficiently.
2499 If you don't follow these guidelines, your information might still be
2500 useful, but using it will take extra work. Maintaining GNU C is a lot
2501 of work in the best of circumstances, and we can't keep up unless you do
2506 Send an explanation with your changes of what problem they fix or what
2507 improvement they bring about. For a bug fix, just include a copy of the
2508 bug report, and explain why the change fixes the bug.
2510 (Referring to a bug report is not as good as including it, because then
2511 we will have to look it up, and we have probably already deleted it if
2512 we've already fixed the bug.)
2515 Always include a proper bug report for the problem you think you have
2516 fixed. We need to convince ourselves that the change is right before
2517 installing it. Even if it is right, we might have trouble judging it if
2518 we don't have a way to reproduce the problem.
2521 Include all the comments that are appropriate to help people reading the
2522 source in the future understand why this change was needed.
2525 Don't mix together changes made for different reasons.
2526 Send them @emph{individually}.
2528 If you make two changes for separate reasons, then we might not want to
2529 install them both. We might want to install just one. If you send them
2530 all jumbled together in a single set of diffs, we have to do extra work
2531 to disentangle them---to figure out which parts of the change serve
2532 which purpose. If we don't have time for this, we might have to ignore
2533 your changes entirely.
2535 If you send each change as soon as you have written it, with its own
2536 explanation, then the two changes never get tangled up, and we can
2537 consider each one properly without any extra work to disentangle them.
2539 Ideally, each change you send should be impossible to subdivide into
2540 parts that we might want to consider separately, because each of its
2541 parts gets its motivation from the other parts.
2544 Send each change as soon as that change is finished. Sometimes people
2545 think they are helping us by accumulating many changes to send them all
2546 together. As explained above, this is absolutely the worst thing you
2549 Since you should send each change separately, you might as well send it
2550 right away. That gives us the option of installing it immediately if it
2554 Use @samp{diff -c} to make your diffs. Diffs without context are hard
2555 for us to install reliably. More than that, they make it hard for us to
2556 study the diffs to decide whether we want to install them. Unidiff
2557 format is better than contextless diffs, but not as easy to read as
2560 If you have GNU diff, use @samp{diff -cp}, which shows the name of the
2561 function that each change occurs in.
2564 Write the change log entries for your changes. We get lots of changes,
2565 and we don't have time to do all the change log writing ourselves.
2567 Read the @file{ChangeLog} file to see what sorts of information to put
2568 in, and to learn the style that we use. The purpose of the change log
2569 is to show people where to find what was changed. So you need to be
2570 specific about what functions you changed; in large functions, it's
2571 often helpful to indicate where within the function the change was.
2573 On the other hand, once you have shown people where to find the change,
2574 you need not explain its purpose. Thus, if you add a new function, all
2575 you need to say about it is that it is new. If you feel that the
2576 purpose needs explaining, it probably does---but the explanation will be
2577 much more useful if you put it in comments in the code.
2579 If you would like your name to appear in the header line for who made
2580 the change, send us the header line.
2583 When you write the fix, keep in mind that we can't install a change that
2584 would break other systems.
2586 People often suggest fixing a problem by changing machine-independent
2587 files such as @file{toplev.c} to do something special that a particular
2588 system needs. Sometimes it is totally obvious that such changes would
2589 break GNU CC for almost all users. We can't possibly make a change like
2590 that. At best it might tell us how to write another patch that would
2591 solve the problem acceptably.
2593 Sometimes people send fixes that @emph{might} be an improvement in
2594 general---but it is hard to be sure of this. It's hard to install
2595 such changes because we have to study them very carefully. Of course,
2596 a good explanation of the reasoning by which you concluded the change
2597 was correct can help convince us.
2599 The safest changes are changes to the configuration files for a
2600 particular machine. These are safe because they can't create new bugs
2603 Please help us keep up with the workload by designing the patch in a
2604 form that is good to install.
2608 @chapter How To Get Help with GNU CC
2610 If you need help installing, using or changing GNU CC, there are two
2615 Send a message to a suitable network mailing list. First try
2616 @code{egcs-bugs@@cygnus.com}, and if that brings no response, try
2617 @code{egcs@@cygnus.com}.
2620 Look in the service directory for someone who might help you for a fee.
2621 The service directory is found in the file named @file{SERVICE} in the
2622 GNU CC distribution.
2626 @chapter Contributing to GNU CC Development
2628 If you would like to help pretest GNU CC releases to assure they work
2629 well, or if you would like to work on improving GNU CC, please contact
2630 the maintainers at @code{egcs@@cygnus.com}. A pretester should
2631 be willing to try to investigate bugs as well as report them.
2633 If you'd like to work on improvements, please ask for suggested projects
2634 or suggest your own ideas. If you have already written an improvement,
2635 please tell us about it. If you have not yet started work, it is useful
2636 to contact @code{egcs@@cygnus.com} before you start; the
2637 maintainers may be able to suggest ways to make your extension fit in
2638 better with the rest of GNU CC and with other development plans.
2641 @chapter Using GNU CC on VMS
2643 @c prevent bad page break with this line
2644 Here is how to use GNU CC on VMS.
2647 * Include Files and VMS:: Where the preprocessor looks for the include files.
2648 * Global Declarations:: How to do globaldef, globalref and globalvalue with
2650 * VMS Misc:: Misc information.
2653 @node Include Files and VMS
2654 @section Include Files and VMS
2656 @cindex include files and VMS
2657 @cindex VMS and include files
2658 @cindex header files and VMS
2659 Due to the differences between the filesystems of Unix and VMS, GNU CC
2660 attempts to translate file names in @samp{#include} into names that VMS
2661 will understand. The basic strategy is to prepend a prefix to the
2662 specification of the include file, convert the whole filename to a VMS
2663 filename, and then try to open the file. GNU CC tries various prefixes
2664 one by one until one of them succeeds:
2668 The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
2669 where GNU C header files are traditionally stored. If you wish to store
2670 header files in non-standard locations, then you can assign the logical
2671 @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
2672 list is suitable for use with a rooted logical.
2675 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where
2676 VAX-C header files are traditionally stored.
2679 If the include file specification by itself is a valid VMS filename, the
2680 preprocessor then uses this name with no prefix in an attempt to open
2684 If the file specification is not a valid VMS filename (i.e. does not
2685 contain a device or a directory specifier, and contains a @samp{/}
2686 character), the preprocessor tries to convert it from Unix syntax to
2689 Conversion works like this: the first directory name becomes a device,
2690 and the rest of the directories are converted into VMS-format directory
2691 names. For example, the name @file{X11/foobar.h} is
2692 translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
2693 whichever one can be opened. This strategy allows you to assign a
2694 logical name to point to the actual location of the header files.
2697 If none of these strategies succeeds, the @samp{#include} fails.
2700 Include directives of the form:
2707 are a common source of incompatibility between VAX-C and GNU CC. VAX-C
2708 treats this much like a standard @code{#include <foobar.h>} directive.
2709 That is incompatible with the ANSI C behavior implemented by GNU CC: to
2710 expand the name @code{foobar} as a macro. Macro expansion should
2711 eventually yield one of the two standard formats for @code{#include}:
2714 #include "@var{file}"
2715 #include <@var{file}>
2718 If you have this problem, the best solution is to modify the source to
2719 convert the @code{#include} directives to one of the two standard forms.
2720 That will work with either compiler. If you want a quick and dirty fix,
2721 define the file names as macros with the proper expansion, like this:
2724 #define stdio <stdio.h>
2728 This will work, as long as the name doesn't conflict with anything else
2731 Another source of incompatibility is that VAX-C assumes that:
2738 is actually asking for the file @file{foobar.h}. GNU CC does not
2739 make this assumption, and instead takes what you ask for literally;
2740 it tries to read the file @file{foobar}. The best way to avoid this
2741 problem is to always specify the desired file extension in your include
2744 GNU CC for VMS is distributed with a set of include files that is
2745 sufficient to compile most general purpose programs. Even though the
2746 GNU CC distribution does not contain header files to define constants
2747 and structures for some VMS system-specific functions, there is no
2748 reason why you cannot use GNU CC with any of these functions. You first
2749 may have to generate or create header files, either by using the public
2750 domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
2751 extracting the relevant modules from one of the system macro libraries,
2752 and using an editor to construct a C header file.
2754 A @code{#include} file name cannot contain a DECNET node name. The
2755 preprocessor reports an I/O error if you attempt to use a node name,
2756 whether explicitly, or implicitly via a logical name.
2758 @node Global Declarations
2759 @section Global Declarations and VMS
2763 @findex GLOBALVALUEDEF
2764 @findex GLOBALVALUEREF
2765 GNU CC does not provide the @code{globalref}, @code{globaldef} and
2766 @code{globalvalue} keywords of VAX-C. You can get the same effect with
2767 an obscure feature of GAS, the GNU assembler. (This requires GAS
2768 version 1.39 or later.) The following macros allow you to use this
2769 feature in a fairly natural way:
2773 #define GLOBALREF(TYPE,NAME) \
2775 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
2776 #define GLOBALDEF(TYPE,NAME,VALUE) \
2778 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
2780 #define GLOBALVALUEREF(TYPE,NAME) \
2781 const TYPE NAME[1] \
2782 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
2783 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2784 const TYPE NAME[1] \
2785 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \
2788 #define GLOBALREF(TYPE,NAME) \
2790 #define GLOBALDEF(TYPE,NAME,VALUE) \
2791 globaldef TYPE NAME = VALUE
2792 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2793 globalvalue TYPE NAME = VALUE
2794 #define GLOBALVALUEREF(TYPE,NAME) \
2795 globalvalue TYPE NAME
2800 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
2801 name is removed by the assembler, after it has modified the attributes
2802 of the symbol). These macros are provided in the VMS binaries
2803 distribution in a header file @file{GNU_HACKS.H}. An example of the
2807 GLOBALREF (int, ijk);
2808 GLOBALDEF (int, jkl, 0);
2811 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
2812 straightforwardly for arrays, since there is no way to insert the array
2813 dimension into the declaration at the right place. However, you can
2814 declare an array with these macros if you first define a typedef for the
2815 array type, like this:
2818 typedef int intvector[10];
2819 GLOBALREF (intvector, foo);
2822 Array and structure initializers will also break the macros; you can
2823 define the initializer to be a macro of its own, or you can expand the
2824 @code{GLOBALDEF} macro by hand. You may find a case where you wish to
2825 use the @code{GLOBALDEF} macro with a large array, but you are not
2826 interested in explicitly initializing each element of the array. In
2827 such cases you can use an initializer like: @code{@{0,@}}, which will
2828 initialize the entire array to @code{0}.
2830 A shortcoming of this implementation is that a variable declared with
2831 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For
2832 example, the declaration:
2835 GLOBALVALUEREF(int, ijk);
2839 declares the variable @code{ijk} as an array of type @code{int [1]}.
2840 This is done because a globalvalue is actually a constant; its ``value''
2841 is what the linker would normally consider an address. That is not how
2842 an integer value works in C, but it is how an array works. So treating
2843 the symbol as an array name gives consistent results---with the
2844 exception that the value seems to have the wrong type. @strong{Don't
2845 try to access an element of the array.} It doesn't have any elements.
2846 The array ``address'' may not be the address of actual storage.
2848 The fact that the symbol is an array may lead to warnings where the
2849 variable is used. Insert type casts to avoid the warnings. Here is an
2850 example; it takes advantage of the ANSI C feature allowing macros that
2851 expand to use the same name as the macro itself.
2854 GLOBALVALUEREF (int, ss$_normal);
2855 GLOBALVALUEDEF (int, xyzzy,123);
2857 #define ss$_normal ((int) ss$_normal)
2858 #define xyzzy ((int) xyzzy)
2862 Don't use @code{globaldef} or @code{globalref} with a variable whose
2863 type is an enumeration type; this is not implemented. Instead, make the
2864 variable an integer, and use a @code{globalvaluedef} for each of the
2865 enumeration values. An example of this would be:
2869 GLOBALDEF (int, color, 0);
2870 GLOBALVALUEDEF (int, RED, 0);
2871 GLOBALVALUEDEF (int, BLUE, 1);
2872 GLOBALVALUEDEF (int, GREEN, 3);
2874 enum globaldef color @{RED, BLUE, GREEN = 3@};
2879 @section Other VMS Issues
2881 @cindex exit status and VMS
2882 @cindex return value of @code{main}
2883 @cindex @code{main} and the exit status
2884 GNU CC automatically arranges for @code{main} to return 1 by default if
2885 you fail to specify an explicit return value. This will be interpreted
2886 by VMS as a status code indicating a normal successful completion.
2887 Version 1 of GNU CC did not provide this default.
2889 GNU CC on VMS works only with the GNU assembler, GAS. You need version
2890 1.37 or later of GAS in order to produce value debugging information for
2891 the VMS debugger. Use the ordinary VMS linker with the object files
2894 @cindex shared VMS run time system
2895 @cindex @file{VAXCRTL}
2896 Under previous versions of GNU CC, the generated code would occasionally
2897 give strange results when linked to the sharable @file{VAXCRTL} library.
2898 Now this should work.
2900 A caveat for use of @code{const} global variables: the @code{const}
2901 modifier must be specified in every external declaration of the variable
2902 in all of the source files that use that variable. Otherwise the linker
2903 will issue warnings about conflicting attributes for the variable. Your
2904 program will still work despite the warnings, but the variable will be
2905 placed in writable storage.
2907 @cindex name augmentation
2908 @cindex case sensitivity and VMS
2909 @cindex VMS and case sensitivity
2910 Although the VMS linker does distinguish between upper and lower case
2911 letters in global symbols, most VMS compilers convert all such symbols
2912 into upper case and most run-time library routines also have upper case
2913 names. To be able to reliably call such routines, GNU CC (by means of
2914 the assembler GAS) converts global symbols into upper case like other
2915 VMS compilers. However, since the usual practice in C is to distinguish
2916 case, GNU CC (via GAS) tries to preserve usual C behavior by augmenting
2917 each name that is not all lower case. This means truncating the name
2918 to at most 23 characters and then adding more characters at the end
2919 which encode the case pattern of those 23. Names which contain at
2920 least one dollar sign are an exception; they are converted directly into
2921 upper case without augmentation.
2923 Name augmentation yields bad results for programs that use precompiled
2924 libraries (such as Xlib) which were generated by another compiler. You
2925 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
2926 it makes external C functions and variables case-independent as is usual
2927 on VMS. Alternatively, you could write all references to the functions
2928 and variables in such libraries using lower case; this will work on VMS,
2929 but is not portable to other systems. The compiler option @samp{/NAMES}
2930 also provides control over global name handling.
2932 Function and variable names are handled somewhat differently with GNU
2933 C++. The GNU C++ compiler performs @dfn{name mangling} on function
2934 names, which means that it adds information to the function name to
2935 describe the data types of the arguments that the function takes. One
2936 result of this is that the name of a function can become very long.
2937 Since the VMS linker only recognizes the first 31 characters in a name,
2938 special action is taken to ensure that each function and variable has a
2939 unique name that can be represented in 31 characters.
2941 If the name (plus a name augmentation, if required) is less than 32
2942 characters in length, then no special action is performed. If the name
2943 is longer than 31 characters, the assembler (GAS) will generate a
2944 hash string based upon the function name, truncate the function name to
2945 23 characters, and append the hash string to the truncated name. If the
2946 @samp{/VERBOSE} compiler option is used, the assembler will print both
2947 the full and truncated names of each symbol that is truncated.
2949 The @samp{/NOCASE_HACK} compiler option should not be used when you are
2950 compiling programs that use libg++. libg++ has several instances of
2951 objects (i.e. @code{Filebuf} and @code{filebuf}) which become
2952 indistinguishable in a case-insensitive environment. This leads to
2953 cases where you need to inhibit augmentation selectively (if you were
2954 using libg++ and Xlib in the same program, for example). There is no
2955 special feature for doing this, but you can get the result by defining a
2956 macro for each mixed case symbol for which you wish to inhibit
2957 augmentation. The macro should expand into the lower case equivalent of
2958 itself. For example:
2961 #define StuDlyCapS studlycaps
2964 These macro definitions can be placed in a header file to minimize the
2965 number of changes to your source code.
2970 @chapter GNU CC and Portability
2972 @cindex GNU CC and portability
2974 The main goal of GNU CC was to make a good, fast compiler for machines in
2975 the class that the GNU system aims to run on: 32-bit machines that address
2976 8-bit bytes and have several general registers. Elegance, theoretical
2977 power and simplicity are only secondary.
2979 GNU CC gets most of the information about the target machine from a machine
2980 description which gives an algebraic formula for each of the machine's
2981 instructions. This is a very clean way to describe the target. But when
2982 the compiler needs information that is difficult to express in this
2983 fashion, I have not hesitated to define an ad-hoc parameter to the machine
2984 description. The purpose of portability is to reduce the total work needed
2985 on the compiler; it was not of interest for its own sake.
2988 @cindex autoincrement addressing, availability
2990 GNU CC does not contain machine dependent code, but it does contain code
2991 that depends on machine parameters such as endianness (whether the most
2992 significant byte has the highest or lowest address of the bytes in a word)
2993 and the availability of autoincrement addressing. In the RTL-generation
2994 pass, it is often necessary to have multiple strategies for generating code
2995 for a particular kind of syntax tree, strategies that are usable for different
2996 combinations of parameters. Often I have not tried to address all possible
2997 cases, but only the common ones or only the ones that I have encountered.
2998 As a result, a new target may require additional strategies. You will know
2999 if this happens because the compiler will call @code{abort}. Fortunately,
3000 the new strategies can be added in a machine-independent fashion, and will
3001 affect only the target machines that need them.
3006 @chapter Interfacing to GNU CC Output
3007 @cindex interfacing to GNU CC output
3008 @cindex run-time conventions
3009 @cindex function call conventions
3010 @cindex conventions, run-time
3012 GNU CC is normally configured to use the same function calling convention
3013 normally in use on the target system. This is done with the
3014 machine-description macros described (@pxref{Target Macros}).
3016 @cindex unions, returning
3017 @cindex structures, returning
3018 @cindex returning structures and unions
3019 However, returning of structure and union values is done differently on
3020 some target machines. As a result, functions compiled with PCC
3021 returning such types cannot be called from code compiled with GNU CC,
3022 and vice versa. This does not cause trouble often because few Unix
3023 library routines return structures or unions.
3025 GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes
3026 long in the same registers used for @code{int} or @code{double} return
3027 values. (GNU CC typically allocates variables of such types in
3028 registers also.) Structures and unions of other sizes are returned by
3029 storing them into an address passed by the caller (usually in a
3030 register). The machine-description macros @code{STRUCT_VALUE} and
3031 @code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address.
3033 By contrast, PCC on most target machines returns structures and unions
3034 of any size by copying the data into an area of static storage, and then
3035 returning the address of that storage as if it were a pointer value.
3036 The caller must copy the data from that memory area to the place where
3037 the value is wanted. This is slower than the method used by GNU CC, and
3038 fails to be reentrant.
3040 On some target machines, such as RISC machines and the 80386, the
3041 standard system convention is to pass to the subroutine the address of
3042 where to return the value. On these machines, GNU CC has been
3043 configured to be compatible with the standard compiler, when this method
3044 is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3046 @cindex argument passing
3047 @cindex passing arguments
3048 GNU CC uses the system's standard convention for passing arguments. On
3049 some machines, the first few arguments are passed in registers; in
3050 others, all are passed on the stack. It would be possible to use
3051 registers for argument passing on any machine, and this would probably
3052 result in a significant speedup. But the result would be complete
3053 incompatibility with code that follows the standard convention. So this
3054 change is practical only if you are switching to GNU CC as the sole C
3055 compiler for the system. We may implement register argument passing on
3056 certain machines once we have a complete GNU system so that we can
3057 compile the libraries with GNU CC.
3059 On some machines (particularly the Sparc), certain types of arguments
3060 are passed ``by invisible reference''. This means that the value is
3061 stored in memory, and the address of the memory location is passed to
3064 @cindex @code{longjmp} and automatic variables
3065 If you use @code{longjmp}, beware of automatic variables. ANSI C says that
3066 automatic variables that are not declared @code{volatile} have undefined
3067 values after a @code{longjmp}. And this is all GNU CC promises to do,
3068 because it is very difficult to restore register variables correctly, and
3069 one of GNU CC's features is that it can put variables in registers without
3072 If you want a variable to be unaltered by @code{longjmp}, and you don't
3073 want to write @code{volatile} because old C compilers don't accept it,
3074 just take the address of the variable. If a variable's address is ever
3075 taken, even if just to compute it and ignore it, then the variable cannot
3086 @cindex arithmetic libraries
3087 @cindex math libraries
3088 Code compiled with GNU CC may call certain library routines. Most of
3089 them handle arithmetic for which there are no instructions. This
3090 includes multiply and divide on some machines, and floating point
3091 operations on any machine for which floating point support is disabled
3092 with @samp{-msoft-float}. Some standard parts of the C library, such as
3093 @code{bcopy} or @code{memcpy}, are also called automatically. The usual
3094 function call interface is used for calling the library routines.
3096 These library routines should be defined in the library @file{libgcc.a},
3097 which GNU CC automatically searches whenever it links a program. On
3098 machines that have multiply and divide instructions, if hardware
3099 floating point is in use, normally @file{libgcc.a} is not needed, but it
3100 is searched just in case.
3102 Each arithmetic function is defined in @file{libgcc1.c} to use the
3103 corresponding C arithmetic operator. As long as the file is compiled
3104 with another C compiler, which supports all the C arithmetic operators,
3105 this file will work portably. However, @file{libgcc1.c} does not work if
3106 compiled with GNU CC, because each arithmetic function would compile
3107 into a call to itself!
3112 @chapter Passes and Files of the Compiler
3113 @cindex passes and files of the compiler
3114 @cindex files and passes of the compiler
3115 @cindex compiler passes and files
3117 @cindex top level of compiler
3118 The overall control structure of the compiler is in @file{toplev.c}. This
3119 file is responsible for initialization, decoding arguments, opening and
3120 closing files, and sequencing the passes.
3122 @cindex parsing pass
3123 The parsing pass is invoked only once, to parse the entire input. The RTL
3124 intermediate code for a function is generated as the function is parsed, a
3125 statement at a time. Each statement is read in as a syntax tree and then
3126 converted to RTL; then the storage for the tree for the statement is
3127 reclaimed. Storage for types (and the expressions for their sizes),
3128 declarations, and a representation of the binding contours and how they nest,
3129 remain until the function is finished being compiled; these are all needed
3130 to output the debugging information.
3132 @findex rest_of_compilation
3133 @findex rest_of_decl_compilation
3134 Each time the parsing pass reads a complete function definition or
3135 top-level declaration, it calls either the function
3136 @code{rest_of_compilation}, or the function
3137 @code{rest_of_decl_compilation} in @file{toplev.c}, which are
3138 responsible for all further processing necessary, ending with output of
3139 the assembler language. All other compiler passes run, in sequence,
3140 within @code{rest_of_compilation}. When that function returns from
3141 compiling a function definition, the storage used for that function
3142 definition's compilation is entirely freed, unless it is an inline
3145 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3148 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3151 Here is a list of all the passes of the compiler and their source files.
3152 Also included is a description of where debugging dumps can be requested
3153 with @samp{-d} options.
3157 Parsing. This pass reads the entire text of a function definition,
3158 constructing partial syntax trees. This and RTL generation are no longer
3159 truly separate passes (formerly they were), but it is easier to think
3160 of them as separate.
3162 The tree representation does not entirely follow C syntax, because it is
3163 intended to support other languages as well.
3165 Language-specific data type analysis is also done in this pass, and every
3166 tree node that represents an expression has a data type attached.
3167 Variables are represented as declaration nodes.
3169 @cindex constant folding
3170 @cindex arithmetic simplifications
3171 @cindex simplifications, arithmetic
3172 Constant folding and some arithmetic simplifications are also done
3175 The language-independent source files for parsing are
3176 @file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}.
3177 There are also header files @file{tree.h} and @file{tree.def}
3178 which define the format of the tree representation.@refill
3180 @c Avoiding overfull is tricky here.
3181 The source files to parse C are
3185 @file{c-aux-info.c},
3188 along with header files
3192 The source files for parsing C++ are @file{cp-parse.y},
3193 @file{cp-class.c},@*
3194 @file{cp-cvt.c}, @file{cp-decl.c}, @file{cp-decl2.c},
3195 @file{cp-dem.c}, @file{cp-except.c},@*
3196 @file{cp-expr.c}, @file{cp-init.c}, @file{cp-lex.c},
3197 @file{cp-method.c}, @file{cp-ptree.c},@*
3198 @file{cp-search.c}, @file{cp-tree.c}, @file{cp-type2.c}, and
3199 @file{cp-typeck.c}, along with header files @file{cp-tree.def},
3200 @file{cp-tree.h}, and @file{cp-decl.h}.
3202 The special source files for parsing Objective C are
3203 @file{objc-parse.y}, @file{objc-actions.c}, @file{objc-tree.def}, and
3204 @file{objc-actions.h}. Certain C-specific files are used for this as
3207 The file @file{c-common.c} is also used for all of the above languages.
3209 @cindex RTL generation
3211 RTL generation. This is the conversion of syntax tree into RTL code.
3212 It is actually done statement-by-statement during parsing, but for
3213 most purposes it can be thought of as a separate pass.
3215 @cindex target-parameter-dependent code
3216 This is where the bulk of target-parameter-dependent code is found,
3217 since often it is necessary for strategies to apply only when certain
3218 standard kinds of instructions are available. The purpose of named
3219 instruction patterns is to provide this information to the RTL
3222 @cindex tail recursion optimization
3223 Optimization is done in this pass for @code{if}-conditions that are
3224 comparisons, boolean operations or conditional expressions. Tail
3225 recursion is detected at this time also. Decisions are made about how
3226 best to arrange loops and how to output @code{switch} statements.
3228 @c Avoiding overfull is tricky here.
3229 The source files for RTL generation include
3237 and @file{emit-rtl.c}.
3239 @file{insn-emit.c}, generated from the machine description by the
3240 program @code{genemit}, is used in this pass. The header file
3241 @file{expr.h} is used for communication within this pass.@refill
3245 The header files @file{insn-flags.h} and @file{insn-codes.h},
3246 generated from the machine description by the programs @code{genflags}
3247 and @code{gencodes}, tell this pass which standard names are available
3248 for use and which patterns correspond to them.@refill
3250 Aside from debugging information output, none of the following passes
3251 refers to the tree structure representation of the function (only
3252 part of which is saved).
3254 @cindex inline, automatic
3255 The decision of whether the function can and should be expanded inline
3256 in its subsequent callers is made at the end of rtl generation. The
3257 function must meet certain criteria, currently related to the size of
3258 the function and the types and number of parameters it has. Note that
3259 this function may contain loops, recursive calls to itself
3260 (tail-recursive functions can be inlined!), gotos, in short, all
3261 constructs supported by GNU CC. The file @file{integrate.c} contains
3262 the code to save a function's rtl for later inlining and to inline that
3263 rtl when the function is called. The header file @file{integrate.h}
3264 is also used for this purpose.
3266 The option @samp{-dr} causes a debugging dump of the RTL code after
3267 this pass. This dump file's name is made by appending @samp{.rtl} to
3268 the input file name.
3270 @cindex jump optimization
3271 @cindex unreachable code
3274 Jump optimization. This pass simplifies jumps to the following
3275 instruction, jumps across jumps, and jumps to jumps. It deletes
3276 unreferenced labels and unreachable code, except that unreachable code
3277 that contains a loop is not recognized as unreachable in this pass.
3278 (Such loops are deleted later in the basic block analysis.) It also
3279 converts some code originally written with jumps into sequences of
3280 instructions that directly set values from the results of comparisons,
3281 if the machine has such instructions.
3283 Jump optimization is performed two or three times. The first time is
3284 immediately following RTL generation. The second time is after CSE,
3285 but only if CSE says repeated jump optimization is needed. The
3286 last time is right before the final pass. That time, cross-jumping
3287 and deletion of no-op move instructions are done together with the
3288 optimizations described above.
3290 The source file of this pass is @file{jump.c}.
3292 The option @samp{-dj} causes a debugging dump of the RTL code after
3293 this pass is run for the first time. This dump file's name is made by
3294 appending @samp{.jump} to the input file name.
3296 @cindex register use analysis
3298 Register scan. This pass finds the first and last use of each
3299 register, as a guide for common subexpression elimination. Its source
3300 is in @file{regclass.c}.
3302 @cindex jump threading
3304 Jump threading. This pass detects a condition jump that branches to an
3305 identical or inverse test. Such jumps can be @samp{threaded} through
3306 the second conditional test. The source code for this pass is in
3307 @file{jump.c}. This optimization is only performed if
3308 @samp{-fthread-jumps} is enabled.
3310 @cindex common subexpression elimination
3311 @cindex constant propagation
3313 Common subexpression elimination. This pass also does constant
3314 propagation. Its source file is @file{cse.c}. If constant
3315 propagation causes conditional jumps to become unconditional or to
3316 become no-ops, jump optimization is run again when CSE is finished.
3318 The option @samp{-ds} causes a debugging dump of the RTL code after
3319 this pass. This dump file's name is made by appending @samp{.cse} to
3320 the input file name.
3322 @cindex global common subexpression elimination
3323 @cindex constant propagation
3324 @cindex copy propagation
3326 Global common subexpression elimination. This pass performs GCSE
3327 using Morel-Renvoise Partial Redundancy Elimination, with the exception
3328 that it does not try to move invariants out of loops - that is left to
3329 the loop optimization pass. This pass also performs global constant
3330 and copy propagation.
3332 The source file for this pass is gcse.c.
3334 The option @samp{-dG} causes a debugging dump of the RTL code after
3335 this pass. This dump file's name is made by appending @samp{.gcse} to
3336 the input file name.
3338 @cindex loop optimization
3340 @cindex strength-reduction
3342 Loop optimization. This pass moves constant expressions out of loops,
3343 and optionally does strength-reduction and loop unrolling as well.
3344 Its source files are @file{loop.c} and @file{unroll.c}, plus the header
3345 @file{loop.h} used for communication between them. Loop unrolling uses
3346 some functions in @file{integrate.c} and the header @file{integrate.h}.
3348 The option @samp{-dL} causes a debugging dump of the RTL code after
3349 this pass. This dump file's name is made by appending @samp{.loop} to
3350 the input file name.
3353 If @samp{-frerun-cse-after-loop} was enabled, a second common
3354 subexpression elimination pass is performed after the loop optimization
3355 pass. Jump threading is also done again at this time if it was specified.
3357 The option @samp{-dt} causes a debugging dump of the RTL code after
3358 this pass. This dump file's name is made by appending @samp{.cse2} to
3359 the input file name.
3361 @cindex register allocation, stupid
3362 @cindex stupid register allocation
3364 Stupid register allocation is performed at this point in a
3365 nonoptimizing compilation. It does a little data flow analysis as
3366 well. When stupid register allocation is in use, the next pass
3367 executed is the reloading pass; the others in between are skipped.
3368 The source file is @file{stupid.c}.
3370 @cindex data flow analysis
3371 @cindex analysis, data flow
3372 @cindex basic blocks
3374 Data flow analysis (@file{flow.c}). This pass divides the program
3375 into basic blocks (and in the process deletes unreachable loops); then
3376 it computes which pseudo-registers are live at each point in the
3377 program, and makes the first instruction that uses a value point at
3378 the instruction that computed the value.
3380 @cindex autoincrement/decrement analysis
3381 This pass also deletes computations whose results are never used, and
3382 combines memory references with add or subtract instructions to make
3383 autoincrement or autodecrement addressing.
3385 The option @samp{-df} causes a debugging dump of the RTL code after
3386 this pass. This dump file's name is made by appending @samp{.flow} to
3387 the input file name. If stupid register allocation is in use, this
3388 dump file reflects the full results of such allocation.
3390 @cindex instruction combination
3392 Instruction combination (@file{combine.c}). This pass attempts to
3393 combine groups of two or three instructions that are related by data
3394 flow into single instructions. It combines the RTL expressions for
3395 the instructions by substitution, simplifies the result using algebra,
3396 and then attempts to match the result against the machine description.
3398 The option @samp{-dc} causes a debugging dump of the RTL code after
3399 this pass. This dump file's name is made by appending @samp{.combine}
3400 to the input file name.
3402 @cindex instruction scheduling
3403 @cindex scheduling, instruction
3405 Instruction scheduling (@file{sched.c}). This pass looks for
3406 instructions whose output will not be available by the time that it is
3407 used in subsequent instructions. (Memory loads and floating point
3408 instructions often have this behavior on RISC machines). It re-orders
3409 instructions within a basic block to try to separate the definition and
3410 use of items that otherwise would cause pipeline stalls.
3412 Instruction scheduling is performed twice. The first time is immediately
3413 after instruction combination and the second is immediately after reload.
3415 The option @samp{-dS} causes a debugging dump of the RTL code after this
3416 pass is run for the first time. The dump file's name is made by
3417 appending @samp{.sched} to the input file name.
3419 @cindex register class preference pass
3421 Register class preferencing. The RTL code is scanned to find out
3422 which register class is best for each pseudo register. The source
3423 file is @file{regclass.c}.
3425 @cindex register allocation
3426 @cindex local register allocation
3428 Local register allocation (@file{local-alloc.c}). This pass allocates
3429 hard registers to pseudo registers that are used only within one basic
3430 block. Because the basic block is linear, it can use fast and
3431 powerful techniques to do a very good job.
3433 The option @samp{-dl} causes a debugging dump of the RTL code after
3434 this pass. This dump file's name is made by appending @samp{.lreg} to
3435 the input file name.
3437 @cindex global register allocation
3439 Global register allocation (@file{global.c}). This pass
3440 allocates hard registers for the remaining pseudo registers (those
3441 whose life spans are not contained in one basic block).
3445 Reloading. This pass renumbers pseudo registers with the hardware
3446 registers numbers they were allocated. Pseudo registers that did not
3447 get hard registers are replaced with stack slots. Then it finds
3448 instructions that are invalid because a value has failed to end up in
3449 a register, or has ended up in a register of the wrong kind. It fixes
3450 up these instructions by reloading the problematical values
3451 temporarily into registers. Additional instructions are generated to
3454 The reload pass also optionally eliminates the frame pointer and inserts
3455 instructions to save and restore call-clobbered registers around calls.
3457 Source files are @file{reload.c} and @file{reload1.c}, plus the header
3458 @file{reload.h} used for communication between them.
3460 The option @samp{-dg} causes a debugging dump of the RTL code after
3461 this pass. This dump file's name is made by appending @samp{.greg} to
3462 the input file name.
3464 @cindex instruction scheduling
3465 @cindex scheduling, instruction
3467 Instruction scheduling is repeated here to try to avoid pipeline stalls
3468 due to memory loads generated for spilled pseudo registers.
3470 The option @samp{-dR} causes a debugging dump of the RTL code after
3471 this pass. This dump file's name is made by appending @samp{.sched2}
3472 to the input file name.
3474 @cindex cross-jumping
3475 @cindex no-op move instructions
3477 Jump optimization is repeated, this time including cross-jumping
3478 and deletion of no-op move instructions.
3480 The option @samp{-dJ} causes a debugging dump of the RTL code after
3481 this pass. This dump file's name is made by appending @samp{.jump2}
3482 to the input file name.
3484 @cindex delayed branch scheduling
3485 @cindex scheduling, delayed branch
3487 Delayed branch scheduling. This optional pass attempts to find
3488 instructions that can go into the delay slots of other instructions,
3489 usually jumps and calls. The source file name is @file{reorg.c}.
3491 The option @samp{-dd} causes a debugging dump of the RTL code after
3492 this pass. This dump file's name is made by appending @samp{.dbr}
3493 to the input file name.
3495 @cindex register-to-stack conversion
3497 Conversion from usage of some hard registers to usage of a register
3498 stack may be done at this point. Currently, this is supported only
3499 for the floating-point registers of the Intel 80387 coprocessor. The
3500 source file name is @file{reg-stack.c}.
3502 The options @samp{-dk} causes a debugging dump of the RTL code after
3503 this pass. This dump file's name is made by appending @samp{.stack}
3504 to the input file name.
3507 @cindex peephole optimization
3509 Final. This pass outputs the assembler code for the function. It is
3510 also responsible for identifying spurious test and compare
3511 instructions. Machine-specific peephole optimizations are performed
3512 at the same time. The function entry and exit sequences are generated
3513 directly as assembler code in this pass; they never exist as RTL.
3515 The source files are @file{final.c} plus @file{insn-output.c}; the
3516 latter is generated automatically from the machine description by the
3517 tool @file{genoutput}. The header file @file{conditions.h} is used
3518 for communication between these files.
3520 @cindex debugging information generation
3522 Debugging information output. This is run after final because it must
3523 output the stack slot offsets for pseudo registers that did not get
3524 hard registers. Source files are @file{dbxout.c} for DBX symbol table
3525 format, @file{sdbout.c} for SDB symbol table format, and
3526 @file{dwarfout.c} for DWARF symbol table format.
3529 Some additional files are used by all or many passes:
3533 Every pass uses @file{machmode.def} and @file{machmode.h} which define
3537 Several passes use @file{real.h}, which defines the default
3538 representation of floating point constants and how to operate on them.
3541 All the passes that work with RTL use the header files @file{rtl.h}
3542 and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
3543 @code{gen*} also use these files to read and work with the machine
3548 Several passes refer to the header file @file{insn-config.h} which
3549 contains a few parameters (C macro definitions) generated
3550 automatically from the machine description RTL by the tool
3553 @cindex instruction recognizer
3555 Several passes use the instruction recognizer, which consists of
3556 @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
3557 and @file{insn-extract.c} that are generated automatically from the
3558 machine description by the tools @file{genrecog} and
3559 @file{genextract}.@refill
3562 Several passes use the header files @file{regs.h} which defines the
3563 information recorded about pseudo register usage, and @file{basic-block.h}
3564 which defines the information recorded about basic blocks.
3567 @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
3568 with a bit for each hard register, and some macros to manipulate it.
3569 This type is just @code{int} if the machine has few enough hard registers;
3570 otherwise it is an array of @code{int} and some of the macros expand
3574 Several passes use instruction attributes. A definition of the
3575 attributes defined for a particular machine is in file
3576 @file{insn-attr.h}, which is generated from the machine description by
3577 the program @file{genattr}. The file @file{insn-attrtab.c} contains
3578 subroutines to obtain the attribute values for insns. It is generated
3579 from the machine description by the program @file{genattrtab}.@refill
3591 @chapter The Configuration File
3592 @cindex configuration file
3593 @cindex @file{xm-@var{machine}.h}
3595 The configuration file @file{xm-@var{machine}.h} contains macro
3596 definitions that describe the machine and system on which the compiler
3597 is running, unlike the definitions in @file{@var{machine}.h}, which
3598 describe the machine for which the compiler is producing output. Most
3599 of the values in @file{xm-@var{machine}.h} are actually the same on all
3600 machines that GNU CC runs on, so large parts of all configuration files
3601 are identical. But there are some macros that vary:
3606 Define this macro if the host system is System V.
3610 Define this macro if the host system is VMS.
3612 @findex FATAL_EXIT_CODE
3613 @item FATAL_EXIT_CODE
3614 A C expression for the status code to be returned when the compiler
3615 exits after serious errors.
3617 @findex SUCCESS_EXIT_CODE
3618 @item SUCCESS_EXIT_CODE
3619 A C expression for the status code to be returned when the compiler
3620 exits without serious errors.
3622 @findex HOST_WORDS_BIG_ENDIAN
3623 @item HOST_WORDS_BIG_ENDIAN
3624 Defined if the host machine stores words of multi-word values in
3625 big-endian order. (GNU CC does not depend on the host byte ordering
3628 @findex HOST_FLOAT_WORDS_BIG_ENDIAN
3629 @item HOST_FLOAT_WORDS_BIG_ENDIAN
3630 Define this macro to be 1 if the host machine stores @code{DFmode},
3631 @code{XFmode} or @code{TFmode} floating point numbers in memory with the
3632 word containing the sign bit at the lowest address; otherwise, define it
3635 This macro need not be defined if the ordering is the same as for
3636 multi-word integers.
3638 @findex HOST_FLOAT_FORMAT
3639 @item HOST_FLOAT_FORMAT
3640 A numeric code distinguishing the floating point format for the host
3641 machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
3642 alternatives and default.
3644 @findex HOST_BITS_PER_CHAR
3645 @item HOST_BITS_PER_CHAR
3646 A C expression for the number of bits in @code{char} on the host
3649 @findex HOST_BITS_PER_SHORT
3650 @item HOST_BITS_PER_SHORT
3651 A C expression for the number of bits in @code{short} on the host
3654 @findex HOST_BITS_PER_INT
3655 @item HOST_BITS_PER_INT
3656 A C expression for the number of bits in @code{int} on the host
3659 @findex HOST_BITS_PER_LONG
3660 @item HOST_BITS_PER_LONG
3661 A C expression for the number of bits in @code{long} on the host
3664 @findex ONLY_INT_FIELDS
3665 @item ONLY_INT_FIELDS
3666 Define this macro to indicate that the host compiler only supports
3667 @code{int} bit fields, rather than other integral types, including
3668 @code{enum}, as do most C compilers.
3670 @findex OBSTACK_CHUNK_SIZE
3671 @item OBSTACK_CHUNK_SIZE
3672 A C expression for the size of ordinary obstack chunks.
3673 If you don't define this, a usually-reasonable default is used.
3675 @findex OBSTACK_CHUNK_ALLOC
3676 @item OBSTACK_CHUNK_ALLOC
3677 The function used to allocate obstack chunks.
3678 If you don't define this, @code{xmalloc} is used.
3680 @findex OBSTACK_CHUNK_FREE
3681 @item OBSTACK_CHUNK_FREE
3682 The function used to free obstack chunks.
3683 If you don't define this, @code{free} is used.
3685 @findex USE_C_ALLOCA
3687 Define this macro to indicate that the compiler is running with the
3688 @code{alloca} implemented in C. This version of @code{alloca} can be
3689 found in the file @file{alloca.c}; to use it, you must also alter the
3690 @file{Makefile} variable @code{ALLOCA}. (This is done automatically
3691 for the systems on which we know it is needed.)
3693 If you do define this macro, you should probably do it as follows:
3697 #define USE_C_ALLOCA
3699 #define alloca __builtin_alloca
3704 so that when the compiler is compiled with GNU CC it uses the more
3705 efficient built-in @code{alloca} function.
3707 @item FUNCTION_CONVERSION_BUG
3708 @findex FUNCTION_CONVERSION_BUG
3709 Define this macro to indicate that the host compiler does not properly
3710 handle converting a function value to a pointer-to-function when it is
3711 used in an expression.
3713 @findex MULTIBYTE_CHARS
3714 @item MULTIBYTE_CHARS
3715 Define this macro to enable support for multibyte characters in the
3716 input to GNU CC. This requires that the host system support the ANSI C
3717 library functions for converting multibyte characters to wide
3722 Define this if your system is POSIX.1 compliant.
3724 @findex NO_SYS_SIGLIST
3725 @item NO_SYS_SIGLIST
3726 Define this if your system @emph{does not} provide the variable
3730 Some systems do provide this variable, but with a different name such
3731 as @code{_sys_siglist}. On these systems, you can define
3732 @code{sys_siglist} as a macro which expands into the name actually
3735 Autoconf normally defines @code{SYS_SIGLIST_DECLARED} when it finds a
3736 declaration of @code{sys_siglist} in the system header files.
3737 However, when you define @code{sys_siglist} to a different name
3738 autoconf will not automatically define @code{SYS_SIGLIST_DECLARED}.
3739 Therefore, if you define @code{sys_siglist}, you should also define
3740 @code{SYS_SIGLIST_DECLARED}.
3742 @findex USE_PROTOTYPES
3743 @item USE_PROTOTYPES
3744 Define this to be 1 if you know that the host compiler supports
3745 prototypes, even if it doesn't define __STDC__, or define
3746 it to be 0 if you do not want any prototypes used in compiling
3747 GNU CC. If @samp{USE_PROTOTYPES} is not defined, it will be
3748 determined automatically whether your compiler supports
3749 prototypes by checking if @samp{__STDC__} is defined.
3751 @findex NO_MD_PROTOTYPES
3752 @item NO_MD_PROTOTYPES
3753 Define this if you wish suppression of prototypes generated from
3754 the machine description file, but to use other prototypes within
3755 GNU CC. If @samp{USE_PROTOTYPES} is defined to be 0, or the
3756 host compiler does not support prototypes, this macro has no
3759 @findex MD_CALL_PROTOTYPES
3760 @item MD_CALL_PROTOTYPES
3761 Define this if you wish to generate prototypes for the
3762 @code{gen_call} or @code{gen_call_value} functions generated from
3763 the machine description file. If @samp{USE_PROTOTYPES} is
3764 defined to be 0, or the host compiler does not support
3765 prototypes, or @samp{NO_MD_PROTOTYPES} is defined, this macro has
3766 no effect. As soon as all of the machine descriptions are
3767 modified to have the appropriate number of arguments, this macro
3770 @findex PATH_SEPARATOR
3771 @item PATH_SEPARATOR
3772 Define this macro to be a C character constant representing the
3773 character used to separate components in paths. The default value is
3776 @findex DIR_SEPARATOR
3778 If your system uses some character other than slash to separate
3779 directory names within a file specification, define this macro to be a C
3780 character constant specifying that character. When GNU CC displays file
3781 names, the character you specify will be used. GNU CC will test for
3782 both slash and the character you specify when parsing filenames.
3784 @findex OBJECT_SUFFIX
3786 Define this macro to be a C string representing the suffix for object
3787 files on your machine. If you do not define this macro, GNU CC will use
3788 @samp{.o} as the suffix for object files.
3790 @findex EXECUTABLE_SUFFIX
3791 @item EXECUTABLE_SUFFIX
3792 Define this macro to be a C string representing the suffix for executable
3793 files on your machine. If you do not define this macro, GNU CC will use
3794 the null string as the suffix for object files.
3796 @findex COLLECT_EXPORT_LIST
3797 @item COLLECT_EXPORT_LIST
3798 If defined, @code{collect2} will scan the individual object files
3799 specified on its command line and create an export list for the linker.
3800 Define this macro for systems like AIX, where the linker discards
3801 object files that are not referenced from @code{main} and uses export
3807 In addition, configuration files for system V define @code{bcopy},
3808 @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
3809 as a macro when compiled with GNU CC, in order to take advantage of the
3810 benefit of GNU CC's built-in @code{alloca}.
3813 @chapter Makefile Fragments
3814 @cindex makefile fragment
3816 When you configure GNU CC using the @file{configure} script
3817 (@pxref{Installation}), it will construct the file @file{Makefile} from
3818 the template file @file{Makefile.in}. When it does this, it will
3819 incorporate makefile fragment files from the @file{config} directory,
3820 named @file{t-@var{target}} and @file{x-@var{host}}. If these files do
3821 not exist, it means nothing needs to be added for a given target or
3825 * Target Fragment:: Writing the @file{t-@var{target}} file.
3826 * Host Fragment:: Writing the @file{x-@var{host}} file.
3829 @node Target Fragment
3830 @section The Target Makefile Fragment
3831 @cindex target makefile fragment
3832 @cindex @file{t-@var{target}}
3834 The target makefile fragment, @file{t-@var{target}}, defines special
3835 target dependent variables and targets used in the @file{Makefile}:
3840 The rule to use to build @file{libgcc1.a}.
3841 If your target does not need to use the functions in @file{libgcc1.a},
3845 @findex CROSS_LIBGCC1
3847 The rule to use to build @file{libgcc1.a} when building a cross
3848 compiler. If your target does not need to use the functions in
3849 @file{libgcc1.a}, set this to empty. @xref{Cross Runtime}.
3851 @findex LIBGCC2_CFLAGS
3852 @item LIBGCC2_CFLAGS
3853 Compiler flags to use when compiling @file{libgcc2.c}.
3855 @findex LIB2FUNCS_EXTRA
3856 @item LIB2FUNCS_EXTRA
3857 A list of source file names to be compiled or assembled and inserted
3858 into @file{libgcc.a}.
3860 @findex CRTSTUFF_T_CFLAGS
3861 @item CRTSTUFF_T_CFLAGS
3862 Special flags used when compiling @file{crtstuff.c}.
3863 @xref{Initialization}.
3865 @findex CRTSTUFF_T_CFLAGS_S
3866 @item CRTSTUFF_T_CFLAGS_S
3867 Special flags used when compiling @file{crtstuff.c} for shared
3868 linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
3869 in @code{EXTRA-PARTS}.
3870 @xref{Initialization}.
3872 @findex MULTILIB_OPTIONS
3873 @item MULTILIB_OPTIONS
3874 For some targets, invoking GNU CC in different ways produces objects
3875 that can not be linked together. For example, for some targets GNU CC
3876 produces both big and little endian code. For these targets, you must
3877 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
3878 each set of incompatible options. When GNU CC invokes the linker, it
3879 arranges to link in the right version of @file{libgcc.a}, based on
3880 the command line options used.
3882 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
3883 special versions of @file{libgcc.a} must be built. Write options that
3884 are mutually incompatible side by side, separated by a slash. Write
3885 options that may be used together separated by a space. The build
3886 procedure will build all combinations of compatible options.
3888 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
3889 msoft-float}, @file{Makefile} will build special versions of
3890 @file{libgcc.a} using the following sets of options: @samp{-m68000},
3891 @samp{-m68020}, @samp{-msoft-float}, @samp{-m68000 -msoft-float}, and
3892 @samp{-m68020 -msoft-float}.
3894 @findex MULTILIB_DIRNAMES
3895 @item MULTILIB_DIRNAMES
3896 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
3897 directory names that should be used to hold the various libraries.
3898 Write one element in @code{MULTILIB_DIRNAMES} for each element in
3899 @code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
3900 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
3903 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
3904 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
3905 @samp{m68000 m68020 msoft-float}. You may specify a different value if
3906 you desire a different set of directory names.
3908 @findex MULTILIB_MATCHES
3909 @item MULTILIB_MATCHES
3910 Sometimes the same option may be written in two different ways. If an
3911 option is listed in @code{MULTILIB_OPTIONS}, GNU CC needs to know about
3912 any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
3913 items of the form @samp{option=option} to describe all relevant
3914 synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
3916 @findex MULTILIB_EXCEPTIONS
3917 @item MULTILIB_EXCEPTIONS
3918 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
3919 specified, there are combinations that should not be built. In that
3920 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
3921 in shell case syntax that should not be built.
3923 For example, in the PowerPC embedded ABI support, it was not desirable
3924 to build libraries that compiled with the @samp{-mcall-aixdesc} option
3925 and either of the @samp{-mcall-aixdesc} or @samp{-mlittle} options at
3926 the same time, and therefore @code{MULTILIB_EXCEPTIONS} is set to
3927 @code{*mrelocatable/*mcall-aixdesc* *mlittle/*mcall-aixdesc*}.
3929 @findex MULTILIB_EXTRA_OPTS
3930 @item MULTILIB_EXTRA_OPTS
3931 Sometimes it is desirable that when building multiple versions of
3932 @file{libgcc.a} certain options should always be passed on to the
3933 compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
3934 of options to be used for all builds.
3938 @section The Host Makefile Fragment
3939 @cindex host makefile fragment
3940 @cindex @file{x-@var{host}}
3942 The host makefile fragment, @file{x-@var{host}}, defines special host
3943 dependent variables and targets used in the @file{Makefile}:
3948 The compiler to use when building the first stage.
3952 Additional host libraries to link with.
3956 The compiler to use when building @file{libgcc1.a} for a native
3961 The version of @code{ar} to use when building @file{libgcc1.a} for a native
3966 The install program to use.
3970 @unnumbered Funding Free Software
3972 If you want to have more free software a few years from now, it makes
3973 sense for you to help encourage people to contribute funds for its
3974 development. The most effective approach known is to encourage
3975 commercial redistributors to donate.
3977 Users of free software systems can boost the pace of development by
3978 encouraging for-a-fee distributors to donate part of their selling price
3979 to free software developers---the Free Software Foundation, and others.
3981 The way to convince distributors to do this is to demand it and expect
3982 it from them. So when you compare distributors, judge them partly by
3983 how much they give to free software development. Show distributors
3984 they must compete to be the one who gives the most.
3986 To make this approach work, you must insist on numbers that you can
3987 compare, such as, ``We will donate ten dollars to the Frobnitz project
3988 for each disk sold.'' Don't be satisfied with a vague promise, such as
3989 ``A portion of the profits are donated,'' since it doesn't give a basis
3992 Even a precise fraction ``of the profits from this disk'' is not very
3993 meaningful, since creative accounting and unrelated business decisions
3994 can greatly alter what fraction of the sales price counts as profit.
3995 If the price you pay is $50, ten percent of the profit is probably
3996 less than a dollar; it might be a few cents, or nothing at all.
3998 Some redistributors do development work themselves. This is useful too;
3999 but to keep everyone honest, you need to inquire how much they do, and
4000 what kind. Some kinds of development make much more long-term
4001 difference than others. For example, maintaining a separate version of
4002 a program contributes very little; maintaining the standard version of a
4003 program for the whole community contributes much. Easy new ports
4004 contribute little, since someone else would surely do them; difficult
4005 ports such as adding a new CPU to the GNU C compiler contribute more;
4006 major new features or packages contribute the most.
4008 By establishing the idea that supporting further development is ``the
4009 proper thing to do'' when distributing free software for a fee, we can
4010 assure a steady flow of resources into making more free software.
4013 Copyright (C) 1994 Free Software Foundation, Inc.
4014 Verbatim copying and redistribution of this section is permitted
4015 without royalty; alteration is not permitted.
4019 @unnumbered Linux and the GNU Project
4021 Many computer users run a modified version of the GNU system every
4022 day, without realizing it. Through a peculiar turn of events, the
4023 version of GNU which is widely used today is more often known as
4024 ``Linux'', and many users are not aware of the extent of its
4025 connection with the GNU Project.
4027 There really is a Linux; it is a kernel, and these people are using
4028 it. But you can't use a kernel by itself; a kernel is useful only as
4029 part of a whole system. The system in which Linux is typically used
4030 is a modified variant of the GNU system---in other words, a Linux-based
4033 Many users are not fully aware of the distinction between the kernel,
4034 which is Linux, and the whole system, which they also call ``Linux''.
4035 The ambiguous use of the name doesn't promote understanding.
4037 Programmers generally know that Linux is a kernel. But since they
4038 have generally heard the whole system called ``Linux'' as well, they
4039 often envisage a history which fits that name. For example, many
4040 believe that once Linus Torvalds finished writing the kernel, his
4041 friends looked around for other free software, and for no particular
4042 reason most everything necessary to make a Unix-like system was
4045 What they found was no accident---it was the GNU system. The available
4046 free software added up to a complete system because the GNU Project
4047 had been working since 1984 to make one. The GNU Manifesto
4048 had set forth the goal of developing a free Unix-like system, called
4049 GNU. By the time Linux was written, the system was almost finished.
4051 Most free software projects have the goal of developing a particular
4052 program for a particular job. For example, Linus Torvalds set out to
4053 write a Unix-like kernel (Linux); Donald Knuth set out to write a text
4054 formatter (TeX); Bob Scheifler set out to develop a window system (X
4055 Windows). It's natural to measure the contribution of this kind of
4056 project by specific programs that came from the project.
4058 If we tried to measure the GNU Project's contribution in this way,
4059 what would we conclude? One CD-ROM vendor found that in their ``Linux
4060 distribution'', GNU software was the largest single contingent, around
4061 28% of the total source code, and this included some of the essential
4062 major components without which there could be no system. Linux itself
4063 was about 3%. So if you were going to pick a name for the system
4064 based on who wrote the programs in the system, the most appropriate
4065 single choice would be ``GNU''.
4067 But we don't think that is the right way to consider the question.
4068 The GNU Project was not, is not, a project to develop specific
4069 software packages. It was not a project to develop a C compiler,
4070 although we did. It was not a project to develop a text editor,
4071 although we developed one. The GNU Project's aim was to develop
4072 @emph{a complete free Unix-like system}.
4074 Many people have made major contributions to the free software in the
4075 system, and they all deserve credit. But the reason it is @emph{a
4076 system}---and not just a collection of useful programs---is because the
4077 GNU Project set out to make it one. We wrote the programs that were
4078 needed to make a @emph{complete} free system. We wrote essential but
4079 unexciting major components, such as the assembler and linker, because
4080 you can't have a system without them. A complete system needs more
4081 than just programming tools, so we wrote other components as well,
4082 such as the Bourne Again SHell, the PostScript interpreter
4083 Ghostscript, and the GNU C library.
4085 By the early 90s we had put together the whole system aside from the
4086 kernel (and we were also working on a kernel, the GNU Hurd, which runs
4087 on top of Mach). Developing this kernel has been a lot harder than we
4088 expected, and we are still working on finishing it.
4090 Fortunately, you don't have to wait for it, because Linux is working
4091 now. When Linus Torvalds wrote Linux, he filled the last major gap.
4092 People could then put Linux together with the GNU system to make a
4093 complete free system: a Linux-based GNU system (or GNU/Linux system,
4096 Putting them together sounds simple, but it was not a trivial job.
4097 The GNU C library (called glibc for short) needed substantial changes.
4098 Integrating a complete system as a distribution that would work ``out
4099 of the box'' was a big job, too. It required addressing the issue of
4100 how to install and boot the system---a problem we had not tackled,
4101 because we hadn't yet reached that point. The people who developed
4102 the various system distributions made a substantial contribution.
4104 The GNU Project supports GNU/Linux systems as well as @emph{the}
4105 GNU system---even with funds. We funded the rewriting of the
4106 Linux-related extensions to the GNU C library, so that now they are
4107 well integrated, and the newest GNU/Linux systems use the current
4108 library release with no changes. We also funded an early stage of the
4109 development of Debian GNU/Linux.
4111 We use Linux-based GNU systems today for most of our work, and we hope
4112 you use them too. But please don't confuse the public by using the
4113 name ``Linux'' ambiguously. Linux is the kernel, one of the essential
4114 major components of the system. The system as a whole is more or less
4118 @unnumbered GNU GENERAL PUBLIC LICENSE
4119 @center Version 2, June 1991
4122 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
4123 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
4125 Everyone is permitted to copy and distribute verbatim copies
4126 of this license document, but changing it is not allowed.
4129 @unnumberedsec Preamble
4131 The licenses for most software are designed to take away your
4132 freedom to share and change it. By contrast, the GNU General Public
4133 License is intended to guarantee your freedom to share and change free
4134 software---to make sure the software is free for all its users. This
4135 General Public License applies to most of the Free Software
4136 Foundation's software and to any other program whose authors commit to
4137 using it. (Some other Free Software Foundation software is covered by
4138 the GNU Library General Public License instead.) You can apply it to
4141 When we speak of free software, we are referring to freedom, not
4142 price. Our General Public Licenses are designed to make sure that you
4143 have the freedom to distribute copies of free software (and charge for
4144 this service if you wish), that you receive source code or can get it
4145 if you want it, that you can change the software or use pieces of it
4146 in new free programs; and that you know you can do these things.
4148 To protect your rights, we need to make restrictions that forbid
4149 anyone to deny you these rights or to ask you to surrender the rights.
4150 These restrictions translate to certain responsibilities for you if you
4151 distribute copies of the software, or if you modify it.
4153 For example, if you distribute copies of such a program, whether
4154 gratis or for a fee, you must give the recipients all the rights that
4155 you have. You must make sure that they, too, receive or can get the
4156 source code. And you must show them these terms so they know their
4159 We protect your rights with two steps: (1) copyright the software, and
4160 (2) offer you this license which gives you legal permission to copy,
4161 distribute and/or modify the software.
4163 Also, for each author's protection and ours, we want to make certain
4164 that everyone understands that there is no warranty for this free
4165 software. If the software is modified by someone else and passed on, we
4166 want its recipients to know that what they have is not the original, so
4167 that any problems introduced by others will not reflect on the original
4168 authors' reputations.
4170 Finally, any free program is threatened constantly by software
4171 patents. We wish to avoid the danger that redistributors of a free
4172 program will individually obtain patent licenses, in effect making the
4173 program proprietary. To prevent this, we have made it clear that any
4174 patent must be licensed for everyone's free use or not licensed at all.
4176 The precise terms and conditions for copying, distribution and
4177 modification follow.
4180 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4183 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4188 This License applies to any program or other work which contains
4189 a notice placed by the copyright holder saying it may be distributed
4190 under the terms of this General Public License. The ``Program'', below,
4191 refers to any such program or work, and a ``work based on the Program''
4192 means either the Program or any derivative work under copyright law:
4193 that is to say, a work containing the Program or a portion of it,
4194 either verbatim or with modifications and/or translated into another
4195 language. (Hereinafter, translation is included without limitation in
4196 the term ``modification''.) Each licensee is addressed as ``you''.
4198 Activities other than copying, distribution and modification are not
4199 covered by this License; they are outside its scope. The act of
4200 running the Program is not restricted, and the output from the Program
4201 is covered only if its contents constitute a work based on the
4202 Program (independent of having been made by running the Program).
4203 Whether that is true depends on what the Program does.
4206 You may copy and distribute verbatim copies of the Program's
4207 source code as you receive it, in any medium, provided that you
4208 conspicuously and appropriately publish on each copy an appropriate
4209 copyright notice and disclaimer of warranty; keep intact all the
4210 notices that refer to this License and to the absence of any warranty;
4211 and give any other recipients of the Program a copy of this License
4212 along with the Program.
4214 You may charge a fee for the physical act of transferring a copy, and
4215 you may at your option offer warranty protection in exchange for a fee.
4218 You may modify your copy or copies of the Program or any portion
4219 of it, thus forming a work based on the Program, and copy and
4220 distribute such modifications or work under the terms of Section 1
4221 above, provided that you also meet all of these conditions:
4225 You must cause the modified files to carry prominent notices
4226 stating that you changed the files and the date of any change.
4229 You must cause any work that you distribute or publish, that in
4230 whole or in part contains or is derived from the Program or any
4231 part thereof, to be licensed as a whole at no charge to all third
4232 parties under the terms of this License.
4235 If the modified program normally reads commands interactively
4236 when run, you must cause it, when started running for such
4237 interactive use in the most ordinary way, to print or display an
4238 announcement including an appropriate copyright notice and a
4239 notice that there is no warranty (or else, saying that you provide
4240 a warranty) and that users may redistribute the program under
4241 these conditions, and telling the user how to view a copy of this
4242 License. (Exception: if the Program itself is interactive but
4243 does not normally print such an announcement, your work based on
4244 the Program is not required to print an announcement.)
4247 These requirements apply to the modified work as a whole. If
4248 identifiable sections of that work are not derived from the Program,
4249 and can be reasonably considered independent and separate works in
4250 themselves, then this License, and its terms, do not apply to those
4251 sections when you distribute them as separate works. But when you
4252 distribute the same sections as part of a whole which is a work based
4253 on the Program, the distribution of the whole must be on the terms of
4254 this License, whose permissions for other licensees extend to the
4255 entire whole, and thus to each and every part regardless of who wrote it.
4257 Thus, it is not the intent of this section to claim rights or contest
4258 your rights to work written entirely by you; rather, the intent is to
4259 exercise the right to control the distribution of derivative or
4260 collective works based on the Program.
4262 In addition, mere aggregation of another work not based on the Program
4263 with the Program (or with a work based on the Program) on a volume of
4264 a storage or distribution medium does not bring the other work under
4265 the scope of this License.
4268 You may copy and distribute the Program (or a work based on it,
4269 under Section 2) in object code or executable form under the terms of
4270 Sections 1 and 2 above provided that you also do one of the following:
4274 Accompany it with the complete corresponding machine-readable
4275 source code, which must be distributed under the terms of Sections
4276 1 and 2 above on a medium customarily used for software interchange; or,
4279 Accompany it with a written offer, valid for at least three
4280 years, to give any third party, for a charge no more than your
4281 cost of physically performing source distribution, a complete
4282 machine-readable copy of the corresponding source code, to be
4283 distributed under the terms of Sections 1 and 2 above on a medium
4284 customarily used for software interchange; or,
4287 Accompany it with the information you received as to the offer
4288 to distribute corresponding source code. (This alternative is
4289 allowed only for noncommercial distribution and only if you
4290 received the program in object code or executable form with such
4291 an offer, in accord with Subsection b above.)
4294 The source code for a work means the preferred form of the work for
4295 making modifications to it. For an executable work, complete source
4296 code means all the source code for all modules it contains, plus any
4297 associated interface definition files, plus the scripts used to
4298 control compilation and installation of the executable. However, as a
4299 special exception, the source code distributed need not include
4300 anything that is normally distributed (in either source or binary
4301 form) with the major components (compiler, kernel, and so on) of the
4302 operating system on which the executable runs, unless that component
4303 itself accompanies the executable.
4305 If distribution of executable or object code is made by offering
4306 access to copy from a designated place, then offering equivalent
4307 access to copy the source code from the same place counts as
4308 distribution of the source code, even though third parties are not
4309 compelled to copy the source along with the object code.
4312 You may not copy, modify, sublicense, or distribute the Program
4313 except as expressly provided under this License. Any attempt
4314 otherwise to copy, modify, sublicense or distribute the Program is
4315 void, and will automatically terminate your rights under this License.
4316 However, parties who have received copies, or rights, from you under
4317 this License will not have their licenses terminated so long as such
4318 parties remain in full compliance.
4321 You are not required to accept this License, since you have not
4322 signed it. However, nothing else grants you permission to modify or
4323 distribute the Program or its derivative works. These actions are
4324 prohibited by law if you do not accept this License. Therefore, by
4325 modifying or distributing the Program (or any work based on the
4326 Program), you indicate your acceptance of this License to do so, and
4327 all its terms and conditions for copying, distributing or modifying
4328 the Program or works based on it.
4331 Each time you redistribute the Program (or any work based on the
4332 Program), the recipient automatically receives a license from the
4333 original licensor to copy, distribute or modify the Program subject to
4334 these terms and conditions. You may not impose any further
4335 restrictions on the recipients' exercise of the rights granted herein.
4336 You are not responsible for enforcing compliance by third parties to
4340 If, as a consequence of a court judgment or allegation of patent
4341 infringement or for any other reason (not limited to patent issues),
4342 conditions are imposed on you (whether by court order, agreement or
4343 otherwise) that contradict the conditions of this License, they do not
4344 excuse you from the conditions of this License. If you cannot
4345 distribute so as to satisfy simultaneously your obligations under this
4346 License and any other pertinent obligations, then as a consequence you
4347 may not distribute the Program at all. For example, if a patent
4348 license would not permit royalty-free redistribution of the Program by
4349 all those who receive copies directly or indirectly through you, then
4350 the only way you could satisfy both it and this License would be to
4351 refrain entirely from distribution of the Program.
4353 If any portion of this section is held invalid or unenforceable under
4354 any particular circumstance, the balance of the section is intended to
4355 apply and the section as a whole is intended to apply in other
4358 It is not the purpose of this section to induce you to infringe any
4359 patents or other property right claims or to contest validity of any
4360 such claims; this section has the sole purpose of protecting the
4361 integrity of the free software distribution system, which is
4362 implemented by public license practices. Many people have made
4363 generous contributions to the wide range of software distributed
4364 through that system in reliance on consistent application of that
4365 system; it is up to the author/donor to decide if he or she is willing
4366 to distribute software through any other system and a licensee cannot
4369 This section is intended to make thoroughly clear what is believed to
4370 be a consequence of the rest of this License.
4373 If the distribution and/or use of the Program is restricted in
4374 certain countries either by patents or by copyrighted interfaces, the
4375 original copyright holder who places the Program under this License
4376 may add an explicit geographical distribution limitation excluding
4377 those countries, so that distribution is permitted only in or among
4378 countries not thus excluded. In such case, this License incorporates
4379 the limitation as if written in the body of this License.
4382 The Free Software Foundation may publish revised and/or new versions
4383 of the General Public License from time to time. Such new versions will
4384 be similar in spirit to the present version, but may differ in detail to
4385 address new problems or concerns.
4387 Each version is given a distinguishing version number. If the Program
4388 specifies a version number of this License which applies to it and ``any
4389 later version'', you have the option of following the terms and conditions
4390 either of that version or of any later version published by the Free
4391 Software Foundation. If the Program does not specify a version number of
4392 this License, you may choose any version ever published by the Free Software
4396 If you wish to incorporate parts of the Program into other free
4397 programs whose distribution conditions are different, write to the author
4398 to ask for permission. For software which is copyrighted by the Free
4399 Software Foundation, write to the Free Software Foundation; we sometimes
4400 make exceptions for this. Our decision will be guided by the two goals
4401 of preserving the free status of all derivatives of our free software and
4402 of promoting the sharing and reuse of software generally.
4405 @heading NO WARRANTY
4412 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
4413 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
4414 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
4415 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
4416 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
4417 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
4418 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
4419 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
4420 REPAIR OR CORRECTION.
4423 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
4424 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
4425 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
4426 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
4427 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
4428 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
4429 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
4430 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
4431 POSSIBILITY OF SUCH DAMAGES.
4435 @heading END OF TERMS AND CONDITIONS
4438 @center END OF TERMS AND CONDITIONS
4442 @unnumberedsec How to Apply These Terms to Your New Programs
4444 If you develop a new program, and you want it to be of the greatest
4445 possible use to the public, the best way to achieve this is to make it
4446 free software which everyone can redistribute and change under these terms.
4448 To do so, attach the following notices to the program. It is safest
4449 to attach them to the start of each source file to most effectively
4450 convey the exclusion of warranty; and each file should have at least
4451 the ``copyright'' line and a pointer to where the full notice is found.
4454 @var{one line to give the program's name and a brief idea of what it does.}
4455 Copyright (C) 19@var{yy} @var{name of author}
4457 This program is free software; you can redistribute it and/or modify
4458 it under the terms of the GNU General Public License as published by
4459 the Free Software Foundation; either version 2 of the License, or
4460 (at your option) any later version.
4462 This program is distributed in the hope that it will be useful,
4463 but WITHOUT ANY WARRANTY; without even the implied warranty of
4464 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4465 GNU General Public License for more details.
4467 You should have received a copy of the GNU General Public License
4468 along with this program; if not, write to the Free Software
4469 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
4472 Also add information on how to contact you by electronic and paper mail.
4474 If the program is interactive, make it output a short notice like this
4475 when it starts in an interactive mode:
4478 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
4479 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
4481 This is free software, and you are welcome to redistribute it
4482 under certain conditions; type `show c' for details.
4485 The hypothetical commands @samp{show w} and @samp{show c} should show
4486 the appropriate parts of the General Public License. Of course, the
4487 commands you use may be called something other than @samp{show w} and
4488 @samp{show c}; they could even be mouse-clicks or menu items---whatever
4491 You should also get your employer (if you work as a programmer) or your
4492 school, if any, to sign a ``copyright disclaimer'' for the program, if
4493 necessary. Here is a sample; alter the names:
4496 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
4497 `Gnomovision' (which makes passes at compilers) written by James Hacker.
4499 @var{signature of Ty Coon}, 1 April 1989
4500 Ty Coon, President of Vice
4503 This General Public License does not permit incorporating your program into
4504 proprietary programs. If your program is a subroutine library, you may
4505 consider it more useful to permit linking proprietary applications with the
4506 library. If this is what you want to do, use the GNU Library General
4507 Public License instead of this License.
4510 @unnumbered Contributors to GNU CC
4511 @cindex contributors
4513 In addition to Richard Stallman, several people have written parts
4518 The idea of using RTL and some of the optimization ideas came from the
4519 program PO written at the University of Arizona by Jack Davidson and
4520 Christopher Fraser. See ``Register Allocation and Exhaustive Peephole
4521 Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
4525 Paul Rubin wrote most of the preprocessor.
4528 Leonard Tower wrote parts of the parser, RTL generator, and RTL
4529 definitions, and of the Vax machine description.
4532 Ted Lemon wrote parts of the RTL reader and printer.
4535 Jim Wilson implemented loop strength reduction and some other
4539 Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
4540 the support for the Sony NEWS machine.
4543 Charles LaBrec contributed the support for the Integrated Solutions
4547 Michael Tiemann of Cygnus Support wrote the front end for C++, as well
4548 as the support for inline functions and instruction scheduling. Also
4549 the descriptions of the National Semiconductor 32000 series cpu, the
4550 SPARC cpu and part of the Motorola 88000 cpu.
4553 Gerald Baumgartner added the signature extension to the C++ front-end.
4556 Jan Stein of the Chalmers Computer Society provided support for
4557 Genix, as well as part of the 32000 machine description.
4560 Randy Smith finished the Sun FPA support.
4563 Robert Brown implemented the support for Encore 32000 systems.
4566 David Kashtan of SRI adapted GNU CC to VMS.
4569 Alex Crain provided changes for the 3b1.
4572 Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for
4573 the 9000 series 300.
4576 William Schelter did most of the work on the Intel 80386 support.
4579 Christopher Smith did the port for Convex machines.
4582 Paul Petersen wrote the machine description for the Alliant FX/8.
4585 Dario Dariol contributed the four varieties of sample programs
4586 that print a copy of their source.
4589 Alain Lichnewsky ported GNU CC to the Mips cpu.
4592 Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the Tahoe.
4595 Jonathan Stone wrote the machine description for the Pyramid computer.
4598 Gary Miller ported GNU CC to Charles River Data Systems machines.
4601 Richard Kenner of the New York University Ultracomputer Research
4602 Laboratory wrote the machine descriptions for the AMD 29000, the DEC
4603 Alpha, the IBM RT PC, and the IBM RS/6000 as well as the support for
4604 instruction attributes. He also made changes to better support RISC
4605 processors including changes to common subexpression elimination,
4606 strength reduction, function calling sequence handling, and condition
4607 code support, in addition to generalizing the code for frame pointer
4611 Richard Kenner and Michael Tiemann jointly developed reorg.c, the delay
4615 Mike Meissner and Tom Wood of Data General finished the port to the
4619 Masanobu Yuhara of Fujitsu Laboratories implemented the machine
4620 description for the Tron architecture (specifically, the Gmicro).
4623 NeXT, Inc.@: donated the front end that supports the Objective C
4625 @c We need to be careful to make it clear that "Objective C"
4626 @c is the name of a language, not that of a program or product.
4629 James van Artsdalen wrote the code that makes efficient use of
4630 the Intel 80387 register stack.
4633 Mike Meissner at the Open Software Foundation finished the port to the
4634 MIPS cpu, including adding ECOFF debug support, and worked on the
4635 Intel port for the Intel 80386 cpu. Later at Cygnus Support, he worked
4636 on the rs6000 and PowerPC ports.
4639 Ron Guilmette implemented the @code{protoize} and @code{unprotoize}
4640 tools, the support for Dwarf symbolic debugging information, and much of
4641 the support for System V Release 4. He has also worked heavily on the
4642 Intel 386 and 860 support.
4645 Torbjorn Granlund implemented multiply- and divide-by-constant
4646 optimization, improved long long support, and improved leaf function
4647 register allocation.
4650 Mike Stump implemented the support for Elxsi 64 bit CPU.
4653 John Wehle added the machine description for the Western Electric 32000
4654 processor used in several 3b series machines (no relation to the
4655 National Semiconductor 32000 processor).
4657 @ignore @c These features aren't advertised yet, since they don't fully work.
4659 Analog Devices helped implement the support for complex data types
4664 Holger Teutsch provided the support for the Clipper cpu.
4667 Kresten Krab Thorup wrote the run time support for the Objective C
4671 Stephen Moshier contributed the floating point emulator that assists in
4672 cross-compilation and permits support for floating point numbers wider
4676 David Edelsohn contributed the changes to RS/6000 port to make it
4677 support the PowerPC and POWER2 architectures.
4680 Steve Chamberlain wrote the support for the Hitachi SH processor.
4683 Peter Schauer wrote the code to allow debugging to work on the Alpha.
4686 Oliver M. Kellogg of Deutsche Aerospace contributed the port to the
4690 Michael K. Gschwind contributed the port to the PDP-11.
4693 David Reese of Sun Microsystems contributed to the Solaris on PowerPC