config:
[official-gcc.git] / gcc / doc / gcc.texi
blob853e77539c4ee313c932ef2e9bca87e26c271ea5
1 \input texinfo  @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename gcc.info
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)
8 @set INTERNALS
9 @set USING
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':
12 @c @clear INTERNALS
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':
15 @c @clear USING
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.
21 @c @smallbook
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
26 @c @finalout
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
36 @c  some such.
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++
48 @c   standards).
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}
62 @code{\body\}
63 @end macro
64 @macro gccoptlist{body}
65 @smallexample
66 \body\
67 @end smallexample
68 @end macro
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.
72 @iftex
73 @alias gol = *
74 @end iftex
75 @ifnottex
76 @macro gol
77 @end macro
78 @end ifnottex
80 @ifset INTERNALS
81 @ifset USING
82 @settitle Using and Porting the GNU Compiler Collection (GCC)
83 @end ifset
84 @end ifset
85 @c seems reasonable to assume at least one of INTERNALS or USING is set...
86 @ifclear INTERNALS
87 @settitle Using the GNU Compiler Collection
88 @end ifclear
89 @ifclear USING
90 @settitle Porting the GNU Compiler Collection
91 @end ifclear
93 @c Create a separate index for command line options.
94 @defcodeindex op
95 @c Merge the standard indexes into a single one.
96 @syncodeindex fn cp
97 @syncodeindex vr cp
98 @syncodeindex ky cp
99 @syncodeindex pg cp
100 @syncodeindex tp cp
102 @c %**end of header
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
113 @c hand margin.
114 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
116 @c @tex
117 @c \global\bindingoffset=0.75in
118 @c \global\normaloffset =0.75in
119 @c @end tex
121 @c Change the font used for @def... commands, since the default
122 @c proportional one used is bad for names starting __.
123 @tex
124 \global\setfont\defbf\ttbshape{10}{\magstep1}
125 @end tex
127 @ifnottex
128 @dircategory Programming
129 @direntry
130 * gcc: (gcc).                  The GNU Compiler Collection.
131 @end direntry
132 @ifset INTERNALS
133 @ifset USING
134 This file documents the use and the internals of the GNU compiler.
135 @end ifset
136 @end ifset
137 @ifclear USING
138 This file documents the internals of the GNU compiler.
139 @end ifclear
140 @ifclear INTERNALS
141 This file documents the use of the GNU compiler.
142 @end ifclear
143 @sp 1
144 Published by the Free Software Foundation@*
145 59 Temple Place - Suite 330@*
146 Boston, MA 02111-1307 USA
147 @sp 1
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.
152 @sp 1
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:
163      A GNU Manual
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.
170 @end ifnottex
172 @setchapternewpage odd
173 @c @finalout
174 @titlepage
175 @ifset INTERNALS
176 @ifset USING
177 @center @titlefont{Using and Porting the GNU Compiler Collection}
179 @end ifset
180 @end ifset
181 @ifclear INTERNALS
182 @title Using the GNU Compiler Collection
183 @end ifclear
184 @ifclear USING
185 @title Porting the GNU Compiler Collection
186 @end ifclear
187 @sp 2
188 @center Richard M. Stallman
189 @sp 3
190 @center Last updated 22 June 2001
191 @sp 1
192 @c The version number appears five times more in this file.
194 @center for GCC 3.1
195 @page
196 @vskip 0pt plus 1filll
197 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
198 1999, 2000, 2001  Free Software Foundation, Inc.
199 @sp 2
200 For GCC Version 3.1@*
201 @sp 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.@*
207 ISBN 1-882114-37-X
208 @sp 1
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:
219      A GNU Manual
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.
226 @end titlepage
227 @summarycontents
228 @contents
229 @page
231 @node Top, G++ and GCC,, (DIR)
232 @top Introduction
233 @cindex introduction
235 @ifset INTERNALS
236 @ifset USING
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.
240 @end ifset
241 @end ifset
243 @ifclear INTERNALS
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.
247 @end ifclear
248 @ifclear USING
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.
252 @end ifclear
254 @menu
255 @ifset USING
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.
271 @end ifset
272 @ifset INTERNALS
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.
282 @end ifset
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.
294 @end menu
296 @ifset USING
297 @node G++ and GCC
298 @chapter Compile C, C++, Objective-C, Fortran, Java or CHILL
300 @cindex Objective-C
301 @cindex Fortran
302 @cindex Java
303 @cindex 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
308 separate manuals.
310 @cindex GCC
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'').
316 @cindex C++
317 @cindex G++
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
333 ends.
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.
357 @node Standards
358 @chapter Language Standards Supported by GCC
359 @cindex C standard
360 @cindex C standards
361 @cindex ANSI C standard
362 @cindex ANSI C
363 @cindex ANSI C89
364 @cindex C89
365 @cindex ANSI X3.159-1989
366 @cindex X3.159-1989
367 @cindex ISO C standard
368 @cindex ISO C
369 @cindex ISO C89
370 @cindex ISO C90
371 @cindex ISO/IEC 9899
372 @cindex ISO 9899
373 @cindex C90
374 @cindex ISO C94
375 @cindex C94
376 @cindex ISO C95
377 @cindex C95
378 @cindex ISO C99
379 @cindex C99
380 @cindex ISO C9X
381 @cindex C9X
382 @cindex Technical Corrigenda
383 @cindex TC1
384 @cindex Technical Corrigendum 1
385 @cindex TC2
386 @cindex Technical Corrigendum 2
387 @cindex AMD1
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.
401 @opindex std
402 @opindex ansi
403 @opindex pedantic
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
422 uncorrected version.
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
438 @dfn{C9X}.)
440 @opindex traditional
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
493 Dialect}.
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
513 information as well.
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.
524 @include invoke.texi
526 @include install-old.texi
528 @include extend.texi
530 @include objc.texi
532 @include gcov.texi
534 @node Trouble
535 @chapter Known Causes of Trouble with GCC
536 @cindex bugs, known
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.
548 @menu
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.
565 @end menu
567 @node Actual Bugs
568 @section Actual Bugs We Haven't Fixed Yet
570 @itemize @bullet
571 @item
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.
577 @item
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
582 prototypes.
584 @item
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.
589 @end itemize
591 @node Cross-Compiler Problems
592 @section Cross-Compiler Problems
594 You may run into problems with cross compilation on certain machines,
595 for several reasons.
597 @itemize @bullet
598 @item
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.
618 @ifset INTERNALS
619 @xref{Cross-compilation}.
620 @end ifset
621 @ifclear INTERNALS
622 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
623 gcc.info, Using and Porting GCC}.
624 @end ifclear
626 @item
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
629 compile environment.
630 @end itemize
632 @node Interoperation
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.
639 @itemize @bullet
640 @item
641 Objective-C does not work on the RS/6000.
643 @item
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
655 at run time.
657 @item
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.
661 @item
662 @cindex DBX
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.
668 @item
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}.
672 @item
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
675 be run.
677 @ignore
678 @cindex @code{vfork}, for the Sun-4
679 @item
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.
691 @end ignore
693 @item
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.
699 @item
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{*}:
717 @smallexample
718 inline double
719 access_double (double *unaligned_ptr)
721   union d2i @{ double d; int i[2]; @};
723   union d2i *p = (union d2i *) unaligned_ptr;
724   union d2i u;
726   u.i[0] = p->i[0];
727   u.i[1] = p->i[1];
729   return u.d;
731 @end smallexample
733 @noindent
734 Storing into the pointer can be done likewise with the same union.
736 @item
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
745 this problem.
747 @item
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.
755 @item
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
765 5.x (Solaris 2.x).
767 @item
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.
773 @item
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.
780 @item
781 Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
782 the preliminary GNU tools (@pxref{Installation}).
784 @item
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.
788 @item
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.
794 @item
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.
801 @item
802 GCC compiled code sometimes emits warnings from the HP-UX assembler of
803 the form:
805 @smallexample
806 (warning) Use of GR3 when
807   frame >= 8192 may cause conflict.
808 @end smallexample
810 These warnings are harmless and can be safely ignored.
812 @item
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
825 command
827 @smallexample
828 as -u < /dev/null
829 @end smallexample
831 @noindent
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
834 order the fix.
836 @item
837 On the IBM RS/6000, compiling code of the form
839 @smallexample
840 extern int foo;
842 @dots{} foo @dots{}
844 static int foo;
845 @end smallexample
847 @noindent
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@.
853 @item
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}.
863 @item
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
868 identifiers.
870 @item
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@.
875 @item
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.
883 @item
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}.
888 @item
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}:
894 @smallexample
895 #ifndef _SIZE_T
896 #define _SIZE_T
897 @var{actual-typedef-here}
898 #endif
899 @end smallexample
901 @cindex Alliant
902 @item
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.
907 @cindex RT PC
908 @cindex IBM RT PC
909 @item
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
914 with it.
916 @cindex VAX calling convention
917 @cindex Ultrix calling convention
918 @item
919 @opindex fcall-saved
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:
927 @smallexample
928 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
929 @end smallexample
931 @item
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
935 options:
937 @smallexample
938 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
939 @end smallexample
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.
949 @item
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}.
955 @item
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.
961 @opindex noasmopt
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}.
968 @end itemize
970 @node External Bugs
971 @section Problems Compiling Certain Programs
973 @c prevent bad page break with this line
974 Certain programs have problems compiling.
976 @itemize @bullet
977 @item
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:
985 @example
986 #ifdef __STDC__
987 #define NeedFunctionPrototypes 0
988 #endif
989 @end example
991 @item
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:
1004 @example
1005 MALLOC=/usr/local/lib/libgmalloc.a
1006 @end example
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
1010 GCC:
1012 @example
1013 MALLOC=gmalloc.o
1014 @end example
1015 @end itemize
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.
1027 @itemize @bullet
1028 @cindex string constants
1029 @cindex read-only strings
1030 @cindex shared strings
1031 @item
1032 GCC normally makes string constants read-only.  If several
1033 identical-looking string constants are used, GCC stores only one
1034 copy of the string.
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.
1057 @item
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.
1064 @item
1065 GCC does not substitute macro arguments when they appear inside of
1066 string constants.  For example, the following macro in GCC
1068 @example
1069 #define foo(a) "a"
1070 @end example
1072 @noindent
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
1080 @item
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:
1086 @example
1087 jmp_buf j;
1089 foo ()
1091   int a, b;
1093   a = fun1 ();
1094   if (setjmp (j))
1095     return a;
1097   a = fun2 ();
1098   /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
1099   return a + fun3 ();
1101 @end example
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
1106 in it.
1108 @opindex W
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.
1117 @item
1118 Programs that use preprocessing directives in the middle of macro
1119 arguments do not work with GCC@.  For example, a program like this
1120 will not work:
1122 @example
1123 @group
1124 foobar (
1125 #define luser
1126         hack)
1127 @end group
1128 @end example
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
1132 implement.
1134 @item
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
1142 @item
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.
1153 @item
1154 In traditional C, you can combine @code{long}, etc., with a typedef name,
1155 as shown here:
1157 @example
1158 typedef int foo;
1159 typedef long foo bar;
1160 @end example
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
1168 @item
1169 PCC allows typedef names to be used as function parameters.  The
1170 difficulty described immediately above applies here too.
1172 @item
1173 When in @option{-traditional} mode, GCC allows the following erroneous
1174 pair of declarations to appear together in a given scope:
1176 @example
1177 typedef int foo;
1178 typedef foo foo;
1179 @end example
1181 @item
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.
1189 @cindex whitespace
1190 @item
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
1194 too.
1196 @cindex apostrophes
1197 @cindex '
1198 @item
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:
1205 @example
1206 #if 0
1207 You can't expect this to work.
1208 #endif
1209 @end example
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.
1215 @item
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
1229 @item
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.
1235 @cindex structures
1236 @cindex unions
1237 @item
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
1268 @item
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.
1286 @end itemize
1288 @node Fixed Headers
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
1295 compilers.
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.
1303 @itemize @bullet
1304 @item
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
1309 shortcut.)
1311 @item
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.
1329 @item
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.
1336 @end itemize
1338 @node Standard Libraries
1339 @section Standard Libraries
1341 @opindex Wall
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
1368 way around them.
1370 @itemize @bullet
1371 @item
1372 Certain local variables aren't recognized by debuggers when you compile
1373 with optimization.
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
1386 @item
1387 Users often think it is a bug when GCC reports an error for code
1388 like this:
1390 @example
1391 int foo (struct mumble *);
1393 struct mumble @{ @dots{} @};
1395 int foo (struct mumble *x)
1396 @{ @dots{} @}
1397 @end example
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
1403 different scopes.
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
1413 shown above.
1415 @item
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.
1424 @item
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.
1438 @item
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}).
1452 @item
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.
1463 @item
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.
1469 @end itemize
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.
1483 @menu
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
1487 @end menu
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:
1499 @example
1500 class Foo
1502   @dots{}
1503   void method();
1504   static int bar;
1506 @end 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
1513 file, such as:
1515 @example
1516 int Foo::bar = 0;
1517 @end example
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.
1525 @node Temporaries
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}:
1544 @example
1545 string strfunc ();
1546 void charfunc (const char *);
1548 void
1549 f ()
1551   const char *p = strfunc().c_str();
1552   @dots{}
1553   charfunc (p);
1554   @dots{}
1555   charfunc (p);
1557 @end example
1559 @noindent
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
1574 example:
1576 @example
1577 string& tmp = strfunc ();
1578 charfunc (tmp.c_str ());
1579 @end example
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:
1589 @example
1590 struct Base@{
1591   char *name;
1592   Base(char *n) : name(strdup(n))@{@}
1593   Base& operator= (const Base& other)@{
1594    free (name);
1595    name = strdup (other.name);
1596   @}
1599 struct A:virtual Base@{
1600   int val;
1601   A():Base("A")@{@}
1604 struct B:virtual Base@{
1605   int bval;
1606   B():Base("B")@{@}
1609 struct Derived:public A, public B@{
1610   Derived():Base("Derived")@{@}
1613 void func(Derived &d1, Derived &d2)
1615   d1 = d2;
1617 @end example
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
1641 rearrange it.
1643 @itemize @bullet
1644 @item
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.
1651 @item
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.
1660 @item
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
1667 without them.
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.
1674 @item
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
1680 them manually.
1682 @item
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
1687 about them.
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.
1694 @item
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
1700 expected) results.
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
1707 problem.
1709 @item
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.
1716 @item
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.)
1720 @end itemize
1722 @node Non-bugs
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.
1728 @itemize @bullet
1729 @item
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.
1739 @item
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.
1745 @item
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.
1751 @item
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
1758 useful.
1760 @item
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.
1770 @item
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
1788 as well.
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
1807 certain machines.
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.)
1828 @item
1829 @opindex ansi
1830 @opindex traditional
1831 @opindex std
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
1841 ``yes''.
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
1850 library.
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.
1869 @item
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.
1888 @item
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
1894 faster.
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
1898 case for C++.
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.
1905 @item
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:
1914 @example
1915 void func (int, int);
1917 int i = 2;
1918 func (i++, i++);
1919 @end example
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}.
1926 @item
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.
1934 @item
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
1946 errors.
1948 @end itemize
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:
1959 @itemize @w{}
1960 @item
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.
1965 @item
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.
1971 @end itemize
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
1978 warnings).
1980 @opindex pedantic
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
1990 or errors.
1992 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
1993 more detail on these and related command-line options.
1995 @node Bugs
1996 @chapter Reporting Bugs
1997 @cindex 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
2004 report the problem.
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.
2019 @menu
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.
2027 @end menu
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:
2035 @itemize @bullet
2036 @cindex fatal signal
2037 @cindex core dump
2038 @item
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
2044 @item
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
2053 @item
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
2074 in your code.
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.
2080 @item
2081 If the compiler produces an error message for valid input, that is a
2082 compiler bug.
2084 @cindex invalid input
2085 @item
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''.
2091 @item
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.
2094 @end itemize
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
2146 things:
2148 @itemize @bullet
2149 @item
2150 The version of GCC@.  You can get this by running it with the
2151 @option{-v} option.
2153 Without this, we won't know whether there is any point in looking for
2154 the bug in the current version of GCC@.
2156 @item
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
2164 generated.
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.
2184 @item
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.
2192 @item
2193 The type of machine you are using, and the operating system name and
2194 version number.
2196 @item
2197 The operands you gave to the @code{configure} command when you installed
2198 the compiler.
2200 @item
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.
2212 @item
2213 Details of any other deviations from the standard procedure for installing
2214 GCC@.
2216 @item
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.
2249 @item
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.
2255 @item
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
2261 maintainers.
2263 @item
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,
2285 not in an argument.
2287 @findex debug_rtx
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.
2296 @end itemize
2298 Here are some things that are not necessary:
2300 @itemize @bullet
2301 @item
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.
2326 @item
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.
2332 @item
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.
2352 @item
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.
2358 @item
2359 A core dump file.
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.
2364 @end itemize
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
2396 your best to help.
2398 @itemize @bullet
2399 @item
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.)
2408 @item
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.
2414 @item
2415 Include all the comments that are appropriate to help people reading the
2416 source in the future understand why this change was needed.
2418 @item
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.
2437 @item
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
2441 could do.
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
2445 is important.
2447 @item
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
2452 @option{-c} format.
2454 If you have GNU diff, use @samp{diff -cp}, which shows the name of the
2455 function that each change occurs in.
2457 @item
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.
2476 @item
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
2495 on other machines.
2497 Please help us keep up with the workload by designing the patch in a
2498 form that is good to install.
2499 @end itemize
2501 @node Service
2502 @chapter How To Get Help with GCC
2504 If you need help installing, using or changing GCC, there are two
2505 ways to find it:
2507 @itemize @bullet
2508 @item
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}.
2516 @item
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}.
2520 @end itemize
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.
2527 @node Contributing
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:
2538 @smallexample
2539 @uref{http://gcc.gnu.org/contribute.html} 
2540 @uref{http://gcc.gnu.org/contributewhy.html}
2541 @end smallexample
2543 @noindent
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/}.
2548 @node VMS
2549 @chapter Using GCC on VMS
2551 @c prevent bad page break with this line
2552 Here is how to use GCC on VMS@.
2554 @menu
2555 * Include Files and VMS::  Where the preprocessor looks for the include files.
2556 * Global Declarations::    How to do globaldef, globalref and globalvalue with
2557                            GCC.
2558 * VMS Misc::               Misc information.
2559 @end menu
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:
2574 @enumerate
2575 @item
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.
2582 @item
2583 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}.  This is where
2584 VAX-C header files are traditionally stored.
2586 @item
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
2589 the include file.
2591 @item
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
2595 VMS syntax.
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.
2604 @item
2605 If none of these strategies succeeds, the @samp{#include} fails.
2606 @end enumerate
2608 Include directives of the form:
2610 @example
2611 #include foobar
2612 @end example
2614 @noindent
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}:
2621 @example
2622 #include "@var{file}"
2623 #include <@var{file}>
2624 @end example
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:
2631 @example
2632 #define stdio <stdio.h>
2633 @end example
2635 @noindent
2636 This will work, as long as the name doesn't conflict with anything else
2637 in the program.
2639 Another source of incompatibility is that VAX-C assumes that:
2641 @example
2642 #include "foobar"
2643 @end example
2645 @noindent
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
2650 directives.
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
2669 @findex GLOBALREF
2670 @findex GLOBALDEF
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:
2679 @smallexample
2680 #ifdef __GNUC__
2681 #define GLOBALREF(TYPE,NAME)                      \
2682   TYPE NAME                                       \
2683   asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
2684 #define GLOBALDEF(TYPE,NAME,VALUE)                \
2685   TYPE NAME                                       \
2686   asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
2687     = VALUE
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)  \
2694     = @{VALUE@}
2695 #else
2696 #define GLOBALREF(TYPE,NAME) \
2697   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
2704 #endif
2705 @end smallexample
2707 @noindent
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
2712 usage is:
2714 @example
2715 GLOBALREF (int, ijk);
2716 GLOBALDEF (int, jkl, 0);
2717 @end example
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:
2725 @example
2726 typedef int intvector[10];
2727 GLOBALREF (intvector, foo);
2728 @end example
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:
2742 @example
2743 GLOBALVALUEREF(int, ijk);
2744 @end example
2746 @noindent
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.
2761 @example
2762 GLOBALVALUEREF (int, ss$_normal);
2763 GLOBALVALUEDEF (int, xyzzy,123);
2764 #ifdef __GNUC__
2765 #define ss$_normal ((int) ss$_normal)
2766 #define xyzzy ((int) xyzzy)
2767 #endif
2768 @end example
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:
2775 @example
2776 #ifdef __GNUC__
2777 GLOBALDEF (int, color, 0);
2778 GLOBALVALUEDEF (int, RED, 0);
2779 GLOBALVALUEDEF (int, BLUE, 1);
2780 GLOBALVALUEDEF (int, GREEN, 3);
2781 #else
2782 enum globaldef color @{RED, BLUE, GREEN = 3@};
2783 #endif
2784 @end example
2786 @node VMS Misc
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
2800 produced by GAS@.
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:
2868 @example
2869 #define StuDlyCapS studlycaps
2870 @end example
2872 These macro definitions can be placed in a header file to minimize the
2873 number of changes to your source code.
2875 @node Makefile
2876 @chapter Additional Makefile and configure information.
2878 @section Makefile Targets
2879 @cindex makefile targets
2880 @cindex targets, makefile
2882 @table @code
2883 @item all
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.
2887 @item doc
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.
2892 @item mostlyclean
2893 Delete the files made while building the compiler.
2895 @item clean
2896 That, and all the other files built by @code{make all}.
2898 @item distclean
2899 That, and all the files created by @code{configure}.
2901 @item extraclean
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
2907 build gcc.
2909 @item install
2910 Installs gcc.
2912 @item uninstall
2913 Deletes installed files.
2915 @item check
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:
2923 @example
2924 make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
2925 @end example
2927 Note that running the testsuite may require additional tools be
2928 installed, such as TCL or dejagnu.
2930 @item bootstrap
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.
2942 @item bubblestrap
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
2948 full bootstrap.
2950 @item quickstrap
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.
2955 @item cleanstrap
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}}
2960 subdirectory.
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
2967 appropriate flags.
2969 @item compare
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.
2974 @end table
2976 @section Configure Terms and History
2977 @cindex configure terms
2978 @cindex canadian
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
2988 know.
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
3029 need it.
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.
3038 @end ifset
3040 @ifset INTERNALS
3041 @node Portability
3042 @chapter GCC and Portability
3043 @cindex 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.
3059 @cindex endianness
3060 @cindex autoincrement addressing, availability
3061 @findex abort
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.
3074 @end ifset
3076 @ifset INTERNALS
3077 @node Interface
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
3134 the subroutine.
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
3142 your asking it to.
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
3148 go in a register:
3150 @example
3152   int careful;
3153   &careful;
3154   @dots{}
3156 @end example
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@.
3174 @end ifset
3176 @ifset INTERNALS
3177 @node Passes
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
3194 @file{stmt.c}.
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).
3216 @ifset USING
3217 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3218 @end ifset
3219 @ifclear USING
3220 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3221 @end ifclear
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.
3227 @itemize @bullet
3228 @item
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
3253 @file{c-convert.c},
3254 @file{c-decl.c},
3255 @file{c-errors.c},
3256 @file{c-lang.c},
3257 @file{c-parse.in},
3258 @file{c-aux-info.c},
3260 @file{c-typeck.c},
3261 along with a header file
3262 @file{c-tree.h}
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},
3267 @file{class.c},
3268 @file{cvt.c}, @file{decl.c}, @file{decl2.c},
3269 @file{except.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.
3282 The files
3283 @file{c-common.c},
3284 @file{c-common.def},
3285 @file{c-dump.c},
3286 @file{c-format.c},
3287 @file{c-pragma.c},
3288 @file{c-semantics.c},
3290 @file{c-lex.c},
3291 along with header files
3292 @file{c-common.h},
3293 @file{c-dump.h},
3294 @file{c-lex.h},
3296 @file{c-pragma.h},
3297 are also used for all of the above languages.
3300 @cindex Tree optimization
3301 @item
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
3307 inlining.
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
3311 addition).
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
3322 @item
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
3330 generation pass.
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
3340 @file{stmt.c},
3341 @file{calls.c},
3342 @file{expr.c},
3343 @file{explow.c},
3344 @file{expmed.c},
3345 @file{function.c},
3346 @file{optabs.c}
3347 and @file{emit-rtl.c}.
3348 Also, the file
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.
3353 @findex genflags
3354 @findex gencodes
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.
3376 @opindex dr
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
3384 @item
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,
3388 whenever possible.
3390 The source file of this pass is @file{sibcall.c}
3392 @opindex di
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
3399 @cindex dead code
3400 @item
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}.
3419 @opindex dj
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
3426 @item
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
3432 @item
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
3442 @opindex fssa
3443 @item
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
3452 @file{ssa.c}.
3454 @opindex de
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.
3458 @itemize @bullet
3459 @cindex SSA Conditional Constant Propagation
3460 @cindex Conditional Constant Propagation, SSA based
3461 @cindex conditional constant propagation
3462 @opindex fssa-ccp
3463 @item
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
3469 in linear time.
3471 @opindex dW
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.
3476 @cindex SSA DCE
3477 @cindex DCE, SSA based
3478 @cindex dead code elimination
3479 @opindex fssa-dce
3480 @item
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
3484 linear time.
3486 @opindex dX
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.
3490 @end itemize
3492 @cindex common subexpression elimination
3493 @cindex constant propagation
3494 @item
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
3499 CSE is finished.
3501 @opindex ds
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
3509 @item
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}.
3529 @opindex dG
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
3535 @cindex code motion
3536 @cindex strength-reduction
3537 @item
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}.
3545 @opindex dL
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.
3550 @item
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.
3556 @opindex dt
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
3564 @item
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.
3576 @opindex df
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
3583 @item
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.
3590 @opindex dc
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
3596 @item
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}.
3602 @opindex dE
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
3608 @item
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
3613 instruction.
3615 @opindex dN
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
3622 @item
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.
3633 @opindex dS
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
3639 @item
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
3646 @item
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.
3652 @opindex dl
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
3658 @item
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).
3663 @cindex reloading
3664 @item
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
3672 do the copying.
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.
3680 @opindex dg
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
3687 @item
3688 Instruction scheduling is repeated here to try to avoid pipeline stalls
3689 due to memory loads generated for spilled pseudo registers.
3691 @opindex dR
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
3698 @item
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}.
3706 @opindex dB
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
3713 @item
3714 Jump optimization is repeated, this time including cross-jumping
3715 and deletion of no-op move instructions.
3717 @opindex dJ
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
3724 @item
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}.
3729 @opindex dd
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
3735 @item
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
3741 branch.
3743 @cindex register-to-stack conversion
3744 @item
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}.
3750 @opindex dk
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.
3755 @cindex final pass
3756 @cindex peephole optimization
3757 @item
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
3770 @item
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.
3777 @end itemize
3779 Some additional files are used by all or many passes:
3781 @itemize @bullet
3782 @item
3783 Every pass uses @file{machmode.def} and @file{machmode.h} which define
3784 the machine modes.
3786 @item
3787 Several passes use @file{real.h}, which defines the default
3788 representation of floating point constants and how to operate on them.
3790 @item
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
3794 description RTL@.
3796 @item
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}.
3800 @findex genconfig
3801 @item
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
3805 @code{genconfig}.
3807 @cindex instruction recognizer
3808 @item
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
3813 @file{genextract}.
3815 @item
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.
3820 @item
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
3825 into loops.
3827 @item
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}.
3834 @end itemize
3835 @end ifset
3837 @ifset INTERNALS
3838 @include c-tree.texi
3839 @include rtl.texi
3840 @include md.texi
3841 @include tm.texi
3842 @end ifset
3844 @ifset INTERNALS
3845 @node Config
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:
3858 @table @code
3859 @findex USG
3860 @item USG
3861 Define this macro if the host system is System V@.
3863 @findex VMS
3864 @item VMS
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
3886 within a word.)
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
3893 to be zero.
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
3907 machine.
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
3912 machine.
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
3917 machine.
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
3922 machine.
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
3927 machine.
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
3951 @item 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:
3960 @example
3961 #ifndef __GNUC__
3962 #define USE_C_ALLOCA
3963 #else
3964 #define alloca __builtin_alloca
3965 #endif
3966 @end example
3968 @noindent
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
3983 characters.
3985 @findex POSIX
3986 @item POSIX
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
3993 the colon character
3995 @findex DIR_SEPARATOR
3996 @item 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
4022 executable files.
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
4035 executable files.
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
4052 lists.
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.
4072 @end table
4074 @findex bzero
4075 @findex bcmp
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}.
4081 @node Fragments
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
4091 host.
4093 @menu
4094 * Target Fragment:: Writing the @file{t-@var{target}} file.
4095 * Host Fragment::   Writing the @file{x-@var{host}} file.
4096 @end menu
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}:
4106 @table @code
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:
4120 @smallexample
4121 # We want fine grained libraries, so use the new code
4122 # to build the floating point emulation libraries.
4123 FPBIT = fp-bit.c
4124 DPBIT = dp-bit.c
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
4133 @end smallexample
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
4180 as spaces.
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
4206 @smallexample
4207 *mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*
4208 @end smallexample
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.
4216 @end table
4218 @node Host Fragment
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}:
4226 @table @code
4227 @findex CC
4228 @item CC
4229 The compiler to use when building the first stage.
4231 @findex INSTALL
4232 @item INSTALL
4233 The install program to use.
4234 @end table
4235 @end ifset
4237 @include funding.texi
4239 @node GNU/Linux
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
4252 GNU system.
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
4264 already available.
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,
4315 for short).
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
4336 the GNU system.
4338 @include gpl.texi
4340 @c ---------------------------------------------------------------------
4341 @c GFDL
4342 @c ---------------------------------------------------------------------
4344 @include fdl.texi
4346 @node Contributors
4347 @unnumbered Contributors to GCC
4348 @cindex contributors
4349 @include contrib.texi
4351 @c ---------------------------------------------------------------------
4352 @c Indexes
4353 @c ---------------------------------------------------------------------
4355 @node Option Index
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.
4364 @printindex op
4366 @node Index
4367 @unnumbered Index
4369 @printindex cp
4371 @c ---------------------------------------------------------------------
4372 @c Epilogue
4373 @c ---------------------------------------------------------------------
4375 @bye