1 \input texinfo @c -*-texinfo-*-
4 @c @setfilename usegcc.info
5 @c @setfilename portgcc.info
6 @c To produce the full manual, use the "gcc.info" setfilename, and
7 @c make sure the following do NOT begin with '@c' (and the @clear lines DO)
10 @c To produce a user-only manual, use the "usegcc.info" setfilename, and
11 @c make sure the following does NOT begin with '@c':
13 @c To produce a porter-only manual, use the "portgcc.info" setfilename,
14 @c and make sure the following does NOT begin with '@c':
17 @c (For FSF printing, turn on smallbook, comment out finalout below;
18 @c that is all that is needed.)
20 @c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition.
23 @c i also commented out the finalout command, so if there *are* any
24 @c overfulls, you'll (hopefully) see the rectangle in the right hand
25 @c margin. -mew 15june93
28 @c NOTE: checks/things to do:
30 @c -have bob do a search in all seven files for "mew" (ideally --mew,
31 @c but i may have forgotten the occasional "--"..).
32 @c Just checked... all have `--'! Bob 22Jul96
33 @c Use this to search: grep -n '\-\-mew' *.texi
34 @c -item/itemx, text after all (sub/sub)section titles, etc..
35 @c -consider putting the lists of options on pp 17--> etc in columns or
38 @c -continuity of phrasing; ie, bit-field vs bitfield in rtl.texi
39 @c -overfulls. do a search for "mew" in the files, and you will see
40 @c overfulls that i noted but could not deal with.
41 @c -have to add text: beginning of chapter 8
44 @c anything else? --mew 10feb93
46 @macro gcctabopt{body}
49 @macro gccoptlist{body}
54 @c Makeinfo handles the above macro OK, TeX needs manual line breaks;
55 @c they get lost at some point in handling the macro. But if @macro is
56 @c used here rather than @alias, it produces double line breaks.
67 @settitle Using and Porting the GNU Compiler Collection (GCC)
70 @c seems reasonable to assume at least one of INTERNALS or USING is set...
72 @settitle Using the GNU Compiler Collection
75 @settitle Porting the GNU Compiler Collection
86 @c Use with @@smallbook.
88 @c Cause even numbered pages to be printed on the left hand side of
89 @c the page and odd numbered pages to be printed on the right hand
90 @c side of the page. Using this, you can print on both sides of a
91 @c sheet of paper and have the text on the same part of the sheet.
93 @c The text on right hand pages is pushed towards the right hand
94 @c margin and the text on left hand pages is pushed toward the left
96 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
99 @c \global\bindingoffset=0.75in
100 @c \global\normaloffset =0.75in
104 @dircategory Programming
106 * gcc: (gcc). The GNU Compiler Collection.
110 This file documents the use and the internals of the GNU compiler.
114 This file documents the internals of the GNU compiler.
117 This file documents the use of the GNU compiler.
120 Published by the Free Software Foundation@*
121 59 Temple Place - Suite 330@*
122 Boston, MA 02111-1307 USA
124 @c When you update the list of years below, search for copyright{} and
125 @c update the other copy too.
126 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
127 1999, 2000, 2001 Free Software Foundation, Inc.
129 Permission is granted to copy, distribute and/or modify this document
130 under the terms of the GNU Free Documentation License, Version 1.1 or
131 any later version published by the Free Software Foundation; with the
132 Invariant Sections being ``GNU General Public License'' and ``Funding
133 Free Software'', the Front-Cover texts being (a) (see below), and with
134 the Back-Cover Texts being (b) (see below). A copy of the license is
135 included in the section entitled ``GNU Free Documentation License''.
137 (a) The FSF's Front-Cover Text is:
141 (b) The FSF's Back-Cover Text is:
143 You have freedom to copy and modify this GNU Manual, like GNU
144 software. Copies published by the Free Software Foundation raise
145 funds for GNU development.
148 @setchapternewpage odd
153 @center @titlefont{Using and Porting the GNU Compiler Collection}
158 @title Using the GNU Compiler Collection
161 @title Porting the GNU Compiler Collection
164 @center Richard M. Stallman
166 @center Last updated 9 May 2001
168 @c The version number appears five times more in this file.
172 @vskip 0pt plus 1filll
173 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
174 1999, 2000, 2001 Free Software Foundation, Inc.
176 For GCC Version 3.1@*
178 Published by the Free Software Foundation @*
179 59 Temple Place - Suite 330@*
180 Boston, MA 02111-1307, USA@*
181 Last printed April, 1998.@*
182 Printed copies are available for $50 each.@*
185 Permission is granted to copy, distribute and/or modify this document
186 under the terms of the GNU Free Documentation License, Version 1.1 or
187 any later version published by the Free Software Foundation; with the
188 Invariant Sections being ``GNU General Public License'', the Front-Cover
189 texts being (a) (see below), and with the Back-Cover Texts being (b)
190 (see below). A copy of the license is included in the section entitled
191 ``GNU Free Documentation License''.
193 (a) The FSF's Front-Cover Text is:
197 (b) The FSF's Back-Cover Text is:
199 You have freedom to copy and modify this GNU Manual, like GNU
200 software. Copies published by the Free Software Foundation raise
201 funds for GNU development.
205 @node Top, G++ and GCC,, (DIR)
211 This manual documents how to run, install and port the GNU
212 compiler, as well as its new features and incompatibilities, and how to
213 report bugs. It corresponds to GCC version 3.1.
218 This manual documents how to run and install the GNU compiler,
219 as well as its new features and incompatibilities, and how to report
220 bugs. It corresponds to GCC version 3.1.
223 This manual documents how to port the GNU compiler,
224 as well as its new features and incompatibilities, and how to report
225 bugs. It corresponds to GCC version 3.1.
230 * G++ and GCC:: You can compile C or C++ programs.
231 * Standards:: Language standards supported by GCC.
232 * Invoking GCC:: Command options supported by @samp{gcc}.
233 * Installation:: How to configure, compile and install GCC.
234 * C Extensions:: GNU extensions to the C language family.
235 * C++ Extensions:: GNU extensions to the C++ language.
236 * Objective C:: GNU Objective-C runtime features.
237 * Gcov:: gcov: a GCC test coverage program.
238 * Trouble:: If you have trouble installing GCC.
239 * Bugs:: How, why and where to report bugs.
240 * Service:: How to find suppliers of support for GCC.
241 * Contributing:: How to contribute to testing and developing GCC.
242 * VMS:: Using GCC on VMS.
243 * Makefile:: List of Makefile targets.
246 * Portability:: Goals of GCC's portability features.
247 * Interface:: Function-call interface of GCC output.
248 * Passes:: Order of passes, what they do, and what each file is for.
249 * Trees:: The source representation used by the C and C++ front-ends.
250 * RTL:: The intermediate representation that most passes work on.
251 * Machine Desc:: How to write machine description instruction patterns.
252 * Target Macros:: How to write the machine description C macros.
253 * Config:: Writing the @file{xm-@var{machine}.h} file.
254 * Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
257 * Funding:: How to help assure funding for free software.
258 * GNU/Linux:: Linux and the GNU Project
260 * Copying:: GNU General Public License says
261 how you can copy and share GCC.
262 * GNU Free Documentation License:: How you can copy and share this manual.
263 * Contributors:: People who have contributed to GCC.
265 * Index:: Index of concepts and symbol names.
270 @chapter Compile C, C++, Objective C, Fortran, Java or CHILL
273 Several versions of the compiler (C, C++, Objective C, Fortran, Java
274 and CHILL) are integrated; this is why we use the name
275 ``GNU Compiler Collection''. GCC can compile programs written in any of these
276 languages. The Fortran, CHILL, and Java compilers are described in
280 ``GCC'' is a common shorthand term for the GNU Compiler Collection. This is both
281 the most general name for the compiler, and the name used when the
282 emphasis is on compiling C programs (as the abbreviation formerly
283 stood for ``GNU C Compiler'').
287 When referring to C++ compilation, it is usual to call the compiler
288 ``G++''. Since there is only one compiler, it is also accurate to call
289 it ``GCC'' no matter what the language context; however, the term
290 ``G++'' is more useful when the emphasis is on compiling C++ programs.
292 We use the name ``GCC'' to refer to the compilation system as a
293 whole, and more specifically to the language-independent part of the
294 compiler. For example, we refer to the optimization options as
295 affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
297 Front ends for other languages, such as Ada 95 and Pascal exist but
298 have not yet been integrated into GCC. These front-ends, like that for C++,
299 are built in subdirectories of GCC and link to it. The result is an
300 integrated compiler that can compile programs written in C, C++,
301 Objective C, or any of the languages for which you have installed front
304 In this manual, we only discuss the options for the C, Objective-C, and
305 C++ compilers and those of the GCC core. Consult the documentation
306 of the other front ends for the options to use when compiling programs
307 written in other languages.
309 @cindex compiler compared to C++ preprocessor
310 @cindex intermediate C version, nonexistent
311 @cindex C intermediate output, nonexistent
312 G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object
313 code directly from your C++ program source. There is no intermediate C
314 version of the program. (By contrast, for example, some other
315 implementations use a program that generates a C program from your C++
316 source.) Avoiding an intermediate C representation of the program means
317 that you get better object code, and better debugging information. The
318 GNU debugger, GDB, works with this information in the object code to
319 give you comprehensive C++ source-level editing capabilities
320 (@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
322 @c FIXME! Someone who knows something about Objective C ought to put in
323 @c a paragraph or two about it here, and move the index entry down when
324 @c there is more to point to than the general mention in the 1st par.
327 @chapter Language Standards Supported by GCC
330 @cindex ANSI C standard
334 @cindex ANSI X3.159-1989
336 @cindex ISO C standard
351 @cindex Technical Corrigenda
353 @cindex Technical Corrigendum 1
355 @cindex Technical Corrigendum 2
357 @cindex freestanding implementation
358 @cindex freestanding environment
359 @cindex hosted implementation
360 @cindex hosted environment
361 @findex __STDC_HOSTED__
363 For each language compiled by GCC for which there is a standard, GCC
364 attempts to follow one or more versions of that standard, possibly
365 with some exceptions, and possibly with some extensions.
367 GCC supports three versions of the C standard, although support for
368 the most recent version is not yet complete.
370 The original ANSI C standard (X3.159-1989) was ratified in 1989 and
371 published in 1990. This standard was ratified as an ISO standard
372 (ISO/IEC 9899:1990) later in 1990. There were no technical
373 differences between these publications, although the sections of the
374 ANSI standard were renumbered and became clauses in the ISO standard.
375 This standard, in both its forms, is commonly known as @dfn{C89}, or
376 occasionally as @dfn{C90}, from the dates of ratification. The ANSI
377 standard, but not the ISO standard, also came with a Rationale
378 document. To select this standard in GCC, use one of the options
379 @samp{-ansi}, @samp{-std=c89} or @samp{-std=iso9899:1990}; to obtain
380 all the diagnostics required by the standard, you should also specify
381 @samp{-pedantic} (or @samp{-pedantic-errors} if you want them to be
382 errors rather than warnings). @xref{C Dialect Options,,Options
383 Controlling C Dialect}.
385 Errors in the 1990 ISO C standard were corrected in two Technical
386 Corrigenda published in 1994 and 1996. GCC does not support the
389 An amendment to the 1990 standard was published in 1995. This
390 amendment added digraphs and @code{__STDC_VERSION__} to the language,
391 but otherwise concerned the library. This amendment is commonly known
392 as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
393 @dfn{C95}. To select this standard in GCC, use the option
394 @samp{-std=iso9899:199409} (with, as for other standard versions,
395 @samp{-pedantic} to receive all required diagnostics).
397 A new edition of the ISO C standard was published in 1999 as ISO/IEC
398 9899:1999, and is commonly known as @dfn{C99}. GCC has incomplete
399 support for this standard version; see
400 @uref{http://gcc.gnu.org/c99status.html} for details. To select this
401 standard, use @samp{-std=c99} or @samp{-std=iso9899:1999}. (While in
402 development, drafts of this standard version were referred to as
405 GCC also has some limited support for traditional (pre-ISO) C with the
406 @samp{-traditional} option. This support may be of use for compiling
407 some very old programs that have not been updated to ISO C, but should
408 not be used for new programs. It will not work with some modern C
409 libraries such as the GNU C library.
411 By default, GCC provides some extensions to the C language that on
412 rare occasions conflict with the C standard. @xref{C
413 Extensions,,Extensions to the C Language Family}. Use of the
414 @samp{-std} options listed above will disable these extensions where
415 they conflict with the C standard version selected. You may also
416 select an extended version of the C language explicitly with
417 @samp{-std=gnu89} (for C89 with GNU extensions) or @samp{-std=gnu99}
418 (for C99 with GNU extensions). The default, if no C language dialect
419 options are given, is @samp{-std=gnu89}; this will change to
420 @samp{-std=gnu99} in some future release when the C99 support is
421 complete. Some features that are part of the C99 standard are
422 accepted as extensions in C89 mode.
424 The ISO C standard defines (in clause 4) two classes of conforming
425 implementation. A @dfn{conforming hosted implementation} supports the
426 whole standard including all the library facilities; a @dfn{conforming
427 freestanding implementation} is only required to provide certain
428 library facilities: those in @code{<float.h>}, @code{<limits.h>},
429 @code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
430 @code{<iso646.h>}; and in C99, also those in @code{<stdbool.h>} and
431 @code{<stdint.h>}. In addition, complex types, added in C99, are not
432 required for freestanding implementations. The standard also defines
433 two environments for programs, a @dfn{freestanding environment},
434 required of all implementations and which may not have library
435 facilities beyond those required of freestanding implementations,
436 where the handling of program startup and termination are
437 implementation-defined, and a @dfn{hosted environment}, which is not
438 required, in which all the library facilities are provided and startup
439 is through a function @code{int main (void)} or @code{int main (int,
440 char *[])}. An OS kernel would be a freestanding environment; a
441 program using the facilities of an operating system would normally be
442 in a hosted implementation.
444 GNU CC aims towards being usable as a conforming freestanding
445 implementation, or as the compiler for a conforming hosted
446 implementation. By default, it will act as the compiler for a hosted
447 implementation, defining @code{__STDC_HOSTED__} as @code{1} and
448 presuming that when the names of ISO C functions are used, they have
449 the semantics defined in the standard. To make it act as a conforming
450 freestanding implementation for a freestanding environment, use the
451 option @samp{-ffreestanding}; it will then define
452 @code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
453 meanings of function names from the standard library. To build an OS
454 kernel, you may well still need to make your own arrangements for
455 linking and startup. @xref{C Dialect Options,,Options Controlling C
458 GNU CC does not provide the library facilities required only of hosted
459 implementations, nor yet all the facilities required by C99 of
460 freestanding implementations; to use the facilities of a hosted
461 environment, you will need to find them elsewhere (for example, in the
462 GNU C library). @xref{Standard Libraries,,Standard Libraries}.
464 For references to Technical Corrigenda, Rationale documents and
465 information concerning the history of C that is available online, see
466 @uref{http://gcc.gnu.org/readings.html}
468 @c FIXME: details of C++ standard.
469 @c FIXME: definitions of Java and Objective C.
471 @xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
472 Fortran}, for details of the Fortran language supported by GCC.
474 @xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj},
475 for details of compatibility between @code{gcj} and the Java Platform.
477 @xref{References,,Language Definition References, chill, GNU Chill},
478 for details of the CHILL standard.
482 @include install.texi
491 @chapter Known Causes of Trouble with GCC
493 @cindex installation trouble
494 @cindex known causes of trouble
496 This section describes known problems that affect users of GCC. Most
497 of these are not GCC bugs per se---if they were, we would fix them.
498 But the result for a user may be like the result of a bug.
500 Some of these problems are due to bugs in other software, some are
501 missing features that are too much work to add, and some are places
502 where people's opinions differ as to what is best.
505 * Actual Bugs:: Bugs we will fix later.
506 * Installation Problems:: Problems that manifest when you install GCC.
507 * Cross-Compiler Problems:: Common problems of cross compiling with GCC.
508 * Interoperation:: Problems using GCC with other compilers,
509 and with certain linkers, assemblers and debuggers.
510 * External Bugs:: Problems compiling certain programs.
511 * Incompatibilities:: GCC is incompatible with traditional C.
512 * Fixed Headers:: GNU C uses corrected versions of system header files.
513 This is necessary, but doesn't always work smoothly.
514 * Standard Libraries:: GNU C uses the system C library, which might not be
515 compliant with the ISO C standard.
516 * Disappointments:: Regrettable things we can't change, but not quite bugs.
517 * C++ Misunderstandings:: Common misunderstandings with GNU C++.
518 * Protoize Caveats:: Things to watch out for when using @code{protoize}.
519 * Non-bugs:: Things we think are right, but some others disagree.
520 * Warnings and Errors:: Which problems in your code get warnings,
521 and which get errors.
525 @section Actual Bugs We Haven't Fixed Yet
529 The @code{fixincludes} script interacts badly with automounters; if the
530 directory of system header files is automounted, it tends to be
531 unmounted while @code{fixincludes} is running. This would seem to be a
532 bug in the automounter. We don't know any good way to work around it.
535 The @code{fixproto} script will sometimes add prototypes for the
536 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
537 @code{jmp_buf} type before that type is defined. To work around this,
538 edit the offending file and place the typedef in front of the
542 When @samp{-pedantic-errors} is specified, GCC will incorrectly give
543 an error message when a function name is specified in an expression
544 involving the comma operator.
547 @node Installation Problems
548 @section Installation Problems
550 This is a list of problems (and some apparent problems which don't
551 really mean anything is wrong) that show up during installation of GNU
556 On certain systems, defining certain environment variables such as
557 @code{CC} can interfere with the functioning of @code{make}.
560 If you encounter seemingly strange errors when trying to build the
561 compiler in a directory other than the source directory, it could be
562 because you have previously configured the compiler in the source
563 directory. Make sure you have done all the necessary preparations.
567 If you build GCC on a BSD system using a directory stored in a System
568 V file system, problems may occur in running @code{fixincludes} if the
569 System V file system doesn't support symbolic links. These problems
570 result in a failure to fix the declaration of @code{size_t} in
571 @file{sys/types.h}. If you find that @code{size_t} is a signed type and
572 that type mismatches occur, this could be the cause.
574 The solution is not to use such a directory for building GCC.
577 Some commands executed when making the compiler may fail (return a
578 non-zero status) and be ignored by @code{make}. These failures, which
579 are often due to files that were not found, are expected, and can safely
583 It is normal to have warnings in compiling certain files about
584 unreachable code and about enumeration type clashes. These files' names
585 begin with @samp{insn-}. Also, @file{real.c} may get some warnings that
589 Sometimes @code{make} recompiles parts of the compiler when installing
590 the compiler. In one case, this was traced down to a bug in
591 @code{make}. Either ignore the problem or switch to GNU Make.
594 On GNU/Linux SLS 1.01, there is a problem with @file{libc.a}: it does not
595 contain the obstack functions. However, GCC assumes that the obstack
596 functions are in @file{libc.a} when it is the GNU C library. To work
597 around this problem, change the @code{__GNU_LIBRARY__} conditional
598 around line 31 to @samp{#if 1}.
601 On SCO systems, when compiling GCC with the system's compiler,
602 do not use @samp{-O}. Some versions of the system's compiler miscompile
605 @cindex @code{genflags}, crash on Sun 4
607 Sometimes on a Sun 4 you may observe a crash in the program
608 @code{genflags} or @code{genoutput} while building GCC. This is said to
609 be due to a bug in @code{sh}. You can probably get around it by running
610 @code{genflags} or @code{genoutput} manually and then retrying the
614 On Solaris 2, executables of GCC version 2.0.2 are commonly
615 available, but they have a bug that shows up when compiling current
616 versions of GCC: undefined symbol errors occur during assembly if you
619 The solution is to compile the current version of GCC without
620 @samp{-g}. That makes a working compiler which you can use to recompile
624 Solaris 2 comes with a number of optional OS packages. Some of these
625 packages are needed to use GCC fully. If you did not install all
626 optional packages when installing Solaris, you will need to verify that
627 the packages that GCC needs are installed.
629 To check whether an optional package is installed, use
630 the @code{pkginfo} command. To add an optional package, use the
631 @code{pkgadd} command. For further details, see the Solaris
634 For Solaris 2.0 and 2.1, GCC needs six packages: @samp{SUNWarc},
635 @samp{SUNWbtool}, @samp{SUNWesu}, @samp{SUNWhea}, @samp{SUNWlibm}, and
638 For Solaris 2.2, GCC needs an additional seventh package: @samp{SUNWsprot}.
641 On Solaris 2, trying to use the linker and other tools in
642 @file{/usr/ucb} to install GCC has been observed to cause trouble.
643 For example, the linker may hang indefinitely. The fix is to remove
644 @file{/usr/ucb} from your @code{PATH}.
647 If you use the 1.31 version of the MIPS assembler (such as was shipped
648 with Ultrix 3.1), you will need to use the -fno-delayed-branch switch
649 when optimizing floating point code. Otherwise, the assembler will
650 complain when the GCC compiler fills a branch delay slot with a
651 floating point instruction, such as @code{add.d}.
654 If on a MIPS system you get an error message saying ``does not have gp
655 sections for all it's [sic] sectons [sic]'', don't worry about it. This
656 happens whenever you use GAS with the MIPS linker, but there is not
657 really anything wrong, and it is okay to use the output file. You can
658 stop such warnings by installing the GNU linker.
660 It would be nice to extend GAS to produce the gp tables, but they are
661 optional, and there should not be a warning about their absence.
664 Users have reported some problems with version 2.0 of the MIPS
665 compiler tools that were shipped with Ultrix 4.1. Version 2.10
666 which came with Ultrix 4.2 seems to work fine.
668 Users have also reported some problems with version 2.20 of the
669 MIPS compiler tools that were shipped with RISC/os 4.x. The earlier
670 version 2.11 seems to work fine.
673 Some versions of the MIPS linker will issue an assertion failure
674 when linking code that uses @code{alloca} against shared
675 libraries on RISC-OS 5.0, and DEC's OSF/1 systems. This is a bug
676 in the linker, that is supposed to be fixed in future revisions.
677 To protect against this, GCC passes @samp{-non_shared} to the
678 linker unless you pass an explicit @samp{-shared} or
679 @samp{-call_shared} switch.
682 On System V release 3, you may get this error message
686 ld fatal: failed to write symbol name @var{something}
687 in strings table for file @var{whatever}
690 This probably indicates that the disk is full or your ULIMIT won't allow
691 the file to be as large as it needs to be.
693 This problem can also result because the kernel parameter @code{MAXUMEM}
694 is too small. If so, you must regenerate the kernel and make the value
695 much larger. The default value is reported to be 1024; a value of 32768
696 is said to work. Smaller values may also work.
699 On System V, if you get an error like this,
702 /usr/local/lib/bison.simple: In function `yyparse':
703 /usr/local/lib/bison.simple:625: virtual memory exhausted
707 that too indicates a problem with disk space, ULIMIT, or @code{MAXUMEM}.
710 Current GCC versions probably do not work on version 2 of the NeXT
714 On NeXTStep 3.0, the Objective C compiler does not work, due,
715 apparently, to a kernel bug that it happens to trigger. This problem
716 does not happen on 3.1.
719 On the Tower models 4@var{n}0 and 6@var{n}0, by default a process is not
720 allowed to have more than one megabyte of memory. GCC cannot compile
721 itself (or many other programs) with @samp{-O} in that much memory.
723 To solve this problem, reconfigure the kernel adding the following line
724 to the configuration file:
731 On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a bug
732 in the assembler that must be fixed before GCC can be built. This
733 bug manifests itself during the first stage of compilation, while
734 building @file{libgcc2.a}:
738 cc1: warning: `-g' option not supported on this version of GCC
739 cc1: warning: `-g1' option not supported on this version of GCC
740 ./xgcc: Internal compiler error: program as got fatal signal 11
743 A patched version of the assembler is available as the file
744 @uref{ftp://altdorf.ai.mit.edu/archive/cph/hpux-8.0-assembler}. If you
745 have HP software support, the patch can also be obtained directly from
746 HP, as described in the following note:
749 This is the patched assembler, to patch SR#1653-010439, where the
750 assembler aborts on floating point constants.
752 The bug is not really in the assembler, but in the shared library
753 version of the function ``cvtnum(3c)''. The bug on ``cvtnum(3c)'' is
754 SR#4701-078451. Anyway, the attached assembler uses the archive
755 library version of ``cvtnum(3c)'' and thus does not exhibit the bug.
758 This patch is also known as PHCO_4484.
761 On HP-UX version 8.05, but not on 8.07 or more recent versions,
762 the @code{fixproto} shell script triggers a bug in the system shell.
763 If you encounter this problem, upgrade your operating system or
764 use BASH (the GNU shell) to run @code{fixproto}.
767 There may be similar problems on System V Release 3.1 on 386 systems.
770 On the Intel Paragon (an i860 machine), if you are using operating
771 system version 1.0, you will get warnings or errors about redefinition
772 of @code{va_arg} when you build GCC.
774 If this happens, then you need to link most programs with the library
775 @file{iclib.a}. You must also modify @file{stdio.h} as follows: before
779 #if defined(__i860__) && !defined(_VA_LIST)
794 extern int vprintf(const char *, va_list );
795 extern int vsprintf(char *, const char *, va_list );
806 These problems don't exist in operating system version 1.1.
809 On the Altos 3068, programs compiled with GCC won't work unless you
810 fix a kernel bug. This happens using system versions V.2.2 1.0gT1 and
811 V.2.2 1.0e and perhaps later versions as well. See the file
815 You will get several sorts of compilation and linking errors on the
816 we32k if you don't follow the special instructions. @xref{Configurations}.
819 A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto
820 program to report an error of the form:
823 ./fixproto: sh internal 1K buffer overflow
826 To fix this, change the first line of the fixproto script to look like:
833 @node Cross-Compiler Problems
834 @section Cross-Compiler Problems
836 You may run into problems with cross compilation on certain machines,
841 Cross compilation can run into trouble for certain machines because
842 some target machines' assemblers require floating point numbers to be
843 written as @emph{integer} constants in certain contexts.
845 The compiler writes these integer constants by examining the floating
846 point value as an integer and printing that integer, because this is
847 simple to write and independent of the details of the floating point
848 representation. But this does not work if the compiler is running on
849 a different machine with an incompatible floating point format, or
850 even a different byte-ordering.
852 In addition, correct constant folding of floating point values
853 requires representing them in the target machine's format.
854 (The C standard does not quite require this, but in practice
855 it is the only way to win.)
857 It is now possible to overcome these problems by defining macros such
858 as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
859 work for each target machine.
861 @xref{Cross-compilation}.
864 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
865 gcc.info, Using and Porting GCC}.
869 At present, the program @file{mips-tfile} which adds debug
870 support to object files on MIPS systems does not work in a cross
875 @section Interoperation
877 This section lists various difficulties encountered in using GNU C or
878 GNU C++ together with other compilers or with the assemblers, linkers,
879 libraries and debuggers on certain systems.
883 Objective C does not work on the RS/6000.
886 GNU C++ does not do name mangling in the same way as other C++
887 compilers. This means that object files compiled with one compiler
888 cannot be used with another.
890 This effect is intentional, to protect you from more subtle problems.
891 Compilers differ as to many internal details of C++ implementation,
892 including: how class instances are laid out, how multiple inheritance is
893 implemented, and how virtual function calls are handled. If the name
894 encoding were made the same, your programs would link against libraries
895 provided from other compilers---but the programs would then crash when
896 run. Incompatible libraries are then detected at link time, rather than
900 Older GDB versions sometimes fail to read the output of GCC version
901 2. If you have trouble, get GDB version 4.4 or later.
905 DBX rejects some files produced by GCC, though it accepts similar
906 constructs in output from PCC. Until someone can supply a coherent
907 description of what is valid DBX input and what is not, there is
908 nothing I can do about these problems. You are on your own.
911 The GNU assembler (GAS) does not support PIC. To generate PIC code, you
912 must use some other assembler, such as @file{/bin/as}.
915 On some BSD systems, including some versions of Ultrix, use of profiling
916 causes static variable destructors (currently used only in C++) not to
920 Use of @samp{-I/usr/include} may cause trouble.
922 Many systems come with header files that won't work with GCC unless
923 corrected by @code{fixincludes}. The corrected header files go in a new
924 directory; GCC searches this directory before @file{/usr/include}.
925 If you use @samp{-I/usr/include}, this tells GCC to search
926 @file{/usr/include} earlier on, before the corrected headers. The
927 result is that you get the uncorrected header files.
929 Instead, you should use these options (when compiling C programs):
932 -I/usr/local/lib/gcc-lib/@var{target}/@var{version}/include -I/usr/include
935 For C++ programs, GCC also uses a special directory that defines C++
936 interfaces to standard C subroutines. This directory is meant to be
937 searched @emph{before} other standard include directories, so that it
938 takes precedence. If you are compiling C++ programs and specifying
939 include directories explicitly, use this option first, then the two
943 -I/usr/local/lib/g++-include
947 @cindex @code{vfork}, for the Sun-4
949 There is a bug in @code{vfork} on the Sun-4 which causes the registers
950 of the child process to clobber those of the parent. Because of this,
951 programs that call @code{vfork} are likely to lose when compiled
952 optimized with GCC when the child code alters registers which contain
953 C variables in the parent. This affects variables which are live in the
954 parent across the call to @code{vfork}.
956 If you encounter this, you can work around the problem by declaring
957 variables @code{volatile} in the function that calls @code{vfork}, until
958 the problem goes away, or by not declaring them @code{register} and not
959 using @samp{-O} for those source files.
963 On some SGI systems, when you use @samp{-lgl_s} as an option,
964 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
965 Naturally, this does not happen when you use GCC.
966 You must specify all three options explicitly.
969 On a Sparc, GCC aligns all values of type @code{double} on an 8-byte
970 boundary, and it expects every @code{double} to be so aligned. The Sun
971 compiler usually gives @code{double} values 8-byte alignment, with one
972 exception: function arguments of type @code{double} may not be aligned.
974 As a result, if a function compiled with Sun CC takes the address of an
975 argument of type @code{double} and passes this pointer of type
976 @code{double *} to a function compiled with GCC, dereferencing the
977 pointer may cause a fatal signal.
979 One way to solve this problem is to compile your entire program with GNU
980 CC. Another solution is to modify the function that is compiled with
981 Sun CC to copy the argument into a local variable; local variables
982 are always properly aligned. A third solution is to modify the function
983 that uses the pointer to dereference it via the following function
984 @code{access_double} instead of directly with @samp{*}:
988 access_double (double *unaligned_ptr)
990 union d2i @{ double d; int i[2]; @};
992 union d2i *p = (union d2i *) unaligned_ptr;
1003 Storing into the pointer can be done likewise with the same union.
1006 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
1007 may allocate memory that is only 4 byte aligned. Since GCC on the
1008 Sparc assumes that doubles are 8 byte aligned, this may result in a
1009 fatal signal if doubles are stored in memory allocated by the
1010 @file{libmalloc.a} library.
1012 The solution is to not use the @file{libmalloc.a} library. Use instead
1013 @code{malloc} and related functions from @file{libc.a}; they do not have
1017 Sun forgot to include a static version of @file{libdl.a} with some
1018 versions of SunOS (mainly 4.1). This results in undefined symbols when
1019 linking static binaries (that is, if you use @samp{-static}). If you
1020 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
1021 when linking, compile and link against the file
1022 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
1025 The 128-bit long double format that the Sparc port supports currently
1026 works by using the architecturally defined quad-word floating point
1027 instructions. Since there is no hardware that supports these
1028 instructions they must be emulated by the operating system. Long
1029 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
1030 kernel emulator uses an obsolete and incompatible format. Long doubles
1031 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
1032 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
1033 does not enable them by default. Long doubles appear to work in Sun OS
1037 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
1038 compile GCC correctly. We do not yet know why. However, GCC
1039 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
1040 compile itself properly on 9.01.
1043 On the HP PA machine, ADB sometimes fails to work on functions compiled
1044 with GCC. Specifically, it fails to work on functions that use
1045 @code{alloca} or variable-size arrays. This is because GCC doesn't
1046 generate HP-UX unwind descriptors for such functions. It may even be
1047 impossible to generate them.
1050 Debugging (@samp{-g}) is not supported on the HP PA machine, unless you use
1051 the preliminary GNU tools (@pxref{Installation}).
1054 Taking the address of a label may generate errors from the HP-UX
1055 PA assembler. GAS for the PA does not have this problem.
1058 Using floating point parameters for indirect calls to static functions
1059 will not work when using the HP assembler. There simply is no way for GCC
1060 to specify what registers hold arguments for static functions when using
1061 the HP assembler. GAS for the PA does not have this problem.
1064 In extremely rare cases involving some very large functions you may
1065 receive errors from the HP linker complaining about an out of bounds
1066 unconditional branch offset. This used to occur more often in previous
1067 versions of GCC, but is now exceptionally rare. If you should run
1068 into it, you can work around by making your function smaller.
1071 GCC compiled code sometimes emits warnings from the HP-UX assembler of
1075 (warning) Use of GR3 when
1076 frame >= 8192 may cause conflict.
1079 These warnings are harmless and can be safely ignored.
1082 The current version of the assembler (@file{/bin/as}) for the RS/6000
1083 has certain problems that prevent the @samp{-g} option in GCC from
1084 working. Note that @file{Makefile.in} uses @samp{-g} by default when
1085 compiling @file{libgcc2.c}.
1087 IBM has produced a fixed version of the assembler. The upgraded
1088 assembler unfortunately was not included in any of the AIX 3.2 update
1089 PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request
1090 PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
1091 See the file @file{README.RS6000} for more details on these updates.
1093 You can test for the presence of a fixed assembler by using the
1101 If the command exits normally, the assembler fix already is installed.
1102 If the assembler complains that "-u" is an unknown flag, you need to
1106 On the IBM RS/6000, compiling code of the form
1117 will cause the linker to report an undefined symbol @code{foo}.
1118 Although this behavior differs from most other systems, it is not a
1119 bug because redefining an @code{extern} variable as @code{static}
1120 is undefined in ISO C.
1123 AIX on the RS/6000 provides support (NLS) for environments outside of
1124 the United States. Compilers and assemblers use NLS to support
1125 locale-specific representations of various objects including
1126 floating-point numbers ("." vs "," for separating decimal fractions).
1127 There have been problems reported where the library linked with GCC does
1128 not produce the same floating-point formats that the assembler accepts.
1129 If you have this problem, set the LANG environment variable to "C" or
1133 Even if you specify @samp{-fdollars-in-identifiers},
1134 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
1135 to a restriction in the IBM assembler. GAS supports these
1139 On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC
1140 version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2
1141 by requesting PTF 421749 from IBM.
1144 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
1145 occurs when the @samp{fldcr} instruction is used. GCC uses
1146 @samp{fldcr} on the 88100 to serialize volatile memory references. Use
1147 the option @samp{-mno-serialize-volatile} if your version of the
1148 assembler has this bug.
1151 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
1152 messages from the linker. These warning messages complain of mismatched
1153 psect attributes. You can ignore them. @xref{VMS Install}.
1156 On NewsOS version 3, if you include both of the files @file{stddef.h}
1157 and @file{sys/types.h}, you get an error because there are two typedefs
1158 of @code{size_t}. You should change @file{sys/types.h} by adding these
1159 lines around the definition of @code{size_t}:
1164 @var{actual typedef here}
1170 On the Alliant, the system's own convention for returning structures
1171 and unions is unusual, and is not compatible with GCC no matter
1172 what options are used.
1177 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
1178 convention for structure and union returning. Use the option
1179 @samp{-mhc-struct-return} to tell GCC to use a convention compatible
1182 @cindex Vax calling convention
1183 @cindex Ultrix calling convention
1185 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
1186 by function calls. However, the C compiler uses conventions compatible
1187 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
1189 GCC uses the same convention as the Ultrix C compiler. You can use
1190 these options to produce code compatible with the Fortran compiler:
1193 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
1197 On the WE32k, you may find that programs compiled with GCC do not
1198 work with the standard shared C library. You may need to link with
1199 the ordinary C compiler. If you do so, you must specify the following
1203 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
1206 The first specifies where to find the library @file{libgcc.a}
1207 specified with the @samp{-lgcc} option.
1209 GCC does linking by invoking @code{ld}, just as @code{cc} does, and
1210 there is no reason why it @emph{should} matter which compilation program
1211 you use to invoke @code{ld}. If someone tracks this problem down,
1212 it can probably be fixed easily.
1215 On the Alpha, you may get assembler errors about invalid syntax as a
1216 result of floating point constants. This is due to a bug in the C
1217 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid
1218 floating point numbers, they sometimes print @samp{NaN}.
1221 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
1222 sometimes reorders instructions incorrectly when optimization is turned
1223 on. If you think this may be happening to you, try using the GNU
1224 assembler; GAS version 2.1 supports ECOFF on Irix.
1226 Or use the @samp{-noasmopt} option when you compile GCC with itself,
1227 and then again when you compile your program. (This is a temporary
1228 kludge to turn off assembler optimization on Irix.) If this proves to
1229 be what you need, edit the assembler spec in the file @file{specs} so
1230 that it unconditionally passes @samp{-O0} to the assembler, and never
1231 passes @samp{-O2} or @samp{-O3}.
1235 @section Problems Compiling Certain Programs
1237 @c prevent bad page break with this line
1238 Certain programs have problems compiling.
1242 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
1243 because of problems in DEC's versions of the X11 header files
1244 @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
1245 @samp{-I/usr/include/mit} to use the MIT versions of the header files,
1246 using the @samp{-traditional} switch to turn off ISO C, or fixing the
1247 header files by adding this:
1251 #define NeedFunctionPrototypes 0
1256 On various 386 Unix systems derived from System V, including SCO, ISC,
1257 and ESIX, you may get error messages about running out of virtual memory
1258 while compiling certain programs.
1260 You can prevent this problem by linking GCC with the GNU malloc
1261 (which thus replaces the malloc that comes with the system). GNU malloc
1262 is available as a separate package, and also in the file
1263 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
1265 If you have installed GNU malloc as a separate library package, use this
1266 option when you relink GCC:
1269 MALLOC=/usr/local/lib/libgmalloc.a
1272 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
1273 the object file to @file{gmalloc.o} and use this option when you relink
1281 @node Incompatibilities
1282 @section Incompatibilities of GCC
1283 @cindex incompatibilities of GCC
1285 There are several noteworthy incompatibilities between GNU C and K&R
1286 (non-ISO) versions of C. The @samp{-traditional} option
1287 eliminates many of these incompatibilities, @emph{but not all}, by
1288 telling GNU C to behave like a K&R C compiler.
1291 @cindex string constants
1292 @cindex read-only strings
1293 @cindex shared strings
1295 GCC normally makes string constants read-only. If several
1296 identical-looking string constants are used, GCC stores only one
1299 @cindex @code{mktemp}, and constant strings
1300 One consequence is that you cannot call @code{mktemp} with a string
1301 constant argument. The function @code{mktemp} always alters the
1302 string its argument points to.
1304 @cindex @code{sscanf}, and constant strings
1305 @cindex @code{fscanf}, and constant strings
1306 @cindex @code{scanf}, and constant strings
1307 Another consequence is that @code{sscanf} does not work on some systems
1308 when passed a string constant as its format control string or input.
1309 This is because @code{sscanf} incorrectly tries to write into the string
1310 constant. Likewise @code{fscanf} and @code{scanf}.
1312 The best solution to these problems is to change the program to use
1313 @code{char}-array variables with initialization strings for these
1314 purposes instead of string constants. But if this is not possible,
1315 you can use the @samp{-fwritable-strings} flag, which directs GCC
1316 to handle string constants the same way most C compilers do.
1317 @samp{-traditional} also has this effect, among others.
1320 @code{-2147483648} is positive.
1322 This is because 2147483648 cannot fit in the type @code{int}, so
1323 (following the ISO C rules) its data type is @code{unsigned long int}.
1324 Negating this value yields 2147483648 again.
1327 GCC does not substitute macro arguments when they appear inside of
1328 string constants. For example, the following macro in GCC
1335 will produce output @code{"a"} regardless of what the argument @var{a} is.
1337 The @samp{-traditional} option directs GCC to handle such cases
1338 (among others) in the old-fashioned (non-ISO) fashion.
1340 @cindex @code{setjmp} incompatibilities
1341 @cindex @code{longjmp} incompatibilities
1343 When you use @code{setjmp} and @code{longjmp}, the only automatic
1344 variables guaranteed to remain valid are those declared
1345 @code{volatile}. This is a consequence of automatic register
1346 allocation. Consider this function:
1360 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
1365 Here @code{a} may or may not be restored to its first value when the
1366 @code{longjmp} occurs. If @code{a} is allocated in a register, then
1367 its first value is restored; otherwise, it keeps the last value stored
1370 If you use the @samp{-W} option with the @samp{-O} option, you will
1371 get a warning when GCC thinks such a problem might be possible.
1373 The @samp{-traditional} option directs GNU C to put variables in
1374 the stack by default, rather than in registers, in functions that
1375 call @code{setjmp}. This results in the behavior found in
1376 traditional C compilers.
1379 Programs that use preprocessing directives in the middle of macro
1380 arguments do not work with GCC. For example, a program like this
1389 ISO C does not permit such a construct. It would make sense to support
1390 it when @samp{-traditional} is used, but it is too much work to
1394 K&R compilers allow comments to cross over an inclusion boundary (i.e.
1395 started in an include file and ended in the including file). I think
1396 this would be quite ugly and can't imagine it could be needed.
1398 @cindex external declaration scope
1399 @cindex scope of external declarations
1400 @cindex declaration scope
1402 Declarations of external variables and functions within a block apply
1403 only to the block containing the declaration. In other words, they
1404 have the same scope as any other declaration in the same place.
1406 In some other C compilers, a @code{extern} declaration affects all the
1407 rest of the file even if it happens within a block.
1409 The @samp{-traditional} option directs GNU C to treat all @code{extern}
1410 declarations as global, like traditional compilers.
1413 In traditional C, you can combine @code{long}, etc., with a typedef name,
1418 typedef long foo bar;
1421 In ISO C, this is not allowed: @code{long} and other type modifiers
1422 require an explicit @code{int}. Because this criterion is expressed
1423 by Bison grammar rules rather than C code, the @samp{-traditional}
1424 flag cannot alter it.
1426 @cindex typedef names as function parameters
1428 PCC allows typedef names to be used as function parameters. The
1429 difficulty described immediately above applies here too.
1432 When in @samp{-traditional} mode, GCC allows the following erroneous
1433 pair of declarations to appear together in a given scope:
1441 GCC treats all characters of identifiers as significant, even when in
1442 @samp{-traditional} mode. According to K&R-1 (2.2), ``No more than the
1443 first eight characters are significant, although more may be used.''.
1444 Also according to K&R-1 (2.2), ``An identifier is a sequence of letters
1445 and digits; the first character must be a letter. The underscore _
1446 counts as a letter.'', but GCC also allows dollar signs in identifiers.
1450 PCC allows whitespace in the middle of compound assignment operators
1451 such as @samp{+=}. GCC, following the ISO standard, does not
1452 allow this. The difficulty described immediately above applies here
1458 GCC complains about unterminated character constants inside of
1459 preprocessing conditionals that fail. Some programs have English
1460 comments enclosed in conditionals that are guaranteed to fail; if these
1461 comments contain apostrophes, GCC will probably report an error. For
1462 example, this code would produce an error:
1466 You can't expect this to work.
1470 The best solution to such a problem is to put the text into an actual
1471 C comment delimited by @samp{/*@dots{}*/}. However,
1472 @samp{-traditional} suppresses these error messages.
1475 Many user programs contain the declaration @samp{long time ();}. In the
1476 past, the system header files on many systems did not actually declare
1477 @code{time}, so it did not matter what type your program declared it to
1478 return. But in systems with ISO C headers, @code{time} is declared to
1479 return @code{time_t}, and if that is not the same as @code{long}, then
1480 @samp{long time ();} is erroneous.
1482 The solution is to change your program to use appropriate system headers
1483 (@code{<time.h>} on systems with ISO C headers) and not to declare
1484 @code{time} if the system header files declare it, or failing that to
1485 use @code{time_t} as the return type of @code{time}.
1487 @cindex @code{float} as function value type
1489 When compiling functions that return @code{float}, PCC converts it to
1490 a double. GCC actually returns a @code{float}. If you are concerned
1491 with PCC compatibility, you should declare your functions to return
1492 @code{double}; you might as well say what you mean.
1497 When compiling functions that return structures or unions, GCC
1498 output code normally uses a method different from that used on most
1499 versions of Unix. As a result, code compiled with GCC cannot call
1500 a structure-returning function compiled with PCC, and vice versa.
1502 The method used by GCC is as follows: a structure or union which is
1503 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
1504 with any other size is stored into an address supplied by the caller
1505 (usually in a special, fixed register, but on some machines it is passed
1506 on the stack). The machine-description macros @code{STRUCT_VALUE} and
1507 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
1509 By contrast, PCC on most target machines returns structures and unions
1510 of any size by copying the data into an area of static storage, and then
1511 returning the address of that storage as if it were a pointer value.
1512 The caller must copy the data from that memory area to the place where
1513 the value is wanted. GCC does not use this method because it is
1514 slower and nonreentrant.
1516 On some newer machines, PCC uses a reentrant convention for all
1517 structure and union returning. GCC on most of these machines uses a
1518 compatible convention when returning structures and unions in memory,
1519 but still returns small structures and unions in registers.
1521 You can tell GCC to use a compatible convention for all structure and
1522 union returning with the option @samp{-fpcc-struct-return}.
1524 @cindex preprocessing tokens
1525 @cindex preprocessing numbers
1527 GNU C complains about program fragments such as @samp{0x74ae-0x4000}
1528 which appear to be two hexadecimal constants separated by the minus
1529 operator. Actually, this string is a single @dfn{preprocessing token}.
1530 Each such token must correspond to one token in C. Since this does not,
1531 GNU C prints an error message. Although it may appear obvious that what
1532 is meant is an operator and two values, the ISO C standard specifically
1533 requires that this be treated as erroneous.
1535 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
1536 begins with a digit and is followed by letters, underscores, digits,
1537 periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
1538 @samp{p-}, @samp{P+}, or @samp{P-} character sequences. (In strict C89
1539 mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
1540 appear in preprocessing numbers.)
1542 To make the above program fragment valid, place whitespace in front of
1543 the minus sign. This whitespace will end the preprocessing number.
1547 @section Fixed Header Files
1549 GCC needs to install corrected versions of some system header files.
1550 This is because most target systems have some header files that won't
1551 work with GCC unless they are changed. Some have bugs, some are
1552 incompatible with ISO C, and some depend on special features of other
1555 Installing GCC automatically creates and installs the fixed header
1556 files, by running a program called @code{fixincludes} (or for certain
1557 targets an alternative such as @code{fixinc.svr4}). Normally, you
1558 don't need to pay attention to this. But there are cases where it
1559 doesn't do the right thing automatically.
1563 If you update the system's header files, such as by installing a new
1564 system version, the fixed header files of GCC are not automatically
1565 updated. The easiest way to update them is to reinstall GCC. (If
1566 you want to be clever, look in the makefile and you can find a
1570 On some systems, in particular SunOS 4, header file directories contain
1571 machine-specific symbolic links in certain places. This makes it
1572 possible to share most of the header files among hosts running the
1573 same version of SunOS 4 on different machine models.
1575 The programs that fix the header files do not understand this special
1576 way of using symbolic links; therefore, the directory of fixed header
1577 files is good only for the machine model used to build it.
1579 In SunOS 4, only programs that look inside the kernel will notice the
1580 difference between machine models. Therefore, for most purposes, you
1581 need not be concerned about this.
1583 It is possible to make separate sets of fixed header files for the
1584 different machine models, and arrange a structure of symbolic links so
1585 as to use the proper set, but you'll have to do this by hand.
1588 On Lynxos, GCC by default does not fix the header files. This is
1589 because bugs in the shell cause the @code{fixincludes} script to fail.
1591 This means you will encounter problems due to bugs in the system header
1592 files. It may be no comfort that they aren't GCC's fault, but it
1593 does mean that there's nothing for us to do about them.
1596 @node Standard Libraries
1597 @section Standard Libraries
1599 GCC by itself attempts to be a conforming freestanding implementation.
1600 @xref{Standards,,Language Standards Supported by GCC}, for details of
1601 what this means. Beyond the library facilities required of such an
1602 implementation, the rest of the C library is supplied by the vendor of
1603 the operating system. If that C library doesn't conform to the C
1604 standards, then your programs might get warnings (especially when using
1605 @samp{-Wall}) that you don't expect.
1607 For example, the @code{sprintf} function on SunOS 4.1.3 returns
1608 @code{char *} while the C standard says that @code{sprintf} returns an
1609 @code{int}. The @code{fixincludes} program could make the prototype for
1610 this function match the Standard, but that would be wrong, since the
1611 function will still return @code{char *}.
1613 If you need a Standard compliant library, then you need to find one, as
1614 GCC does not provide one. The GNU C library (called @code{glibc})
1615 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
1616 GNU/Linux and HURD-based GNU systems; no recent version of it supports
1617 other systems, though some very old versions did. Version 2.2 of the
1618 GNU C library includes nearly complete C99 support. You could also ask
1619 your operating system vendor if newer libraries are available.
1621 @node Disappointments
1622 @section Disappointments and Misunderstandings
1624 These problems are perhaps regrettable, but we don't know any practical
1629 Certain local variables aren't recognized by debuggers when you compile
1632 This occurs because sometimes GCC optimizes the variable out of
1633 existence. There is no way to tell the debugger how to compute the
1634 value such a variable ``would have had'', and it is not clear that would
1635 be desirable anyway. So GCC simply does not mention the eliminated
1636 variable when it writes debugging information.
1638 You have to expect a certain amount of disagreement between the
1639 executable and your source code, when you use optimization.
1641 @cindex conflicting types
1642 @cindex scope of declaration
1644 Users often think it is a bug when GCC reports an error for code
1648 int foo (struct mumble *);
1650 struct mumble @{ @dots{} @};
1652 int foo (struct mumble *x)
1656 This code really is erroneous, because the scope of @code{struct
1657 mumble} in the prototype is limited to the argument list containing it.
1658 It does not refer to the @code{struct mumble} defined with file scope
1659 immediately below---they are two unrelated types with similar names in
1662 But in the definition of @code{foo}, the file-scope type is used
1663 because that is available to be inherited. Thus, the definition and
1664 the prototype do not match, and you get an error.
1666 This behavior may seem silly, but it's what the ISO standard specifies.
1667 It is easy enough for you to make your code work by moving the
1668 definition of @code{struct mumble} above the prototype. It's not worth
1669 being incompatible with ISO C just to avoid an error for the example
1673 Accesses to bitfields even in volatile objects works by accessing larger
1674 objects, such as a byte or a word. You cannot rely on what size of
1675 object is accessed in order to read or write the bitfield; it may even
1676 vary for a given bitfield according to the precise usage.
1678 If you care about controlling the amount of memory that is accessed, use
1679 volatile but do not use bitfields.
1682 GCC comes with shell scripts to fix certain known problems in system
1683 header files. They install corrected copies of various header files in
1684 a special directory where only GCC will normally look for them. The
1685 scripts adapt to various systems by searching all the system header
1686 files for the problem cases that we know about.
1688 If new system header files are installed, nothing automatically arranges
1689 to update the corrected header files. You will have to reinstall GCC
1690 to fix the new header files. More specifically, go to the build
1691 directory and delete the files @file{stmp-fixinc} and
1692 @file{stmp-headers}, and the subdirectory @code{include}; then do
1693 @samp{make install} again.
1696 @cindex floating point precision
1697 On 68000 and x86 systems, for instance, you can get paradoxical results
1698 if you test the precise values of floating point numbers. For example,
1699 you can find that a floating point value which is not a NaN is not equal
1700 to itself. This results from the fact that the floating point registers
1701 hold a few more bits of precision than fit in a @code{double} in memory.
1702 Compiled code moves values between memory and floating point registers
1703 at its convenience, and moving them into memory truncates them.
1705 You can partially avoid this problem by using the @samp{-ffloat-store}
1706 option (@pxref{Optimize Options}).
1709 On the MIPS, variable argument functions using @file{varargs.h}
1710 cannot have a floating point value for the first argument. The
1711 reason for this is that in the absence of a prototype in scope,
1712 if the first argument is a floating point, it is passed in a
1713 floating point register, rather than an integer register.
1715 If the code is rewritten to use the ISO standard @file{stdarg.h}
1716 method of variable arguments, and the prototype is in scope at
1717 the time of the call, everything will work fine.
1720 On the H8/300 and H8/300H, variable argument functions must be
1721 implemented using the ISO standard @file{stdarg.h} method of
1722 variable arguments. Furthermore, calls to functions using @file{stdarg.h}
1723 variable arguments must have a prototype for the called function
1724 in scope at the time of the call.
1727 @node C++ Misunderstandings
1728 @section Common Misunderstandings with GNU C++
1730 @cindex misunderstandings in C++
1731 @cindex surprises in C++
1732 @cindex C++ misunderstandings
1733 C++ is a complex language and an evolving one, and its standard
1734 definition (the ISO C++ standard) was only recently completed. As a
1735 result, your C++ compiler may occasionally surprise you, even when its
1736 behavior is correct. This section discusses some areas that frequently
1737 give rise to questions of this sort.
1740 * Static Definitions:: Static member declarations are not definitions
1741 * Temporaries:: Temporaries may vanish before you expect
1742 * Copy Assignment:: Copy Assignment operators copy virtual bases twice
1745 @node Static Definitions
1746 @subsection Declare @emph{and} Define Static Members
1748 @cindex C++ static data, declaring and defining
1749 @cindex static data in C++, declaring and defining
1750 @cindex declaring static data in C++
1751 @cindex defining static data in C++
1752 When a class has static data members, it is not enough to @emph{declare}
1753 the static member; you must also @emph{define} it. For example:
1764 This declaration only establishes that the class @code{Foo} has an
1765 @code{int} named @code{Foo::bar}, and a member function named
1766 @code{Foo::method}. But you still need to define @emph{both}
1767 @code{method} and @code{bar} elsewhere. According to the ISO
1768 standard, you must supply an initializer in one (and only one) source
1775 Other C++ compilers may not correctly implement the standard behavior.
1776 As a result, when you switch to @code{g++} from one of these compilers,
1777 you may discover that a program that appeared to work correctly in fact
1778 does not conform to the standard: @code{g++} reports as undefined
1779 symbols any static data members that lack definitions.
1782 @subsection Temporaries May Vanish Before You Expect
1784 @cindex temporaries, lifetime of
1785 @cindex portions of temporary objects, pointers to
1786 It is dangerous to use pointers or references to @emph{portions} of a
1787 temporary object. The compiler may very well delete the object before
1788 you expect it to, leaving a pointer to garbage. The most common place
1789 where this problem crops up is in classes like string classes,
1790 especially ones that define a conversion function to type @code{char *}
1791 or @code{const char *} -- which is one reason why the standard
1792 @code{string} class requires you to call the @code{c_str} member
1793 function. However, any class that returns a pointer to some internal
1794 structure is potentially subject to this problem.
1796 For example, a program may use a function @code{strfunc} that returns
1797 @code{string} objects, and another function @code{charfunc} that
1798 operates on pointers to @code{char}:
1802 void charfunc (const char *);
1807 const char *p = strfunc().c_str();
1816 In this situation, it may seem reasonable to save a pointer to the C
1817 string returned by the @code{c_str} member function and use that rather
1818 than call @code{c_str} repeatedly. However, the temporary string
1819 created by the call to @code{strfunc} is destroyed after @code{p} is
1820 initialized, at which point @code{p} is left pointing to freed memory.
1822 Code like this may run successfully under some other compilers,
1823 particularly obsolete cfront-based compilers that delete temporaries
1824 along with normal local variables. However, the GNU C++ behavior is
1825 standard-conforming, so if your program depends on late destruction of
1826 temporaries it is not portable.
1828 The safe way to write such code is to give the temporary a name, which
1829 forces it to remain until the end of the scope of the name. For
1833 string& tmp = strfunc ();
1834 charfunc (tmp.c_str ());
1837 @node Copy Assignment
1838 @subsection Implicit Copy-Assignment for Virtual Bases
1840 When a base class is virtual, only one subobject of the base class
1841 belongs to each full object. Also, the constructors and destructors are
1842 invoked only once, and called from the most-derived class. However, such
1843 objects behave unspecified when being assigned. For example:
1848 Base(char *n) : name(strdup(n))@{@}
1849 Base& operator= (const Base& other)@{
1851 name = strdup (other.name);
1855 struct A:virtual Base@{
1860 struct B:virtual Base@{
1865 struct Derived:public A, public B@{
1866 Derived():Base("Derived")@{@}
1869 void func(Derived &d1, Derived &d2)
1875 The C++ standard specifies that @samp{Base::Base} is only called once
1876 when constructing or copy-constructing a Derived object. It is
1877 unspecified whether @samp{Base::operator=} is called more than once when
1878 the implicit copy-assignment for Derived objects is invoked (as it is
1879 inside @samp{func} in the example).
1881 g++ implements the "intuitive" algorithm for copy-assignment: assign all
1882 direct bases, then assign all members. In that algorithm, the virtual
1883 base subobject can be encountered many times. In the example, copying
1884 proceeds in the following order: @samp{val}, @samp{name} (via
1885 @code{strdup}), @samp{bval}, and @samp{name} again.
1887 If application code relies on copy-assignment, a user-defined
1888 copy-assignment operator removes any uncertainties. With such an
1889 operator, the application can define whether and how the virtual base
1890 subobject is assigned.
1892 @node Protoize Caveats
1893 @section Caveats of using @code{protoize}
1895 The conversion programs @code{protoize} and @code{unprotoize} can
1896 sometimes change a source file in a way that won't work unless you
1901 @code{protoize} can insert references to a type name or type tag before
1902 the definition, or in a file where they are not defined.
1904 If this happens, compiler error messages should show you where the new
1905 references are, so fixing the file by hand is straightforward.
1908 There are some C constructs which @code{protoize} cannot figure out.
1909 For example, it can't determine argument types for declaring a
1910 pointer-to-function variable; this you must do by hand. @code{protoize}
1911 inserts a comment containing @samp{???} each time it finds such a
1912 variable; so you can find all such variables by searching for this
1913 string. ISO C does not require declaring the argument types of
1914 pointer-to-function types.
1917 Using @code{unprotoize} can easily introduce bugs. If the program
1918 relied on prototypes to bring about conversion of arguments, these
1919 conversions will not take place in the program without prototypes.
1920 One case in which you can be sure @code{unprotoize} is safe is when
1921 you are removing prototypes that were made with @code{protoize}; if
1922 the program worked before without any prototypes, it will work again
1925 You can find all the places where this problem might occur by compiling
1926 the program with the @samp{-Wconversion} option. It prints a warning
1927 whenever an argument is converted.
1930 Both conversion programs can be confused if there are macro calls in and
1931 around the text to be converted. In other words, the standard syntax
1932 for a declaration or definition must not result from expanding a macro.
1933 This problem is inherent in the design of C and cannot be fixed. If
1934 only a few functions have confusing macro calls, you can easily convert
1938 @code{protoize} cannot get the argument types for a function whose
1939 definition was not actually compiled due to preprocessing conditionals.
1940 When this happens, @code{protoize} changes nothing in regard to such
1941 a function. @code{protoize} tries to detect such instances and warn
1944 You can generally work around this problem by using @code{protoize} step
1945 by step, each time specifying a different set of @samp{-D} options for
1946 compilation, until all of the functions have been converted. There is
1947 no automatic way to verify that you have got them all, however.
1950 Confusion may result if there is an occasion to convert a function
1951 declaration or definition in a region of source code where there is more
1952 than one formal parameter list present. Thus, attempts to convert code
1953 containing multiple (conditionally compiled) versions of a single
1954 function header (in the same vicinity) may not produce the desired (or
1957 If you plan on converting source files which contain such code, it is
1958 recommended that you first make sure that each conditionally compiled
1959 region of source code which contains an alternative function header also
1960 contains at least one additional follower token (past the final right
1961 parenthesis of the function header). This should circumvent the
1965 @code{unprotoize} can become confused when trying to convert a function
1966 definition or declaration which contains a declaration for a
1967 pointer-to-function formal argument which has the same name as the
1968 function being defined or declared. We recommend you avoid such choices
1969 of formal parameter names.
1972 You might also want to correct some of the indentation by hand and break
1973 long lines. (The conversion programs don't write lines longer than
1974 eighty characters in any case.)
1978 @section Certain Changes We Don't Want to Make
1980 This section lists changes that people frequently request, but which
1981 we do not make because we think GCC is better without them.
1985 Checking the number and type of arguments to a function which has an
1986 old-fashioned definition and no prototype.
1988 Such a feature would work only occasionally---only for calls that appear
1989 in the same file as the called function, following the definition. The
1990 only way to check all calls reliably is to add a prototype for the
1991 function. But adding a prototype eliminates the motivation for this
1992 feature. So the feature is not worthwhile.
1995 Warning about using an expression whose type is signed as a shift count.
1997 Shift count operands are probably signed more often than unsigned.
1998 Warning about this would cause far more annoyance than good.
2001 Warning about assigning a signed value to an unsigned variable.
2003 Such assignments must be very common; warning about them would cause
2004 more annoyance than good.
2007 Warning when a non-void function value is ignored.
2009 Coming as I do from a Lisp background, I balk at the idea that there is
2010 something dangerous about discarding a value. There are functions that
2011 return values which some callers may find useful; it makes no sense to
2012 clutter the program with a cast to @code{void} whenever the value isn't
2016 Making @samp{-fshort-enums} the default.
2018 This would cause storage layout to be incompatible with most other C
2019 compilers. And it doesn't seem very important, given that you can get
2020 the same result in other ways. The case where it matters most is when
2021 the enumeration-valued object is inside a structure, and in that case
2022 you can specify a field width explicitly.
2025 Making bitfields unsigned by default on particular machines where ``the
2026 ABI standard'' says to do so.
2028 The ISO C standard leaves it up to the implementation whether a bitfield
2029 declared plain @code{int} is signed or not. This in effect creates two
2030 alternative dialects of C.
2032 The GNU C compiler supports both dialects; you can specify the signed
2033 dialect with @samp{-fsigned-bitfields} and the unsigned dialect with
2034 @samp{-funsigned-bitfields}. However, this leaves open the question of
2035 which dialect to use by default.
2037 Currently, the preferred dialect makes plain bitfields signed, because
2038 this is simplest. Since @code{int} is the same as @code{signed int} in
2039 every other context, it is cleanest for them to be the same in bitfields
2042 Some computer manufacturers have published Application Binary Interface
2043 standards which specify that plain bitfields should be unsigned. It is
2044 a mistake, however, to say anything about this issue in an ABI. This is
2045 because the handling of plain bitfields distinguishes two dialects of C.
2046 Both dialects are meaningful on every type of machine. Whether a
2047 particular object file was compiled using signed bitfields or unsigned
2048 is of no concern to other object files, even if they access the same
2049 bitfields in the same data structures.
2051 A given program is written in one or the other of these two dialects.
2052 The program stands a chance to work on most any machine if it is
2053 compiled with the proper dialect. It is unlikely to work at all if
2054 compiled with the wrong dialect.
2056 Many users appreciate the GNU C compiler because it provides an
2057 environment that is uniform across machines. These users would be
2058 inconvenienced if the compiler treated plain bitfields differently on
2061 Occasionally users write programs intended only for a particular machine
2062 type. On these occasions, the users would benefit if the GNU C compiler
2063 were to support by default the same dialect as the other compilers on
2064 that machine. But such applications are rare. And users writing a
2065 program to run on more than one type of machine cannot possibly benefit
2066 from this kind of compatibility.
2068 This is why GCC does and will treat plain bitfields in the same
2069 fashion on all types of machines (by default).
2071 There are some arguments for making bitfields unsigned by default on all
2072 machines. If, for example, this becomes a universal de facto standard,
2073 it would make sense for GCC to go along with it. This is something
2074 to be considered in the future.
2076 (Of course, users strongly concerned about portability should indicate
2077 explicitly in each bitfield whether it is signed or not. In this way,
2078 they write programs which have the same meaning in both C dialects.)
2081 Undefining @code{__STDC__} when @samp{-ansi} is not used.
2083 Currently, GCC defines @code{__STDC__} as long as you don't use
2084 @samp{-traditional}. This provides good results in practice.
2086 Programmers normally use conditionals on @code{__STDC__} to ask whether
2087 it is safe to use certain features of ISO C, such as function
2088 prototypes or ISO token concatenation. Since plain @samp{gcc} supports
2089 all the features of ISO C, the correct answer to these questions is
2092 Some users try to use @code{__STDC__} to check for the availability of
2093 certain library facilities. This is actually incorrect usage in an ISO
2094 C program, because the ISO C standard says that a conforming
2095 freestanding implementation should define @code{__STDC__} even though it
2096 does not have the library facilities. @samp{gcc -ansi -pedantic} is a
2097 conforming freestanding implementation, and it is therefore required to
2098 define @code{__STDC__}, even though it does not come with an ISO C
2101 Sometimes people say that defining @code{__STDC__} in a compiler that
2102 does not completely conform to the ISO C standard somehow violates the
2103 standard. This is illogical. The standard is a standard for compilers
2104 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
2105 compilers such as plain @samp{gcc}. Whatever the ISO C standard says
2106 is relevant to the design of plain @samp{gcc} without @samp{-ansi} only
2107 for pragmatic reasons, not as a requirement.
2109 GCC normally defines @code{__STDC__} to be 1, and in addition
2110 defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
2111 or a @option{-std} option for strict conformance to some version of ISO C.
2112 On some hosts, system include files use a different convention, where
2113 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
2114 conformance to the C Standard. GCC follows the host convention when
2115 processing system include files, but when processing user files it follows
2116 the usual GNU C convention.
2119 Undefining @code{__STDC__} in C++.
2121 Programs written to compile with C++-to-C translators get the
2122 value of @code{__STDC__} that goes with the C compiler that is
2123 subsequently used. These programs must test @code{__STDC__}
2124 to determine what kind of C preprocessor that compiler uses:
2125 whether they should concatenate tokens in the ISO C fashion
2126 or in the traditional fashion.
2128 These programs work properly with GNU C++ if @code{__STDC__} is defined.
2129 They would not work otherwise.
2131 In addition, many header files are written to provide prototypes in ISO
2132 C but not in traditional C. Many of these header files can work without
2133 change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
2134 is not defined, they will all fail, and will all need to be changed to
2135 test explicitly for C++ as well.
2138 Deleting ``empty'' loops.
2140 Historically, GCC has not deleted ``empty'' loops under the
2141 assumption that the most likely reason you would put one in a program is
2142 to have a delay, so deleting them will not make real programs run any
2145 However, the rationale here is that optimization of a nonempty loop
2146 cannot produce an empty one, which holds for C but is not always the
2149 Moreover, with @samp{-funroll-loops} small ``empty'' loops are already
2150 removed, so the current behavior is both sub-optimal and inconsistent
2151 and will change in the future.
2154 Making side effects happen in the same order as in some other compiler.
2156 @cindex side effects, order of evaluation
2157 @cindex order of evaluation, side effects
2158 It is never safe to depend on the order of evaluation of side effects.
2159 For example, a function call like this may very well behave differently
2160 from one compiler to another:
2163 void func (int, int);
2169 There is no guarantee (in either the C or the C++ standard language
2170 definitions) that the increments will be evaluated in any particular
2171 order. Either increment might happen first. @code{func} might get the
2172 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
2175 Not allowing structures with volatile fields in registers.
2177 Strictly speaking, there is no prohibition in the ISO C standard
2178 against allowing structures with volatile fields in registers, but
2179 it does not seem to make any sense and is probably not what you wanted
2180 to do. So the compiler will give an error message in this case.
2183 Making certain warnings into errors by default.
2185 Some ISO C testsuites report failure when the compiler does not produce
2186 an error message for a certain program.
2188 ISO C requires a ``diagnostic'' message for certain kinds of invalid
2189 programs, but a warning is defined by GCC to count as a diagnostic. If
2190 GCC produces a warning but not an error, that is correct ISO C support.
2191 If test suites call this ``failure'', they should be run with the GCC
2192 option @samp{-pedantic-errors}, which will turn these warnings into
2197 @node Warnings and Errors
2198 @section Warning Messages and Error Messages
2200 @cindex error messages
2201 @cindex warnings vs errors
2202 @cindex messages, warning and error
2203 The GNU compiler can produce two kinds of diagnostics: errors and
2204 warnings. Each kind has a different purpose:
2208 @emph{Errors} report problems that make it impossible to compile your
2209 program. GCC reports errors with the source file name and line
2210 number where the problem is apparent.
2213 @emph{Warnings} report other unusual conditions in your code that
2214 @emph{may} indicate a problem, although compilation can (and does)
2215 proceed. Warning messages also report the source file name and line
2216 number, but include the text @samp{warning:} to distinguish them
2217 from error messages.
2220 Warnings may indicate danger points where you should check to make sure
2221 that your program really does what you intend; or the use of obsolete
2222 features; or the use of nonstandard features of GNU C or C++. Many
2223 warnings are issued only if you ask for them, with one of the @samp{-W}
2224 options (for instance, @samp{-Wall} requests a variety of useful
2227 GCC always tries to compile your program if possible; it never
2228 gratuitously rejects a program whose meaning is clear merely because
2229 (for instance) it fails to conform to a standard. In some cases,
2230 however, the C and C++ standards specify that certain extensions are
2231 forbidden, and a diagnostic @emph{must} be issued by a conforming
2232 compiler. The @samp{-pedantic} option tells GCC to issue warnings in
2233 such cases; @samp{-pedantic-errors} says to make them errors instead.
2234 This does not mean that @emph{all} non-ISO constructs get warnings
2237 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
2238 more detail on these and related command-line options.
2241 @chapter Reporting Bugs
2243 @cindex reporting bugs
2245 Your bug reports play an essential role in making GCC reliable.
2247 When you encounter a problem, the first thing to do is to see if it is
2248 already known. @xref{Trouble}. If it isn't known, then you should
2251 Reporting a bug may help you by bringing a solution to your problem, or
2252 it may not. (If it does not, look in the service directory; see
2253 @ref{Service}.) In any case, the principal function of a bug report is
2254 to help the entire community by making the next version of GCC work
2255 better. Bug reports are your contribution to the maintenance of GCC.
2257 Since the maintainers are very overloaded, we cannot respond to every
2258 bug report. However, if the bug has not been fixed, we are likely to
2259 send you a patch and ask you to tell us whether it works.
2261 In order for a bug report to serve its purpose, you must include the
2262 information that makes for fixing the bug.
2265 * Criteria: Bug Criteria. Have you really found a bug?
2266 * Where: Bug Lists. Where to send your bug report.
2267 * Reporting: Bug Reporting. How to report a bug effectively.
2268 * GNATS: gccbug. You can use a bug reporting tool.
2269 * Patches: Sending Patches. How to send a patch for GCC.
2270 * Known: Trouble. Known problems.
2271 * Help: Service. Where to ask for help.
2274 @node Bug Criteria,Bug Lists,,Bugs
2275 @section Have You Found a Bug?
2276 @cindex bug criteria
2278 If you are not sure whether you have found a bug, here are some guidelines:
2281 @cindex fatal signal
2284 If the compiler gets a fatal signal, for any input whatever, that is a
2285 compiler bug. Reliable compilers never crash.
2287 @cindex invalid assembly code
2288 @cindex assembly code, invalid
2290 If the compiler produces invalid assembly code, for any input whatever
2291 (except an @code{asm} statement), that is a compiler bug, unless the
2292 compiler reports errors (not just warnings) which would ordinarily
2293 prevent the assembler from being run.
2295 @cindex undefined behavior
2296 @cindex undefined function value
2297 @cindex increment operators
2299 If the compiler produces valid assembly code that does not correctly
2300 execute the input source code, that is a compiler bug.
2302 However, you must double-check to make sure, because you may have run
2303 into an incompatibility between GNU C and traditional C
2304 (@pxref{Incompatibilities}). These incompatibilities might be considered
2305 bugs, but they are inescapable consequences of valuable features.
2307 Or you may have a program whose behavior is undefined, which happened
2308 by chance to give the desired results with another C or C++ compiler.
2310 For example, in many nonoptimizing compilers, you can write @samp{x;}
2311 at the end of a function instead of @samp{return x;}, with the same
2312 results. But the value of the function is undefined if @code{return}
2313 is omitted; it is not a bug when GCC produces different results.
2315 Problems often result from expressions with two increment operators,
2316 as in @code{f (*p++, *p++)}. Your previous compiler might have
2317 interpreted that expression the way you intended; GCC might
2318 interpret it another way. Neither compiler is wrong. The bug is
2321 After you have localized the error to a single source line, it should
2322 be easy to check for these things. If your program is correct and
2323 well defined, you have found a compiler bug.
2326 If the compiler produces an error message for valid input, that is a
2329 @cindex invalid input
2331 If the compiler does not produce an error message for invalid input,
2332 that is a compiler bug. However, you should note that your idea of
2333 ``invalid input'' might be my idea of ``an extension'' or ``support
2334 for traditional practice''.
2337 If you are an experienced user of one of the languages GCC supports, your
2338 suggestions for improvement of GCC are welcome in any case.
2341 @node Bug Lists,Bug Reporting,Bug Criteria,Bugs
2342 @section Where to Report Bugs
2343 @cindex bug report mailing lists
2344 @kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
2345 Send bug reports for the GNU Compiler Collection to
2346 @email{gcc-bugs@@gcc.gnu.org}. In accordance with the GNU-wide
2347 convention, in which bug reports for tool ``foo'' are sent
2348 to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
2349 may also be used; it will forward to the address given above.
2351 Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or
2352 more up-to-date bug reporting instructions before you post a bug report.
2354 @node Bug Reporting,gccbug,Bug Lists,Bugs
2355 @section How to Report Bugs
2356 @cindex compiler bugs, reporting
2358 The fundamental principle of reporting bugs usefully is this:
2359 @strong{report all the facts}. If you are not sure whether to state a
2360 fact or leave it out, state it!
2362 Often people omit facts because they think they know what causes the
2363 problem and they conclude that some details don't matter. Thus, you might
2364 assume that the name of the variable you use in an example does not matter.
2365 Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
2366 stray memory reference which happens to fetch from the location where that
2367 name is stored in memory; perhaps, if the name were different, the contents
2368 of that location would fool the compiler into doing the right thing despite
2369 the bug. Play it safe and give a specific, complete example. That is the
2370 easiest thing for you to do, and the most helpful.
2372 Keep in mind that the purpose of a bug report is to enable someone to
2373 fix the bug if it is not known. It isn't very important what happens if
2374 the bug is already known. Therefore, always write your bug reports on
2375 the assumption that the bug is not known.
2377 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2378 bell?'' This cannot help us fix a bug, so it is basically useless. We
2379 respond by asking for enough details to enable us to investigate.
2380 You might as well expedite matters by sending them to begin with.
2382 Try to make your bug report self-contained. If we have to ask you for
2383 more information, it is best if you include all the previous information
2384 in your response, as well as the information that was missing.
2386 Please report each bug in a separate message. This makes it easier for
2387 us to track which bugs have been fixed and to forward your bugs reports
2388 to the appropriate maintainer.
2390 To enable someone to investigate the bug, you should include all these
2395 The version of GCC. You can get this by running it with the
2398 Without this, we won't know whether there is any point in looking for
2399 the bug in the current version of GCC.
2402 A complete input file that will reproduce the bug. If the bug is in the
2403 C preprocessor, send a source file and any header files that it
2404 requires. If the bug is in the compiler proper (@file{cc1}), send the
2405 preprocessor output generated by adding @samp{-save-temps} to the
2406 compilation command (@pxref{Debugging Options}). When you do this, use
2407 the same @samp{-I}, @samp{-D} or @samp{-U} options that you used in
2408 actual compilation. Then send the @var{input}.i or @var{input}.ii files
2411 A single statement is not enough of an example. In order to compile it,
2412 it must be embedded in a complete file of compiler input; and the bug
2413 might depend on the details of how this is done.
2415 Without a real example one can compile, all anyone can do about your bug
2416 report is wish you luck. It would be futile to try to guess how to
2417 provoke the bug. For example, bugs in register allocation and reloading
2418 frequently depend on every little detail of the function they happen in.
2420 Even if the input file that fails comes from a GNU program, you should
2421 still send the complete test case. Don't ask the GCC maintainers to
2422 do the extra work of obtaining the program in question---they are all
2423 overworked as it is. Also, the problem may depend on what is in the
2424 header files on your system; it is unreliable for the GCC maintainers
2425 to try the problem with the header files available to them. By sending
2426 CPP output, you can eliminate this source of uncertainty and save us
2427 a certain percentage of wild goose chases.
2430 The command arguments you gave GCC to compile that example
2431 and observe the bug. For example, did you use @samp{-O}? To guarantee
2432 you won't omit something important, list all the options.
2434 If we were to try to guess the arguments, we would probably guess wrong
2435 and then we would not encounter the bug.
2438 The type of machine you are using, and the operating system name and
2442 The operands you gave to the @code{configure} command when you installed
2446 A complete list of any modifications you have made to the compiler
2447 source. (We don't promise to investigate the bug unless it happens in
2448 an unmodified compiler. But if you've made modifications and don't tell
2449 us, then you are sending us on a wild goose chase.)
2451 Be precise about these changes. A description in English is not
2452 enough---send a context diff for them.
2454 Adding files of your own (such as a machine description for a machine we
2455 don't support) is a modification of the compiler source.
2458 Details of any other deviations from the standard procedure for installing
2462 A description of what behavior you observe that you believe is
2463 incorrect. For example, ``The compiler gets a fatal signal,'' or,
2464 ``The assembler instruction at line 208 in the output is incorrect.''
2466 Of course, if the bug is that the compiler gets a fatal signal, then one
2467 can't miss it. But if the bug is incorrect output, the maintainer might
2468 not notice unless it is glaringly wrong. None of us has time to study
2469 all the assembler code from a 50-line C program just on the chance that
2470 one instruction might be wrong. We need @emph{you} to do this part!
2472 Even if the problem you experience is a fatal signal, you should still
2473 say so explicitly. Suppose something strange is going on, such as, your
2474 copy of the compiler is out of synch, or you have encountered a bug in
2475 the C library on your system. (This has happened!) Your copy might
2476 crash and the copy here would not. If you @i{said} to expect a crash,
2477 then when the compiler here fails to crash, we would know that the bug
2478 was not happening. If you don't say to expect a crash, then we would
2479 not know whether the bug was happening. We would not be able to draw
2480 any conclusion from our observations.
2482 If the problem is a diagnostic when compiling GCC with some other
2483 compiler, say whether it is a warning or an error.
2485 Often the observed symptom is incorrect output when your program is run.
2486 Sad to say, this is not enough information unless the program is short
2487 and simple. None of us has time to study a large program to figure out
2488 how it would work if compiled correctly, much less which line of it was
2489 compiled wrong. So you will have to do that. Tell us which source line
2490 it is, and what incorrect result happens when that line is executed. A
2491 person who understands the program can find this as easily as finding a
2492 bug in the program itself.
2495 If you send examples of assembler code output from GCC,
2496 please use @samp{-g} when you make them. The debugging information
2497 includes source line numbers which are essential for correlating the
2498 output with the input.
2501 If you wish to mention something in the GCC source, refer to it by
2502 context, not by line number.
2504 The line numbers in the development sources don't match those in your
2505 sources. Your line numbers would convey no useful information to the
2509 Additional information from a debugger might enable someone to find a
2510 problem on a machine which he does not have available. However, you
2511 need to think when you collect this information if you want it to have
2512 any chance of being useful.
2514 @cindex backtrace for bug reports
2515 For example, many people send just a backtrace, but that is never
2516 useful by itself. A simple backtrace with arguments conveys little
2517 about GCC because the compiler is largely data-driven; the same
2518 functions are called over and over for different RTL insns, doing
2519 different things depending on the details of the insn.
2521 Most of the arguments listed in the backtrace are useless because they
2522 are pointers to RTL list structure. The numeric values of the
2523 pointers, which the debugger prints in the backtrace, have no
2524 significance whatever; all that matters is the contents of the objects
2525 they point to (and most of the contents are other such pointers).
2527 In addition, most compiler passes consist of one or more loops that
2528 scan the RTL insn sequence. The most vital piece of information about
2529 such a loop---which insn it has reached---is usually in a local variable,
2533 What you need to provide in addition to a backtrace are the values of
2534 the local variables for several stack frames up. When a local
2535 variable or an argument is an RTX, first print its value and then use
2536 the GDB command @code{pr} to print the RTL expression that it points
2537 to. (If GDB doesn't run on your machine, use your debugger to call
2538 the function @code{debug_rtx} with the RTX as an argument.) In
2539 general, whenever a variable is a pointer, its value is no use
2540 without the data it points to.
2543 Here are some things that are not necessary:
2547 A description of the envelope of the bug.
2549 Often people who encounter a bug spend a lot of time investigating
2550 which changes to the input file will make the bug go away and which
2551 changes will not affect it.
2553 This is often time consuming and not very useful, because the way we
2554 will find the bug is by running a single example under the debugger with
2555 breakpoints, not by pure deduction from a series of examples. You might
2556 as well save your time for something else.
2558 Of course, if you can find a simpler example to report @emph{instead} of
2559 the original one, that is a convenience. Errors in the output will be
2560 easier to spot, running under the debugger will take less time, etc.
2561 Most GCC bugs involve just one function, so the most straightforward
2562 way to simplify an example is to delete all the function definitions
2563 except the one where the bug occurs. Those earlier in the file may be
2564 replaced by external declarations if the crucial function depends on
2565 them. (Exception: inline functions may affect compilation of functions
2566 defined later in the file.)
2568 However, simplification is not vital; if you don't want to do this,
2569 report the bug anyway and send the entire test case you used.
2572 In particular, some people insert conditionals @samp{#ifdef BUG} around
2573 a statement which, if removed, makes the bug not happen. These are just
2574 clutter; we won't pay any attention to them anyway. Besides, you should
2575 send us cpp output, and that can't have conditionals.
2578 A patch for the bug.
2580 A patch for the bug is useful if it is a good one. But don't omit the
2581 necessary information, such as the test case, on the assumption that a
2582 patch is all we need. We might see problems with your patch and decide
2583 to fix the problem another way, or we might not understand it at all.
2585 Sometimes with a program as complicated as GCC it is very hard to
2586 construct an example that will make the program follow a certain path
2587 through the code. If you don't send the example, we won't be able to
2588 construct one, so we won't be able to verify that the bug is fixed.
2590 And if we can't understand what bug you are trying to fix, or why your
2591 patch should be an improvement, we won't install it. A test case will
2592 help us to understand.
2594 @xref{Sending Patches}, for guidelines on how to make it easy for us to
2595 understand and install your patches.
2598 A guess about what the bug is or what it depends on.
2600 Such guesses are usually wrong. Even I can't guess right about such
2601 things without first using the debugger to find the facts.
2606 We have no way of examining a core dump for your type of machine
2607 unless we have an identical system---and if we do have one,
2608 we should be able to reproduce the crash ourselves.
2611 @node gccbug,Sending Patches, Bug Reporting, Bugs
2612 @section The gccbug script
2613 @cindex gccbug script
2615 To simplify creation of bug reports, and to allow better tracking of
2616 reports, we use the GNATS bug tracking system. Part of that system is
2617 the @code{gccbug} script. This is a Unix shell script, so you need a
2618 shell to run it. It is normally installed in the same directory where
2619 @code{gcc} is installed.
2621 The gccbug script is derived from send-pr, @pxref{using
2622 send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
2623 invoked, it starts a text editor so you can fill out the various fields
2624 of the report. When the you quit the editor, the report is automatically
2625 send to the bug reporting address.
2627 A number of fields in this bug report form are specific to GCC, and are
2628 explained at @uref{http://gcc.gnu.org/gnats.html}.
2630 @node Sending Patches,, gccbug, Bugs
2631 @section Sending Patches for GCC
2633 If you would like to write bug fixes or improvements for the GNU C
2634 compiler, that is very helpful. Send suggested fixes to the patches
2635 mailing list, @email{gcc-patches@@gcc.gnu.org}.
2637 Please follow these guidelines so we can study your patches efficiently.
2638 If you don't follow these guidelines, your information might still be
2639 useful, but using it will take extra work. Maintaining GNU C is a lot
2640 of work in the best of circumstances, and we can't keep up unless you do
2645 Send an explanation with your changes of what problem they fix or what
2646 improvement they bring about. For a bug fix, just include a copy of the
2647 bug report, and explain why the change fixes the bug.
2649 (Referring to a bug report is not as good as including it, because then
2650 we will have to look it up, and we have probably already deleted it if
2651 we've already fixed the bug.)
2654 Always include a proper bug report for the problem you think you have
2655 fixed. We need to convince ourselves that the change is right before
2656 installing it. Even if it is right, we might have trouble judging it if
2657 we don't have a way to reproduce the problem.
2660 Include all the comments that are appropriate to help people reading the
2661 source in the future understand why this change was needed.
2664 Don't mix together changes made for different reasons.
2665 Send them @emph{individually}.
2667 If you make two changes for separate reasons, then we might not want to
2668 install them both. We might want to install just one. If you send them
2669 all jumbled together in a single set of diffs, we have to do extra work
2670 to disentangle them---to figure out which parts of the change serve
2671 which purpose. If we don't have time for this, we might have to ignore
2672 your changes entirely.
2674 If you send each change as soon as you have written it, with its own
2675 explanation, then the two changes never get tangled up, and we can
2676 consider each one properly without any extra work to disentangle them.
2678 Ideally, each change you send should be impossible to subdivide into
2679 parts that we might want to consider separately, because each of its
2680 parts gets its motivation from the other parts.
2683 Send each change as soon as that change is finished. Sometimes people
2684 think they are helping us by accumulating many changes to send them all
2685 together. As explained above, this is absolutely the worst thing you
2688 Since you should send each change separately, you might as well send it
2689 right away. That gives us the option of installing it immediately if it
2693 Use @samp{diff -c} to make your diffs. Diffs without context are hard
2694 for us to install reliably. More than that, they make it hard for us to
2695 study the diffs to decide whether we want to install them. Unidiff
2696 format is better than contextless diffs, but not as easy to read as
2699 If you have GNU diff, use @samp{diff -cp}, which shows the name of the
2700 function that each change occurs in.
2703 Write the change log entries for your changes. We get lots of changes,
2704 and we don't have time to do all the change log writing ourselves.
2706 Read the @file{ChangeLog} file to see what sorts of information to put
2707 in, and to learn the style that we use. The purpose of the change log
2708 is to show people where to find what was changed. So you need to be
2709 specific about what functions you changed; in large functions, it's
2710 often helpful to indicate where within the function the change was.
2712 On the other hand, once you have shown people where to find the change,
2713 you need not explain its purpose. Thus, if you add a new function, all
2714 you need to say about it is that it is new. If you feel that the
2715 purpose needs explaining, it probably does---but the explanation will be
2716 much more useful if you put it in comments in the code.
2718 If you would like your name to appear in the header line for who made
2719 the change, send us the header line.
2722 When you write the fix, keep in mind that we can't install a change that
2723 would break other systems.
2725 People often suggest fixing a problem by changing machine-independent
2726 files such as @file{toplev.c} to do something special that a particular
2727 system needs. Sometimes it is totally obvious that such changes would
2728 break GCC for almost all users. We can't possibly make a change like
2729 that. At best it might tell us how to write another patch that would
2730 solve the problem acceptably.
2732 Sometimes people send fixes that @emph{might} be an improvement in
2733 general---but it is hard to be sure of this. It's hard to install
2734 such changes because we have to study them very carefully. Of course,
2735 a good explanation of the reasoning by which you concluded the change
2736 was correct can help convince us.
2738 The safest changes are changes to the configuration files for a
2739 particular machine. These are safe because they can't create new bugs
2742 Please help us keep up with the workload by designing the patch in a
2743 form that is good to install.
2747 @chapter How To Get Help with GCC
2749 If you need help installing, using or changing GCC, there are two
2754 Send a message to a suitable network mailing list. First try
2755 @email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
2756 that brings no response, try @email{gcc@@gcc.gnu.org}. For help
2757 changing GCC, ask @email{gcc@@gcc.gnu.org}. If you think you have found
2758 a bug in GCC, please report it following the instructions at
2759 @pxref{Bug Reporting}.
2762 Look in the service directory for someone who might help you for a fee.
2763 The service directory is found at
2764 @uref{http://www.gnu.org/prep/service.html}.
2767 @c For further information, see
2768 @c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}.
2769 @c FIXME: this URL may be too volatile, this FAQ entry needs to move to
2770 @c the regular web pages before we can uncomment the reference.
2773 @chapter Contributing to GCC Development
2775 If you would like to help pretest GCC releases to assure they work well,
2776 our current development sources are available by CVS (see
2777 @uref{http://gcc.gnu.org/cvs.html}). Source and binary snapshots are
2778 also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
2780 If you would like to work on improvements to GCC, please read
2781 @uref{http://gcc.gnu.org/contribute.html} and
2782 @uref{http://gcc.gnu.org/contributewhy.html} for information on how to
2783 make useful contributions and avoid duplication of effort. Suggested
2784 projects are listed at @uref{http://gcc.gnu.org/projects/}.
2787 @chapter Using GCC on VMS
2789 @c prevent bad page break with this line
2790 Here is how to use GCC on VMS.
2793 * Include Files and VMS:: Where the preprocessor looks for the include files.
2794 * Global Declarations:: How to do globaldef, globalref and globalvalue with
2796 * VMS Misc:: Misc information.
2799 @node Include Files and VMS
2800 @section Include Files and VMS
2802 @cindex include files and VMS
2803 @cindex VMS and include files
2804 @cindex header files and VMS
2805 Due to the differences between the filesystems of Unix and VMS, GCC
2806 attempts to translate file names in @samp{#include} into names that VMS
2807 will understand. The basic strategy is to prepend a prefix to the
2808 specification of the include file, convert the whole filename to a VMS
2809 filename, and then try to open the file. GCC tries various prefixes
2810 one by one until one of them succeeds:
2814 The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
2815 where GNU C header files are traditionally stored. If you wish to store
2816 header files in non-standard locations, then you can assign the logical
2817 @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
2818 list is suitable for use with a rooted logical.
2821 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where
2822 VAX-C header files are traditionally stored.
2825 If the include file specification by itself is a valid VMS filename, the
2826 preprocessor then uses this name with no prefix in an attempt to open
2830 If the file specification is not a valid VMS filename (i.e. does not
2831 contain a device or a directory specifier, and contains a @samp{/}
2832 character), the preprocessor tries to convert it from Unix syntax to
2835 Conversion works like this: the first directory name becomes a device,
2836 and the rest of the directories are converted into VMS-format directory
2837 names. For example, the name @file{X11/foobar.h} is
2838 translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
2839 whichever one can be opened. This strategy allows you to assign a
2840 logical name to point to the actual location of the header files.
2843 If none of these strategies succeeds, the @samp{#include} fails.
2846 Include directives of the form:
2853 are a common source of incompatibility between VAX-C and GCC. VAX-C
2854 treats this much like a standard @code{#include <foobar.h>} directive.
2855 That is incompatible with the ISO C behavior implemented by GCC: to
2856 expand the name @code{foobar} as a macro. Macro expansion should
2857 eventually yield one of the two standard formats for @code{#include}:
2860 #include "@var{file}"
2861 #include <@var{file}>
2864 If you have this problem, the best solution is to modify the source to
2865 convert the @code{#include} directives to one of the two standard forms.
2866 That will work with either compiler. If you want a quick and dirty fix,
2867 define the file names as macros with the proper expansion, like this:
2870 #define stdio <stdio.h>
2874 This will work, as long as the name doesn't conflict with anything else
2877 Another source of incompatibility is that VAX-C assumes that:
2884 is actually asking for the file @file{foobar.h}. GCC does not
2885 make this assumption, and instead takes what you ask for literally;
2886 it tries to read the file @file{foobar}. The best way to avoid this
2887 problem is to always specify the desired file extension in your include
2890 GCC for VMS is distributed with a set of include files that is
2891 sufficient to compile most general purpose programs. Even though the
2892 GCC distribution does not contain header files to define constants
2893 and structures for some VMS system-specific functions, there is no
2894 reason why you cannot use GCC with any of these functions. You first
2895 may have to generate or create header files, either by using the public
2896 domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
2897 extracting the relevant modules from one of the system macro libraries,
2898 and using an editor to construct a C header file.
2900 A @code{#include} file name cannot contain a DECNET node name. The
2901 preprocessor reports an I/O error if you attempt to use a node name,
2902 whether explicitly, or implicitly via a logical name.
2904 @node Global Declarations
2905 @section Global Declarations and VMS
2909 @findex GLOBALVALUEDEF
2910 @findex GLOBALVALUEREF
2911 GCC does not provide the @code{globalref}, @code{globaldef} and
2912 @code{globalvalue} keywords of VAX-C. You can get the same effect with
2913 an obscure feature of GAS, the GNU assembler. (This requires GAS
2914 version 1.39 or later.) The following macros allow you to use this
2915 feature in a fairly natural way:
2919 #define GLOBALREF(TYPE,NAME) \
2921 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
2922 #define GLOBALDEF(TYPE,NAME,VALUE) \
2924 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
2926 #define GLOBALVALUEREF(TYPE,NAME) \
2927 const TYPE NAME[1] \
2928 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
2929 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2930 const TYPE NAME[1] \
2931 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \
2934 #define GLOBALREF(TYPE,NAME) \
2936 #define GLOBALDEF(TYPE,NAME,VALUE) \
2937 globaldef TYPE NAME = VALUE
2938 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2939 globalvalue TYPE NAME = VALUE
2940 #define GLOBALVALUEREF(TYPE,NAME) \
2941 globalvalue TYPE NAME
2946 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
2947 name is removed by the assembler, after it has modified the attributes
2948 of the symbol). These macros are provided in the VMS binaries
2949 distribution in a header file @file{GNU_HACKS.H}. An example of the
2953 GLOBALREF (int, ijk);
2954 GLOBALDEF (int, jkl, 0);
2957 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
2958 straightforwardly for arrays, since there is no way to insert the array
2959 dimension into the declaration at the right place. However, you can
2960 declare an array with these macros if you first define a typedef for the
2961 array type, like this:
2964 typedef int intvector[10];
2965 GLOBALREF (intvector, foo);
2968 Array and structure initializers will also break the macros; you can
2969 define the initializer to be a macro of its own, or you can expand the
2970 @code{GLOBALDEF} macro by hand. You may find a case where you wish to
2971 use the @code{GLOBALDEF} macro with a large array, but you are not
2972 interested in explicitly initializing each element of the array. In
2973 such cases you can use an initializer like: @code{@{0,@}}, which will
2974 initialize the entire array to @code{0}.
2976 A shortcoming of this implementation is that a variable declared with
2977 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For
2978 example, the declaration:
2981 GLOBALVALUEREF(int, ijk);
2985 declares the variable @code{ijk} as an array of type @code{int [1]}.
2986 This is done because a globalvalue is actually a constant; its ``value''
2987 is what the linker would normally consider an address. That is not how
2988 an integer value works in C, but it is how an array works. So treating
2989 the symbol as an array name gives consistent results---with the
2990 exception that the value seems to have the wrong type. @strong{Don't
2991 try to access an element of the array.} It doesn't have any elements.
2992 The array ``address'' may not be the address of actual storage.
2994 The fact that the symbol is an array may lead to warnings where the
2995 variable is used. Insert type casts to avoid the warnings. Here is an
2996 example; it takes advantage of the ISO C feature allowing macros that
2997 expand to use the same name as the macro itself.
3000 GLOBALVALUEREF (int, ss$_normal);
3001 GLOBALVALUEDEF (int, xyzzy,123);
3003 #define ss$_normal ((int) ss$_normal)
3004 #define xyzzy ((int) xyzzy)
3008 Don't use @code{globaldef} or @code{globalref} with a variable whose
3009 type is an enumeration type; this is not implemented. Instead, make the
3010 variable an integer, and use a @code{globalvaluedef} for each of the
3011 enumeration values. An example of this would be:
3015 GLOBALDEF (int, color, 0);
3016 GLOBALVALUEDEF (int, RED, 0);
3017 GLOBALVALUEDEF (int, BLUE, 1);
3018 GLOBALVALUEDEF (int, GREEN, 3);
3020 enum globaldef color @{RED, BLUE, GREEN = 3@};
3025 @section Other VMS Issues
3027 @cindex exit status and VMS
3028 @cindex return value of @code{main}
3029 @cindex @code{main} and the exit status
3030 GCC automatically arranges for @code{main} to return 1 by default if
3031 you fail to specify an explicit return value. This will be interpreted
3032 by VMS as a status code indicating a normal successful completion.
3033 Version 1 of GCC did not provide this default.
3035 GCC on VMS works only with the GNU assembler, GAS. You need version
3036 1.37 or later of GAS in order to produce value debugging information for
3037 the VMS debugger. Use the ordinary VMS linker with the object files
3040 @cindex shared VMS run time system
3041 @cindex @file{VAXCRTL}
3042 Under previous versions of GCC, the generated code would occasionally
3043 give strange results when linked to the sharable @file{VAXCRTL} library.
3044 Now this should work.
3046 A caveat for use of @code{const} global variables: the @code{const}
3047 modifier must be specified in every external declaration of the variable
3048 in all of the source files that use that variable. Otherwise the linker
3049 will issue warnings about conflicting attributes for the variable. Your
3050 program will still work despite the warnings, but the variable will be
3051 placed in writable storage.
3053 @cindex name augmentation
3054 @cindex case sensitivity and VMS
3055 @cindex VMS and case sensitivity
3056 Although the VMS linker does distinguish between upper and lower case
3057 letters in global symbols, most VMS compilers convert all such symbols
3058 into upper case and most run-time library routines also have upper case
3059 names. To be able to reliably call such routines, GCC (by means of
3060 the assembler GAS) converts global symbols into upper case like other
3061 VMS compilers. However, since the usual practice in C is to distinguish
3062 case, GCC (via GAS) tries to preserve usual C behavior by augmenting
3063 each name that is not all lower case. This means truncating the name
3064 to at most 23 characters and then adding more characters at the end
3065 which encode the case pattern of those 23. Names which contain at
3066 least one dollar sign are an exception; they are converted directly into
3067 upper case without augmentation.
3069 Name augmentation yields bad results for programs that use precompiled
3070 libraries (such as Xlib) which were generated by another compiler. You
3071 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
3072 it makes external C functions and variables case-independent as is usual
3073 on VMS. Alternatively, you could write all references to the functions
3074 and variables in such libraries using lower case; this will work on VMS,
3075 but is not portable to other systems. The compiler option @samp{/NAMES}
3076 also provides control over global name handling.
3078 Function and variable names are handled somewhat differently with GNU
3079 C++. The GNU C++ compiler performs @dfn{name mangling} on function
3080 names, which means that it adds information to the function name to
3081 describe the data types of the arguments that the function takes. One
3082 result of this is that the name of a function can become very long.
3083 Since the VMS linker only recognizes the first 31 characters in a name,
3084 special action is taken to ensure that each function and variable has a
3085 unique name that can be represented in 31 characters.
3087 If the name (plus a name augmentation, if required) is less than 32
3088 characters in length, then no special action is performed. If the name
3089 is longer than 31 characters, the assembler (GAS) will generate a
3090 hash string based upon the function name, truncate the function name to
3091 23 characters, and append the hash string to the truncated name. If the
3092 @samp{/VERBOSE} compiler option is used, the assembler will print both
3093 the full and truncated names of each symbol that is truncated.
3095 The @samp{/NOCASE_HACK} compiler option should not be used when you are
3096 compiling programs that use libg++. libg++ has several instances of
3097 objects (i.e. @code{Filebuf} and @code{filebuf}) which become
3098 indistinguishable in a case-insensitive environment. This leads to
3099 cases where you need to inhibit augmentation selectively (if you were
3100 using libg++ and Xlib in the same program, for example). There is no
3101 special feature for doing this, but you can get the result by defining a
3102 macro for each mixed case symbol for which you wish to inhibit
3103 augmentation. The macro should expand into the lower case equivalent of
3104 itself. For example:
3107 #define StuDlyCapS studlycaps
3110 These macro definitions can be placed in a header file to minimize the
3111 number of changes to your source code.
3114 @chapter Makefile Targets
3115 @cindex makefile targets
3116 @cindex targets, makefile
3120 This is the default target. Depending on what your build/host/target
3121 configuration is, it coordinates all the things that need to be built.
3124 Produce info-formatted documentation. Also, @code{make dvi} is
3125 available for DVI-formatted documentation, and @code{make
3126 generated-manpages} to generate man pages.
3129 Delete the files made while building the compiler.
3132 That, and all the other files built by @code{make all}.
3135 That, and all the files created by @code{configure}.
3138 That, and any temporary or intermediate files, like emacs backup files.
3140 @item maintainer-clean
3141 Distclean plus any file that can be generated from other files. Note
3142 that additional tools may be required beyond what is normally needed to
3149 Deletes installed files.
3152 Run the testsuite. This creates a @file{testsuite} subdirectory that
3153 has various @file{.sum} and @file{.log} files containing the results of
3154 the testing. You can run subsets with, for example, @code{make check-gcc}.
3155 You can specify specific tests by setting RUNTESTFLAGS to be the name
3156 of the @file{.exp} file, optionally followed by (for some tests) an equals
3157 and a file wildcard, like:
3160 make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
3163 Note that running the testsuite may require additional tools be
3164 installed, such as TCL or dejagnu.
3167 Builds gcc three times - once with the native compiler, once with the
3168 native-built compiler it just built, and once with the compiler it built
3169 the second time. In theory, the last two should produce the same
3170 results, which @code{make compare} can check. Each step of this process
3171 is called a "stage", and the results of each stage N (N=1..3) are copied
3172 to a subdirectory @file{stageN/}.
3174 @item bootstrap-lean
3175 Like @code{bootstrap}, except that the various stages are removed once
3176 they're no longer needed. This saves disk space.
3179 Once bootstrapped, this incrementally rebuilds each of the three stages,
3180 one at a time. It does this by "bubbling" the stages up from their
3181 stubdirectories, rebuilding them, and copying them back to their
3182 subdirectories. This will allow you to, for example, quickly rebuild a
3183 bootstrapped compiler after changing the sources, without having to do a
3187 Rebuilds the most recently built stage. Since each stage requires
3188 special invocation, using this target means you don't have to keep track
3189 of which stage you're on or what invocation that stage needs.
3192 Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}).
3194 @item stageN (N=1..4)
3195 For each stage, moves the appropriate files to the stageN subdirectory.
3197 @item unstageN (N=1..4)
3198 Undoes the corresponding @code{stageN}.
3200 @item restageN (N=1..4)
3201 Undoes the corresponding @code{stageN} and rebuilds it with the
3205 Compares the results of stages 2 and 3. This ensures that the compiler
3206 is running properly, since it should produce the same object files
3207 regardless of how it itself was compiled.
3215 @chapter GCC and Portability
3217 @cindex GCC and portability
3219 The main goal of GCC was to make a good, fast compiler for machines in
3220 the class that the GNU system aims to run on: 32-bit machines that address
3221 8-bit bytes and have several general registers. Elegance, theoretical
3222 power and simplicity are only secondary.
3224 GCC gets most of the information about the target machine from a machine
3225 description which gives an algebraic formula for each of the machine's
3226 instructions. This is a very clean way to describe the target. But when
3227 the compiler needs information that is difficult to express in this
3228 fashion, I have not hesitated to define an ad-hoc parameter to the machine
3229 description. The purpose of portability is to reduce the total work needed
3230 on the compiler; it was not of interest for its own sake.
3233 @cindex autoincrement addressing, availability
3235 GCC does not contain machine dependent code, but it does contain code
3236 that depends on machine parameters such as endianness (whether the most
3237 significant byte has the highest or lowest address of the bytes in a word)
3238 and the availability of autoincrement addressing. In the RTL-generation
3239 pass, it is often necessary to have multiple strategies for generating code
3240 for a particular kind of syntax tree, strategies that are usable for different
3241 combinations of parameters. Often I have not tried to address all possible
3242 cases, but only the common ones or only the ones that I have encountered.
3243 As a result, a new target may require additional strategies. You will know
3244 if this happens because the compiler will call @code{abort}. Fortunately,
3245 the new strategies can be added in a machine-independent fashion, and will
3246 affect only the target machines that need them.
3251 @chapter Interfacing to GCC Output
3252 @cindex interfacing to GCC output
3253 @cindex run-time conventions
3254 @cindex function call conventions
3255 @cindex conventions, run-time
3257 GCC is normally configured to use the same function calling convention
3258 normally in use on the target system. This is done with the
3259 machine-description macros described (@pxref{Target Macros}).
3261 @cindex unions, returning
3262 @cindex structures, returning
3263 @cindex returning structures and unions
3264 However, returning of structure and union values is done differently on
3265 some target machines. As a result, functions compiled with PCC
3266 returning such types cannot be called from code compiled with GCC,
3267 and vice versa. This does not cause trouble often because few Unix
3268 library routines return structures or unions.
3270 GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
3271 long in the same registers used for @code{int} or @code{double} return
3272 values. (GCC typically allocates variables of such types in
3273 registers also.) Structures and unions of other sizes are returned by
3274 storing them into an address passed by the caller (usually in a
3275 register). The machine-description macros @code{STRUCT_VALUE} and
3276 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
3278 By contrast, PCC on most target machines returns structures and unions
3279 of any size by copying the data into an area of static storage, and then
3280 returning the address of that storage as if it were a pointer value.
3281 The caller must copy the data from that memory area to the place where
3282 the value is wanted. This is slower than the method used by GCC, and
3283 fails to be reentrant.
3285 On some target machines, such as RISC machines and the 80386, the
3286 standard system convention is to pass to the subroutine the address of
3287 where to return the value. On these machines, GCC has been
3288 configured to be compatible with the standard compiler, when this method
3289 is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3291 @cindex argument passing
3292 @cindex passing arguments
3293 GCC uses the system's standard convention for passing arguments. On
3294 some machines, the first few arguments are passed in registers; in
3295 others, all are passed on the stack. It would be possible to use
3296 registers for argument passing on any machine, and this would probably
3297 result in a significant speedup. But the result would be complete
3298 incompatibility with code that follows the standard convention. So this
3299 change is practical only if you are switching to GCC as the sole C
3300 compiler for the system. We may implement register argument passing on
3301 certain machines once we have a complete GNU system so that we can
3302 compile the libraries with GCC.
3304 On some machines (particularly the Sparc), certain types of arguments
3305 are passed ``by invisible reference''. This means that the value is
3306 stored in memory, and the address of the memory location is passed to
3309 @cindex @code{longjmp} and automatic variables
3310 If you use @code{longjmp}, beware of automatic variables. ISO C says that
3311 automatic variables that are not declared @code{volatile} have undefined
3312 values after a @code{longjmp}. And this is all GCC promises to do,
3313 because it is very difficult to restore register variables correctly, and
3314 one of GCC's features is that it can put variables in registers without
3317 If you want a variable to be unaltered by @code{longjmp}, and you don't
3318 want to write @code{volatile} because old C compilers don't accept it,
3319 just take the address of the variable. If a variable's address is ever
3320 taken, even if just to compute it and ignore it, then the variable cannot
3331 @cindex arithmetic libraries
3332 @cindex math libraries
3333 Code compiled with GCC may call certain library routines. Most of
3334 them handle arithmetic for which there are no instructions. This
3335 includes multiply and divide on some machines, and floating point
3336 operations on any machine for which floating point support is disabled
3337 with @samp{-msoft-float}. Some standard parts of the C library, such as
3338 @code{bcopy} or @code{memcpy}, are also called automatically. The usual
3339 function call interface is used for calling the library routines.
3341 Some of these routines can be defined in mostly machine-independent C;
3342 they appear in @file{libgcc2.c}. Others must be hand-written in
3343 assembly language for each processor. Wherever they are defined, they
3344 are compiled into the support library, @file{libgcc.a}, which is
3345 automatically searched when you link programs with GCC.
3350 @chapter Passes and Files of the Compiler
3351 @cindex passes and files of the compiler
3352 @cindex files and passes of the compiler
3353 @cindex compiler passes and files
3355 @cindex top level of compiler
3356 The overall control structure of the compiler is in @file{toplev.c}. This
3357 file is responsible for initialization, decoding arguments, opening and
3358 closing files, and sequencing the passes.
3360 @cindex parsing pass
3361 The parsing pass is invoked only once, to parse the entire input. The RTL
3362 intermediate code for a function is generated as the function is parsed, a
3363 statement at a time. Each statement is read in as a syntax tree and then
3364 converted to RTL; then the storage for the tree for the statement is
3365 reclaimed. Storage for types (and the expressions for their sizes),
3366 declarations, and a representation of the binding contours and how they nest,
3367 remain until the function is finished being compiled; these are all needed
3368 to output the debugging information.
3370 @findex rest_of_compilation
3371 @findex rest_of_decl_compilation
3372 Each time the parsing pass reads a complete function definition or
3373 top-level declaration, it calls either the function
3374 @code{rest_of_compilation}, or the function
3375 @code{rest_of_decl_compilation} in @file{toplev.c}, which are
3376 responsible for all further processing necessary, ending with output of
3377 the assembler language. All other compiler passes run, in sequence,
3378 within @code{rest_of_compilation}. When that function returns from
3379 compiling a function definition, the storage used for that function
3380 definition's compilation is entirely freed, unless it is an inline
3383 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3386 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3389 Here is a list of all the passes of the compiler and their source files.
3390 Also included is a description of where debugging dumps can be requested
3391 with @samp{-d} options.
3395 Parsing. This pass reads the entire text of a function definition,
3396 constructing partial syntax trees. This and RTL generation are no longer
3397 truly separate passes (formerly they were), but it is easier to think
3398 of them as separate.
3400 The tree representation does not entirely follow C syntax, because it is
3401 intended to support other languages as well.
3403 Language-specific data type analysis is also done in this pass, and every
3404 tree node that represents an expression has a data type attached.
3405 Variables are represented as declaration nodes.
3407 @cindex constant folding
3408 @cindex arithmetic simplifications
3409 @cindex simplifications, arithmetic
3410 Constant folding and some arithmetic simplifications are also done
3413 The language-independent source files for parsing are
3414 @file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}.
3415 There are also header files @file{tree.h} and @file{tree.def}
3416 which define the format of the tree representation.@refill
3418 @c Avoiding overfull is tricky here.
3419 The source files to parse C are
3423 @file{c-aux-info.c},
3426 along with header files
3430 The source files for parsing C++ are in @file{cp/}.
3431 They are @file{parse.y},
3433 @file{cvt.c}, @file{decl.c}, @file{decl2.c},
3435 @file{expr.c}, @file{init.c}, @file{lex.c},
3436 @file{method.c}, @file{ptree.c},@*
3437 @file{search.c}, @file{tree.c},
3438 @file{typeck2.c}, and
3439 @file{typeck.c}, along with header files @file{cp-tree.def},
3440 @file{cp-tree.h}, and @file{decl.h}.
3442 The special source files for parsing Objective C are in @file{objc/}.
3443 They are @file{objc-parse.y}, @file{objc-act.c}, @file{objc-tree.def}, and
3444 @file{objc-act.h}. Certain C-specific files are used for this as
3447 The file @file{c-common.c} is also used for all of the above languages.
3449 @cindex RTL generation
3451 RTL generation. This is the conversion of syntax tree into RTL code.
3452 It is actually done statement-by-statement during parsing, but for
3453 most purposes it can be thought of as a separate pass.
3455 @cindex target-parameter-dependent code
3456 This is where the bulk of target-parameter-dependent code is found,
3457 since often it is necessary for strategies to apply only when certain
3458 standard kinds of instructions are available. The purpose of named
3459 instruction patterns is to provide this information to the RTL
3462 @cindex tail recursion optimization
3463 Optimization is done in this pass for @code{if}-conditions that are
3464 comparisons, boolean operations or conditional expressions. Tail
3465 recursion is detected at this time also. Decisions are made about how
3466 best to arrange loops and how to output @code{switch} statements.
3468 @c Avoiding overfull is tricky here.
3469 The source files for RTL generation include
3477 and @file{emit-rtl.c}.
3479 @file{insn-emit.c}, generated from the machine description by the
3480 program @code{genemit}, is used in this pass. The header file
3481 @file{expr.h} is used for communication within this pass.@refill
3485 The header files @file{insn-flags.h} and @file{insn-codes.h},
3486 generated from the machine description by the programs @code{genflags}
3487 and @code{gencodes}, tell this pass which standard names are available
3488 for use and which patterns correspond to them.@refill
3490 Aside from debugging information output, none of the following passes
3491 refers to the tree structure representation of the function (only
3492 part of which is saved).
3494 @cindex inline, automatic
3495 The decision of whether the function can and should be expanded inline
3496 in its subsequent callers is made at the end of rtl generation. The
3497 function must meet certain criteria, currently related to the size of
3498 the function and the types and number of parameters it has. Note that
3499 this function may contain loops, recursive calls to itself
3500 (tail-recursive functions can be inlined!), gotos, in short, all
3501 constructs supported by GCC. The file @file{integrate.c} contains
3502 the code to save a function's rtl for later inlining and to inline that
3503 rtl when the function is called. The header file @file{integrate.h}
3504 is also used for this purpose.
3506 The option @samp{-dr} causes a debugging dump of the RTL code after
3507 this pass. This dump file's name is made by appending @samp{.rtl} to
3508 the input file name.
3510 @cindex jump optimization
3511 @cindex unreachable code
3514 Jump optimization. This pass simplifies jumps to the following
3515 instruction, jumps across jumps, and jumps to jumps. It deletes
3516 unreferenced labels and unreachable code, except that unreachable code
3517 that contains a loop is not recognized as unreachable in this pass.
3518 (Such loops are deleted later in the basic block analysis.) It also
3519 converts some code originally written with jumps into sequences of
3520 instructions that directly set values from the results of comparisons,
3521 if the machine has such instructions.
3523 Jump optimization is performed two or three times. The first time is
3524 immediately following RTL generation. The second time is after CSE,
3525 but only if CSE says repeated jump optimization is needed. The
3526 last time is right before the final pass. That time, cross-jumping
3527 and deletion of no-op move instructions are done together with the
3528 optimizations described above.
3530 The source file of this pass is @file{jump.c}.
3532 The option @samp{-dj} causes a debugging dump of the RTL code after
3533 this pass is run for the first time. This dump file's name is made by
3534 appending @samp{.jump} to the input file name.
3536 @cindex register use analysis
3538 Register scan. This pass finds the first and last use of each
3539 register, as a guide for common subexpression elimination. Its source
3540 is in @file{regclass.c}.
3542 @cindex jump threading
3544 Jump threading. This pass detects a condition jump that branches to an
3545 identical or inverse test. Such jumps can be @samp{threaded} through
3546 the second conditional test. The source code for this pass is in
3547 @file{jump.c}. This optimization is only performed if
3548 @samp{-fthread-jumps} is enabled.
3550 @cindex common subexpression elimination
3551 @cindex constant propagation
3553 Common subexpression elimination. This pass also does constant
3554 propagation. Its source file is @file{cse.c}. If constant
3555 propagation causes conditional jumps to become unconditional or to
3556 become no-ops, jump optimization is run again when CSE is finished.
3558 The option @samp{-ds} causes a debugging dump of the RTL code after
3559 this pass. This dump file's name is made by appending @samp{.cse} to
3560 the input file name.
3562 @cindex global common subexpression elimination
3563 @cindex constant propagation
3564 @cindex copy propagation
3566 Global common subexpression elimination. This pass performs GCSE
3567 using Morel-Renvoise Partial Redundancy Elimination, with the exception
3568 that it does not try to move invariants out of loops - that is left to
3569 the loop optimization pass. This pass also performs global constant
3570 and copy propagation.
3572 The source file for this pass is gcse.c.
3574 The option @samp{-dG} causes a debugging dump of the RTL code after
3575 this pass. This dump file's name is made by appending @samp{.gcse} to
3576 the input file name.
3578 @cindex loop optimization
3580 @cindex strength-reduction
3582 Loop optimization. This pass moves constant expressions out of loops,
3583 and optionally does strength-reduction and loop unrolling as well.
3584 Its source files are @file{loop.c} and @file{unroll.c}, plus the header
3585 @file{loop.h} used for communication between them. Loop unrolling uses
3586 some functions in @file{integrate.c} and the header @file{integrate.h}.
3588 The option @samp{-dL} causes a debugging dump of the RTL code after
3589 this pass. This dump file's name is made by appending @samp{.loop} to
3590 the input file name.
3593 If @samp{-frerun-cse-after-loop} was enabled, a second common
3594 subexpression elimination pass is performed after the loop optimization
3595 pass. Jump threading is also done again at this time if it was specified.
3597 The option @samp{-dt} causes a debugging dump of the RTL code after
3598 this pass. This dump file's name is made by appending @samp{.cse2} to
3599 the input file name.
3601 @cindex data flow analysis
3602 @cindex analysis, data flow
3603 @cindex basic blocks
3605 Data flow analysis (@file{flow.c}). This pass divides the program
3606 into basic blocks (and in the process deletes unreachable loops); then
3607 it computes which pseudo-registers are live at each point in the
3608 program, and makes the first instruction that uses a value point at
3609 the instruction that computed the value.
3611 @cindex autoincrement/decrement analysis
3612 This pass also deletes computations whose results are never used, and
3613 combines memory references with add or subtract instructions to make
3614 autoincrement or autodecrement addressing.
3616 The option @samp{-df} causes a debugging dump of the RTL code after
3617 this pass. This dump file's name is made by appending @samp{.flow} to
3618 the input file name. If stupid register allocation is in use, this
3619 dump file reflects the full results of such allocation.
3621 @cindex instruction combination
3623 Instruction combination (@file{combine.c}). This pass attempts to
3624 combine groups of two or three instructions that are related by data
3625 flow into single instructions. It combines the RTL expressions for
3626 the instructions by substitution, simplifies the result using algebra,
3627 and then attempts to match the result against the machine description.
3629 The option @samp{-dc} causes a debugging dump of the RTL code after
3630 this pass. This dump file's name is made by appending @samp{.combine}
3631 to the input file name.
3633 @cindex register movement
3635 Register movement (@file{regmove.c}). This pass looks for cases where
3636 matching constraints would force an instruction to need a reload, and
3637 this reload would be a register to register move. It then attempts
3638 to change the registers used by the instruction to avoid the move
3641 The option @samp{-dN} causes a debugging dump of the RTL code after
3642 this pass. This dump file's name is made by appending @samp{.regmove}
3643 to the input file name.
3645 @cindex instruction scheduling
3646 @cindex scheduling, instruction
3648 Instruction scheduling (@file{sched.c}). This pass looks for
3649 instructions whose output will not be available by the time that it is
3650 used in subsequent instructions. (Memory loads and floating point
3651 instructions often have this behavior on RISC machines). It re-orders
3652 instructions within a basic block to try to separate the definition and
3653 use of items that otherwise would cause pipeline stalls.
3655 Instruction scheduling is performed twice. The first time is immediately
3656 after instruction combination and the second is immediately after reload.
3658 The option @samp{-dS} causes a debugging dump of the RTL code after this
3659 pass is run for the first time. The dump file's name is made by
3660 appending @samp{.sched} to the input file name.
3662 @cindex register class preference pass
3664 Register class preferencing. The RTL code is scanned to find out
3665 which register class is best for each pseudo register. The source
3666 file is @file{regclass.c}.
3668 @cindex register allocation
3669 @cindex local register allocation
3671 Local register allocation (@file{local-alloc.c}). This pass allocates
3672 hard registers to pseudo registers that are used only within one basic
3673 block. Because the basic block is linear, it can use fast and
3674 powerful techniques to do a very good job.
3676 The option @samp{-dl} causes a debugging dump of the RTL code after
3677 this pass. This dump file's name is made by appending @samp{.lreg} to
3678 the input file name.
3680 @cindex global register allocation
3682 Global register allocation (@file{global.c}). This pass
3683 allocates hard registers for the remaining pseudo registers (those
3684 whose life spans are not contained in one basic block).
3688 Reloading. This pass renumbers pseudo registers with the hardware
3689 registers numbers they were allocated. Pseudo registers that did not
3690 get hard registers are replaced with stack slots. Then it finds
3691 instructions that are invalid because a value has failed to end up in
3692 a register, or has ended up in a register of the wrong kind. It fixes
3693 up these instructions by reloading the problematical values
3694 temporarily into registers. Additional instructions are generated to
3697 The reload pass also optionally eliminates the frame pointer and inserts
3698 instructions to save and restore call-clobbered registers around calls.
3700 Source files are @file{reload.c} and @file{reload1.c}, plus the header
3701 @file{reload.h} used for communication between them.
3703 The option @samp{-dg} causes a debugging dump of the RTL code after
3704 this pass. This dump file's name is made by appending @samp{.greg} to
3705 the input file name.
3707 @cindex instruction scheduling
3708 @cindex scheduling, instruction
3710 Instruction scheduling is repeated here to try to avoid pipeline stalls
3711 due to memory loads generated for spilled pseudo registers.
3713 The option @samp{-dR} causes a debugging dump of the RTL code after
3714 this pass. This dump file's name is made by appending @samp{.sched2}
3715 to the input file name.
3717 @cindex cross-jumping
3718 @cindex no-op move instructions
3720 Jump optimization is repeated, this time including cross-jumping
3721 and deletion of no-op move instructions.
3723 The option @samp{-dJ} causes a debugging dump of the RTL code after
3724 this pass. This dump file's name is made by appending @samp{.jump2}
3725 to the input file name.
3727 @cindex delayed branch scheduling
3728 @cindex scheduling, delayed branch
3730 Delayed branch scheduling. This optional pass attempts to find
3731 instructions that can go into the delay slots of other instructions,
3732 usually jumps and calls. The source file name is @file{reorg.c}.
3734 The option @samp{-dd} causes a debugging dump of the RTL code after
3735 this pass. This dump file's name is made by appending @samp{.dbr}
3736 to the input file name.
3738 @cindex branch shortening
3740 Branch shortening. On many RISC machines, branch instructions have a
3741 limited range. Thus, longer sequences of instructions must be used for
3742 long branches. In this pass, the compiler figures out what how far each
3743 instruction will be from each other instruction, and therefore whether
3744 the usual instructions, or the longer sequences, must be used for each
3747 @cindex register-to-stack conversion
3749 Conversion from usage of some hard registers to usage of a register
3750 stack may be done at this point. Currently, this is supported only
3751 for the floating-point registers of the Intel 80387 coprocessor. The
3752 source file name is @file{reg-stack.c}.
3754 The options @samp{-dk} causes a debugging dump of the RTL code after
3755 this pass. This dump file's name is made by appending @samp{.stack}
3756 to the input file name.
3759 @cindex peephole optimization
3761 Final. This pass outputs the assembler code for the function. It is
3762 also responsible for identifying spurious test and compare
3763 instructions. Machine-specific peephole optimizations are performed
3764 at the same time. The function entry and exit sequences are generated
3765 directly as assembler code in this pass; they never exist as RTL.
3767 The source files are @file{final.c} plus @file{insn-output.c}; the
3768 latter is generated automatically from the machine description by the
3769 tool @file{genoutput}. The header file @file{conditions.h} is used
3770 for communication between these files.
3772 @cindex debugging information generation
3774 Debugging information output. This is run after final because it must
3775 output the stack slot offsets for pseudo registers that did not get
3776 hard registers. Source files are @file{dbxout.c} for DBX symbol table
3777 format, @file{sdbout.c} for SDB symbol table format, and
3778 @file{dwarfout.c} for DWARF symbol table format.
3781 Some additional files are used by all or many passes:
3785 Every pass uses @file{machmode.def} and @file{machmode.h} which define
3789 Several passes use @file{real.h}, which defines the default
3790 representation of floating point constants and how to operate on them.
3793 All the passes that work with RTL use the header files @file{rtl.h}
3794 and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
3795 @code{gen*} also use these files to read and work with the machine
3800 Several passes refer to the header file @file{insn-config.h} which
3801 contains a few parameters (C macro definitions) generated
3802 automatically from the machine description RTL by the tool
3805 @cindex instruction recognizer
3807 Several passes use the instruction recognizer, which consists of
3808 @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
3809 and @file{insn-extract.c} that are generated automatically from the
3810 machine description by the tools @file{genrecog} and
3811 @file{genextract}.@refill
3814 Several passes use the header files @file{regs.h} which defines the
3815 information recorded about pseudo register usage, and @file{basic-block.h}
3816 which defines the information recorded about basic blocks.
3819 @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
3820 with a bit for each hard register, and some macros to manipulate it.
3821 This type is just @code{int} if the machine has few enough hard registers;
3822 otherwise it is an array of @code{int} and some of the macros expand
3826 Several passes use instruction attributes. A definition of the
3827 attributes defined for a particular machine is in file
3828 @file{insn-attr.h}, which is generated from the machine description by
3829 the program @file{genattr}. The file @file{insn-attrtab.c} contains
3830 subroutines to obtain the attribute values for insns. It is generated
3831 from the machine description by the program @file{genattrtab}.@refill
3836 @include c-tree.texi
3844 @chapter The Configuration File
3845 @cindex configuration file
3846 @cindex @file{xm-@var{machine}.h}
3848 The configuration file @file{xm-@var{machine}.h} contains macro
3849 definitions that describe the machine and system on which the compiler
3850 is running, unlike the definitions in @file{@var{machine}.h}, which
3851 describe the machine for which the compiler is producing output. Most
3852 of the values in @file{xm-@var{machine}.h} are actually the same on all
3853 machines that GCC runs on, so large parts of all configuration files
3854 are identical. But there are some macros that vary:
3859 Define this macro if the host system is System V.
3863 Define this macro if the host system is VMS.
3865 @findex FATAL_EXIT_CODE
3866 @item FATAL_EXIT_CODE
3867 A C expression for the status code to be returned when the compiler
3868 exits after serious errors. The default is the system-provided macro
3869 @samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
3870 macro. Define this macro only if these defaults are incorrect.
3872 @findex SUCCESS_EXIT_CODE
3873 @item SUCCESS_EXIT_CODE
3874 A C expression for the status code to be returned when the compiler
3875 exits without serious errors. (Warnings are not serious errors.) The
3876 default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
3877 the system doesn't define that macro. Define this macro only if these
3878 defaults are incorrect.
3880 @findex HOST_WORDS_BIG_ENDIAN
3881 @item HOST_WORDS_BIG_ENDIAN
3882 Defined if the host machine stores words of multi-word values in
3883 big-endian order. (GCC does not depend on the host byte ordering
3886 @findex HOST_FLOAT_WORDS_BIG_ENDIAN
3887 @item HOST_FLOAT_WORDS_BIG_ENDIAN
3888 Define this macro to be 1 if the host machine stores @code{DFmode},
3889 @code{XFmode} or @code{TFmode} floating point numbers in memory with the
3890 word containing the sign bit at the lowest address; otherwise, define it
3893 This macro need not be defined if the ordering is the same as for
3894 multi-word integers.
3896 @findex HOST_FLOAT_FORMAT
3897 @item HOST_FLOAT_FORMAT
3898 A numeric code distinguishing the floating point format for the host
3899 machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
3900 alternatives and default.
3902 @findex HOST_BITS_PER_CHAR
3903 @item HOST_BITS_PER_CHAR
3904 A C expression for the number of bits in @code{char} on the host
3907 @findex HOST_BITS_PER_SHORT
3908 @item HOST_BITS_PER_SHORT
3909 A C expression for the number of bits in @code{short} on the host
3912 @findex HOST_BITS_PER_INT
3913 @item HOST_BITS_PER_INT
3914 A C expression for the number of bits in @code{int} on the host
3917 @findex HOST_BITS_PER_LONG
3918 @item HOST_BITS_PER_LONG
3919 A C expression for the number of bits in @code{long} on the host
3922 @findex ONLY_INT_FIELDS
3923 @item ONLY_INT_FIELDS
3924 Define this macro to indicate that the host compiler only supports
3925 @code{int} bit fields, rather than other integral types, including
3926 @code{enum}, as do most C compilers.
3928 @findex OBSTACK_CHUNK_SIZE
3929 @item OBSTACK_CHUNK_SIZE
3930 A C expression for the size of ordinary obstack chunks.
3931 If you don't define this, a usually-reasonable default is used.
3933 @findex OBSTACK_CHUNK_ALLOC
3934 @item OBSTACK_CHUNK_ALLOC
3935 The function used to allocate obstack chunks.
3936 If you don't define this, @code{xmalloc} is used.
3938 @findex OBSTACK_CHUNK_FREE
3939 @item OBSTACK_CHUNK_FREE
3940 The function used to free obstack chunks.
3941 If you don't define this, @code{free} is used.
3943 @findex USE_C_ALLOCA
3945 Define this macro to indicate that the compiler is running with the
3946 @code{alloca} implemented in C. This version of @code{alloca} can be
3947 found in the file @file{alloca.c}; to use it, you must also alter the
3948 @file{Makefile} variable @code{ALLOCA}. (This is done automatically
3949 for the systems on which we know it is needed.)
3951 If you do define this macro, you should probably do it as follows:
3955 #define USE_C_ALLOCA
3957 #define alloca __builtin_alloca
3962 so that when the compiler is compiled with GCC it uses the more
3963 efficient built-in @code{alloca} function.
3965 @item FUNCTION_CONVERSION_BUG
3966 @findex FUNCTION_CONVERSION_BUG
3967 Define this macro to indicate that the host compiler does not properly
3968 handle converting a function value to a pointer-to-function when it is
3969 used in an expression.
3971 @findex MULTIBYTE_CHARS
3972 @item MULTIBYTE_CHARS
3973 Define this macro to enable support for multibyte characters in the
3974 input to GCC. This requires that the host system support the ISO C
3975 library functions for converting multibyte characters to wide
3980 Define this if your system is POSIX.1 compliant.
3982 @findex PATH_SEPARATOR
3983 @item PATH_SEPARATOR
3984 Define this macro to be a C character constant representing the
3985 character used to separate components in paths. The default value is
3988 @findex DIR_SEPARATOR
3990 If your system uses some character other than slash to separate
3991 directory names within a file specification, define this macro to be a C
3992 character constant specifying that character. When GCC displays file
3993 names, the character you specify will be used. GCC will test for
3994 both slash and the character you specify when parsing filenames.
3996 @findex TARGET_OBJECT_SUFFIX
3997 @item TARGET_OBJECT_SUFFIX
3998 Define this macro to be a C string representing the suffix for object
3999 files on your target machine. If you do not define this macro, GCC will
4000 use @samp{.o} as the suffix for object files.
4002 @findex TARGET_EXECUTABLE_SUFFIX
4003 @item TARGET_EXECUTABLE_SUFFIX
4004 Define this macro to be a C string representing the suffix to be
4005 automatically added to executable files on your target machine. If you
4006 do not define this macro, GCC will use the null string as the suffix for
4009 @findex HOST_OBJECT_SUFFIX
4010 @item HOST_OBJECT_SUFFIX
4011 Define this macro to be a C string representing the suffix for object
4012 files on your host machine (@samp{xm-*.h}). If you do not define this
4013 macro, GCC will use @samp{.o} as the suffix for object files.
4015 @findex HOST_EXECUTABLE_SUFFIX
4016 @item HOST_EXECUTABLE_SUFFIX
4017 Define this macro to be a C string representing the suffix for
4018 executable files on your host machine (@samp{xm-*.h}). If you do not
4019 define this macro, GCC will use the null string as the suffix for
4022 @findex HOST_BIT_BUCKET
4023 @item HOST_BIT_BUCKET
4024 The name of a file or file-like object on the host system which acts as
4025 a ``bit bucket''. If you do not define this macro, GCC will use
4026 @samp{/dev/null} as the bit bucket. If the target does not support a
4027 bit bucket, this should be defined to the null string, or some other
4028 illegal filename. If the bit bucket is not writable, GCC will use a
4029 temporary file instead.
4031 @findex COLLECT_EXPORT_LIST
4032 @item COLLECT_EXPORT_LIST
4033 If defined, @code{collect2} will scan the individual object files
4034 specified on its command line and create an export list for the linker.
4035 Define this macro for systems like AIX, where the linker discards
4036 object files that are not referenced from @code{main} and uses export
4039 @findex COLLECT2_HOST_INITIALIZATION
4040 @item COLLECT2_HOST_INITIALIZATION
4041 If defined, a C statement (sans semicolon) that performs host-dependent
4042 initialization when @code{collect2} is being initialized.
4044 @findex GCC_DRIVER_HOST_INITIALIZATION
4045 @item GCC_DRIVER_HOST_INITIALIZATION
4046 If defined, a C statement (sans semicolon) that performs host-dependent
4047 initialization when a compilation driver is being initialized.
4049 @findex UPDATE_PATH_HOST_CANONICALIZE
4050 @item UPDATE_PATH_HOST_CANONICALIZE (@var{path}, @var{key})
4051 If defined, a C statement (sans semicolon) that performs host-dependent
4052 canonicalization when a path used in a compilation driver or preprocessor is
4053 canonicalized. @var{path} is the path to be canonicalized, and @var{key} is
4054 a translation prefix when its value isn't @code{NULL}. If the C statement
4055 does canonicalize @var{path}, the new path should be returned.
4060 In addition, configuration files for system V define @code{bcopy},
4061 @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
4062 as a macro when compiled with GCC, in order to take advantage of the
4063 benefit of GCC's built-in @code{alloca}.
4066 @chapter Makefile Fragments
4067 @cindex makefile fragment
4069 When you configure GCC using the @file{configure} script
4070 (@pxref{Installation}), it will construct the file @file{Makefile} from
4071 the template file @file{Makefile.in}. When it does this, it will
4072 incorporate makefile fragment files from the @file{config} directory,
4073 named @file{t-@var{target}} and @file{x-@var{host}}. If these files do
4074 not exist, it means nothing needs to be added for a given target or
4078 * Target Fragment:: Writing the @file{t-@var{target}} file.
4079 * Host Fragment:: Writing the @file{x-@var{host}} file.
4082 @node Target Fragment
4083 @section The Target Makefile Fragment
4084 @cindex target makefile fragment
4085 @cindex @file{t-@var{target}}
4087 The target makefile fragment, @file{t-@var{target}}, defines special
4088 target dependent variables and targets used in the @file{Makefile}:
4091 @findex LIBGCC2_CFLAGS
4092 @item LIBGCC2_CFLAGS
4093 Compiler flags to use when compiling @file{libgcc2.c}.
4095 @findex LIB2FUNCS_EXTRA
4096 @item LIB2FUNCS_EXTRA
4097 A list of source file names to be compiled or assembled and inserted
4098 into @file{libgcc.a}.
4100 @findex Floating Point Emulation
4101 @item Floating Point Emulation
4102 To have GCC include software floating point libraries in @file{libgcc.a}
4103 define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
4105 # We want fine grained libraries, so use the new code to build the
4106 # floating point emulation libraries.
4111 fp-bit.c: $(srcdir)/config/fp-bit.c
4112 echo '#define FLOAT' > fp-bit.c
4113 cat $(srcdir)/config/fp-bit.c >> fp-bit.c
4115 dp-bit.c: $(srcdir)/config/fp-bit.c
4116 cat $(srcdir)/config/fp-bit.c > dp-bit.c
4119 You may need to provide additional #defines at the beginning of @file{fp-bit.c}
4120 and @file{dp-bit.c} to control target endianness and other options.
4123 @findex CRTSTUFF_T_CFLAGS
4124 @item CRTSTUFF_T_CFLAGS
4125 Special flags used when compiling @file{crtstuff.c}.
4126 @xref{Initialization}.
4128 @findex CRTSTUFF_T_CFLAGS_S
4129 @item CRTSTUFF_T_CFLAGS_S
4130 Special flags used when compiling @file{crtstuff.c} for shared
4131 linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
4132 in @code{EXTRA-PARTS}.
4133 @xref{Initialization}.
4135 @findex MULTILIB_OPTIONS
4136 @item MULTILIB_OPTIONS
4137 For some targets, invoking GCC in different ways produces objects
4138 that can not be linked together. For example, for some targets GCC
4139 produces both big and little endian code. For these targets, you must
4140 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
4141 each set of incompatible options. When GCC invokes the linker, it
4142 arranges to link in the right version of @file{libgcc.a}, based on
4143 the command line options used.
4145 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
4146 special versions of @file{libgcc.a} must be built. Write options that
4147 are mutually incompatible side by side, separated by a slash. Write
4148 options that may be used together separated by a space. The build
4149 procedure will build all combinations of compatible options.
4151 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
4152 msoft-float}, @file{Makefile} will build special versions of
4153 @file{libgcc.a} using the following sets of options: @samp{-m68000},
4154 @samp{-m68020}, @samp{-msoft-float}, @samp{-m68000 -msoft-float}, and
4155 @samp{-m68020 -msoft-float}.
4157 @findex MULTILIB_DIRNAMES
4158 @item MULTILIB_DIRNAMES
4159 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
4160 directory names that should be used to hold the various libraries.
4161 Write one element in @code{MULTILIB_DIRNAMES} for each element in
4162 @code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
4163 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
4166 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
4167 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
4168 @samp{m68000 m68020 msoft-float}. You may specify a different value if
4169 you desire a different set of directory names.
4171 @findex MULTILIB_MATCHES
4172 @item MULTILIB_MATCHES
4173 Sometimes the same option may be written in two different ways. If an
4174 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
4175 any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
4176 items of the form @samp{option=option} to describe all relevant
4177 synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
4179 @findex MULTILIB_EXCEPTIONS
4180 @item MULTILIB_EXCEPTIONS
4181 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
4182 specified, there are combinations that should not be built. In that
4183 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
4184 in shell case syntax that should not be built.
4186 For example, in the PowerPC embedded ABI support, it is not desirable
4187 to build libraries compiled with the @samp{-mcall-aix} option
4188 and either of the @samp{-fleading-underscore} or @samp{-mlittle} options
4189 at the same time. Therefore @code{MULTILIB_EXCEPTIONS} is set to
4190 @code{*mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*}.
4192 @findex MULTILIB_EXTRA_OPTS
4193 @item MULTILIB_EXTRA_OPTS
4194 Sometimes it is desirable that when building multiple versions of
4195 @file{libgcc.a} certain options should always be passed on to the
4196 compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
4197 of options to be used for all builds.
4201 @section The Host Makefile Fragment
4202 @cindex host makefile fragment
4203 @cindex @file{x-@var{host}}
4205 The host makefile fragment, @file{x-@var{host}}, defines special host
4206 dependent variables and targets used in the @file{Makefile}:
4211 The compiler to use when building the first stage.
4215 The install program to use.
4220 @unnumbered Funding Free Software
4222 If you want to have more free software a few years from now, it makes
4223 sense for you to help encourage people to contribute funds for its
4224 development. The most effective approach known is to encourage
4225 commercial redistributors to donate.
4227 Users of free software systems can boost the pace of development by
4228 encouraging for-a-fee distributors to donate part of their selling price
4229 to free software developers---the Free Software Foundation, and others.
4231 The way to convince distributors to do this is to demand it and expect
4232 it from them. So when you compare distributors, judge them partly by
4233 how much they give to free software development. Show distributors
4234 they must compete to be the one who gives the most.
4236 To make this approach work, you must insist on numbers that you can
4237 compare, such as, ``We will donate ten dollars to the Frobnitz project
4238 for each disk sold.'' Don't be satisfied with a vague promise, such as
4239 ``A portion of the profits are donated,'' since it doesn't give a basis
4242 Even a precise fraction ``of the profits from this disk'' is not very
4243 meaningful, since creative accounting and unrelated business decisions
4244 can greatly alter what fraction of the sales price counts as profit.
4245 If the price you pay is $50, ten percent of the profit is probably
4246 less than a dollar; it might be a few cents, or nothing at all.
4248 Some redistributors do development work themselves. This is useful too;
4249 but to keep everyone honest, you need to inquire how much they do, and
4250 what kind. Some kinds of development make much more long-term
4251 difference than others. For example, maintaining a separate version of
4252 a program contributes very little; maintaining the standard version of a
4253 program for the whole community contributes much. Easy new ports
4254 contribute little, since someone else would surely do them; difficult
4255 ports such as adding a new CPU to the GNU Compiler Collection contribute more;
4256 major new features or packages contribute the most.
4258 By establishing the idea that supporting further development is ``the
4259 proper thing to do'' when distributing free software for a fee, we can
4260 assure a steady flow of resources into making more free software.
4263 Copyright (C) 1994 Free Software Foundation, Inc.
4264 Verbatim copying and redistribution of this section is permitted
4265 without royalty; alteration is not permitted.
4269 @unnumbered Linux and the GNU Project
4271 Many computer users run a modified version of the GNU system every
4272 day, without realizing it. Through a peculiar turn of events, the
4273 version of GNU which is widely used today is more often known as
4274 ``Linux'', and many users are not aware of the extent of its
4275 connection with the GNU Project.
4277 There really is a Linux; it is a kernel, and these people are using
4278 it. But you can't use a kernel by itself; a kernel is useful only as
4279 part of a whole system. The system in which Linux is typically used
4280 is a modified variant of the GNU system---in other words, a Linux-based
4283 Many users are not fully aware of the distinction between the kernel,
4284 which is Linux, and the whole system, which they also call ``Linux''.
4285 The ambiguous use of the name doesn't promote understanding.
4287 Programmers generally know that Linux is a kernel. But since they
4288 have generally heard the whole system called ``Linux'' as well, they
4289 often envisage a history which fits that name. For example, many
4290 believe that once Linus Torvalds finished writing the kernel, his
4291 friends looked around for other free software, and for no particular
4292 reason most everything necessary to make a Unix-like system was
4295 What they found was no accident---it was the GNU system. The available
4296 free software added up to a complete system because the GNU Project
4297 had been working since 1984 to make one. The GNU Manifesto
4298 had set forth the goal of developing a free Unix-like system, called
4299 GNU. By the time Linux was written, the system was almost finished.
4301 Most free software projects have the goal of developing a particular
4302 program for a particular job. For example, Linus Torvalds set out to
4303 write a Unix-like kernel (Linux); Donald Knuth set out to write a text
4304 formatter (TeX); Bob Scheifler set out to develop a window system (X
4305 Windows). It's natural to measure the contribution of this kind of
4306 project by specific programs that came from the project.
4308 If we tried to measure the GNU Project's contribution in this way,
4309 what would we conclude? One CD-ROM vendor found that in their ``Linux
4310 distribution'', GNU software was the largest single contingent, around
4311 28% of the total source code, and this included some of the essential
4312 major components without which there could be no system. Linux itself
4313 was about 3%. So if you were going to pick a name for the system
4314 based on who wrote the programs in the system, the most appropriate
4315 single choice would be ``GNU''.
4317 But we don't think that is the right way to consider the question.
4318 The GNU Project was not, is not, a project to develop specific
4319 software packages. It was not a project to develop a C compiler,
4320 although we did. It was not a project to develop a text editor,
4321 although we developed one. The GNU Project's aim was to develop
4322 @emph{a complete free Unix-like system}.
4324 Many people have made major contributions to the free software in the
4325 system, and they all deserve credit. But the reason it is @emph{a
4326 system}---and not just a collection of useful programs---is because the
4327 GNU Project set out to make it one. We wrote the programs that were
4328 needed to make a @emph{complete} free system. We wrote essential but
4329 unexciting major components, such as the assembler and linker, because
4330 you can't have a system without them. A complete system needs more
4331 than just programming tools, so we wrote other components as well,
4332 such as the Bourne Again SHell, the PostScript interpreter
4333 Ghostscript, and the GNU C library.
4335 By the early 90s we had put together the whole system aside from the
4336 kernel (and we were also working on a kernel, the GNU Hurd, which runs
4337 on top of Mach). Developing this kernel has been a lot harder than we
4338 expected, and we are still working on finishing it.
4340 Fortunately, you don't have to wait for it, because Linux is working
4341 now. When Linus Torvalds wrote Linux, he filled the last major gap.
4342 People could then put Linux together with the GNU system to make a
4343 complete free system: a Linux-based GNU system (or GNU/Linux system,
4346 Putting them together sounds simple, but it was not a trivial job.
4347 The GNU C library (called glibc for short) needed substantial changes.
4348 Integrating a complete system as a distribution that would work ``out
4349 of the box'' was a big job, too. It required addressing the issue of
4350 how to install and boot the system---a problem we had not tackled,
4351 because we hadn't yet reached that point. The people who developed
4352 the various system distributions made a substantial contribution.
4354 The GNU Project supports GNU/Linux systems as well as @emph{the}
4355 GNU system---even with funds. We funded the rewriting of the
4356 Linux-related extensions to the GNU C library, so that now they are
4357 well integrated, and the newest GNU/Linux systems use the current
4358 library release with no changes. We also funded an early stage of the
4359 development of Debian GNU/Linux.
4361 We use Linux-based GNU systems today for most of our work, and we hope
4362 you use them too. But please don't confuse the public by using the
4363 name ``Linux'' ambiguously. Linux is the kernel, one of the essential
4364 major components of the system. The system as a whole is more or less
4368 @unnumbered GNU GENERAL PUBLIC LICENSE
4369 @center Version 2, June 1991
4372 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
4373 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
4375 Everyone is permitted to copy and distribute verbatim copies
4376 of this license document, but changing it is not allowed.
4379 @unnumberedsec Preamble
4381 The licenses for most software are designed to take away your
4382 freedom to share and change it. By contrast, the GNU General Public
4383 License is intended to guarantee your freedom to share and change free
4384 software---to make sure the software is free for all its users. This
4385 General Public License applies to most of the Free Software
4386 Foundation's software and to any other program whose authors commit to
4387 using it. (Some other Free Software Foundation software is covered by
4388 the GNU Library General Public License instead.) You can apply it to
4391 When we speak of free software, we are referring to freedom, not
4392 price. Our General Public Licenses are designed to make sure that you
4393 have the freedom to distribute copies of free software (and charge for
4394 this service if you wish), that you receive source code or can get it
4395 if you want it, that you can change the software or use pieces of it
4396 in new free programs; and that you know you can do these things.
4398 To protect your rights, we need to make restrictions that forbid
4399 anyone to deny you these rights or to ask you to surrender the rights.
4400 These restrictions translate to certain responsibilities for you if you
4401 distribute copies of the software, or if you modify it.
4403 For example, if you distribute copies of such a program, whether
4404 gratis or for a fee, you must give the recipients all the rights that
4405 you have. You must make sure that they, too, receive or can get the
4406 source code. And you must show them these terms so they know their
4409 We protect your rights with two steps: (1) copyright the software, and
4410 (2) offer you this license which gives you legal permission to copy,
4411 distribute and/or modify the software.
4413 Also, for each author's protection and ours, we want to make certain
4414 that everyone understands that there is no warranty for this free
4415 software. If the software is modified by someone else and passed on, we
4416 want its recipients to know that what they have is not the original, so
4417 that any problems introduced by others will not reflect on the original
4418 authors' reputations.
4420 Finally, any free program is threatened constantly by software
4421 patents. We wish to avoid the danger that redistributors of a free
4422 program will individually obtain patent licenses, in effect making the
4423 program proprietary. To prevent this, we have made it clear that any
4424 patent must be licensed for everyone's free use or not licensed at all.
4426 The precise terms and conditions for copying, distribution and
4427 modification follow.
4430 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4433 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
4438 This License applies to any program or other work which contains
4439 a notice placed by the copyright holder saying it may be distributed
4440 under the terms of this General Public License. The ``Program'', below,
4441 refers to any such program or work, and a ``work based on the Program''
4442 means either the Program or any derivative work under copyright law:
4443 that is to say, a work containing the Program or a portion of it,
4444 either verbatim or with modifications and/or translated into another
4445 language. (Hereinafter, translation is included without limitation in
4446 the term ``modification''.) Each licensee is addressed as ``you''.
4448 Activities other than copying, distribution and modification are not
4449 covered by this License; they are outside its scope. The act of
4450 running the Program is not restricted, and the output from the Program
4451 is covered only if its contents constitute a work based on the
4452 Program (independent of having been made by running the Program).
4453 Whether that is true depends on what the Program does.
4456 You may copy and distribute verbatim copies of the Program's
4457 source code as you receive it, in any medium, provided that you
4458 conspicuously and appropriately publish on each copy an appropriate
4459 copyright notice and disclaimer of warranty; keep intact all the
4460 notices that refer to this License and to the absence of any warranty;
4461 and give any other recipients of the Program a copy of this License
4462 along with the Program.
4464 You may charge a fee for the physical act of transferring a copy, and
4465 you may at your option offer warranty protection in exchange for a fee.
4468 You may modify your copy or copies of the Program or any portion
4469 of it, thus forming a work based on the Program, and copy and
4470 distribute such modifications or work under the terms of Section 1
4471 above, provided that you also meet all of these conditions:
4475 You must cause the modified files to carry prominent notices
4476 stating that you changed the files and the date of any change.
4479 You must cause any work that you distribute or publish, that in
4480 whole or in part contains or is derived from the Program or any
4481 part thereof, to be licensed as a whole at no charge to all third
4482 parties under the terms of this License.
4485 If the modified program normally reads commands interactively
4486 when run, you must cause it, when started running for such
4487 interactive use in the most ordinary way, to print or display an
4488 announcement including an appropriate copyright notice and a
4489 notice that there is no warranty (or else, saying that you provide
4490 a warranty) and that users may redistribute the program under
4491 these conditions, and telling the user how to view a copy of this
4492 License. (Exception: if the Program itself is interactive but
4493 does not normally print such an announcement, your work based on
4494 the Program is not required to print an announcement.)
4497 These requirements apply to the modified work as a whole. If
4498 identifiable sections of that work are not derived from the Program,
4499 and can be reasonably considered independent and separate works in
4500 themselves, then this License, and its terms, do not apply to those
4501 sections when you distribute them as separate works. But when you
4502 distribute the same sections as part of a whole which is a work based
4503 on the Program, the distribution of the whole must be on the terms of
4504 this License, whose permissions for other licensees extend to the
4505 entire whole, and thus to each and every part regardless of who wrote it.
4507 Thus, it is not the intent of this section to claim rights or contest
4508 your rights to work written entirely by you; rather, the intent is to
4509 exercise the right to control the distribution of derivative or
4510 collective works based on the Program.
4512 In addition, mere aggregation of another work not based on the Program
4513 with the Program (or with a work based on the Program) on a volume of
4514 a storage or distribution medium does not bring the other work under
4515 the scope of this License.
4518 You may copy and distribute the Program (or a work based on it,
4519 under Section 2) in object code or executable form under the terms of
4520 Sections 1 and 2 above provided that you also do one of the following:
4524 Accompany it with the complete corresponding machine-readable
4525 source code, which must be distributed under the terms of Sections
4526 1 and 2 above on a medium customarily used for software interchange; or,
4529 Accompany it with a written offer, valid for at least three
4530 years, to give any third party, for a charge no more than your
4531 cost of physically performing source distribution, a complete
4532 machine-readable copy of the corresponding source code, to be
4533 distributed under the terms of Sections 1 and 2 above on a medium
4534 customarily used for software interchange; or,
4537 Accompany it with the information you received as to the offer
4538 to distribute corresponding source code. (This alternative is
4539 allowed only for noncommercial distribution and only if you
4540 received the program in object code or executable form with such
4541 an offer, in accord with Subsection b above.)
4544 The source code for a work means the preferred form of the work for
4545 making modifications to it. For an executable work, complete source
4546 code means all the source code for all modules it contains, plus any
4547 associated interface definition files, plus the scripts used to
4548 control compilation and installation of the executable. However, as a
4549 special exception, the source code distributed need not include
4550 anything that is normally distributed (in either source or binary
4551 form) with the major components (compiler, kernel, and so on) of the
4552 operating system on which the executable runs, unless that component
4553 itself accompanies the executable.
4555 If distribution of executable or object code is made by offering
4556 access to copy from a designated place, then offering equivalent
4557 access to copy the source code from the same place counts as
4558 distribution of the source code, even though third parties are not
4559 compelled to copy the source along with the object code.
4562 You may not copy, modify, sublicense, or distribute the Program
4563 except as expressly provided under this License. Any attempt
4564 otherwise to copy, modify, sublicense or distribute the Program is
4565 void, and will automatically terminate your rights under this License.
4566 However, parties who have received copies, or rights, from you under
4567 this License will not have their licenses terminated so long as such
4568 parties remain in full compliance.
4571 You are not required to accept this License, since you have not
4572 signed it. However, nothing else grants you permission to modify or
4573 distribute the Program or its derivative works. These actions are
4574 prohibited by law if you do not accept this License. Therefore, by
4575 modifying or distributing the Program (or any work based on the
4576 Program), you indicate your acceptance of this License to do so, and
4577 all its terms and conditions for copying, distributing or modifying
4578 the Program or works based on it.
4581 Each time you redistribute the Program (or any work based on the
4582 Program), the recipient automatically receives a license from the
4583 original licensor to copy, distribute or modify the Program subject to
4584 these terms and conditions. You may not impose any further
4585 restrictions on the recipients' exercise of the rights granted herein.
4586 You are not responsible for enforcing compliance by third parties to
4590 If, as a consequence of a court judgment or allegation of patent
4591 infringement or for any other reason (not limited to patent issues),
4592 conditions are imposed on you (whether by court order, agreement or
4593 otherwise) that contradict the conditions of this License, they do not
4594 excuse you from the conditions of this License. If you cannot
4595 distribute so as to satisfy simultaneously your obligations under this
4596 License and any other pertinent obligations, then as a consequence you
4597 may not distribute the Program at all. For example, if a patent
4598 license would not permit royalty-free redistribution of the Program by
4599 all those who receive copies directly or indirectly through you, then
4600 the only way you could satisfy both it and this License would be to
4601 refrain entirely from distribution of the Program.
4603 If any portion of this section is held invalid or unenforceable under
4604 any particular circumstance, the balance of the section is intended to
4605 apply and the section as a whole is intended to apply in other
4608 It is not the purpose of this section to induce you to infringe any
4609 patents or other property right claims or to contest validity of any
4610 such claims; this section has the sole purpose of protecting the
4611 integrity of the free software distribution system, which is
4612 implemented by public license practices. Many people have made
4613 generous contributions to the wide range of software distributed
4614 through that system in reliance on consistent application of that
4615 system; it is up to the author/donor to decide if he or she is willing
4616 to distribute software through any other system and a licensee cannot
4619 This section is intended to make thoroughly clear what is believed to
4620 be a consequence of the rest of this License.
4623 If the distribution and/or use of the Program is restricted in
4624 certain countries either by patents or by copyrighted interfaces, the
4625 original copyright holder who places the Program under this License
4626 may add an explicit geographical distribution limitation excluding
4627 those countries, so that distribution is permitted only in or among
4628 countries not thus excluded. In such case, this License incorporates
4629 the limitation as if written in the body of this License.
4632 The Free Software Foundation may publish revised and/or new versions
4633 of the General Public License from time to time. Such new versions will
4634 be similar in spirit to the present version, but may differ in detail to
4635 address new problems or concerns.
4637 Each version is given a distinguishing version number. If the Program
4638 specifies a version number of this License which applies to it and ``any
4639 later version'', you have the option of following the terms and conditions
4640 either of that version or of any later version published by the Free
4641 Software Foundation. If the Program does not specify a version number of
4642 this License, you may choose any version ever published by the Free Software
4646 If you wish to incorporate parts of the Program into other free
4647 programs whose distribution conditions are different, write to the author
4648 to ask for permission. For software which is copyrighted by the Free
4649 Software Foundation, write to the Free Software Foundation; we sometimes
4650 make exceptions for this. Our decision will be guided by the two goals
4651 of preserving the free status of all derivatives of our free software and
4652 of promoting the sharing and reuse of software generally.
4655 @heading NO WARRANTY
4662 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
4663 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
4664 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
4665 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
4666 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
4667 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
4668 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
4669 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
4670 REPAIR OR CORRECTION.
4673 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
4674 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
4675 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
4676 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
4677 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
4678 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
4679 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
4680 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
4681 POSSIBILITY OF SUCH DAMAGES.
4685 @heading END OF TERMS AND CONDITIONS
4688 @center END OF TERMS AND CONDITIONS
4692 @unnumberedsec How to Apply These Terms to Your New Programs
4694 If you develop a new program, and you want it to be of the greatest
4695 possible use to the public, the best way to achieve this is to make it
4696 free software which everyone can redistribute and change under these terms.
4698 To do so, attach the following notices to the program. It is safest
4699 to attach them to the start of each source file to most effectively
4700 convey the exclusion of warranty; and each file should have at least
4701 the ``copyright'' line and a pointer to where the full notice is found.
4704 @var{one line to give the program's name and a brief idea of what it does.}
4705 Copyright (C) @var{yyyy} @var{name of author}
4707 This program is free software; you can redistribute it and/or modify
4708 it under the terms of the GNU General Public License as published by
4709 the Free Software Foundation; either version 2 of the License, or
4710 (at your option) any later version.
4712 This program is distributed in the hope that it will be useful,
4713 but WITHOUT ANY WARRANTY; without even the implied warranty of
4714 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4715 GNU General Public License for more details.
4717 You should have received a copy of the GNU General Public License
4718 along with this program; if not, write to the Free Software
4719 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
4722 Also add information on how to contact you by electronic and paper mail.
4724 If the program is interactive, make it output a short notice like this
4725 when it starts in an interactive mode:
4728 Gnomovision version 69, Copyright (C) @var{yyyy} @var{name of author}
4729 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
4731 This is free software, and you are welcome to redistribute it
4732 under certain conditions; type `show c' for details.
4735 The hypothetical commands @samp{show w} and @samp{show c} should show
4736 the appropriate parts of the General Public License. Of course, the
4737 commands you use may be called something other than @samp{show w} and
4738 @samp{show c}; they could even be mouse-clicks or menu items---whatever
4741 You should also get your employer (if you work as a programmer) or your
4742 school, if any, to sign a ``copyright disclaimer'' for the program, if
4743 necessary. Here is a sample; alter the names:
4746 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
4747 `Gnomovision' (which makes passes at compilers) written by James Hacker.
4749 @var{signature of Ty Coon}, 1 April 1989
4750 Ty Coon, President of Vice
4753 This General Public License does not permit incorporating your program into
4754 proprietary programs. If your program is a subroutine library, you may
4755 consider it more useful to permit linking proprietary applications with the
4756 library. If this is what you want to do, use the GNU Library General
4757 Public License instead of this License.
4759 @c ---------------------------------------------------------------------
4761 @c ---------------------------------------------------------------------
4766 @unnumbered Contributors to GCC
4767 @cindex contributors
4768 @include contrib.texi
4770 @c ---------------------------------------------------------------------
4772 @c ---------------------------------------------------------------------
4779 @c ---------------------------------------------------------------------
4781 @c ---------------------------------------------------------------------