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
37 @c -overfulls. do a search for "mew" in the files, and you will see
38 @c overfulls that i noted but could not deal with.
39 @c -have to add text: beginning of chapter 8
42 @c anything else? --mew 10feb93
44 @c For consistency, use the following:
45 @c - "32-bit" rather than "32 bit" as an adjective.
46 @c - "back end" as a noun, "back-end" as an adjective.
47 @c - "bit-field" not "bitfield" or "bit field" (following the C and C++
49 @c - "built-in" as an adjective ("built-in function"), or sometimes
50 @c "built in", not "builtin" (which isn't a word).
51 @c - "front end" as a noun, "front-end" as an adjective.
52 @c - "GCC" for the GNU Compiler Collection, both generally
53 @c and as the GNU C Compiler in the context of compiling C;
54 @c "G++" for the C++ compiler; "gcc" and "g++" (lowercase),
55 @c marked up with @command, for the commands for compilation when the
56 @c emphasis is on those; "GNU C" and "GNU C++" for language dialects;
57 @c and try to avoid the older term "GNU CC".
58 @c - "@code{NULL}" rather than "NULL".
59 @c - "Objective-C" rather than "Objective C".
61 @macro gcctabopt{body}
64 @macro gccoptlist{body}
69 @c Makeinfo handles the above macro OK, TeX needs manual line breaks;
70 @c they get lost at some point in handling the macro. But if @macro is
71 @c used here rather than @alias, it produces double line breaks.
82 @settitle Using and Porting the GNU Compiler Collection (GCC)
85 @c seems reasonable to assume at least one of INTERNALS or USING is set...
87 @settitle Using the GNU Compiler Collection
90 @settitle Porting the GNU Compiler Collection
93 @c Create a separate index for command line options.
95 @c Merge the standard indexes into a single one.
104 @c Use with @@smallbook.
106 @c Cause even numbered pages to be printed on the left hand side of
107 @c the page and odd numbered pages to be printed on the right hand
108 @c side of the page. Using this, you can print on both sides of a
109 @c sheet of paper and have the text on the same part of the sheet.
111 @c The text on right hand pages is pushed towards the right hand
112 @c margin and the text on left hand pages is pushed toward the left
114 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
117 @c \global\bindingoffset=0.75in
118 @c \global\normaloffset =0.75in
121 @c Change the font used for @def... commands, since the default
122 @c proportional one used is bad for names starting __.
124 \global\setfont\defbf\ttbshape{10}{\magstep1}
128 @dircategory Programming
130 * gcc: (gcc). The GNU Compiler Collection.
134 This file documents the use and the internals of the GNU compiler.
138 This file documents the internals of the GNU compiler.
141 This file documents the use of the GNU compiler.
144 Published by the Free Software Foundation@*
145 59 Temple Place - Suite 330@*
146 Boston, MA 02111-1307 USA
148 @c When you update the list of years below, search for copyright{} and
149 @c update the other copy too.
150 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
151 1999, 2000, 2001 Free Software Foundation, Inc.
153 Permission is granted to copy, distribute and/or modify this document
154 under the terms of the GNU Free Documentation License, Version 1.1 or
155 any later version published by the Free Software Foundation; with the
156 Invariant Sections being ``GNU General Public License'' and ``Funding
157 Free Software'', the Front-Cover texts being (a) (see below), and with
158 the Back-Cover Texts being (b) (see below). A copy of the license is
159 included in the section entitled ``GNU Free Documentation License''.
161 (a) The FSF's Front-Cover Text is:
165 (b) The FSF's Back-Cover Text is:
167 You have freedom to copy and modify this GNU Manual, like GNU
168 software. Copies published by the Free Software Foundation raise
169 funds for GNU development.
172 @setchapternewpage odd
177 @center @titlefont{Using and Porting the GNU Compiler Collection}
182 @title Using the GNU Compiler Collection
185 @title Porting the GNU Compiler Collection
188 @center Richard M. Stallman
190 @center Last updated 22 June 2001
192 @c The version number appears five times more in this file.
196 @vskip 0pt plus 1filll
197 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
198 1999, 2000, 2001 Free Software Foundation, Inc.
200 For GCC Version 3.1@*
202 Published by the Free Software Foundation @*
203 59 Temple Place---Suite 330@*
204 Boston, MA 02111-1307, USA@*
205 Last printed April, 1998.@*
206 Printed copies are available for $50 each.@*
209 Permission is granted to copy, distribute and/or modify this document
210 under the terms of the GNU Free Documentation License, Version 1.1 or
211 any later version published by the Free Software Foundation; with the
212 Invariant Sections being ``GNU General Public License'', the Front-Cover
213 texts being (a) (see below), and with the Back-Cover Texts being (b)
214 (see below). A copy of the license is included in the section entitled
215 ``GNU Free Documentation License''.
217 (a) The FSF's Front-Cover Text is:
221 (b) The FSF's Back-Cover Text is:
223 You have freedom to copy and modify this GNU Manual, like GNU
224 software. Copies published by the Free Software Foundation raise
225 funds for GNU development.
231 @node Top, G++ and GCC,, (DIR)
237 This manual documents how to run, install and port the GNU
238 compiler, as well as its new features and incompatibilities, and how to
239 report bugs. It corresponds to GCC version 3.1.
244 This manual documents how to run and install the GNU compiler,
245 as well as its new features and incompatibilities, and how to report
246 bugs. It corresponds to GCC version 3.1.
249 This manual documents how to port the GNU compiler,
250 as well as its new features and incompatibilities, and how to report
251 bugs. It corresponds to GCC version 3.1.
256 * G++ and GCC:: You can compile C or C++ programs.
257 * Standards:: Language standards supported by GCC.
258 * Invoking GCC:: Command options supported by @samp{gcc}.
259 * Installation:: How to configure, compile and install GCC.
260 * C Implementation:: How GCC implements the ISO C specification.
261 * C Extensions:: GNU extensions to the C language family.
262 * C++ Extensions:: GNU extensions to the C++ language.
263 * Objective-C:: GNU Objective-C runtime features.
264 * Gcov:: gcov: a GCC test coverage program.
265 * Trouble:: If you have trouble installing GCC.
266 * Bugs:: How, why and where to report bugs.
267 * Service:: How to find suppliers of support for GCC.
268 * Contributing:: How to contribute to testing and developing GCC.
269 * VMS:: Using GCC on VMS.
270 * Makefile:: Additional Makefile and configure information.
273 * Portability:: Goals of GCC's portability features.
274 * Interface:: Function-call interface of GCC output.
275 * Passes:: Order of passes, what they do, and what each file is for.
276 * Trees:: The source representation used by the C and C++ front ends.
277 * RTL:: The intermediate representation that most passes work on.
278 * Machine Desc:: How to write machine description instruction patterns.
279 * Target Macros:: How to write the machine description C macros and functions.
280 * Config:: Writing the @file{xm-@var{machine}.h} file.
281 * Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
284 * Funding:: How to help assure funding for free software.
285 * GNU/Linux:: Linux and the GNU Project
287 * Copying:: GNU General Public License says
288 how you can copy and share GCC.
289 * GNU Free Documentation License:: How you can copy and share this manual.
290 * Contributors:: People who have contributed to GCC.
292 * Option Index:: Index to command line options.
293 * Index:: Index of concepts and symbol names.
298 @chapter Compile C, C++, Objective-C, Fortran, Java or CHILL
304 Several versions of the compiler (C, C++, Objective-C, Fortran, Java
305 and CHILL) are integrated; this is why we use the name
306 ``GNU Compiler Collection''. GCC can compile programs written in any of these
307 languages. The Fortran, CHILL, and Java compilers are described in
311 ``GCC'' is a common shorthand term for the GNU Compiler Collection. This is both
312 the most general name for the compiler, and the name used when the
313 emphasis is on compiling C programs (as the abbreviation formerly
314 stood for ``GNU C Compiler'').
318 When referring to C++ compilation, it is usual to call the compiler
319 ``G++''. Since there is only one compiler, it is also accurate to call
320 it ``GCC'' no matter what the language context; however, the term
321 ``G++'' is more useful when the emphasis is on compiling C++ programs.
323 We use the name ``GCC'' to refer to the compilation system as a
324 whole, and more specifically to the language-independent part of the
325 compiler. For example, we refer to the optimization options as
326 affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
328 Front ends for other languages, such as Ada 95 and Pascal exist but
329 have not yet been integrated into GCC@. These front ends, like that for C++,
330 are built in subdirectories of GCC and link to it. The result is an
331 integrated compiler that can compile programs written in C, C++,
332 Objective-C, or any of the languages for which you have installed front
335 In this manual, we only discuss the options for the C, Objective-C, and
336 C++ compilers and those of the GCC core. Consult the documentation
337 of the other front ends for the options to use when compiling programs
338 written in other languages.
340 @cindex compiler compared to C++ preprocessor
341 @cindex intermediate C version, nonexistent
342 @cindex C intermediate output, nonexistent
343 G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object
344 code directly from your C++ program source. There is no intermediate C
345 version of the program. (By contrast, for example, some other
346 implementations use a program that generates a C program from your C++
347 source.) Avoiding an intermediate C representation of the program means
348 that you get better object code, and better debugging information. The
349 GNU debugger, GDB, works with this information in the object code to
350 give you comprehensive C++ source-level editing capabilities
351 (@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
353 @c FIXME! Someone who knows something about Objective-C ought to put in
354 @c a paragraph or two about it here, and move the index entry down when
355 @c there is more to point to than the general mention in the 1st par.
358 @chapter Language Standards Supported by GCC
361 @cindex ANSI C standard
365 @cindex ANSI X3.159-1989
367 @cindex ISO C standard
382 @cindex Technical Corrigenda
384 @cindex Technical Corrigendum 1
386 @cindex Technical Corrigendum 2
388 @cindex freestanding implementation
389 @cindex freestanding environment
390 @cindex hosted implementation
391 @cindex hosted environment
392 @findex __STDC_HOSTED__
394 For each language compiled by GCC for which there is a standard, GCC
395 attempts to follow one or more versions of that standard, possibly
396 with some exceptions, and possibly with some extensions.
398 GCC supports three versions of the C standard, although support for
399 the most recent version is not yet complete.
404 @opindex pedantic-errors
405 The original ANSI C standard (X3.159-1989) was ratified in 1989 and
406 published in 1990. This standard was ratified as an ISO standard
407 (ISO/IEC 9899:1990) later in 1990. There were no technical
408 differences between these publications, although the sections of the
409 ANSI standard were renumbered and became clauses in the ISO standard.
410 This standard, in both its forms, is commonly known as @dfn{C89}, or
411 occasionally as @dfn{C90}, from the dates of ratification. The ANSI
412 standard, but not the ISO standard, also came with a Rationale
413 document. To select this standard in GCC, use one of the options
414 @option{-ansi}, @option{-std=c89} or @option{-std=iso9899:1990}; to obtain
415 all the diagnostics required by the standard, you should also specify
416 @option{-pedantic} (or @option{-pedantic-errors} if you want them to be
417 errors rather than warnings). @xref{C Dialect Options,,Options
418 Controlling C Dialect}.
420 Errors in the 1990 ISO C standard were corrected in two Technical
421 Corrigenda published in 1994 and 1996. GCC does not support the
424 An amendment to the 1990 standard was published in 1995. This
425 amendment added digraphs and @code{__STDC_VERSION__} to the language,
426 but otherwise concerned the library. This amendment is commonly known
427 as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
428 @dfn{C95}. To select this standard in GCC, use the option
429 @option{-std=iso9899:199409} (with, as for other standard versions,
430 @option{-pedantic} to receive all required diagnostics).
432 A new edition of the ISO C standard was published in 1999 as ISO/IEC
433 9899:1999, and is commonly known as @dfn{C99}. GCC has incomplete
434 support for this standard version; see
435 @uref{http://gcc.gnu.org/c99status.html} for details. To select this
436 standard, use @option{-std=c99} or @option{-std=iso9899:1999}. (While in
437 development, drafts of this standard version were referred to as
441 GCC also has some limited support for traditional (pre-ISO) C with the
442 @option{-traditional} option. This support may be of use for compiling
443 some very old programs that have not been updated to ISO C, but should
444 not be used for new programs. It will not work with some modern C
445 libraries such as the GNU C library.
447 By default, GCC provides some extensions to the C language that on
448 rare occasions conflict with the C standard. @xref{C
449 Extensions,,Extensions to the C Language Family}. Use of the
450 @option{-std} options listed above will disable these extensions where
451 they conflict with the C standard version selected. You may also
452 select an extended version of the C language explicitly with
453 @option{-std=gnu89} (for C89 with GNU extensions) or @option{-std=gnu99}
454 (for C99 with GNU extensions). The default, if no C language dialect
455 options are given, is @option{-std=gnu89}; this will change to
456 @option{-std=gnu99} in some future release when the C99 support is
457 complete. Some features that are part of the C99 standard are
458 accepted as extensions in C89 mode.
460 The ISO C standard defines (in clause 4) two classes of conforming
461 implementation. A @dfn{conforming hosted implementation} supports the
462 whole standard including all the library facilities; a @dfn{conforming
463 freestanding implementation} is only required to provide certain
464 library facilities: those in @code{<float.h>}, @code{<limits.h>},
465 @code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
466 @code{<iso646.h>}; and in C99, also those in @code{<stdbool.h>} and
467 @code{<stdint.h>}. In addition, complex types, added in C99, are not
468 required for freestanding implementations. The standard also defines
469 two environments for programs, a @dfn{freestanding environment},
470 required of all implementations and which may not have library
471 facilities beyond those required of freestanding implementations,
472 where the handling of program startup and termination are
473 implementation-defined, and a @dfn{hosted environment}, which is not
474 required, in which all the library facilities are provided and startup
475 is through a function @code{int main (void)} or @code{int main (int,
476 char *[])}. An OS kernel would be a freestanding environment; a
477 program using the facilities of an operating system would normally be
478 in a hosted implementation.
480 @opindex ffreestanding
481 GCC aims towards being usable as a conforming freestanding
482 implementation, or as the compiler for a conforming hosted
483 implementation. By default, it will act as the compiler for a hosted
484 implementation, defining @code{__STDC_HOSTED__} as @code{1} and
485 presuming that when the names of ISO C functions are used, they have
486 the semantics defined in the standard. To make it act as a conforming
487 freestanding implementation for a freestanding environment, use the
488 option @option{-ffreestanding}; it will then define
489 @code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
490 meanings of function names from the standard library. To build an OS
491 kernel, you may well still need to make your own arrangements for
492 linking and startup. @xref{C Dialect Options,,Options Controlling C
495 GCC does not provide the library facilities required only of hosted
496 implementations, nor yet all the facilities required by C99 of
497 freestanding implementations; to use the facilities of a hosted
498 environment, you will need to find them elsewhere (for example, in the
499 GNU C library). @xref{Standard Libraries,,Standard Libraries}.
501 For references to Technical Corrigenda, Rationale documents and
502 information concerning the history of C that is available online, see
503 @uref{http://gcc.gnu.org/readings.html}
505 @c FIXME: details of C++ standard.
507 There is no formal written standard for Objective-C@. The most
508 authoritative manual is ``Object-Oriented Programming and the
509 Objective-C Language'', available at a number of web sites;
510 @uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/} has a
511 recent version, while @uref{http://www.toodarkpark.org/computers/objc/}
512 is an older example. @uref{http://www.gnustep.org} includes useful
515 @xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
516 Fortran}, for details of the Fortran language supported by GCC@.
518 @xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj},
519 for details of compatibility between @code{gcj} and the Java Platform.
521 @xref{References,,Language Definition References, chill, GNU Chill},
522 for details of the CHILL standard.
526 @include install-old.texi
535 @chapter Known Causes of Trouble with GCC
537 @cindex installation trouble
538 @cindex known causes of trouble
540 This section describes known problems that affect users of GCC@. Most
541 of these are not GCC bugs per se---if they were, we would fix them.
542 But the result for a user may be like the result of a bug.
544 Some of these problems are due to bugs in other software, some are
545 missing features that are too much work to add, and some are places
546 where people's opinions differ as to what is best.
549 * Actual Bugs:: Bugs we will fix later.
550 * Cross-Compiler Problems:: Common problems of cross compiling with GCC.
551 * Interoperation:: Problems using GCC with other compilers,
552 and with certain linkers, assemblers and debuggers.
553 * External Bugs:: Problems compiling certain programs.
554 * Incompatibilities:: GCC is incompatible with traditional C.
555 * Fixed Headers:: GCC uses corrected versions of system header files.
556 This is necessary, but doesn't always work smoothly.
557 * Standard Libraries:: GCC uses the system C library, which might not be
558 compliant with the ISO C standard.
559 * Disappointments:: Regrettable things we can't change, but not quite bugs.
560 * C++ Misunderstandings:: Common misunderstandings with GNU C++.
561 * Protoize Caveats:: Things to watch out for when using @code{protoize}.
562 * Non-bugs:: Things we think are right, but some others disagree.
563 * Warnings and Errors:: Which problems in your code get warnings,
564 and which get errors.
568 @section Actual Bugs We Haven't Fixed Yet
572 The @code{fixincludes} script interacts badly with automounters; if the
573 directory of system header files is automounted, it tends to be
574 unmounted while @code{fixincludes} is running. This would seem to be a
575 bug in the automounter. We don't know any good way to work around it.
578 The @code{fixproto} script will sometimes add prototypes for the
579 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
580 @code{jmp_buf} type before that type is defined. To work around this,
581 edit the offending file and place the typedef in front of the
585 @opindex pedantic-errors
586 When @option{-pedantic-errors} is specified, GCC will incorrectly give
587 an error message when a function name is specified in an expression
588 involving the comma operator.
591 @node Cross-Compiler Problems
592 @section Cross-Compiler Problems
594 You may run into problems with cross compilation on certain machines,
599 Cross compilation can run into trouble for certain machines because
600 some target machines' assemblers require floating point numbers to be
601 written as @emph{integer} constants in certain contexts.
603 The compiler writes these integer constants by examining the floating
604 point value as an integer and printing that integer, because this is
605 simple to write and independent of the details of the floating point
606 representation. But this does not work if the compiler is running on
607 a different machine with an incompatible floating point format, or
608 even a different byte-ordering.
610 In addition, correct constant folding of floating point values
611 requires representing them in the target machine's format.
612 (The C standard does not quite require this, but in practice
613 it is the only way to win.)
615 It is now possible to overcome these problems by defining macros such
616 as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
617 work for each target machine.
619 @xref{Cross-compilation}.
622 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
623 gcc.info, Using and Porting GCC}.
627 At present, the program @file{mips-tfile} which adds debug
628 support to object files on MIPS systems does not work in a cross
633 @section Interoperation
635 This section lists various difficulties encountered in using GCC
636 together with other compilers or with the assemblers, linkers,
637 libraries and debuggers on certain systems.
641 Objective-C does not work on the RS/6000.
644 G++ does not do name mangling in the same way as other C++
645 compilers. This means that object files compiled with one compiler
646 cannot be used with another.
648 This effect is intentional, to protect you from more subtle problems.
649 Compilers differ as to many internal details of C++ implementation,
650 including: how class instances are laid out, how multiple inheritance is
651 implemented, and how virtual function calls are handled. If the name
652 encoding were made the same, your programs would link against libraries
653 provided from other compilers---but the programs would then crash when
654 run. Incompatible libraries are then detected at link time, rather than
658 Older GDB versions sometimes fail to read the output of GCC version
659 2. If you have trouble, get GDB version 4.4 or later.
663 DBX rejects some files produced by GCC, though it accepts similar
664 constructs in output from PCC@. Until someone can supply a coherent
665 description of what is valid DBX input and what is not, there is
666 nothing I can do about these problems. You are on your own.
669 The GNU assembler (GAS) does not support PIC@. To generate PIC code, you
670 must use some other assembler, such as @file{/bin/as}.
673 On some BSD systems, including some versions of Ultrix, use of profiling
674 causes static variable destructors (currently used only in C++) not to
678 @cindex @code{vfork}, for the Sun-4
680 There is a bug in @code{vfork} on the Sun-4 which causes the registers
681 of the child process to clobber those of the parent. Because of this,
682 programs that call @code{vfork} are likely to lose when compiled
683 optimized with GCC when the child code alters registers which contain
684 C variables in the parent. This affects variables which are live in the
685 parent across the call to @code{vfork}.
687 If you encounter this, you can work around the problem by declaring
688 variables @code{volatile} in the function that calls @code{vfork}, until
689 the problem goes away, or by not declaring them @code{register} and not
690 using @option{-O} for those source files.
694 On some SGI systems, when you use @option{-lgl_s} as an option,
695 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
696 Naturally, this does not happen when you use GCC@.
697 You must specify all three options explicitly.
700 On a Sparc, GCC aligns all values of type @code{double} on an 8-byte
701 boundary, and it expects every @code{double} to be so aligned. The Sun
702 compiler usually gives @code{double} values 8-byte alignment, with one
703 exception: function arguments of type @code{double} may not be aligned.
705 As a result, if a function compiled with Sun CC takes the address of an
706 argument of type @code{double} and passes this pointer of type
707 @code{double *} to a function compiled with GCC, dereferencing the
708 pointer may cause a fatal signal.
710 One way to solve this problem is to compile your entire program with GCC@.
711 Another solution is to modify the function that is compiled with
712 Sun CC to copy the argument into a local variable; local variables
713 are always properly aligned. A third solution is to modify the function
714 that uses the pointer to dereference it via the following function
715 @code{access_double} instead of directly with @samp{*}:
719 access_double (double *unaligned_ptr)
721 union d2i @{ double d; int i[2]; @};
723 union d2i *p = (union d2i *) unaligned_ptr;
734 Storing into the pointer can be done likewise with the same union.
737 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
738 may allocate memory that is only 4 byte aligned. Since GCC on the
739 Sparc assumes that doubles are 8 byte aligned, this may result in a
740 fatal signal if doubles are stored in memory allocated by the
741 @file{libmalloc.a} library.
743 The solution is to not use the @file{libmalloc.a} library. Use instead
744 @code{malloc} and related functions from @file{libc.a}; they do not have
748 Sun forgot to include a static version of @file{libdl.a} with some
749 versions of SunOS (mainly 4.1). This results in undefined symbols when
750 linking static binaries (that is, if you use @option{-static}). If you
751 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
752 when linking, compile and link against the file
753 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
756 The 128-bit long double format that the Sparc port supports currently
757 works by using the architecturally defined quad-word floating point
758 instructions. Since there is no hardware that supports these
759 instructions they must be emulated by the operating system. Long
760 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
761 kernel emulator uses an obsolete and incompatible format. Long doubles
762 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
763 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
764 does not enable them by default. Long doubles appear to work in Sun OS
768 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
769 compile GCC correctly. We do not yet know why. However, GCC
770 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
771 compile itself properly on 9.01.
774 On the HP PA machine, ADB sometimes fails to work on functions compiled
775 with GCC@. Specifically, it fails to work on functions that use
776 @code{alloca} or variable-size arrays. This is because GCC doesn't
777 generate HP-UX unwind descriptors for such functions. It may even be
778 impossible to generate them.
781 Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
782 the preliminary GNU tools (@pxref{Installation}).
785 Taking the address of a label may generate errors from the HP-UX
786 PA assembler. GAS for the PA does not have this problem.
789 Using floating point parameters for indirect calls to static functions
790 will not work when using the HP assembler. There simply is no way for GCC
791 to specify what registers hold arguments for static functions when using
792 the HP assembler. GAS for the PA does not have this problem.
795 In extremely rare cases involving some very large functions you may
796 receive errors from the HP linker complaining about an out of bounds
797 unconditional branch offset. This used to occur more often in previous
798 versions of GCC, but is now exceptionally rare. If you should run
799 into it, you can work around by making your function smaller.
802 GCC compiled code sometimes emits warnings from the HP-UX assembler of
806 (warning) Use of GR3 when
807 frame >= 8192 may cause conflict.
810 These warnings are harmless and can be safely ignored.
813 The current version of the assembler (@file{/bin/as}) for the RS/6000
814 has certain problems that prevent the @option{-g} option in GCC from
815 working. Note that @file{Makefile.in} uses @option{-g} by default when
816 compiling @file{libgcc2.c}.
818 IBM has produced a fixed version of the assembler. The upgraded
819 assembler unfortunately was not included in any of the AIX 3.2 update
820 PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request
821 PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
822 See the file @file{README.RS6000} for more details on these updates.
824 You can test for the presence of a fixed assembler by using the
832 If the command exits normally, the assembler fix already is installed.
833 If the assembler complains that @option{-u} is an unknown flag, you need to
837 On the IBM RS/6000, compiling code of the form
848 will cause the linker to report an undefined symbol @code{foo}.
849 Although this behavior differs from most other systems, it is not a
850 bug because redefining an @code{extern} variable as @code{static}
851 is undefined in ISO C@.
854 AIX on the RS/6000 provides support (NLS) for environments outside of
855 the United States. Compilers and assemblers use NLS to support
856 locale-specific representations of various objects including
857 floating-point numbers (@samp{.} vs @samp{,} for separating decimal fractions).
858 There have been problems reported where the library linked with GCC does
859 not produce the same floating-point formats that the assembler accepts.
860 If you have this problem, set the @env{LANG} environment variable to
861 @samp{C} or @samp{En_US}.
864 @opindex fdollars-in-identifiers
865 Even if you specify @option{-fdollars-in-identifiers},
866 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
867 to a restriction in the IBM assembler. GAS supports these
871 On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC
872 version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2
873 by requesting PTF 421749 from IBM@.
876 @opindex mno-serialize-volatile
877 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
878 occurs when the @samp{fldcr} instruction is used. GCC uses
879 @samp{fldcr} on the 88100 to serialize volatile memory references. Use
880 the option @option{-mno-serialize-volatile} if your version of the
881 assembler has this bug.
884 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
885 messages from the linker. These warning messages complain of mismatched
886 psect attributes. You can ignore them. @xref{VMS Install}.
889 On NewsOS version 3, if you include both of the files @file{stddef.h}
890 and @file{sys/types.h}, you get an error because there are two typedefs
891 of @code{size_t}. You should change @file{sys/types.h} by adding these
892 lines around the definition of @code{size_t}:
897 @var{actual-typedef-here}
903 On the Alliant, the system's own convention for returning structures
904 and unions is unusual, and is not compatible with GCC no matter
905 what options are used.
910 @opindex mhc-struct-return
911 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
912 convention for structure and union returning. Use the option
913 @option{-mhc-struct-return} to tell GCC to use a convention compatible
916 @cindex VAX calling convention
917 @cindex Ultrix calling convention
920 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
921 by function calls. However, the C compiler uses conventions compatible
922 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
924 GCC uses the same convention as the Ultrix C compiler. You can use
925 these options to produce code compatible with the Fortran compiler:
928 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
932 On the WE32k, you may find that programs compiled with GCC do not
933 work with the standard shared C library. You may need to link with
934 the ordinary C compiler. If you do so, you must specify the following
938 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
941 The first specifies where to find the library @file{libgcc.a}
942 specified with the @option{-lgcc} option.
944 GCC does linking by invoking @command{ld}, just as @command{cc} does, and
945 there is no reason why it @emph{should} matter which compilation program
946 you use to invoke @command{ld}. If someone tracks this problem down,
947 it can probably be fixed easily.
950 On the Alpha, you may get assembler errors about invalid syntax as a
951 result of floating point constants. This is due to a bug in the C
952 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid
953 floating point numbers, they sometimes print @samp{NaN}.
956 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
957 sometimes reorders instructions incorrectly when optimization is turned
958 on. If you think this may be happening to you, try using the GNU
959 assembler; GAS version 2.1 supports ECOFF on Irix.
962 Or use the @option{-noasmopt} option when you compile GCC with itself,
963 and then again when you compile your program. (This is a temporary
964 kludge to turn off assembler optimization on Irix.) If this proves to
965 be what you need, edit the assembler spec in the file @file{specs} so
966 that it unconditionally passes @option{-O0} to the assembler, and never
967 passes @option{-O2} or @option{-O3}.
971 @section Problems Compiling Certain Programs
973 @c prevent bad page break with this line
974 Certain programs have problems compiling.
978 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
979 because of problems in DEC's versions of the X11 header files
980 @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
981 @option{-I/usr/include/mit} to use the MIT versions of the header files,
982 using the @option{-traditional} switch to turn off ISO C, or fixing the
983 header files by adding this:
987 #define NeedFunctionPrototypes 0
992 On various 386 Unix systems derived from System V, including SCO, ISC,
993 and ESIX, you may get error messages about running out of virtual memory
994 while compiling certain programs.
996 You can prevent this problem by linking GCC with the GNU malloc
997 (which thus replaces the malloc that comes with the system). GNU malloc
998 is available as a separate package, and also in the file
999 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
1001 If you have installed GNU malloc as a separate library package, use this
1002 option when you relink GCC:
1005 MALLOC=/usr/local/lib/libgmalloc.a
1008 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
1009 the object file to @file{gmalloc.o} and use this option when you relink
1017 @node Incompatibilities
1018 @section Incompatibilities of GCC
1019 @cindex incompatibilities of GCC
1020 @opindex traditional
1022 There are several noteworthy incompatibilities between GNU C and K&R
1023 (non-ISO) versions of C@. The @option{-traditional} option
1024 eliminates many of these incompatibilities, @emph{but not all}, by
1025 telling GCC to behave like a K&R C compiler.
1028 @cindex string constants
1029 @cindex read-only strings
1030 @cindex shared strings
1032 GCC normally makes string constants read-only. If several
1033 identical-looking string constants are used, GCC stores only one
1036 @cindex @code{mktemp}, and constant strings
1037 One consequence is that you cannot call @code{mktemp} with a string
1038 constant argument. The function @code{mktemp} always alters the
1039 string its argument points to.
1041 @cindex @code{sscanf}, and constant strings
1042 @cindex @code{fscanf}, and constant strings
1043 @cindex @code{scanf}, and constant strings
1044 Another consequence is that @code{sscanf} does not work on some systems
1045 when passed a string constant as its format control string or input.
1046 This is because @code{sscanf} incorrectly tries to write into the string
1047 constant. Likewise @code{fscanf} and @code{scanf}.
1049 @opindex fwritable-strings
1050 The best solution to these problems is to change the program to use
1051 @code{char}-array variables with initialization strings for these
1052 purposes instead of string constants. But if this is not possible,
1053 you can use the @option{-fwritable-strings} flag, which directs GCC
1054 to handle string constants the same way most C compilers do.
1055 @option{-traditional} also has this effect, among others.
1058 @code{-2147483648} is positive.
1060 This is because 2147483648 cannot fit in the type @code{int}, so
1061 (following the ISO C rules) its data type is @code{unsigned long int}.
1062 Negating this value yields 2147483648 again.
1065 GCC does not substitute macro arguments when they appear inside of
1066 string constants. For example, the following macro in GCC
1073 will produce output @code{"a"} regardless of what the argument @var{a} is.
1075 The @option{-traditional} option directs GCC to handle such cases
1076 (among others) in the old-fashioned (non-ISO) fashion.
1078 @cindex @code{setjmp} incompatibilities
1079 @cindex @code{longjmp} incompatibilities
1081 When you use @code{setjmp} and @code{longjmp}, the only automatic
1082 variables guaranteed to remain valid are those declared
1083 @code{volatile}. This is a consequence of automatic register
1084 allocation. Consider this function:
1098 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
1103 Here @code{a} may or may not be restored to its first value when the
1104 @code{longjmp} occurs. If @code{a} is allocated in a register, then
1105 its first value is restored; otherwise, it keeps the last value stored
1109 If you use the @option{-W} option with the @option{-O} option, you will
1110 get a warning when GCC thinks such a problem might be possible.
1112 The @option{-traditional} option directs GCC to put variables in
1113 the stack by default, rather than in registers, in functions that
1114 call @code{setjmp}. This results in the behavior found in
1115 traditional C compilers.
1118 Programs that use preprocessing directives in the middle of macro
1119 arguments do not work with GCC@. For example, a program like this
1130 ISO C does not permit such a construct. It would make sense to support
1131 it when @option{-traditional} is used, but it is too much work to
1135 K&R compilers allow comments to cross over an inclusion boundary
1136 (i.e.@: started in an include file and ended in the including file). I think
1137 this would be quite ugly and can't imagine it could be needed.
1139 @cindex external declaration scope
1140 @cindex scope of external declarations
1141 @cindex declaration scope
1143 Declarations of external variables and functions within a block apply
1144 only to the block containing the declaration. In other words, they
1145 have the same scope as any other declaration in the same place.
1147 In some other C compilers, a @code{extern} declaration affects all the
1148 rest of the file even if it happens within a block.
1150 The @option{-traditional} option directs GCC to treat all @code{extern}
1151 declarations as global, like traditional compilers.
1154 In traditional C, you can combine @code{long}, etc., with a typedef name,
1159 typedef long foo bar;
1162 In ISO C, this is not allowed: @code{long} and other type modifiers
1163 require an explicit @code{int}. Because this criterion is expressed
1164 by Bison grammar rules rather than C code, the @option{-traditional}
1165 flag cannot alter it.
1167 @cindex typedef names as function parameters
1169 PCC allows typedef names to be used as function parameters. The
1170 difficulty described immediately above applies here too.
1173 When in @option{-traditional} mode, GCC allows the following erroneous
1174 pair of declarations to appear together in a given scope:
1182 GCC treats all characters of identifiers as significant, even when in
1183 @option{-traditional} mode. According to K&R-1 (2.2), ``No more than the
1184 first eight characters are significant, although more may be used.''.
1185 Also according to K&R-1 (2.2), ``An identifier is a sequence of letters
1186 and digits; the first character must be a letter. The underscore _
1187 counts as a letter.'', but GCC also allows dollar signs in identifiers.
1191 PCC allows whitespace in the middle of compound assignment operators
1192 such as @samp{+=}. GCC, following the ISO standard, does not
1193 allow this. The difficulty described immediately above applies here
1199 GCC complains about unterminated character constants inside of
1200 preprocessing conditionals that fail. Some programs have English
1201 comments enclosed in conditionals that are guaranteed to fail; if these
1202 comments contain apostrophes, GCC will probably report an error. For
1203 example, this code would produce an error:
1207 You can't expect this to work.
1211 The best solution to such a problem is to put the text into an actual
1212 C comment delimited by @samp{/*@dots{}*/}. However,
1213 @option{-traditional} suppresses these error messages.
1216 Many user programs contain the declaration @samp{long time ();}. In the
1217 past, the system header files on many systems did not actually declare
1218 @code{time}, so it did not matter what type your program declared it to
1219 return. But in systems with ISO C headers, @code{time} is declared to
1220 return @code{time_t}, and if that is not the same as @code{long}, then
1221 @samp{long time ();} is erroneous.
1223 The solution is to change your program to use appropriate system headers
1224 (@code{<time.h>} on systems with ISO C headers) and not to declare
1225 @code{time} if the system header files declare it, or failing that to
1226 use @code{time_t} as the return type of @code{time}.
1228 @cindex @code{float} as function value type
1230 When compiling functions that return @code{float}, PCC converts it to
1231 a double. GCC actually returns a @code{float}. If you are concerned
1232 with PCC compatibility, you should declare your functions to return
1233 @code{double}; you might as well say what you mean.
1238 When compiling functions that return structures or unions, GCC
1239 output code normally uses a method different from that used on most
1240 versions of Unix. As a result, code compiled with GCC cannot call
1241 a structure-returning function compiled with PCC, and vice versa.
1243 The method used by GCC is as follows: a structure or union which is
1244 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
1245 with any other size is stored into an address supplied by the caller
1246 (usually in a special, fixed register, but on some machines it is passed
1247 on the stack). The machine-description macros @code{STRUCT_VALUE} and
1248 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
1250 By contrast, PCC on most target machines returns structures and unions
1251 of any size by copying the data into an area of static storage, and then
1252 returning the address of that storage as if it were a pointer value.
1253 The caller must copy the data from that memory area to the place where
1254 the value is wanted. GCC does not use this method because it is
1255 slower and nonreentrant.
1257 On some newer machines, PCC uses a reentrant convention for all
1258 structure and union returning. GCC on most of these machines uses a
1259 compatible convention when returning structures and unions in memory,
1260 but still returns small structures and unions in registers.
1262 @opindex fpcc-struct-return
1263 You can tell GCC to use a compatible convention for all structure and
1264 union returning with the option @option{-fpcc-struct-return}.
1266 @cindex preprocessing tokens
1267 @cindex preprocessing numbers
1269 GCC complains about program fragments such as @samp{0x74ae-0x4000}
1270 which appear to be two hexadecimal constants separated by the minus
1271 operator. Actually, this string is a single @dfn{preprocessing token}.
1272 Each such token must correspond to one token in C@. Since this does not,
1273 GCC prints an error message. Although it may appear obvious that what
1274 is meant is an operator and two values, the ISO C standard specifically
1275 requires that this be treated as erroneous.
1277 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
1278 begins with a digit and is followed by letters, underscores, digits,
1279 periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
1280 @samp{p-}, @samp{P+}, or @samp{P-} character sequences. (In strict C89
1281 mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
1282 appear in preprocessing numbers.)
1284 To make the above program fragment valid, place whitespace in front of
1285 the minus sign. This whitespace will end the preprocessing number.
1289 @section Fixed Header Files
1291 GCC needs to install corrected versions of some system header files.
1292 This is because most target systems have some header files that won't
1293 work with GCC unless they are changed. Some have bugs, some are
1294 incompatible with ISO C, and some depend on special features of other
1297 Installing GCC automatically creates and installs the fixed header
1298 files, by running a program called @code{fixincludes} (or for certain
1299 targets an alternative such as @code{fixinc.svr4}). Normally, you
1300 don't need to pay attention to this. But there are cases where it
1301 doesn't do the right thing automatically.
1305 If you update the system's header files, such as by installing a new
1306 system version, the fixed header files of GCC are not automatically
1307 updated. The easiest way to update them is to reinstall GCC@. (If
1308 you want to be clever, look in the makefile and you can find a
1312 On some systems, in particular SunOS 4, header file directories contain
1313 machine-specific symbolic links in certain places. This makes it
1314 possible to share most of the header files among hosts running the
1315 same version of SunOS 4 on different machine models.
1317 The programs that fix the header files do not understand this special
1318 way of using symbolic links; therefore, the directory of fixed header
1319 files is good only for the machine model used to build it.
1321 In SunOS 4, only programs that look inside the kernel will notice the
1322 difference between machine models. Therefore, for most purposes, you
1323 need not be concerned about this.
1325 It is possible to make separate sets of fixed header files for the
1326 different machine models, and arrange a structure of symbolic links so
1327 as to use the proper set, but you'll have to do this by hand.
1330 On Lynxos, GCC by default does not fix the header files. This is
1331 because bugs in the shell cause the @code{fixincludes} script to fail.
1333 This means you will encounter problems due to bugs in the system header
1334 files. It may be no comfort that they aren't GCC's fault, but it
1335 does mean that there's nothing for us to do about them.
1338 @node Standard Libraries
1339 @section Standard Libraries
1342 GCC by itself attempts to be a conforming freestanding implementation.
1343 @xref{Standards,,Language Standards Supported by GCC}, for details of
1344 what this means. Beyond the library facilities required of such an
1345 implementation, the rest of the C library is supplied by the vendor of
1346 the operating system. If that C library doesn't conform to the C
1347 standards, then your programs might get warnings (especially when using
1348 @option{-Wall}) that you don't expect.
1350 For example, the @code{sprintf} function on SunOS 4.1.3 returns
1351 @code{char *} while the C standard says that @code{sprintf} returns an
1352 @code{int}. The @code{fixincludes} program could make the prototype for
1353 this function match the Standard, but that would be wrong, since the
1354 function will still return @code{char *}.
1356 If you need a Standard compliant library, then you need to find one, as
1357 GCC does not provide one. The GNU C library (called @code{glibc})
1358 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
1359 GNU/Linux and HURD-based GNU systems; no recent version of it supports
1360 other systems, though some very old versions did. Version 2.2 of the
1361 GNU C library includes nearly complete C99 support. You could also ask
1362 your operating system vendor if newer libraries are available.
1364 @node Disappointments
1365 @section Disappointments and Misunderstandings
1367 These problems are perhaps regrettable, but we don't know any practical
1372 Certain local variables aren't recognized by debuggers when you compile
1375 This occurs because sometimes GCC optimizes the variable out of
1376 existence. There is no way to tell the debugger how to compute the
1377 value such a variable ``would have had'', and it is not clear that would
1378 be desirable anyway. So GCC simply does not mention the eliminated
1379 variable when it writes debugging information.
1381 You have to expect a certain amount of disagreement between the
1382 executable and your source code, when you use optimization.
1384 @cindex conflicting types
1385 @cindex scope of declaration
1387 Users often think it is a bug when GCC reports an error for code
1391 int foo (struct mumble *);
1393 struct mumble @{ @dots{} @};
1395 int foo (struct mumble *x)
1399 This code really is erroneous, because the scope of @code{struct
1400 mumble} in the prototype is limited to the argument list containing it.
1401 It does not refer to the @code{struct mumble} defined with file scope
1402 immediately below---they are two unrelated types with similar names in
1405 But in the definition of @code{foo}, the file-scope type is used
1406 because that is available to be inherited. Thus, the definition and
1407 the prototype do not match, and you get an error.
1409 This behavior may seem silly, but it's what the ISO standard specifies.
1410 It is easy enough for you to make your code work by moving the
1411 definition of @code{struct mumble} above the prototype. It's not worth
1412 being incompatible with ISO C just to avoid an error for the example
1416 Accesses to bit-fields even in volatile objects works by accessing larger
1417 objects, such as a byte or a word. You cannot rely on what size of
1418 object is accessed in order to read or write the bit-field; it may even
1419 vary for a given bit-field according to the precise usage.
1421 If you care about controlling the amount of memory that is accessed, use
1422 volatile but do not use bit-fields.
1425 GCC comes with shell scripts to fix certain known problems in system
1426 header files. They install corrected copies of various header files in
1427 a special directory where only GCC will normally look for them. The
1428 scripts adapt to various systems by searching all the system header
1429 files for the problem cases that we know about.
1431 If new system header files are installed, nothing automatically arranges
1432 to update the corrected header files. You will have to reinstall GCC
1433 to fix the new header files. More specifically, go to the build
1434 directory and delete the files @file{stmp-fixinc} and
1435 @file{stmp-headers}, and the subdirectory @code{include}; then do
1436 @samp{make install} again.
1439 @cindex floating point precision
1440 On 68000 and x86 systems, for instance, you can get paradoxical results
1441 if you test the precise values of floating point numbers. For example,
1442 you can find that a floating point value which is not a NaN is not equal
1443 to itself. This results from the fact that the floating point registers
1444 hold a few more bits of precision than fit in a @code{double} in memory.
1445 Compiled code moves values between memory and floating point registers
1446 at its convenience, and moving them into memory truncates them.
1448 @opindex ffloat-store
1449 You can partially avoid this problem by using the @option{-ffloat-store}
1450 option (@pxref{Optimize Options}).
1453 On the MIPS, variable argument functions using @file{varargs.h}
1454 cannot have a floating point value for the first argument. The
1455 reason for this is that in the absence of a prototype in scope,
1456 if the first argument is a floating point, it is passed in a
1457 floating point register, rather than an integer register.
1459 If the code is rewritten to use the ISO standard @file{stdarg.h}
1460 method of variable arguments, and the prototype is in scope at
1461 the time of the call, everything will work fine.
1464 On the H8/300 and H8/300H, variable argument functions must be
1465 implemented using the ISO standard @file{stdarg.h} method of
1466 variable arguments. Furthermore, calls to functions using @file{stdarg.h}
1467 variable arguments must have a prototype for the called function
1468 in scope at the time of the call.
1471 @node C++ Misunderstandings
1472 @section Common Misunderstandings with GNU C++
1474 @cindex misunderstandings in C++
1475 @cindex surprises in C++
1476 @cindex C++ misunderstandings
1477 C++ is a complex language and an evolving one, and its standard
1478 definition (the ISO C++ standard) was only recently completed. As a
1479 result, your C++ compiler may occasionally surprise you, even when its
1480 behavior is correct. This section discusses some areas that frequently
1481 give rise to questions of this sort.
1484 * Static Definitions:: Static member declarations are not definitions
1485 * Temporaries:: Temporaries may vanish before you expect
1486 * Copy Assignment:: Copy Assignment operators copy virtual bases twice
1489 @node Static Definitions
1490 @subsection Declare @emph{and} Define Static Members
1492 @cindex C++ static data, declaring and defining
1493 @cindex static data in C++, declaring and defining
1494 @cindex declaring static data in C++
1495 @cindex defining static data in C++
1496 When a class has static data members, it is not enough to @emph{declare}
1497 the static member; you must also @emph{define} it. For example:
1508 This declaration only establishes that the class @code{Foo} has an
1509 @code{int} named @code{Foo::bar}, and a member function named
1510 @code{Foo::method}. But you still need to define @emph{both}
1511 @code{method} and @code{bar} elsewhere. According to the ISO
1512 standard, you must supply an initializer in one (and only one) source
1519 Other C++ compilers may not correctly implement the standard behavior.
1520 As a result, when you switch to @code{g++} from one of these compilers,
1521 you may discover that a program that appeared to work correctly in fact
1522 does not conform to the standard: @code{g++} reports as undefined
1523 symbols any static data members that lack definitions.
1526 @subsection Temporaries May Vanish Before You Expect
1528 @cindex temporaries, lifetime of
1529 @cindex portions of temporary objects, pointers to
1530 It is dangerous to use pointers or references to @emph{portions} of a
1531 temporary object. The compiler may very well delete the object before
1532 you expect it to, leaving a pointer to garbage. The most common place
1533 where this problem crops up is in classes like string classes,
1534 especially ones that define a conversion function to type @code{char *}
1535 or @code{const char *}---which is one reason why the standard
1536 @code{string} class requires you to call the @code{c_str} member
1537 function. However, any class that returns a pointer to some internal
1538 structure is potentially subject to this problem.
1540 For example, a program may use a function @code{strfunc} that returns
1541 @code{string} objects, and another function @code{charfunc} that
1542 operates on pointers to @code{char}:
1546 void charfunc (const char *);
1551 const char *p = strfunc().c_str();
1560 In this situation, it may seem reasonable to save a pointer to the C
1561 string returned by the @code{c_str} member function and use that rather
1562 than call @code{c_str} repeatedly. However, the temporary string
1563 created by the call to @code{strfunc} is destroyed after @code{p} is
1564 initialized, at which point @code{p} is left pointing to freed memory.
1566 Code like this may run successfully under some other compilers,
1567 particularly obsolete cfront-based compilers that delete temporaries
1568 along with normal local variables. However, the GNU C++ behavior is
1569 standard-conforming, so if your program depends on late destruction of
1570 temporaries it is not portable.
1572 The safe way to write such code is to give the temporary a name, which
1573 forces it to remain until the end of the scope of the name. For
1577 string& tmp = strfunc ();
1578 charfunc (tmp.c_str ());
1581 @node Copy Assignment
1582 @subsection Implicit Copy-Assignment for Virtual Bases
1584 When a base class is virtual, only one subobject of the base class
1585 belongs to each full object. Also, the constructors and destructors are
1586 invoked only once, and called from the most-derived class. However, such
1587 objects behave unspecified when being assigned. For example:
1592 Base(char *n) : name(strdup(n))@{@}
1593 Base& operator= (const Base& other)@{
1595 name = strdup (other.name);
1599 struct A:virtual Base@{
1604 struct B:virtual Base@{
1609 struct Derived:public A, public B@{
1610 Derived():Base("Derived")@{@}
1613 void func(Derived &d1, Derived &d2)
1619 The C++ standard specifies that @samp{Base::Base} is only called once
1620 when constructing or copy-constructing a Derived object. It is
1621 unspecified whether @samp{Base::operator=} is called more than once when
1622 the implicit copy-assignment for Derived objects is invoked (as it is
1623 inside @samp{func} in the example).
1625 g++ implements the ``intuitive'' algorithm for copy-assignment: assign all
1626 direct bases, then assign all members. In that algorithm, the virtual
1627 base subobject can be encountered many times. In the example, copying
1628 proceeds in the following order: @samp{val}, @samp{name} (via
1629 @code{strdup}), @samp{bval}, and @samp{name} again.
1631 If application code relies on copy-assignment, a user-defined
1632 copy-assignment operator removes any uncertainties. With such an
1633 operator, the application can define whether and how the virtual base
1634 subobject is assigned.
1636 @node Protoize Caveats
1637 @section Caveats of using @command{protoize}
1639 The conversion programs @command{protoize} and @command{unprotoize} can
1640 sometimes change a source file in a way that won't work unless you
1645 @command{protoize} can insert references to a type name or type tag before
1646 the definition, or in a file where they are not defined.
1648 If this happens, compiler error messages should show you where the new
1649 references are, so fixing the file by hand is straightforward.
1652 There are some C constructs which @command{protoize} cannot figure out.
1653 For example, it can't determine argument types for declaring a
1654 pointer-to-function variable; this you must do by hand. @command{protoize}
1655 inserts a comment containing @samp{???} each time it finds such a
1656 variable; so you can find all such variables by searching for this
1657 string. ISO C does not require declaring the argument types of
1658 pointer-to-function types.
1661 Using @command{unprotoize} can easily introduce bugs. If the program
1662 relied on prototypes to bring about conversion of arguments, these
1663 conversions will not take place in the program without prototypes.
1664 One case in which you can be sure @command{unprotoize} is safe is when
1665 you are removing prototypes that were made with @command{protoize}; if
1666 the program worked before without any prototypes, it will work again
1669 @opindex Wconversion
1670 You can find all the places where this problem might occur by compiling
1671 the program with the @option{-Wconversion} option. It prints a warning
1672 whenever an argument is converted.
1675 Both conversion programs can be confused if there are macro calls in and
1676 around the text to be converted. In other words, the standard syntax
1677 for a declaration or definition must not result from expanding a macro.
1678 This problem is inherent in the design of C and cannot be fixed. If
1679 only a few functions have confusing macro calls, you can easily convert
1683 @command{protoize} cannot get the argument types for a function whose
1684 definition was not actually compiled due to preprocessing conditionals.
1685 When this happens, @command{protoize} changes nothing in regard to such
1686 a function. @command{protoize} tries to detect such instances and warn
1689 You can generally work around this problem by using @command{protoize} step
1690 by step, each time specifying a different set of @option{-D} options for
1691 compilation, until all of the functions have been converted. There is
1692 no automatic way to verify that you have got them all, however.
1695 Confusion may result if there is an occasion to convert a function
1696 declaration or definition in a region of source code where there is more
1697 than one formal parameter list present. Thus, attempts to convert code
1698 containing multiple (conditionally compiled) versions of a single
1699 function header (in the same vicinity) may not produce the desired (or
1702 If you plan on converting source files which contain such code, it is
1703 recommended that you first make sure that each conditionally compiled
1704 region of source code which contains an alternative function header also
1705 contains at least one additional follower token (past the final right
1706 parenthesis of the function header). This should circumvent the
1710 @command{unprotoize} can become confused when trying to convert a function
1711 definition or declaration which contains a declaration for a
1712 pointer-to-function formal argument which has the same name as the
1713 function being defined or declared. We recommend you avoid such choices
1714 of formal parameter names.
1717 You might also want to correct some of the indentation by hand and break
1718 long lines. (The conversion programs don't write lines longer than
1719 eighty characters in any case.)
1723 @section Certain Changes We Don't Want to Make
1725 This section lists changes that people frequently request, but which
1726 we do not make because we think GCC is better without them.
1730 Checking the number and type of arguments to a function which has an
1731 old-fashioned definition and no prototype.
1733 Such a feature would work only occasionally---only for calls that appear
1734 in the same file as the called function, following the definition. The
1735 only way to check all calls reliably is to add a prototype for the
1736 function. But adding a prototype eliminates the motivation for this
1737 feature. So the feature is not worthwhile.
1740 Warning about using an expression whose type is signed as a shift count.
1742 Shift count operands are probably signed more often than unsigned.
1743 Warning about this would cause far more annoyance than good.
1746 Warning about assigning a signed value to an unsigned variable.
1748 Such assignments must be very common; warning about them would cause
1749 more annoyance than good.
1752 Warning when a non-void function value is ignored.
1754 Coming as I do from a Lisp background, I balk at the idea that there is
1755 something dangerous about discarding a value. There are functions that
1756 return values which some callers may find useful; it makes no sense to
1757 clutter the program with a cast to @code{void} whenever the value isn't
1761 @opindex fshort-enums
1762 Making @option{-fshort-enums} the default.
1764 This would cause storage layout to be incompatible with most other C
1765 compilers. And it doesn't seem very important, given that you can get
1766 the same result in other ways. The case where it matters most is when
1767 the enumeration-valued object is inside a structure, and in that case
1768 you can specify a field width explicitly.
1771 Making bit-fields unsigned by default on particular machines where ``the
1772 ABI standard'' says to do so.
1774 The ISO C standard leaves it up to the implementation whether a bit-field
1775 declared plain @code{int} is signed or not. This in effect creates two
1776 alternative dialects of C@.
1778 @opindex fsigned-bitfields
1779 @opindex funsigned-bitfields
1780 The GNU C compiler supports both dialects; you can specify the signed
1781 dialect with @option{-fsigned-bitfields} and the unsigned dialect with
1782 @option{-funsigned-bitfields}. However, this leaves open the question of
1783 which dialect to use by default.
1785 Currently, the preferred dialect makes plain bit-fields signed, because
1786 this is simplest. Since @code{int} is the same as @code{signed int} in
1787 every other context, it is cleanest for them to be the same in bit-fields
1790 Some computer manufacturers have published Application Binary Interface
1791 standards which specify that plain bit-fields should be unsigned. It is
1792 a mistake, however, to say anything about this issue in an ABI@. This is
1793 because the handling of plain bit-fields distinguishes two dialects of C@.
1794 Both dialects are meaningful on every type of machine. Whether a
1795 particular object file was compiled using signed bit-fields or unsigned
1796 is of no concern to other object files, even if they access the same
1797 bit-fields in the same data structures.
1799 A given program is written in one or the other of these two dialects.
1800 The program stands a chance to work on most any machine if it is
1801 compiled with the proper dialect. It is unlikely to work at all if
1802 compiled with the wrong dialect.
1804 Many users appreciate the GNU C compiler because it provides an
1805 environment that is uniform across machines. These users would be
1806 inconvenienced if the compiler treated plain bit-fields differently on
1809 Occasionally users write programs intended only for a particular machine
1810 type. On these occasions, the users would benefit if the GNU C compiler
1811 were to support by default the same dialect as the other compilers on
1812 that machine. But such applications are rare. And users writing a
1813 program to run on more than one type of machine cannot possibly benefit
1814 from this kind of compatibility.
1816 This is why GCC does and will treat plain bit-fields in the same
1817 fashion on all types of machines (by default).
1819 There are some arguments for making bit-fields unsigned by default on all
1820 machines. If, for example, this becomes a universal de facto standard,
1821 it would make sense for GCC to go along with it. This is something
1822 to be considered in the future.
1824 (Of course, users strongly concerned about portability should indicate
1825 explicitly in each bit-field whether it is signed or not. In this way,
1826 they write programs which have the same meaning in both C dialects.)
1830 @opindex traditional
1832 Undefining @code{__STDC__} when @option{-ansi} is not used.
1834 Currently, GCC defines @code{__STDC__} as long as you don't use
1835 @option{-traditional}. This provides good results in practice.
1837 Programmers normally use conditionals on @code{__STDC__} to ask whether
1838 it is safe to use certain features of ISO C, such as function
1839 prototypes or ISO token concatenation. Since plain @command{gcc} supports
1840 all the features of ISO C, the correct answer to these questions is
1843 Some users try to use @code{__STDC__} to check for the availability of
1844 certain library facilities. This is actually incorrect usage in an ISO
1845 C program, because the ISO C standard says that a conforming
1846 freestanding implementation should define @code{__STDC__} even though it
1847 does not have the library facilities. @samp{gcc -ansi -pedantic} is a
1848 conforming freestanding implementation, and it is therefore required to
1849 define @code{__STDC__}, even though it does not come with an ISO C
1852 Sometimes people say that defining @code{__STDC__} in a compiler that
1853 does not completely conform to the ISO C standard somehow violates the
1854 standard. This is illogical. The standard is a standard for compilers
1855 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
1856 compilers such as plain @command{gcc}. Whatever the ISO C standard says
1857 is relevant to the design of plain @command{gcc} without @option{-ansi} only
1858 for pragmatic reasons, not as a requirement.
1860 GCC normally defines @code{__STDC__} to be 1, and in addition
1861 defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
1862 or a @option{-std} option for strict conformance to some version of ISO C@.
1863 On some hosts, system include files use a different convention, where
1864 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
1865 conformance to the C Standard. GCC follows the host convention when
1866 processing system include files, but when processing user files it follows
1867 the usual GNU C convention.
1870 Undefining @code{__STDC__} in C++.
1872 Programs written to compile with C++-to-C translators get the
1873 value of @code{__STDC__} that goes with the C compiler that is
1874 subsequently used. These programs must test @code{__STDC__}
1875 to determine what kind of C preprocessor that compiler uses:
1876 whether they should concatenate tokens in the ISO C fashion
1877 or in the traditional fashion.
1879 These programs work properly with GNU C++ if @code{__STDC__} is defined.
1880 They would not work otherwise.
1882 In addition, many header files are written to provide prototypes in ISO
1883 C but not in traditional C@. Many of these header files can work without
1884 change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
1885 is not defined, they will all fail, and will all need to be changed to
1886 test explicitly for C++ as well.
1889 Deleting ``empty'' loops.
1891 Historically, GCC has not deleted ``empty'' loops under the
1892 assumption that the most likely reason you would put one in a program is
1893 to have a delay, so deleting them will not make real programs run any
1896 However, the rationale here is that optimization of a nonempty loop
1897 cannot produce an empty one, which holds for C but is not always the
1900 @opindex funroll-loops
1901 Moreover, with @option{-funroll-loops} small ``empty'' loops are already
1902 removed, so the current behavior is both sub-optimal and inconsistent
1903 and will change in the future.
1906 Making side effects happen in the same order as in some other compiler.
1908 @cindex side effects, order of evaluation
1909 @cindex order of evaluation, side effects
1910 It is never safe to depend on the order of evaluation of side effects.
1911 For example, a function call like this may very well behave differently
1912 from one compiler to another:
1915 void func (int, int);
1921 There is no guarantee (in either the C or the C++ standard language
1922 definitions) that the increments will be evaluated in any particular
1923 order. Either increment might happen first. @code{func} might get the
1924 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
1927 Not allowing structures with volatile fields in registers.
1929 Strictly speaking, there is no prohibition in the ISO C standard
1930 against allowing structures with volatile fields in registers, but
1931 it does not seem to make any sense and is probably not what you wanted
1932 to do. So the compiler will give an error message in this case.
1935 Making certain warnings into errors by default.
1937 Some ISO C testsuites report failure when the compiler does not produce
1938 an error message for a certain program.
1940 @opindex pedantic-errors
1941 ISO C requires a ``diagnostic'' message for certain kinds of invalid
1942 programs, but a warning is defined by GCC to count as a diagnostic. If
1943 GCC produces a warning but not an error, that is correct ISO C support.
1944 If test suites call this ``failure'', they should be run with the GCC
1945 option @option{-pedantic-errors}, which will turn these warnings into
1950 @node Warnings and Errors
1951 @section Warning Messages and Error Messages
1953 @cindex error messages
1954 @cindex warnings vs errors
1955 @cindex messages, warning and error
1956 The GNU compiler can produce two kinds of diagnostics: errors and
1957 warnings. Each kind has a different purpose:
1961 @dfn{Errors} report problems that make it impossible to compile your
1962 program. GCC reports errors with the source file name and line
1963 number where the problem is apparent.
1966 @dfn{Warnings} report other unusual conditions in your code that
1967 @emph{may} indicate a problem, although compilation can (and does)
1968 proceed. Warning messages also report the source file name and line
1969 number, but include the text @samp{warning:} to distinguish them
1970 from error messages.
1973 Warnings may indicate danger points where you should check to make sure
1974 that your program really does what you intend; or the use of obsolete
1975 features; or the use of nonstandard features of GNU C or C++. Many
1976 warnings are issued only if you ask for them, with one of the @option{-W}
1977 options (for instance, @option{-Wall} requests a variety of useful
1981 @opindex pedantic-errors
1982 GCC always tries to compile your program if possible; it never
1983 gratuitously rejects a program whose meaning is clear merely because
1984 (for instance) it fails to conform to a standard. In some cases,
1985 however, the C and C++ standards specify that certain extensions are
1986 forbidden, and a diagnostic @emph{must} be issued by a conforming
1987 compiler. The @option{-pedantic} option tells GCC to issue warnings in
1988 such cases; @option{-pedantic-errors} says to make them errors instead.
1989 This does not mean that @emph{all} non-ISO constructs get warnings
1992 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
1993 more detail on these and related command-line options.
1996 @chapter Reporting Bugs
1998 @cindex reporting bugs
2000 Your bug reports play an essential role in making GCC reliable.
2002 When you encounter a problem, the first thing to do is to see if it is
2003 already known. @xref{Trouble}. If it isn't known, then you should
2006 Reporting a bug may help you by bringing a solution to your problem, or
2007 it may not. (If it does not, look in the service directory; see
2008 @ref{Service}.) In any case, the principal function of a bug report is
2009 to help the entire community by making the next version of GCC work
2010 better. Bug reports are your contribution to the maintenance of GCC@.
2012 Since the maintainers are very overloaded, we cannot respond to every
2013 bug report. However, if the bug has not been fixed, we are likely to
2014 send you a patch and ask you to tell us whether it works.
2016 In order for a bug report to serve its purpose, you must include the
2017 information that makes for fixing the bug.
2020 * Criteria: Bug Criteria. Have you really found a bug?
2021 * Where: Bug Lists. Where to send your bug report.
2022 * Reporting: Bug Reporting. How to report a bug effectively.
2023 * GNATS: gccbug. You can use a bug reporting tool.
2024 * Patches: Sending Patches. How to send a patch for GCC.
2025 * Known: Trouble. Known problems.
2026 * Help: Service. Where to ask for help.
2029 @node Bug Criteria,Bug Lists,,Bugs
2030 @section Have You Found a Bug?
2031 @cindex bug criteria
2033 If you are not sure whether you have found a bug, here are some guidelines:
2036 @cindex fatal signal
2039 If the compiler gets a fatal signal, for any input whatever, that is a
2040 compiler bug. Reliable compilers never crash.
2042 @cindex invalid assembly code
2043 @cindex assembly code, invalid
2045 If the compiler produces invalid assembly code, for any input whatever
2046 (except an @code{asm} statement), that is a compiler bug, unless the
2047 compiler reports errors (not just warnings) which would ordinarily
2048 prevent the assembler from being run.
2050 @cindex undefined behavior
2051 @cindex undefined function value
2052 @cindex increment operators
2054 If the compiler produces valid assembly code that does not correctly
2055 execute the input source code, that is a compiler bug.
2057 However, you must double-check to make sure, because you may have run
2058 into an incompatibility between GNU C and traditional C
2059 (@pxref{Incompatibilities}). These incompatibilities might be considered
2060 bugs, but they are inescapable consequences of valuable features.
2062 Or you may have a program whose behavior is undefined, which happened
2063 by chance to give the desired results with another C or C++ compiler.
2065 For example, in many nonoptimizing compilers, you can write @samp{x;}
2066 at the end of a function instead of @samp{return x;}, with the same
2067 results. But the value of the function is undefined if @code{return}
2068 is omitted; it is not a bug when GCC produces different results.
2070 Problems often result from expressions with two increment operators,
2071 as in @code{f (*p++, *p++)}. Your previous compiler might have
2072 interpreted that expression the way you intended; GCC might
2073 interpret it another way. Neither compiler is wrong. The bug is
2076 After you have localized the error to a single source line, it should
2077 be easy to check for these things. If your program is correct and
2078 well defined, you have found a compiler bug.
2081 If the compiler produces an error message for valid input, that is a
2084 @cindex invalid input
2086 If the compiler does not produce an error message for invalid input,
2087 that is a compiler bug. However, you should note that your idea of
2088 ``invalid input'' might be my idea of ``an extension'' or ``support
2089 for traditional practice''.
2092 If you are an experienced user of one of the languages GCC supports, your
2093 suggestions for improvement of GCC are welcome in any case.
2096 @node Bug Lists,Bug Reporting,Bug Criteria,Bugs
2097 @section Where to Report Bugs
2098 @cindex bug report mailing lists
2099 @kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
2100 Send bug reports for the GNU Compiler Collection to
2101 @email{gcc-bugs@@gcc.gnu.org}. In accordance with the GNU-wide
2102 convention, in which bug reports for tool ``foo'' are sent
2103 to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
2104 may also be used; it will forward to the address given above.
2106 Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or
2107 more up-to-date bug reporting instructions before you post a bug report.
2109 @node Bug Reporting,gccbug,Bug Lists,Bugs
2110 @section How to Report Bugs
2111 @cindex compiler bugs, reporting
2113 The fundamental principle of reporting bugs usefully is this:
2114 @strong{report all the facts}. If you are not sure whether to state a
2115 fact or leave it out, state it!
2117 Often people omit facts because they think they know what causes the
2118 problem and they conclude that some details don't matter. Thus, you might
2119 assume that the name of the variable you use in an example does not matter.
2120 Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
2121 stray memory reference which happens to fetch from the location where that
2122 name is stored in memory; perhaps, if the name were different, the contents
2123 of that location would fool the compiler into doing the right thing despite
2124 the bug. Play it safe and give a specific, complete example. That is the
2125 easiest thing for you to do, and the most helpful.
2127 Keep in mind that the purpose of a bug report is to enable someone to
2128 fix the bug if it is not known. It isn't very important what happens if
2129 the bug is already known. Therefore, always write your bug reports on
2130 the assumption that the bug is not known.
2132 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2133 bell?'' This cannot help us fix a bug, so it is basically useless. We
2134 respond by asking for enough details to enable us to investigate.
2135 You might as well expedite matters by sending them to begin with.
2137 Try to make your bug report self-contained. If we have to ask you for
2138 more information, it is best if you include all the previous information
2139 in your response, as well as the information that was missing.
2141 Please report each bug in a separate message. This makes it easier for
2142 us to track which bugs have been fixed and to forward your bugs reports
2143 to the appropriate maintainer.
2145 To enable someone to investigate the bug, you should include all these
2150 The version of GCC@. You can get this by running it with the
2153 Without this, we won't know whether there is any point in looking for
2154 the bug in the current version of GCC@.
2157 A complete input file that will reproduce the bug. If the bug is in the
2158 C preprocessor, send a source file and any header files that it
2159 requires. If the bug is in the compiler proper (@file{cc1}), send the
2160 preprocessor output generated by adding @option{-save-temps} to the
2161 compilation command (@pxref{Debugging Options}). When you do this, use
2162 the same @option{-I}, @option{-D} or @option{-U} options that you used in
2163 actual compilation. Then send the @var{input}.i or @var{input}.ii files
2166 A single statement is not enough of an example. In order to compile it,
2167 it must be embedded in a complete file of compiler input; and the bug
2168 might depend on the details of how this is done.
2170 Without a real example one can compile, all anyone can do about your bug
2171 report is wish you luck. It would be futile to try to guess how to
2172 provoke the bug. For example, bugs in register allocation and reloading
2173 frequently depend on every little detail of the function they happen in.
2175 Even if the input file that fails comes from a GNU program, you should
2176 still send the complete test case. Don't ask the GCC maintainers to
2177 do the extra work of obtaining the program in question---they are all
2178 overworked as it is. Also, the problem may depend on what is in the
2179 header files on your system; it is unreliable for the GCC maintainers
2180 to try the problem with the header files available to them. By sending
2181 CPP output, you can eliminate this source of uncertainty and save us
2182 a certain percentage of wild goose chases.
2185 The command arguments you gave GCC to compile that example
2186 and observe the bug. For example, did you use @option{-O}? To guarantee
2187 you won't omit something important, list all the options.
2189 If we were to try to guess the arguments, we would probably guess wrong
2190 and then we would not encounter the bug.
2193 The type of machine you are using, and the operating system name and
2197 The operands you gave to the @code{configure} command when you installed
2201 A complete list of any modifications you have made to the compiler
2202 source. (We don't promise to investigate the bug unless it happens in
2203 an unmodified compiler. But if you've made modifications and don't tell
2204 us, then you are sending us on a wild goose chase.)
2206 Be precise about these changes. A description in English is not
2207 enough---send a context diff for them.
2209 Adding files of your own (such as a machine description for a machine we
2210 don't support) is a modification of the compiler source.
2213 Details of any other deviations from the standard procedure for installing
2217 A description of what behavior you observe that you believe is
2218 incorrect. For example, ``The compiler gets a fatal signal,'' or,
2219 ``The assembler instruction at line 208 in the output is incorrect.''
2221 Of course, if the bug is that the compiler gets a fatal signal, then one
2222 can't miss it. But if the bug is incorrect output, the maintainer might
2223 not notice unless it is glaringly wrong. None of us has time to study
2224 all the assembler code from a 50-line C program just on the chance that
2225 one instruction might be wrong. We need @emph{you} to do this part!
2227 Even if the problem you experience is a fatal signal, you should still
2228 say so explicitly. Suppose something strange is going on, such as, your
2229 copy of the compiler is out of synch, or you have encountered a bug in
2230 the C library on your system. (This has happened!) Your copy might
2231 crash and the copy here would not. If you @i{said} to expect a crash,
2232 then when the compiler here fails to crash, we would know that the bug
2233 was not happening. If you don't say to expect a crash, then we would
2234 not know whether the bug was happening. We would not be able to draw
2235 any conclusion from our observations.
2237 If the problem is a diagnostic when compiling GCC with some other
2238 compiler, say whether it is a warning or an error.
2240 Often the observed symptom is incorrect output when your program is run.
2241 Sad to say, this is not enough information unless the program is short
2242 and simple. None of us has time to study a large program to figure out
2243 how it would work if compiled correctly, much less which line of it was
2244 compiled wrong. So you will have to do that. Tell us which source line
2245 it is, and what incorrect result happens when that line is executed. A
2246 person who understands the program can find this as easily as finding a
2247 bug in the program itself.
2250 If you send examples of assembler code output from GCC,
2251 please use @option{-g} when you make them. The debugging information
2252 includes source line numbers which are essential for correlating the
2253 output with the input.
2256 If you wish to mention something in the GCC source, refer to it by
2257 context, not by line number.
2259 The line numbers in the development sources don't match those in your
2260 sources. Your line numbers would convey no useful information to the
2264 Additional information from a debugger might enable someone to find a
2265 problem on a machine which he does not have available. However, you
2266 need to think when you collect this information if you want it to have
2267 any chance of being useful.
2269 @cindex backtrace for bug reports
2270 For example, many people send just a backtrace, but that is never
2271 useful by itself. A simple backtrace with arguments conveys little
2272 about GCC because the compiler is largely data-driven; the same
2273 functions are called over and over for different RTL insns, doing
2274 different things depending on the details of the insn.
2276 Most of the arguments listed in the backtrace are useless because they
2277 are pointers to RTL list structure. The numeric values of the
2278 pointers, which the debugger prints in the backtrace, have no
2279 significance whatever; all that matters is the contents of the objects
2280 they point to (and most of the contents are other such pointers).
2282 In addition, most compiler passes consist of one or more loops that
2283 scan the RTL insn sequence. The most vital piece of information about
2284 such a loop---which insn it has reached---is usually in a local variable,
2288 What you need to provide in addition to a backtrace are the values of
2289 the local variables for several stack frames up. When a local
2290 variable or an argument is an RTX, first print its value and then use
2291 the GDB command @code{pr} to print the RTL expression that it points
2292 to. (If GDB doesn't run on your machine, use your debugger to call
2293 the function @code{debug_rtx} with the RTX as an argument.) In
2294 general, whenever a variable is a pointer, its value is no use
2295 without the data it points to.
2298 Here are some things that are not necessary:
2302 A description of the envelope of the bug.
2304 Often people who encounter a bug spend a lot of time investigating
2305 which changes to the input file will make the bug go away and which
2306 changes will not affect it.
2308 This is often time consuming and not very useful, because the way we
2309 will find the bug is by running a single example under the debugger with
2310 breakpoints, not by pure deduction from a series of examples. You might
2311 as well save your time for something else.
2313 Of course, if you can find a simpler example to report @emph{instead} of
2314 the original one, that is a convenience. Errors in the output will be
2315 easier to spot, running under the debugger will take less time, etc.
2316 Most GCC bugs involve just one function, so the most straightforward
2317 way to simplify an example is to delete all the function definitions
2318 except the one where the bug occurs. Those earlier in the file may be
2319 replaced by external declarations if the crucial function depends on
2320 them. (Exception: inline functions may affect compilation of functions
2321 defined later in the file.)
2323 However, simplification is not vital; if you don't want to do this,
2324 report the bug anyway and send the entire test case you used.
2327 In particular, some people insert conditionals @samp{#ifdef BUG} around
2328 a statement which, if removed, makes the bug not happen. These are just
2329 clutter; we won't pay any attention to them anyway. Besides, you should
2330 send us cpp output, and that can't have conditionals.
2333 A patch for the bug.
2335 A patch for the bug is useful if it is a good one. But don't omit the
2336 necessary information, such as the test case, on the assumption that a
2337 patch is all we need. We might see problems with your patch and decide
2338 to fix the problem another way, or we might not understand it at all.
2340 Sometimes with a program as complicated as GCC it is very hard to
2341 construct an example that will make the program follow a certain path
2342 through the code. If you don't send the example, we won't be able to
2343 construct one, so we won't be able to verify that the bug is fixed.
2345 And if we can't understand what bug you are trying to fix, or why your
2346 patch should be an improvement, we won't install it. A test case will
2347 help us to understand.
2349 @xref{Sending Patches}, for guidelines on how to make it easy for us to
2350 understand and install your patches.
2353 A guess about what the bug is or what it depends on.
2355 Such guesses are usually wrong. Even I can't guess right about such
2356 things without first using the debugger to find the facts.
2361 We have no way of examining a core dump for your type of machine
2362 unless we have an identical system---and if we do have one,
2363 we should be able to reproduce the crash ourselves.
2366 @node gccbug,Sending Patches, Bug Reporting, Bugs
2367 @section The gccbug script
2368 @cindex gccbug script
2370 To simplify creation of bug reports, and to allow better tracking of
2371 reports, we use the GNATS bug tracking system. Part of that system is
2372 the @code{gccbug} script. This is a Unix shell script, so you need a
2373 shell to run it. It is normally installed in the same directory where
2374 @code{gcc} is installed.
2376 The gccbug script is derived from send-pr, @pxref{using
2377 send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
2378 invoked, it starts a text editor so you can fill out the various fields
2379 of the report. When the you quit the editor, the report is automatically
2380 send to the bug reporting address.
2382 A number of fields in this bug report form are specific to GCC, and are
2383 explained at @uref{http://gcc.gnu.org/gnats.html}.
2385 @node Sending Patches,, gccbug, Bugs
2386 @section Sending Patches for GCC
2388 If you would like to write bug fixes or improvements for the GNU C
2389 compiler, that is very helpful. Send suggested fixes to the patches
2390 mailing list, @email{gcc-patches@@gcc.gnu.org}.
2392 Please follow these guidelines so we can study your patches efficiently.
2393 If you don't follow these guidelines, your information might still be
2394 useful, but using it will take extra work. Maintaining GCC is a lot
2395 of work in the best of circumstances, and we can't keep up unless you do
2400 Send an explanation with your changes of what problem they fix or what
2401 improvement they bring about. For a bug fix, just include a copy of the
2402 bug report, and explain why the change fixes the bug.
2404 (Referring to a bug report is not as good as including it, because then
2405 we will have to look it up, and we have probably already deleted it if
2406 we've already fixed the bug.)
2409 Always include a proper bug report for the problem you think you have
2410 fixed. We need to convince ourselves that the change is right before
2411 installing it. Even if it is right, we might have trouble judging it if
2412 we don't have a way to reproduce the problem.
2415 Include all the comments that are appropriate to help people reading the
2416 source in the future understand why this change was needed.
2419 Don't mix together changes made for different reasons.
2420 Send them @emph{individually}.
2422 If you make two changes for separate reasons, then we might not want to
2423 install them both. We might want to install just one. If you send them
2424 all jumbled together in a single set of diffs, we have to do extra work
2425 to disentangle them---to figure out which parts of the change serve
2426 which purpose. If we don't have time for this, we might have to ignore
2427 your changes entirely.
2429 If you send each change as soon as you have written it, with its own
2430 explanation, then the two changes never get tangled up, and we can
2431 consider each one properly without any extra work to disentangle them.
2433 Ideally, each change you send should be impossible to subdivide into
2434 parts that we might want to consider separately, because each of its
2435 parts gets its motivation from the other parts.
2438 Send each change as soon as that change is finished. Sometimes people
2439 think they are helping us by accumulating many changes to send them all
2440 together. As explained above, this is absolutely the worst thing you
2443 Since you should send each change separately, you might as well send it
2444 right away. That gives us the option of installing it immediately if it
2448 Use @samp{diff -c} to make your diffs. Diffs without context are hard
2449 for us to install reliably. More than that, they make it hard for us to
2450 study the diffs to decide whether we want to install them. Unidiff
2451 format is better than contextless diffs, but not as easy to read as
2454 If you have GNU diff, use @samp{diff -cp}, which shows the name of the
2455 function that each change occurs in.
2458 Write the change log entries for your changes. We get lots of changes,
2459 and we don't have time to do all the change log writing ourselves.
2461 Read the @file{ChangeLog} file to see what sorts of information to put
2462 in, and to learn the style that we use. The purpose of the change log
2463 is to show people where to find what was changed. So you need to be
2464 specific about what functions you changed; in large functions, it's
2465 often helpful to indicate where within the function the change was.
2467 On the other hand, once you have shown people where to find the change,
2468 you need not explain its purpose. Thus, if you add a new function, all
2469 you need to say about it is that it is new. If you feel that the
2470 purpose needs explaining, it probably does---but the explanation will be
2471 much more useful if you put it in comments in the code.
2473 If you would like your name to appear in the header line for who made
2474 the change, send us the header line.
2477 When you write the fix, keep in mind that we can't install a change that
2478 would break other systems.
2480 People often suggest fixing a problem by changing machine-independent
2481 files such as @file{toplev.c} to do something special that a particular
2482 system needs. Sometimes it is totally obvious that such changes would
2483 break GCC for almost all users. We can't possibly make a change like
2484 that. At best it might tell us how to write another patch that would
2485 solve the problem acceptably.
2487 Sometimes people send fixes that @emph{might} be an improvement in
2488 general---but it is hard to be sure of this. It's hard to install
2489 such changes because we have to study them very carefully. Of course,
2490 a good explanation of the reasoning by which you concluded the change
2491 was correct can help convince us.
2493 The safest changes are changes to the configuration files for a
2494 particular machine. These are safe because they can't create new bugs
2497 Please help us keep up with the workload by designing the patch in a
2498 form that is good to install.
2502 @chapter How To Get Help with GCC
2504 If you need help installing, using or changing GCC, there are two
2509 Send a message to a suitable network mailing list. First try
2510 @email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
2511 that brings no response, try @email{gcc@@gcc.gnu.org}. For help
2512 changing GCC, ask @email{gcc@@gcc.gnu.org}. If you think you have found
2513 a bug in GCC, please report it following the instructions at
2514 @pxref{Bug Reporting}.
2517 Look in the service directory for someone who might help you for a fee.
2518 The service directory is found at
2519 @uref{http://www.gnu.org/prep/service.html}.
2522 @c For further information, see
2523 @c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}.
2524 @c FIXME: this URL may be too volatile, this FAQ entry needs to move to
2525 @c the regular web pages before we can uncomment the reference.
2528 @chapter Contributing to GCC Development
2530 If you would like to help pretest GCC releases to assure they work well,
2531 our current development sources are available by CVS (see
2532 @uref{http://gcc.gnu.org/cvs.html}). Source and binary snapshots are
2533 also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
2535 If you would like to work on improvements to GCC, please read the
2536 advice at these URLs:
2539 @uref{http://gcc.gnu.org/contribute.html}
2540 @uref{http://gcc.gnu.org/contributewhy.html}
2544 for information on how to make useful contributions and avoid
2545 duplication of effort. Suggested projects are listed at
2546 @uref{http://gcc.gnu.org/projects/}.
2549 @chapter Using GCC on VMS
2551 @c prevent bad page break with this line
2552 Here is how to use GCC on VMS@.
2555 * Include Files and VMS:: Where the preprocessor looks for the include files.
2556 * Global Declarations:: How to do globaldef, globalref and globalvalue with
2558 * VMS Misc:: Misc information.
2561 @node Include Files and VMS
2562 @section Include Files and VMS
2564 @cindex include files and VMS
2565 @cindex VMS and include files
2566 @cindex header files and VMS
2567 Due to the differences between the filesystems of Unix and VMS, GCC
2568 attempts to translate file names in @samp{#include} into names that VMS
2569 will understand. The basic strategy is to prepend a prefix to the
2570 specification of the include file, convert the whole filename to a VMS
2571 filename, and then try to open the file. GCC tries various prefixes
2572 one by one until one of them succeeds:
2576 The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
2577 where GNU C header files are traditionally stored. If you wish to store
2578 header files in non-standard locations, then you can assign the logical
2579 @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
2580 list is suitable for use with a rooted logical.
2583 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where
2584 VAX-C header files are traditionally stored.
2587 If the include file specification by itself is a valid VMS filename, the
2588 preprocessor then uses this name with no prefix in an attempt to open
2592 If the file specification is not a valid VMS filename (i.e.@: does not
2593 contain a device or a directory specifier, and contains a @samp{/}
2594 character), the preprocessor tries to convert it from Unix syntax to
2597 Conversion works like this: the first directory name becomes a device,
2598 and the rest of the directories are converted into VMS-format directory
2599 names. For example, the name @file{X11/foobar.h} is
2600 translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
2601 whichever one can be opened. This strategy allows you to assign a
2602 logical name to point to the actual location of the header files.
2605 If none of these strategies succeeds, the @samp{#include} fails.
2608 Include directives of the form:
2615 are a common source of incompatibility between VAX-C and GCC@. VAX-C
2616 treats this much like a standard @code{#include <foobar.h>} directive.
2617 That is incompatible with the ISO C behavior implemented by GCC: to
2618 expand the name @code{foobar} as a macro. Macro expansion should
2619 eventually yield one of the two standard formats for @code{#include}:
2622 #include "@var{file}"
2623 #include <@var{file}>
2626 If you have this problem, the best solution is to modify the source to
2627 convert the @code{#include} directives to one of the two standard forms.
2628 That will work with either compiler. If you want a quick and dirty fix,
2629 define the file names as macros with the proper expansion, like this:
2632 #define stdio <stdio.h>
2636 This will work, as long as the name doesn't conflict with anything else
2639 Another source of incompatibility is that VAX-C assumes that:
2646 is actually asking for the file @file{foobar.h}. GCC does not
2647 make this assumption, and instead takes what you ask for literally;
2648 it tries to read the file @file{foobar}. The best way to avoid this
2649 problem is to always specify the desired file extension in your include
2652 GCC for VMS is distributed with a set of include files that is
2653 sufficient to compile most general purpose programs. Even though the
2654 GCC distribution does not contain header files to define constants
2655 and structures for some VMS system-specific functions, there is no
2656 reason why you cannot use GCC with any of these functions. You first
2657 may have to generate or create header files, either by using the public
2658 domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
2659 extracting the relevant modules from one of the system macro libraries,
2660 and using an editor to construct a C header file.
2662 A @code{#include} file name cannot contain a DECNET node name. The
2663 preprocessor reports an I/O error if you attempt to use a node name,
2664 whether explicitly, or implicitly via a logical name.
2666 @node Global Declarations
2667 @section Global Declarations and VMS
2671 @findex GLOBALVALUEDEF
2672 @findex GLOBALVALUEREF
2673 GCC does not provide the @code{globalref}, @code{globaldef} and
2674 @code{globalvalue} keywords of VAX-C@. You can get the same effect with
2675 an obscure feature of GAS, the GNU assembler. (This requires GAS
2676 version 1.39 or later.) The following macros allow you to use this
2677 feature in a fairly natural way:
2681 #define GLOBALREF(TYPE,NAME) \
2683 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
2684 #define GLOBALDEF(TYPE,NAME,VALUE) \
2686 asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
2688 #define GLOBALVALUEREF(TYPE,NAME) \
2689 const TYPE NAME[1] \
2690 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
2691 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2692 const TYPE NAME[1] \
2693 asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \
2696 #define GLOBALREF(TYPE,NAME) \
2698 #define GLOBALDEF(TYPE,NAME,VALUE) \
2699 globaldef TYPE NAME = VALUE
2700 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
2701 globalvalue TYPE NAME = VALUE
2702 #define GLOBALVALUEREF(TYPE,NAME) \
2703 globalvalue TYPE NAME
2708 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
2709 name is removed by the assembler, after it has modified the attributes
2710 of the symbol). These macros are provided in the VMS binaries
2711 distribution in a header file @file{GNU_HACKS.H}. An example of the
2715 GLOBALREF (int, ijk);
2716 GLOBALDEF (int, jkl, 0);
2719 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
2720 straightforwardly for arrays, since there is no way to insert the array
2721 dimension into the declaration at the right place. However, you can
2722 declare an array with these macros if you first define a typedef for the
2723 array type, like this:
2726 typedef int intvector[10];
2727 GLOBALREF (intvector, foo);
2730 Array and structure initializers will also break the macros; you can
2731 define the initializer to be a macro of its own, or you can expand the
2732 @code{GLOBALDEF} macro by hand. You may find a case where you wish to
2733 use the @code{GLOBALDEF} macro with a large array, but you are not
2734 interested in explicitly initializing each element of the array. In
2735 such cases you can use an initializer like: @code{@{0,@}}, which will
2736 initialize the entire array to @code{0}.
2738 A shortcoming of this implementation is that a variable declared with
2739 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For
2740 example, the declaration:
2743 GLOBALVALUEREF(int, ijk);
2747 declares the variable @code{ijk} as an array of type @code{int [1]}.
2748 This is done because a globalvalue is actually a constant; its ``value''
2749 is what the linker would normally consider an address. That is not how
2750 an integer value works in C, but it is how an array works. So treating
2751 the symbol as an array name gives consistent results---with the
2752 exception that the value seems to have the wrong type. @strong{Don't
2753 try to access an element of the array.} It doesn't have any elements.
2754 The array ``address'' may not be the address of actual storage.
2756 The fact that the symbol is an array may lead to warnings where the
2757 variable is used. Insert type casts to avoid the warnings. Here is an
2758 example; it takes advantage of the ISO C feature allowing macros that
2759 expand to use the same name as the macro itself.
2762 GLOBALVALUEREF (int, ss$_normal);
2763 GLOBALVALUEDEF (int, xyzzy,123);
2765 #define ss$_normal ((int) ss$_normal)
2766 #define xyzzy ((int) xyzzy)
2770 Don't use @code{globaldef} or @code{globalref} with a variable whose
2771 type is an enumeration type; this is not implemented. Instead, make the
2772 variable an integer, and use a @code{globalvaluedef} for each of the
2773 enumeration values. An example of this would be:
2777 GLOBALDEF (int, color, 0);
2778 GLOBALVALUEDEF (int, RED, 0);
2779 GLOBALVALUEDEF (int, BLUE, 1);
2780 GLOBALVALUEDEF (int, GREEN, 3);
2782 enum globaldef color @{RED, BLUE, GREEN = 3@};
2787 @section Other VMS Issues
2789 @cindex exit status and VMS
2790 @cindex return value of @code{main}
2791 @cindex @code{main} and the exit status
2792 GCC automatically arranges for @code{main} to return 1 by default if
2793 you fail to specify an explicit return value. This will be interpreted
2794 by VMS as a status code indicating a normal successful completion.
2795 Version 1 of GCC did not provide this default.
2797 GCC on VMS works only with the GNU assembler, GAS@. You need version
2798 1.37 or later of GAS in order to produce value debugging information for
2799 the VMS debugger. Use the ordinary VMS linker with the object files
2802 @cindex shared VMS run time system
2803 @cindex @file{VAXCRTL}
2804 Under previous versions of GCC, the generated code would occasionally
2805 give strange results when linked to the sharable @file{VAXCRTL} library.
2806 Now this should work.
2808 A caveat for use of @code{const} global variables: the @code{const}
2809 modifier must be specified in every external declaration of the variable
2810 in all of the source files that use that variable. Otherwise the linker
2811 will issue warnings about conflicting attributes for the variable. Your
2812 program will still work despite the warnings, but the variable will be
2813 placed in writable storage.
2815 @cindex name augmentation
2816 @cindex case sensitivity and VMS
2817 @cindex VMS and case sensitivity
2818 Although the VMS linker does distinguish between upper and lower case
2819 letters in global symbols, most VMS compilers convert all such symbols
2820 into upper case and most run-time library routines also have upper case
2821 names. To be able to reliably call such routines, GCC (by means of
2822 the assembler GAS) converts global symbols into upper case like other
2823 VMS compilers. However, since the usual practice in C is to distinguish
2824 case, GCC (via GAS) tries to preserve usual C behavior by augmenting
2825 each name that is not all lower case. This means truncating the name
2826 to at most 23 characters and then adding more characters at the end
2827 which encode the case pattern of those 23. Names which contain at
2828 least one dollar sign are an exception; they are converted directly into
2829 upper case without augmentation.
2831 Name augmentation yields bad results for programs that use precompiled
2832 libraries (such as Xlib) which were generated by another compiler. You
2833 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
2834 it makes external C functions and variables case-independent as is usual
2835 on VMS@. Alternatively, you could write all references to the functions
2836 and variables in such libraries using lower case; this will work on VMS,
2837 but is not portable to other systems. The compiler option @samp{/NAMES}
2838 also provides control over global name handling.
2840 Function and variable names are handled somewhat differently with G++.
2841 The GNU C++ compiler performs @dfn{name mangling} on function
2842 names, which means that it adds information to the function name to
2843 describe the data types of the arguments that the function takes. One
2844 result of this is that the name of a function can become very long.
2845 Since the VMS linker only recognizes the first 31 characters in a name,
2846 special action is taken to ensure that each function and variable has a
2847 unique name that can be represented in 31 characters.
2849 If the name (plus a name augmentation, if required) is less than 32
2850 characters in length, then no special action is performed. If the name
2851 is longer than 31 characters, the assembler (GAS) will generate a
2852 hash string based upon the function name, truncate the function name to
2853 23 characters, and append the hash string to the truncated name. If the
2854 @samp{/VERBOSE} compiler option is used, the assembler will print both
2855 the full and truncated names of each symbol that is truncated.
2857 The @samp{/NOCASE_HACK} compiler option should not be used when you are
2858 compiling programs that use libg++. libg++ has several instances of
2859 objects (i.e. @code{Filebuf} and @code{filebuf}) which become
2860 indistinguishable in a case-insensitive environment. This leads to
2861 cases where you need to inhibit augmentation selectively (if you were
2862 using libg++ and Xlib in the same program, for example). There is no
2863 special feature for doing this, but you can get the result by defining a
2864 macro for each mixed case symbol for which you wish to inhibit
2865 augmentation. The macro should expand into the lower case equivalent of
2866 itself. For example:
2869 #define StuDlyCapS studlycaps
2872 These macro definitions can be placed in a header file to minimize the
2873 number of changes to your source code.
2876 @chapter Additional Makefile and configure information.
2878 @section Makefile Targets
2879 @cindex makefile targets
2880 @cindex targets, makefile
2884 This is the default target. Depending on what your build/host/target
2885 configuration is, it coordinates all the things that need to be built.
2888 Produce info-formatted documentation. Also, @code{make dvi} is
2889 available for DVI-formatted documentation, and @code{make
2890 generated-manpages} to generate man pages.
2893 Delete the files made while building the compiler.
2896 That, and all the other files built by @code{make all}.
2899 That, and all the files created by @code{configure}.
2902 That, and any temporary or intermediate files, like emacs backup files.
2904 @item maintainer-clean
2905 Distclean plus any file that can be generated from other files. Note
2906 that additional tools may be required beyond what is normally needed to
2913 Deletes installed files.
2916 Run the testsuite. This creates a @file{testsuite} subdirectory that
2917 has various @file{.sum} and @file{.log} files containing the results of
2918 the testing. You can run subsets with, for example, @code{make check-gcc}.
2919 You can specify specific tests by setting RUNTESTFLAGS to be the name
2920 of the @file{.exp} file, optionally followed by (for some tests) an equals
2921 and a file wildcard, like:
2924 make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
2927 Note that running the testsuite may require additional tools be
2928 installed, such as TCL or dejagnu.
2931 Builds gcc three times---once with the native compiler, once with the
2932 native-built compiler it just built, and once with the compiler it built
2933 the second time. In theory, the last two should produce the same
2934 results, which @code{make compare} can check. Each step of this process
2935 is called a ``stage'', and the results of each stage @var{N}
2936 (@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}.
2938 @item bootstrap-lean
2939 Like @code{bootstrap}, except that the various stages are removed once
2940 they're no longer needed. This saves disk space.
2943 Once bootstrapped, this incrementally rebuilds each of the three stages,
2944 one at a time. It does this by ``bubbling'' the stages up from their
2945 subdirectories, rebuilding them, and copying them back to their
2946 subdirectories. This will allow you to, for example, quickly rebuild a
2947 bootstrapped compiler after changing the sources, without having to do a
2951 Rebuilds the most recently built stage. Since each stage requires
2952 special invocation, using this target means you don't have to keep track
2953 of which stage you're on or what invocation that stage needs.
2956 Removed everything (@code{make clean}) and rebuilds (@code{make bootstrap}).
2958 @item stage@var{N} (@var{N} = 1@dots{}4)
2959 For each stage, moves the appropriate files to the @file{stage@var{N}}
2962 @item unstage@var{N} (@var{N} = 1@dots{}4)
2963 Undoes the corresponding @code{stage@var{N}}.
2965 @item restage@var{N} (@var{N} = 1@dots{}4)
2966 Undoes the corresponding @code{stage@var{N}} and rebuilds it with the
2970 Compares the results of stages 2 and 3. This ensures that the compiler
2971 is running properly, since it should produce the same object files
2972 regardless of how it itself was compiled.
2976 @section Configure Terms and History
2977 @cindex configure terms
2980 This section is not instructions for building GCC. If you are trying to
2981 do a build, you should first read @uref{http://gcc.gnu.org/install/} or
2982 whatever installation instructions came with your source package.
2984 The configure and build process has a long and colorful history, and can
2985 be confusing to anyone who doesn't know why things are the way they are.
2986 While there are other documents which describe the configuration process
2987 in detail, here are a few things that everyone working on GCC should
2990 There are three system names that the build knows about: the machine you
2991 are building on (@dfn{build}), the machine that you are building for
2992 (@dfn{host}), and the machine that GCC will produce code for
2993 (@dfn{target}). When you configure GCC, you specify these with
2994 @option{--build=}, @option{--host=}, and @option{--target=}.
2996 Specifying the host without specifying the build should be avoided, as
2997 @command{configure} may (and once did) assume that the host you specify
2998 is also the build, which may not be true.
3000 If build, host, and target are all the same, this is called a
3001 @dfn{native}. If build and host are the same but target is different,
3002 this is called a @dfn{cross}. If build, host, and target are all
3003 different this is called a @dfn{canadian} (for obscure reasons dealing
3004 with Canada's political party and the background of the person working
3005 on the build at that time). If host and target are the same, but build
3006 is different, you are using a cross-compiler to build a native for a
3007 different system. Some people call this a @dfn{host-x-host},
3008 @dfn{crossed native}, or @dfn{cross-built native}. If build and target
3009 are the same, but host is different, you are using a cross compiler to
3010 build a cross compiler that produces code for the machine you're
3011 building on. This is rare, so there is no common say of describing it
3012 (although I propose calling it a @dfn{crossback}).
3014 If build and host are the same, the GCC you are building will also be
3015 used to build the target libraries (like @code{libstdc++}). If build and host
3016 are different, you must have already build and installed a cross
3017 compiler that will be used to build the target libraries (if you
3018 configured with @option{--target=foo-bar}, this compiler will be called
3019 @command{foo-bar-gcc}).
3021 In the case of target libraries, the machine you're building for is the
3022 machine you specified with @option{--target}. So, build is the machine
3023 you're building on (no change there), host is the machine you're
3024 building for (the target libraries are built for the target, so host is
3025 the target you specified), and target doesn't apply (because you're not
3026 building a compiler, you're building libraries). The configure/make
3027 process will adjust these variables as needed. It also sets
3028 @code{$with_cross_host} to the original @option{--host} value in case you
3031 Libiberty, for example, is built twice. The first time, host comes from
3032 @option{--host} and the second time host comes from @option{--target}.
3033 Historically, libiberty has not been built for the build machine,
3034 though, which causes some interesting issues with programs used to
3035 generate sources for the build. Fixing this, so that libiberty is built
3036 three times, has long been on the to-do list.
3042 @chapter GCC and Portability
3044 @cindex GCC and portability
3046 The main goal of GCC was to make a good, fast compiler for machines in
3047 the class that the GNU system aims to run on: 32-bit machines that address
3048 8-bit bytes and have several general registers. Elegance, theoretical
3049 power and simplicity are only secondary.
3051 GCC gets most of the information about the target machine from a machine
3052 description which gives an algebraic formula for each of the machine's
3053 instructions. This is a very clean way to describe the target. But when
3054 the compiler needs information that is difficult to express in this
3055 fashion, I have not hesitated to define an ad-hoc parameter to the machine
3056 description. The purpose of portability is to reduce the total work needed
3057 on the compiler; it was not of interest for its own sake.
3060 @cindex autoincrement addressing, availability
3062 GCC does not contain machine dependent code, but it does contain code
3063 that depends on machine parameters such as endianness (whether the most
3064 significant byte has the highest or lowest address of the bytes in a word)
3065 and the availability of autoincrement addressing. In the RTL-generation
3066 pass, it is often necessary to have multiple strategies for generating code
3067 for a particular kind of syntax tree, strategies that are usable for different
3068 combinations of parameters. Often I have not tried to address all possible
3069 cases, but only the common ones or only the ones that I have encountered.
3070 As a result, a new target may require additional strategies. You will know
3071 if this happens because the compiler will call @code{abort}. Fortunately,
3072 the new strategies can be added in a machine-independent fashion, and will
3073 affect only the target machines that need them.
3078 @chapter Interfacing to GCC Output
3079 @cindex interfacing to GCC output
3080 @cindex run-time conventions
3081 @cindex function call conventions
3082 @cindex conventions, run-time
3084 GCC is normally configured to use the same function calling convention
3085 normally in use on the target system. This is done with the
3086 machine-description macros described (@pxref{Target Macros}).
3088 @cindex unions, returning
3089 @cindex structures, returning
3090 @cindex returning structures and unions
3091 However, returning of structure and union values is done differently on
3092 some target machines. As a result, functions compiled with PCC
3093 returning such types cannot be called from code compiled with GCC,
3094 and vice versa. This does not cause trouble often because few Unix
3095 library routines return structures or unions.
3097 GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
3098 long in the same registers used for @code{int} or @code{double} return
3099 values. (GCC typically allocates variables of such types in
3100 registers also.) Structures and unions of other sizes are returned by
3101 storing them into an address passed by the caller (usually in a
3102 register). The machine-description macros @code{STRUCT_VALUE} and
3103 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
3105 By contrast, PCC on most target machines returns structures and unions
3106 of any size by copying the data into an area of static storage, and then
3107 returning the address of that storage as if it were a pointer value.
3108 The caller must copy the data from that memory area to the place where
3109 the value is wanted. This is slower than the method used by GCC, and
3110 fails to be reentrant.
3112 On some target machines, such as RISC machines and the 80386, the
3113 standard system convention is to pass to the subroutine the address of
3114 where to return the value. On these machines, GCC has been
3115 configured to be compatible with the standard compiler, when this method
3116 is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3118 @cindex argument passing
3119 @cindex passing arguments
3120 GCC uses the system's standard convention for passing arguments. On
3121 some machines, the first few arguments are passed in registers; in
3122 others, all are passed on the stack. It would be possible to use
3123 registers for argument passing on any machine, and this would probably
3124 result in a significant speedup. But the result would be complete
3125 incompatibility with code that follows the standard convention. So this
3126 change is practical only if you are switching to GCC as the sole C
3127 compiler for the system. We may implement register argument passing on
3128 certain machines once we have a complete GNU system so that we can
3129 compile the libraries with GCC@.
3131 On some machines (particularly the Sparc), certain types of arguments
3132 are passed ``by invisible reference''. This means that the value is
3133 stored in memory, and the address of the memory location is passed to
3136 @cindex @code{longjmp} and automatic variables
3137 If you use @code{longjmp}, beware of automatic variables. ISO C says that
3138 automatic variables that are not declared @code{volatile} have undefined
3139 values after a @code{longjmp}. And this is all GCC promises to do,
3140 because it is very difficult to restore register variables correctly, and
3141 one of GCC's features is that it can put variables in registers without
3144 If you want a variable to be unaltered by @code{longjmp}, and you don't
3145 want to write @code{volatile} because old C compilers don't accept it,
3146 just take the address of the variable. If a variable's address is ever
3147 taken, even if just to compute it and ignore it, then the variable cannot
3158 @cindex arithmetic libraries
3159 @cindex math libraries
3160 @opindex msoft-float
3161 Code compiled with GCC may call certain library routines. Most of
3162 them handle arithmetic for which there are no instructions. This
3163 includes multiply and divide on some machines, and floating point
3164 operations on any machine for which floating point support is disabled
3165 with @option{-msoft-float}. Some standard parts of the C library, such as
3166 @code{bcopy} or @code{memcpy}, are also called automatically. The usual
3167 function call interface is used for calling the library routines.
3169 Some of these routines can be defined in mostly machine-independent C;
3170 they appear in @file{libgcc2.c}. Others must be hand-written in
3171 assembly language for each processor. Wherever they are defined, they
3172 are compiled into the support library, @file{libgcc.a}, which is
3173 automatically searched when you link programs with GCC@.
3178 @chapter Passes and Files of the Compiler
3179 @cindex passes and files of the compiler
3180 @cindex files and passes of the compiler
3181 @cindex compiler passes and files
3183 @cindex top level of compiler
3184 The overall control structure of the compiler is in @file{toplev.c}. This
3185 file is responsible for initialization, decoding arguments, opening and
3186 closing files, and sequencing the passes.
3188 @cindex parsing pass
3189 The parsing pass is invoked only once, to parse the entire input. A
3190 high level tree representation is then generated from the input,
3191 one function at a time. This tree code is then transformed into RTL
3192 intermediate code, and processed. The files involved in transforming
3193 the trees into RTL are @file{expr.c}, @file{expmed.c}, and
3195 @c Note, the above files aren't strictly the only files involved. It's
3196 @c all over the place (function.c, final.c,etc). However, those are
3197 @c the files that are supposed to be directly involved, and have
3198 @c their purpose listed as such, so i've only listed them.
3199 The order of trees that are processed, is not
3200 necessarily the same order they are generated from
3201 the input, due to deferred inlining, and other considerations.
3203 @findex rest_of_compilation
3204 @findex rest_of_decl_compilation
3205 Each time the parsing pass reads a complete function definition or
3206 top-level declaration, it calls either the function
3207 @code{rest_of_compilation}, or the function
3208 @code{rest_of_decl_compilation} in @file{toplev.c}, which are
3209 responsible for all further processing necessary, ending with output of
3210 the assembler language. All other compiler passes run, in sequence,
3211 within @code{rest_of_compilation}. When that function returns from
3212 compiling a function definition, the storage used for that function
3213 definition's compilation is entirely freed, unless it is an inline
3214 function, or was deferred for some reason (this can occur in
3215 templates, for example).
3217 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3220 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3223 Here is a list of all the passes of the compiler and their source files.
3224 Also included is a description of where debugging dumps can be requested
3225 with @option{-d} options.
3229 Parsing. This pass reads the entire text of a function definition,
3230 constructing a high level tree representation. (Because of the semantic
3231 analysis that takes place during this pass, it does more than is
3232 formally considered to be parsing.)
3234 The tree representation does not entirely follow C syntax, because it is
3235 intended to support other languages as well.
3237 Language-specific data type analysis is also done in this pass, and every
3238 tree node that represents an expression has a data type attached.
3239 Variables are represented as declaration nodes.
3241 The language-independent source files for parsing are
3242 @file{tree.c}, @file{fold-const.c}, and @file{stor-layout.c}.
3243 There are also header files @file{tree.h} and @file{tree.def}
3244 which define the format of the tree representation.
3246 C preprocessing, for language front ends, that want or require it, is
3247 performed by cpplib, which is covered in separate documentation. In
3248 particular, the internals are covered in @xref{Top, ,Cpplib internals,
3249 cppinternals, Cpplib Internals}.
3251 @c Avoiding overfull is tricky here.
3252 The source files to parse C are
3258 @file{c-aux-info.c},
3261 along with a header file
3263 and some files shared with Objective-C and C++.
3265 The source files for parsing C++ are in @file{cp/}.
3266 They are @file{parse.y},
3268 @file{cvt.c}, @file{decl.c}, @file{decl2.c},
3270 @file{expr.c}, @file{init.c}, @file{lex.c},
3271 @file{method.c}, @file{ptree.c},
3272 @file{search.c}, @file{spew.c},
3273 @file{semantics.c}, @file{tree.c},
3274 @file{typeck2.c}, and
3275 @file{typeck.c}, along with header files @file{cp-tree.def},
3276 @file{cp-tree.h}, and @file{decl.h}.
3278 The special source files for parsing Objective-C are in @file{objc/}.
3279 They are @file{objc-act.c}, @file{objc-tree.def}, and @file{objc-act.h}.
3280 Certain C-specific files are used for this as well.
3284 @file{c-common.def},
3288 @file{c-semantics.c},
3291 along with header files
3297 are also used for all of the above languages.
3300 @cindex Tree optimization
3302 Tree optimization. This is the optimization of the tree
3303 representation, before converting into RTL code.
3305 @cindex inline on trees, automatic
3306 Currently, the main optimization performed here is tree-based
3308 This is implemented for C++ in @file{cp/optimize.c}. Note that
3309 tree based inlining turns off rtx based inlining (since it's more
3310 powerful, it would be a waste of time to do rtx based inlining in
3312 The C front end currently does not perform tree based inlining.
3314 @cindex constant folding
3315 @cindex arithmetic simplifications
3316 @cindex simplifications, arithmetic
3317 Constant folding and some arithmetic simplifications are also done
3318 during this pass, on the tree representation.
3319 The routines that perform these tasks are located in @file{fold-const.c}.
3321 @cindex RTL generation
3323 RTL generation. This is the conversion of syntax tree into RTL code.
3325 @cindex target-parameter-dependent code
3326 This is where the bulk of target-parameter-dependent code is found,
3327 since often it is necessary for strategies to apply only when certain
3328 standard kinds of instructions are available. The purpose of named
3329 instruction patterns is to provide this information to the RTL
3332 @cindex tail recursion optimization
3333 Optimization is done in this pass for @code{if}-conditions that are
3334 comparisons, boolean operations or conditional expressions. Tail
3335 recursion is detected at this time also. Decisions are made about how
3336 best to arrange loops and how to output @code{switch} statements.
3338 @c Avoiding overfull is tricky here.
3339 The source files for RTL generation include
3347 and @file{emit-rtl.c}.
3349 @file{insn-emit.c}, generated from the machine description by the
3350 program @code{genemit}, is used in this pass. The header file
3351 @file{expr.h} is used for communication within this pass.
3355 The header files @file{insn-flags.h} and @file{insn-codes.h},
3356 generated from the machine description by the programs @code{genflags}
3357 and @code{gencodes}, tell this pass which standard names are available
3358 for use and which patterns correspond to them.
3360 Aside from debugging information output, none of the following passes
3361 refers to the tree structure representation of the function (only
3362 part of which is saved).
3364 @cindex inline on rtx, automatic
3365 The decision of whether the function can and should be expanded inline
3366 in its subsequent callers is made at the end of rtl generation. The
3367 function must meet certain criteria, currently related to the size of
3368 the function and the types and number of parameters it has. Note that
3369 this function may contain loops, recursive calls to itself
3370 (tail-recursive functions can be inlined!), gotos, in short, all
3371 constructs supported by GCC@. The file @file{integrate.c} contains
3372 the code to save a function's rtl for later inlining and to inline that
3373 rtl when the function is called. The header file @file{integrate.h}
3374 is also used for this purpose.
3377 The option @option{-dr} causes a debugging dump of the RTL code after
3378 this pass. This dump file's name is made by appending @samp{.rtl} to
3379 the input file name.
3381 @c Should the exception handling pass be talked about here?
3383 @cindex sibling call optimization
3385 Sibiling call optimization. This pass performs tail recursion
3386 elimination, and tail and sibling call optimizations. The purpose of
3387 these optimizations is to reduce the overhead of function calls,
3390 The source file of this pass is @file{sibcall.c}
3393 The option @option{-di} causes a debugging dump of the RTL code after
3394 this pass is run. This dump file's name is made by appending
3395 @samp{.sibling} to the input file name.
3397 @cindex jump optimization
3398 @cindex unreachable code
3401 Jump optimization. This pass simplifies jumps to the following
3402 instruction, jumps across jumps, and jumps to jumps. It deletes
3403 unreferenced labels and unreachable code, except that unreachable code
3404 that contains a loop is not recognized as unreachable in this pass.
3405 (Such loops are deleted later in the basic block analysis.) It also
3406 converts some code originally written with jumps into sequences of
3407 instructions that directly set values from the results of comparisons,
3408 if the machine has such instructions.
3410 Jump optimization is performed two or three times. The first time is
3411 immediately following RTL generation. The second time is after CSE,
3412 but only if CSE says repeated jump optimization is needed. The
3413 last time is right before the final pass. That time, cross-jumping
3414 and deletion of no-op move instructions are done together with the
3415 optimizations described above.
3417 The source file of this pass is @file{jump.c}.
3420 The option @option{-dj} causes a debugging dump of the RTL code after
3421 this pass is run for the first time. This dump file's name is made by
3422 appending @samp{.jump} to the input file name.
3425 @cindex register use analysis
3427 Register scan. This pass finds the first and last use of each
3428 register, as a guide for common subexpression elimination. Its source
3429 is in @file{regclass.c}.
3431 @cindex jump threading
3433 @opindex fthread-jumps
3434 Jump threading. This pass detects a condition jump that branches to an
3435 identical or inverse test. Such jumps can be @samp{threaded} through
3436 the second conditional test. The source code for this pass is in
3437 @file{jump.c}. This optimization is only performed if
3438 @option{-fthread-jumps} is enabled.
3440 @cindex SSA optimizations
3441 @cindex Single Static Assignment optimizations
3444 Static Single Assignment (SSA) based optimization passes. The
3445 SSA conversion passes (to/from) are turned on by the @option{-fssa}
3446 option (it is also done automatically if you enable an SSA optimization pass).
3447 These passes utilize a form called Static Single Assignment. In SSA form,
3448 each variable (pseudo register) is only set once, giving you def-use
3449 and use-def chains for free, and enabling a lot more optimization
3450 passes to be run in linear time.
3451 Conversion to and from SSA form is handled by functions in
3455 The option @option{-de} causes a debugging dump of the RTL code after
3456 this pass. This dump file's name is made by appending @samp{.ssa} to
3457 the input file name.
3459 @cindex SSA Conditional Constant Propagation
3460 @cindex Conditional Constant Propagation, SSA based
3461 @cindex conditional constant propagation
3464 SSA Conditional Constant Propagation. Turned on by the @option{-fssa-ccp}
3465 SSA Aggressive Dead Code Elimination. Turned on by the @option{-fssa-dce}
3466 option. This pass performs conditional constant propagation to simplify
3467 instructions including conditional branches. This pass is more aggressive
3468 than the constant propgation done by the CSE and GCSE pases, but operates
3472 The option @option{-dW} causes a debugging dump of the RTL code after
3473 this pass. This dump file's name is made by appending @samp{.ssaccp} to
3474 the input file name.
3477 @cindex DCE, SSA based
3478 @cindex dead code elimination
3481 SSA Aggressive Dead Code Elimination. Turned on by the @option{-fssa-dce}
3482 option. This pass performs elimination of code considered unnecessary because
3483 it has no externally visible effects on the program. It operates in
3487 The option @option{-dX} causes a debugging dump of the RTL code after
3488 this pass. This dump file's name is made by appending @samp{.ssadce} to
3489 the input file name.
3492 @cindex common subexpression elimination
3493 @cindex constant propagation
3495 Common subexpression elimination. This pass also does constant
3496 propagation. Its source files are @file{cse.c}, and @file{cselib.c}.
3497 If constant propagation causes conditional jumps to become
3498 unconditional or to become no-ops, jump optimization is run again when
3502 The option @option{-ds} causes a debugging dump of the RTL code after
3503 this pass. This dump file's name is made by appending @samp{.cse} to
3504 the input file name.
3506 @cindex global common subexpression elimination
3507 @cindex constant propagation
3508 @cindex copy propagation
3510 Global common subexpression elimination. This pass performs two
3511 different types of GCSE depending on whether you are optimizing for
3512 size or not (LCM based GCSE tends to increase code size for a gain in
3513 speed, while Morel-Renvoise based GCSE does not).
3514 When optimizing for size, GCSE is done using Morel-Renvoise Partial
3515 Redundancy Elimination, with the exception that it does not try to move
3516 invariants out of loops---that is left to the loop optimization pass.
3517 If MR PRE GCSE is done, code hoisting (aka unification) is also done, as
3518 well as load motion.
3519 If you are optimizing for speed, LCM (lazy code motion) based GCSE is
3520 done. LCM is based on the work of Knoop, Ruthing, and Steffen. LCM
3521 based GCSE also does loop invariant code motion. We also perform load
3522 and store motion when optimizing for speed.
3523 Regardless of which type of GCSE is used, the GCSE pass also performs
3524 global constant and copy propagation.
3526 The source file for this pass is @file{gcse.c}, and the LCM routines
3527 are in @file{lcm.c}.
3530 The option @option{-dG} causes a debugging dump of the RTL code after
3531 this pass. This dump file's name is made by appending @samp{.gcse} to
3532 the input file name.
3534 @cindex loop optimization
3536 @cindex strength-reduction
3538 Loop optimization. This pass moves constant expressions out of loops,
3539 and optionally does strength-reduction and loop unrolling as well.
3540 Its source files are @file{loop.c} and @file{unroll.c}, plus the header
3541 @file{loop.h} used for communication between them. Loop unrolling uses
3542 some functions in @file{integrate.c} and the header @file{integrate.h}.
3543 Loop dependency analysis routines are contained in @file{dependence.c}.
3546 The option @option{-dL} causes a debugging dump of the RTL code after
3547 this pass. This dump file's name is made by appending @samp{.loop} to
3548 the input file name.
3551 @opindex frerun-cse-after-loop
3552 If @option{-frerun-cse-after-loop} was enabled, a second common
3553 subexpression elimination pass is performed after the loop optimization
3554 pass. Jump threading is also done again at this time if it was specified.
3557 The option @option{-dt} causes a debugging dump of the RTL code after
3558 this pass. This dump file's name is made by appending @samp{.cse2} to
3559 the input file name.
3561 @cindex data flow analysis
3562 @cindex analysis, data flow
3563 @cindex basic blocks
3565 Data flow analysis (@file{flow.c}). This pass divides the program
3566 into basic blocks (and in the process deletes unreachable loops); then
3567 it computes which pseudo-registers are live at each point in the
3568 program, and makes the first instruction that uses a value point at
3569 the instruction that computed the value.
3571 @cindex autoincrement/decrement analysis
3572 This pass also deletes computations whose results are never used, and
3573 combines memory references with add or subtract instructions to make
3574 autoincrement or autodecrement addressing.
3577 The option @option{-df} causes a debugging dump of the RTL code after
3578 this pass. This dump file's name is made by appending @samp{.flow} to
3579 the input file name. If stupid register allocation is in use, this
3580 dump file reflects the full results of such allocation.
3582 @cindex instruction combination
3584 Instruction combination (@file{combine.c}). This pass attempts to
3585 combine groups of two or three instructions that are related by data
3586 flow into single instructions. It combines the RTL expressions for
3587 the instructions by substitution, simplifies the result using algebra,
3588 and then attempts to match the result against the machine description.
3591 The option @option{-dc} causes a debugging dump of the RTL code after
3592 this pass. This dump file's name is made by appending @samp{.combine}
3593 to the input file name.
3595 @cindex if conversion
3597 If-conversion is a transformation that transforms control dependencies
3598 into data dependencies (IE it transforms conditional code into a
3599 single control stream).
3600 It is implemented in the file @file{ifcvt.c}.
3603 The option @option{-dE} causes a debugging dump of the RTL code after
3604 this pass. This dump file's name is made by appending @samp{.ce} to
3605 the input file name.
3607 @cindex register movement
3609 Register movement (@file{regmove.c}). This pass looks for cases where
3610 matching constraints would force an instruction to need a reload, and
3611 this reload would be a register to register move. It then attempts
3612 to change the registers used by the instruction to avoid the move
3616 The option @option{-dN} causes a debugging dump of the RTL code after
3617 this pass. This dump file's name is made by appending @samp{.regmove}
3618 to the input file name.
3620 @cindex instruction scheduling
3621 @cindex scheduling, instruction
3623 Instruction scheduling (@file{sched.c}). This pass looks for
3624 instructions whose output will not be available by the time that it is
3625 used in subsequent instructions. (Memory loads and floating point
3626 instructions often have this behavior on RISC machines). It re-orders
3627 instructions within a basic block to try to separate the definition and
3628 use of items that otherwise would cause pipeline stalls.
3630 Instruction scheduling is performed twice. The first time is immediately
3631 after instruction combination and the second is immediately after reload.
3634 The option @option{-dS} causes a debugging dump of the RTL code after this
3635 pass is run for the first time. The dump file's name is made by
3636 appending @samp{.sched} to the input file name.
3638 @cindex register class preference pass
3640 Register class preferencing. The RTL code is scanned to find out
3641 which register class is best for each pseudo register. The source
3642 file is @file{regclass.c}.
3644 @cindex register allocation
3645 @cindex local register allocation
3647 Local register allocation (@file{local-alloc.c}). This pass allocates
3648 hard registers to pseudo registers that are used only within one basic
3649 block. Because the basic block is linear, it can use fast and
3650 powerful techniques to do a very good job.
3653 The option @option{-dl} causes a debugging dump of the RTL code after
3654 this pass. This dump file's name is made by appending @samp{.lreg} to
3655 the input file name.
3657 @cindex global register allocation
3659 Global register allocation (@file{global.c}). This pass
3660 allocates hard registers for the remaining pseudo registers (those
3661 whose life spans are not contained in one basic block).
3665 Reloading. This pass renumbers pseudo registers with the hardware
3666 registers numbers they were allocated. Pseudo registers that did not
3667 get hard registers are replaced with stack slots. Then it finds
3668 instructions that are invalid because a value has failed to end up in
3669 a register, or has ended up in a register of the wrong kind. It fixes
3670 up these instructions by reloading the problematical values
3671 temporarily into registers. Additional instructions are generated to
3674 The reload pass also optionally eliminates the frame pointer and inserts
3675 instructions to save and restore call-clobbered registers around calls.
3677 Source files are @file{reload.c} and @file{reload1.c}, plus the header
3678 @file{reload.h} used for communication between them.
3681 The option @option{-dg} causes a debugging dump of the RTL code after
3682 this pass. This dump file's name is made by appending @samp{.greg} to
3683 the input file name.
3685 @cindex instruction scheduling
3686 @cindex scheduling, instruction
3688 Instruction scheduling is repeated here to try to avoid pipeline stalls
3689 due to memory loads generated for spilled pseudo registers.
3692 The option @option{-dR} causes a debugging dump of the RTL code after
3693 this pass. This dump file's name is made by appending @samp{.sched2}
3694 to the input file name.
3696 @cindex basic block reordering
3697 @cindex reordering, block
3699 Basic block reordering. This pass implements profile guided code
3700 positioning. If profile information is not available, various types of
3701 static analysis are performed to make the predictions normally coming
3702 from the profile feedback (IE execution frequency, branch probability,
3703 etc). It is implemented in the file @file{bb-reorder.c}, and the
3704 various prediction routines are in @file{predict.c}.
3707 The option @option{-dB} causes a debugging dump of the RTL code after
3708 this pass. This dump file's name is made by appending @samp{.bbro} to
3709 the input file name.
3711 @cindex cross-jumping
3712 @cindex no-op move instructions
3714 Jump optimization is repeated, this time including cross-jumping
3715 and deletion of no-op move instructions.
3718 The option @option{-dJ} causes a debugging dump of the RTL code after
3719 this pass. This dump file's name is made by appending @samp{.jump2}
3720 to the input file name.
3722 @cindex delayed branch scheduling
3723 @cindex scheduling, delayed branch
3725 Delayed branch scheduling. This optional pass attempts to find
3726 instructions that can go into the delay slots of other instructions,
3727 usually jumps and calls. The source file name is @file{reorg.c}.
3730 The option @option{-dd} causes a debugging dump of the RTL code after
3731 this pass. This dump file's name is made by appending @samp{.dbr}
3732 to the input file name.
3734 @cindex branch shortening
3736 Branch shortening. On many RISC machines, branch instructions have a
3737 limited range. Thus, longer sequences of instructions must be used for
3738 long branches. In this pass, the compiler figures out what how far each
3739 instruction will be from each other instruction, and therefore whether
3740 the usual instructions, or the longer sequences, must be used for each
3743 @cindex register-to-stack conversion
3745 Conversion from usage of some hard registers to usage of a register
3746 stack may be done at this point. Currently, this is supported only
3747 for the floating-point registers of the Intel 80387 coprocessor. The
3748 source file name is @file{reg-stack.c}.
3751 The options @option{-dk} causes a debugging dump of the RTL code after
3752 this pass. This dump file's name is made by appending @samp{.stack}
3753 to the input file name.
3756 @cindex peephole optimization
3758 Final. This pass outputs the assembler code for the function. It is
3759 also responsible for identifying spurious test and compare
3760 instructions. Machine-specific peephole optimizations are performed
3761 at the same time. The function entry and exit sequences are generated
3762 directly as assembler code in this pass; they never exist as RTL@.
3764 The source files are @file{final.c} plus @file{insn-output.c}; the
3765 latter is generated automatically from the machine description by the
3766 tool @file{genoutput}. The header file @file{conditions.h} is used
3767 for communication between these files.
3769 @cindex debugging information generation
3771 Debugging information output. This is run after final because it must
3772 output the stack slot offsets for pseudo registers that did not get
3773 hard registers. Source files are @file{dbxout.c} for DBX symbol table
3774 format, @file{sdbout.c} for SDB symbol table format, @file{dwarfout.c}
3775 for DWARF symbol table format, and the files @file{dwarf2out.c} and
3776 @file{dwarf2asm.c} for DWARF2 symbol table format.
3779 Some additional files are used by all or many passes:
3783 Every pass uses @file{machmode.def} and @file{machmode.h} which define
3787 Several passes use @file{real.h}, which defines the default
3788 representation of floating point constants and how to operate on them.
3791 All the passes that work with RTL use the header files @file{rtl.h}
3792 and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
3793 @code{gen*} also use these files to read and work with the machine
3797 All the tools that read the machine description use support routines
3798 found in @file{gensupport.c}, @file{errors.c}, and @file{read-rtl.c}.
3802 Several passes refer to the header file @file{insn-config.h} which
3803 contains a few parameters (C macro definitions) generated
3804 automatically from the machine description RTL by the tool
3807 @cindex instruction recognizer
3809 Several passes use the instruction recognizer, which consists of
3810 @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
3811 and @file{insn-extract.c} that are generated automatically from the
3812 machine description by the tools @file{genrecog} and
3816 Several passes use the header files @file{regs.h} which defines the
3817 information recorded about pseudo register usage, and @file{basic-block.h}
3818 which defines the information recorded about basic blocks.
3821 @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
3822 with a bit for each hard register, and some macros to manipulate it.
3823 This type is just @code{int} if the machine has few enough hard registers;
3824 otherwise it is an array of @code{int} and some of the macros expand
3828 Several passes use instruction attributes. A definition of the
3829 attributes defined for a particular machine is in file
3830 @file{insn-attr.h}, which is generated from the machine description by
3831 the program @file{genattr}. The file @file{insn-attrtab.c} contains
3832 subroutines to obtain the attribute values for insns. It is generated
3833 from the machine description by the program @file{genattrtab}.
3838 @include c-tree.texi
3846 @chapter The Configuration File
3847 @cindex configuration file
3848 @cindex @file{xm-@var{machine}.h}
3850 The configuration file @file{xm-@var{machine}.h} contains macro
3851 definitions that describe the machine and system on which the compiler
3852 is running, unlike the definitions in @file{@var{machine}.h}, which
3853 describe the machine for which the compiler is producing output. Most
3854 of the values in @file{xm-@var{machine}.h} are actually the same on all
3855 machines that GCC runs on, so large parts of all configuration files
3856 are identical. But there are some macros that vary:
3861 Define this macro if the host system is System V@.
3865 Define this macro if the host system is VMS@.
3867 @findex FATAL_EXIT_CODE
3868 @item FATAL_EXIT_CODE
3869 A C expression for the status code to be returned when the compiler
3870 exits after serious errors. The default is the system-provided macro
3871 @samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
3872 macro. Define this macro only if these defaults are incorrect.
3874 @findex SUCCESS_EXIT_CODE
3875 @item SUCCESS_EXIT_CODE
3876 A C expression for the status code to be returned when the compiler
3877 exits without serious errors. (Warnings are not serious errors.) The
3878 default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
3879 the system doesn't define that macro. Define this macro only if these
3880 defaults are incorrect.
3882 @findex HOST_WORDS_BIG_ENDIAN
3883 @item HOST_WORDS_BIG_ENDIAN
3884 Defined if the host machine stores words of multi-word values in
3885 big-endian order. (GCC does not depend on the host byte ordering
3888 @findex HOST_FLOAT_WORDS_BIG_ENDIAN
3889 @item HOST_FLOAT_WORDS_BIG_ENDIAN
3890 Define this macro to be 1 if the host machine stores @code{DFmode},
3891 @code{XFmode} or @code{TFmode} floating point numbers in memory with the
3892 word containing the sign bit at the lowest address; otherwise, define it
3895 This macro need not be defined if the ordering is the same as for
3896 multi-word integers.
3898 @findex HOST_FLOAT_FORMAT
3899 @item HOST_FLOAT_FORMAT
3900 A numeric code distinguishing the floating point format for the host
3901 machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
3902 alternatives and default.
3904 @findex HOST_BITS_PER_CHAR
3905 @item HOST_BITS_PER_CHAR
3906 A C expression for the number of bits in @code{char} on the host
3909 @findex HOST_BITS_PER_SHORT
3910 @item HOST_BITS_PER_SHORT
3911 A C expression for the number of bits in @code{short} on the host
3914 @findex HOST_BITS_PER_INT
3915 @item HOST_BITS_PER_INT
3916 A C expression for the number of bits in @code{int} on the host
3919 @findex HOST_BITS_PER_LONG
3920 @item HOST_BITS_PER_LONG
3921 A C expression for the number of bits in @code{long} on the host
3924 @findex HOST_BITS_PER_LONGLONG
3925 @item HOST_BITS_PER_LONGLONG
3926 A C expression for the number of bits in @code{long long} on the host
3929 @findex ONLY_INT_FIELDS
3930 @item ONLY_INT_FIELDS
3931 Define this macro to indicate that the host compiler only supports
3932 @code{int} bit-fields, rather than other integral types, including
3933 @code{enum}, as do most C compilers.
3935 @findex OBSTACK_CHUNK_SIZE
3936 @item OBSTACK_CHUNK_SIZE
3937 A C expression for the size of ordinary obstack chunks.
3938 If you don't define this, a usually-reasonable default is used.
3940 @findex OBSTACK_CHUNK_ALLOC
3941 @item OBSTACK_CHUNK_ALLOC
3942 The function used to allocate obstack chunks.
3943 If you don't define this, @code{xmalloc} is used.
3945 @findex OBSTACK_CHUNK_FREE
3946 @item OBSTACK_CHUNK_FREE
3947 The function used to free obstack chunks.
3948 If you don't define this, @code{free} is used.
3950 @findex USE_C_ALLOCA
3952 Define this macro to indicate that the compiler is running with the
3953 @code{alloca} implemented in C@. This version of @code{alloca} can be
3954 found in the file @file{alloca.c}; to use it, you must also alter the
3955 @file{Makefile} variable @code{ALLOCA}. (This is done automatically
3956 for the systems on which we know it is needed.)
3958 If you do define this macro, you should probably do it as follows:
3962 #define USE_C_ALLOCA
3964 #define alloca __builtin_alloca
3969 so that when the compiler is compiled with GCC it uses the more
3970 efficient built-in @code{alloca} function.
3972 @item FUNCTION_CONVERSION_BUG
3973 @findex FUNCTION_CONVERSION_BUG
3974 Define this macro to indicate that the host compiler does not properly
3975 handle converting a function value to a pointer-to-function when it is
3976 used in an expression.
3978 @findex MULTIBYTE_CHARS
3979 @item MULTIBYTE_CHARS
3980 Define this macro to enable support for multibyte characters in the
3981 input to GCC@. This requires that the host system support the ISO C
3982 library functions for converting multibyte characters to wide
3987 Define this if your system is POSIX.1 compliant.
3989 @findex PATH_SEPARATOR
3990 @item PATH_SEPARATOR
3991 Define this macro to be a C character constant representing the
3992 character used to separate components in paths. The default value is
3995 @findex DIR_SEPARATOR
3997 If your system uses some character other than slash to separate
3998 directory names within a file specification, define this macro to be a C
3999 character constant specifying that character. When GCC displays file
4000 names, the character you specify will be used. GCC will test for
4001 both slash and the character you specify when parsing filenames.
4003 @findex DIR_SEPARATOR_2
4004 @item DIR_SEPARATOR_2
4005 If your system uses an alternative character other than
4006 @samp{DIR_SEPARATOR} to separate directory names within a file
4007 specification, define this macro to be a C character constant specifying
4008 that character. If you define this macro, GCC will test for slash,
4009 @samp{DIR_SEPARATOR}, and @samp{DIR_SEPARATOR_2} when parsing filenames.
4011 @findex TARGET_OBJECT_SUFFIX
4012 @item TARGET_OBJECT_SUFFIX
4013 Define this macro to be a C string representing the suffix for object
4014 files on your target machine. If you do not define this macro, GCC will
4015 use @samp{.o} as the suffix for object files.
4017 @findex TARGET_EXECUTABLE_SUFFIX
4018 @item TARGET_EXECUTABLE_SUFFIX
4019 Define this macro to be a C string representing the suffix to be
4020 automatically added to executable files on your target machine. If you
4021 do not define this macro, GCC will use the null string as the suffix for
4024 @findex HOST_OBJECT_SUFFIX
4025 @item HOST_OBJECT_SUFFIX
4026 Define this macro to be a C string representing the suffix for object
4027 files on your host machine (@samp{xm-*.h}). If you do not define this
4028 macro, GCC will use @samp{.o} as the suffix for object files.
4030 @findex HOST_EXECUTABLE_SUFFIX
4031 @item HOST_EXECUTABLE_SUFFIX
4032 Define this macro to be a C string representing the suffix for
4033 executable files on your host machine (@samp{xm-*.h}). If you do not
4034 define this macro, GCC will use the null string as the suffix for
4037 @findex HOST_BIT_BUCKET
4038 @item HOST_BIT_BUCKET
4039 The name of a file or file-like object on the host system which acts as
4040 a ``bit bucket''. If you do not define this macro, GCC will use
4041 @samp{/dev/null} as the bit bucket. If the target does not support a
4042 bit bucket, this should be defined to the null string, or some other
4043 illegal filename. If the bit bucket is not writable, GCC will use a
4044 temporary file instead.
4046 @findex COLLECT_EXPORT_LIST
4047 @item COLLECT_EXPORT_LIST
4048 If defined, @code{collect2} will scan the individual object files
4049 specified on its command line and create an export list for the linker.
4050 Define this macro for systems like AIX, where the linker discards
4051 object files that are not referenced from @code{main} and uses export
4054 @findex COLLECT2_HOST_INITIALIZATION
4055 @item COLLECT2_HOST_INITIALIZATION
4056 If defined, a C statement (sans semicolon) that performs host-dependent
4057 initialization when @code{collect2} is being initialized.
4059 @findex GCC_DRIVER_HOST_INITIALIZATION
4060 @item GCC_DRIVER_HOST_INITIALIZATION
4061 If defined, a C statement (sans semicolon) that performs host-dependent
4062 initialization when a compilation driver is being initialized.
4064 @findex UPDATE_PATH_HOST_CANONICALIZE
4065 @item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
4066 If defined, a C statement (sans semicolon) that performs host-dependent
4067 canonicalization when a path used in a compilation driver or
4068 preprocessor is canonicalized. @var{path} is a malloc-ed path to be
4069 canonicalized. If the C statement does canonicalize @var{path} into a
4070 different buffer, the old path should be freed and the new buffer should
4071 have been allocated with malloc.
4076 In addition, configuration files for system V define @code{bcopy},
4077 @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
4078 as a macro when compiled with GCC, in order to take advantage of the
4079 benefit of GCC's built-in @code{alloca}.
4082 @chapter Makefile Fragments
4083 @cindex makefile fragment
4085 When you configure GCC using the @file{configure} script
4086 (@pxref{Installation}), it will construct the file @file{Makefile} from
4087 the template file @file{Makefile.in}. When it does this, it will
4088 incorporate makefile fragment files from the @file{config} directory,
4089 named @file{t-@var{target}} and @file{x-@var{host}}. If these files do
4090 not exist, it means nothing needs to be added for a given target or
4094 * Target Fragment:: Writing the @file{t-@var{target}} file.
4095 * Host Fragment:: Writing the @file{x-@var{host}} file.
4098 @node Target Fragment
4099 @section The Target Makefile Fragment
4100 @cindex target makefile fragment
4101 @cindex @file{t-@var{target}}
4103 The target makefile fragment, @file{t-@var{target}}, defines special
4104 target dependent variables and targets used in the @file{Makefile}:
4107 @findex LIBGCC2_CFLAGS
4108 @item LIBGCC2_CFLAGS
4109 Compiler flags to use when compiling @file{libgcc2.c}.
4111 @findex LIB2FUNCS_EXTRA
4112 @item LIB2FUNCS_EXTRA
4113 A list of source file names to be compiled or assembled and inserted
4114 into @file{libgcc.a}.
4116 @findex Floating Point Emulation
4117 @item Floating Point Emulation
4118 To have GCC include software floating point libraries in @file{libgcc.a}
4119 define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
4121 # We want fine grained libraries, so use the new code
4122 # to build the floating point emulation libraries.
4127 fp-bit.c: $(srcdir)/config/fp-bit.c
4128 echo '#define FLOAT' > fp-bit.c
4129 cat $(srcdir)/config/fp-bit.c >> fp-bit.c
4131 dp-bit.c: $(srcdir)/config/fp-bit.c
4132 cat $(srcdir)/config/fp-bit.c > dp-bit.c
4135 You may need to provide additional #defines at the beginning of @file{fp-bit.c}
4136 and @file{dp-bit.c} to control target endianness and other options.
4139 @findex CRTSTUFF_T_CFLAGS
4140 @item CRTSTUFF_T_CFLAGS
4141 Special flags used when compiling @file{crtstuff.c}.
4142 @xref{Initialization}.
4144 @findex CRTSTUFF_T_CFLAGS_S
4145 @item CRTSTUFF_T_CFLAGS_S
4146 Special flags used when compiling @file{crtstuff.c} for shared
4147 linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o}
4148 in @code{EXTRA-PARTS}.
4149 @xref{Initialization}.
4151 @findex MULTILIB_OPTIONS
4152 @item MULTILIB_OPTIONS
4153 For some targets, invoking GCC in different ways produces objects
4154 that can not be linked together. For example, for some targets GCC
4155 produces both big and little endian code. For these targets, you must
4156 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
4157 each set of incompatible options. When GCC invokes the linker, it
4158 arranges to link in the right version of @file{libgcc.a}, based on
4159 the command line options used.
4161 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
4162 special versions of @file{libgcc.a} must be built. Write options that
4163 are mutually incompatible side by side, separated by a slash. Write
4164 options that may be used together separated by a space. The build
4165 procedure will build all combinations of compatible options.
4167 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
4168 msoft-float}, @file{Makefile} will build special versions of
4169 @file{libgcc.a} using the following sets of options: @option{-m68000},
4170 @option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and
4171 @samp{-m68020 -msoft-float}.
4173 @findex MULTILIB_DIRNAMES
4174 @item MULTILIB_DIRNAMES
4175 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
4176 directory names that should be used to hold the various libraries.
4177 Write one element in @code{MULTILIB_DIRNAMES} for each element in
4178 @code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
4179 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
4182 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
4183 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
4184 @samp{m68000 m68020 msoft-float}. You may specify a different value if
4185 you desire a different set of directory names.
4187 @findex MULTILIB_MATCHES
4188 @item MULTILIB_MATCHES
4189 Sometimes the same option may be written in two different ways. If an
4190 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
4191 any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
4192 items of the form @samp{option=option} to describe all relevant
4193 synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
4195 @findex MULTILIB_EXCEPTIONS
4196 @item MULTILIB_EXCEPTIONS
4197 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
4198 specified, there are combinations that should not be built. In that
4199 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
4200 in shell case syntax that should not be built.
4202 For example, in the PowerPC embedded ABI support, it is not desirable
4203 to build libraries compiled with the @option{-mcall-aix} option
4204 and either of the @option{-fleading-underscore} or @option{-mlittle} options
4205 at the same time. Therefore @code{MULTILIB_EXCEPTIONS} is set to
4207 *mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*
4210 @findex MULTILIB_EXTRA_OPTS
4211 @item MULTILIB_EXTRA_OPTS
4212 Sometimes it is desirable that when building multiple versions of
4213 @file{libgcc.a} certain options should always be passed on to the
4214 compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
4215 of options to be used for all builds.
4219 @section The Host Makefile Fragment
4220 @cindex host makefile fragment
4221 @cindex @file{x-@var{host}}
4223 The host makefile fragment, @file{x-@var{host}}, defines special host
4224 dependent variables and targets used in the @file{Makefile}:
4229 The compiler to use when building the first stage.
4233 The install program to use.
4237 @include funding.texi
4240 @unnumbered Linux and the GNU Project
4242 Many computer users run a modified version of the GNU system every
4243 day, without realizing it. Through a peculiar turn of events, the
4244 version of GNU which is widely used today is more often known as
4245 ``Linux'', and many users are not aware of the extent of its
4246 connection with the GNU Project.
4248 There really is a Linux; it is a kernel, and these people are using
4249 it. But you can't use a kernel by itself; a kernel is useful only as
4250 part of a whole system. The system in which Linux is typically used
4251 is a modified variant of the GNU system---in other words, a Linux-based
4254 Many users are not fully aware of the distinction between the kernel,
4255 which is Linux, and the whole system, which they also call ``Linux''.
4256 The ambiguous use of the name doesn't promote understanding.
4258 Programmers generally know that Linux is a kernel. But since they
4259 have generally heard the whole system called ``Linux'' as well, they
4260 often envisage a history which fits that name. For example, many
4261 believe that once Linus Torvalds finished writing the kernel, his
4262 friends looked around for other free software, and for no particular
4263 reason most everything necessary to make a Unix-like system was
4266 What they found was no accident---it was the GNU system. The available
4267 free software added up to a complete system because the GNU Project
4268 had been working since 1984 to make one. The GNU Manifesto
4269 had set forth the goal of developing a free Unix-like system, called
4270 GNU@. By the time Linux was written, the system was almost finished.
4272 Most free software projects have the goal of developing a particular
4273 program for a particular job. For example, Linus Torvalds set out to
4274 write a Unix-like kernel (Linux); Donald Knuth set out to write a text
4275 formatter (TeX); Bob Scheifler set out to develop a window system (X
4276 Windows). It's natural to measure the contribution of this kind of
4277 project by specific programs that came from the project.
4279 If we tried to measure the GNU Project's contribution in this way,
4280 what would we conclude? One CD-ROM vendor found that in their ``Linux
4281 distribution'', GNU software was the largest single contingent, around
4282 28% of the total source code, and this included some of the essential
4283 major components without which there could be no system. Linux itself
4284 was about 3%. So if you were going to pick a name for the system
4285 based on who wrote the programs in the system, the most appropriate
4286 single choice would be ``GNU''@.
4288 But we don't think that is the right way to consider the question.
4289 The GNU Project was not, is not, a project to develop specific
4290 software packages. It was not a project to develop a C compiler,
4291 although we did. It was not a project to develop a text editor,
4292 although we developed one. The GNU Project's aim was to develop
4293 @emph{a complete free Unix-like system}.
4295 Many people have made major contributions to the free software in the
4296 system, and they all deserve credit. But the reason it is @emph{a
4297 system}---and not just a collection of useful programs---is because the
4298 GNU Project set out to make it one. We wrote the programs that were
4299 needed to make a @emph{complete} free system. We wrote essential but
4300 unexciting major components, such as the assembler and linker, because
4301 you can't have a system without them. A complete system needs more
4302 than just programming tools, so we wrote other components as well,
4303 such as the Bourne Again SHell, the PostScript interpreter
4304 Ghostscript, and the GNU C library.
4306 By the early 90s we had put together the whole system aside from the
4307 kernel (and we were also working on a kernel, the GNU Hurd, which runs
4308 on top of Mach). Developing this kernel has been a lot harder than we
4309 expected, and we are still working on finishing it.
4311 Fortunately, you don't have to wait for it, because Linux is working
4312 now. When Linus Torvalds wrote Linux, he filled the last major gap.
4313 People could then put Linux together with the GNU system to make a
4314 complete free system: a Linux-based GNU system (or GNU/Linux system,
4317 Putting them together sounds simple, but it was not a trivial job.
4318 The GNU C library (called glibc for short) needed substantial changes.
4319 Integrating a complete system as a distribution that would work ``out
4320 of the box'' was a big job, too. It required addressing the issue of
4321 how to install and boot the system---a problem we had not tackled,
4322 because we hadn't yet reached that point. The people who developed
4323 the various system distributions made a substantial contribution.
4325 The GNU Project supports GNU/Linux systems as well as @emph{the}
4326 GNU system---even with funds. We funded the rewriting of the
4327 Linux-related extensions to the GNU C library, so that now they are
4328 well integrated, and the newest GNU/Linux systems use the current
4329 library release with no changes. We also funded an early stage of the
4330 development of Debian GNU/Linux.
4332 We use Linux-based GNU systems today for most of our work, and we hope
4333 you use them too. But please don't confuse the public by using the
4334 name ``Linux'' ambiguously. Linux is the kernel, one of the essential
4335 major components of the system. The system as a whole is more or less
4340 @c ---------------------------------------------------------------------
4342 @c ---------------------------------------------------------------------
4347 @unnumbered Contributors to GCC
4348 @cindex contributors
4349 @include contrib.texi
4351 @c ---------------------------------------------------------------------
4353 @c ---------------------------------------------------------------------
4356 @unnumbered Option Index
4358 GCC's command line options are indexed here without any initial @samp{-}
4359 or @samp{--}. Where an option has both positive and negative forms
4360 (such as @option{-f@var{option}} and @option{-fno-@var{option}}),
4361 relevant entries in the manual are indexed under the most appropriate
4362 form; it may sometimes be useful to look up both forms.
4371 @c ---------------------------------------------------------------------
4373 @c ---------------------------------------------------------------------