OSDN Git Service

2d15b42a6a84813bd60e822b31bd45a15ca666a2
[pf3gnuchains/gcc-fork.git] / gcc / gcc.texi
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
16
17 @c (For FSF printing, turn on smallbook, comment out finalout below;
18 @c that is all that is needed.)
19
20 @c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition.
21 @c @smallbook
22
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
27
28 @c NOTE: checks/things to do:
29 @c
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 -spellcheck
38 @c -continuity of phrasing; ie, bit-field vs bitfield in rtl.texi
39 @c -overfulls.  do a search for "mew" in the files, and you will see
40 @c   overfulls that i noted but could not deal with.
41 @c -have to add text:  beginning of chapter 8
42
43 @c
44 @c anything else?                       --mew 10feb93
45
46
47
48 @ifset INTERNALS
49 @ifset USING
50 @settitle Using and Porting the GNU Compiler Collection (GCC)
51 @end ifset
52 @end ifset
53 @c seems reasonable to assume at least one of INTERNALS or USING is set...
54 @ifclear INTERNALS
55 @settitle Using the GNU Compiler Collection
56 @end ifclear
57 @ifclear USING
58 @settitle Porting the GNU Compiler Collection
59 @end ifclear
60
61 @syncodeindex fn cp
62 @syncodeindex vr cp
63 @c %**end of header
64
65 @c Use with @@smallbook.
66
67 @c Cause even numbered pages to be printed on the left hand side of
68 @c the page and odd numbered pages to be printed on the right hand
69 @c side of the page.  Using this, you can print on both sides of a
70 @c sheet of paper and have the text on the same part of the sheet.
71
72 @c The text on right hand pages is pushed towards the right hand
73 @c margin and the text on left hand pages is pushed toward the left
74 @c hand margin.
75 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
76
77 @c @tex
78 @c \global\bindingoffset=0.75in
79 @c \global\normaloffset =0.75in
80 @c @end tex
81
82 @ifnottex
83 @dircategory Programming
84 @direntry
85 * gcc: (gcc).                  The GNU Compiler Collection.
86 @end direntry
87 @ifset INTERNALS
88 @ifset USING
89 This file documents the use and the internals of the GNU compiler.
90 @end ifset
91 @end ifset
92 @ifclear USING
93 This file documents the internals of the GNU compiler.
94 @end ifclear
95 @ifclear INTERNALS
96 This file documents the use of the GNU compiler.
97 @end ifclear
98 @sp 1
99 Published by the Free Software Foundation@*
100 59 Temple Place - Suite 330@*
101 Boston, MA 02111-1307 USA
102 @sp 1
103 @c When you update the list of years below, search for copyright{} and
104 @c update the other copy too.
105 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
106 1999, 2000, 2001 Free Software Foundation, Inc.
107 @sp 1
108 Permission is granted to make and distribute verbatim copies of
109 this manual provided the copyright notice and this permission notice
110 are preserved on all copies.
111 @sp 1
112 @ignore
113 Permission is granted to process this file through Tex and print the
114 results, provided the printed document carries copying permission
115 notice identical to this one except for the removal of this paragraph
116 (this paragraph not being relevant to the printed manual).
117
118 @end ignore
119 Permission is granted to copy and distribute modified versions of this
120 manual under the conditions for verbatim copying, provided also that the
121 sections entitled ``GNU General Public License'' and ``Funding for Free
122 Software'' are included exactly as in the original, and provided that 
123 the entire resulting derived work is distributed under the terms of a 
124 permission notice identical to this one.
125 @sp 1
126 Permission is granted to copy and distribute translations of this manual
127 into another language, under the above conditions for modified versions,
128 except that the sections entitled ``GNU General Public License'' and
129 ``Funding for Free Software'', and this permission notice, may be 
130 included in translations approved by the Free Software Foundation 
131 instead of in the original English.
132 @end ifnottex
133
134 @setchapternewpage odd
135 @c @finalout
136 @titlepage
137 @ifset INTERNALS
138 @ifset USING
139 @center @titlefont{Using and Porting the GNU Compiler Collection}
140
141 @end ifset
142 @end ifset
143 @ifclear INTERNALS
144 @title Using the GNU Compiler Collection
145 @end ifclear
146 @ifclear USING
147 @title Porting the GNU Compiler Collection
148 @end ifclear
149 @sp 2
150 @center Richard M. Stallman
151 @sp 3
152 @center Last updated 20 December 2000
153 @sp 1
154 @c The version number appears five times more in this file.
155
156 @center for gcc-2.97
157 @page
158 @vskip 0pt plus 1filll
159 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
160 1999, 2000, 2001  Free Software Foundation, Inc.
161 @sp 2
162 For GCC Version 2.97@*
163 @sp 1
164 Published by the Free Software Foundation @*
165 59 Temple Place - Suite 330@*
166 Boston, MA 02111-1307, USA@*
167 Last printed April, 1998.@*
168 Printed copies are available for $50 each.@*
169 ISBN 1-882114-37-X
170 @sp 1
171 Permission is granted to make and distribute verbatim copies of
172 this manual provided the copyright notice and this permission notice
173 are preserved on all copies.
174
175 Permission is granted to copy and distribute modified versions of this
176 manual under the conditions for verbatim copying, provided also that the
177 sections entitled ``GNU General Public License'' and ``Funding for Free
178 Software'' are included exactly as in the original, and provided that 
179 the entire resulting derived work is distributed under the terms of a 
180 permission notice identical to this one.
181
182 Permission is granted to copy and distribute translations of this manual
183 into another language, under the above conditions for modified versions,
184 except that the sections entitled ``GNU General Public License'' and
185 ``Funding for Free Software'', and this permission notice, may be 
186 included in translations approved by the Free Software Foundation 
187 instead of in the original English.
188 @end titlepage
189 @page
190
191 @node Top, G++ and GCC,, (DIR)
192 @top Introduction
193 @cindex introduction
194
195 @ifset INTERNALS
196 @ifset USING
197 This manual documents how to run, install and port the GNU
198 compiler, as well as its new features and incompatibilities, and how to
199 report bugs.  It corresponds to GCC version 2.97.
200 @end ifset
201 @end ifset
202
203 @ifclear INTERNALS
204 This manual documents how to run and install the GNU compiler,
205 as well as its new features and incompatibilities, and how to report
206 bugs.  It corresponds to GCC version 2.97.
207 @end ifclear
208 @ifclear USING
209 This manual documents how to port the GNU compiler,
210 as well as its new features and incompatibilities, and how to report
211 bugs.  It corresponds to GCC version 2.97.
212 @end ifclear
213
214 @menu
215 @ifset USING
216 * G++ and GCC::     You can compile C or C++ programs.
217 * Standards::       Language standards supported by GCC.
218 * Invoking GCC::    Command options supported by @samp{gcc}.
219 * Installation::    How to configure, compile and install GCC.
220 * C Extensions::    GNU extensions to the C language family.
221 * C++ Extensions::  GNU extensions to the C++ language.
222 * Gcov::            gcov: a GCC test coverage program.
223 * Trouble::         If you have trouble installing GCC.
224 * Bugs::            How, why and where to report bugs.
225 * Service::         How to find suppliers of support for GCC.
226 * Contributing::    How to contribute to testing and developing GCC.
227 * VMS::             Using GCC on VMS.
228 @end ifset
229 @ifset INTERNALS
230 * Portability::     Goals of GCC's portability features.
231 * Interface::       Function-call interface of GCC output.
232 * Passes::          Order of passes, what they do, and what each file is for.
233 * RTL::             The intermediate representation that most passes work on.
234 * Machine Desc::    How to write machine description instruction patterns.
235 * Target Macros::   How to write the machine description C macros.
236 * Config::          Writing the @file{xm-@var{machine}.h} file.
237 * Fragments::       Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
238 @end ifset
239
240 * Funding::         How to help assure funding for free software.
241 * GNU/Linux::       Linux and the GNU Project
242
243 * Copying::         GNU General Public License says
244                      how you can copy and share GCC.
245 * Contributors::    People who have contributed to GCC.
246
247 * Index::           Index of concepts and symbol names.
248 @end menu
249
250 @ifset USING
251 @node G++ and GCC
252 @chapter Compile C, C++, Objective C, Fortran, Java or CHILL
253
254 @cindex Objective C
255 Several versions of the compiler (C, C++, Objective C, Fortran, Java
256 and CHILL) are integrated; this is why we use the name 
257 ``GNU Compiler Collection''. GCC can compile programs written in any of these
258 languages. The Fortran and CHILL compilers are described in 
259 separate manuals. The Java compiler currently has no manual documenting it.
260
261 @cindex GCC
262 ``GCC'' is a common shorthand term for the GNU Compiler Collection.  This is both
263 the most general name for the compiler, and the name used when the
264 emphasis is on compiling C programs (as the abbreviation formerly
265 stood for ``GNU C Compiler'').
266
267 @cindex C++
268 @cindex G++
269 When referring to C++ compilation, it is usual to call the compiler
270 ``G++''.  Since there is only one compiler, it is also accurate to call
271 it ``GCC'' no matter what the language context; however, the term
272 ``G++'' is more useful when the emphasis is on compiling C++ programs.
273
274 We use the name ``GCC'' to refer to the compilation system as a
275 whole, and more specifically to the language-independent part of the
276 compiler.  For example, we refer to the optimization options as
277 affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
278
279 Front ends for other languages, such as Ada 95 and Pascal exist but
280 have not yet been integrated into GCC. These front-ends, like that for C++, 
281 are built in subdirectories of GCC and link to it.  The result is an
282 integrated compiler that can compile programs written in C, C++,
283 Objective C, or any of the languages for which you have installed front
284 ends.
285
286 In this manual, we only discuss the options for the C, Objective-C, and
287 C++ compilers and those of the GCC core.  Consult the documentation
288 of the other front ends for the options to use when compiling programs
289 written in other languages.
290
291 @cindex compiler compared to C++ preprocessor
292 @cindex intermediate C version, nonexistent
293 @cindex C intermediate output, nonexistent
294 G++ is a @emph{compiler}, not merely a preprocessor.  G++ builds object
295 code directly from your C++ program source.  There is no intermediate C
296 version of the program.  (By contrast, for example, some other
297 implementations use a program that generates a C program from your C++
298 source.)  Avoiding an intermediate C representation of the program means
299 that you get better object code, and better debugging information.  The
300 GNU debugger, GDB, works with this information in the object code to
301 give you comprehensive C++ source-level editing capabilities
302 (@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
303
304 @c FIXME!  Someone who knows something about Objective C ought to put in
305 @c a paragraph or two about it here, and move the index entry down when
306 @c there is more to point to than the general mention in the 1st par.
307
308 @node Standards
309 @chapter Language Standards Supported by GCC
310 @cindex C standard
311 @cindex C standards
312 @cindex ANSI C standard
313 @cindex ANSI C
314 @cindex ANSI C89
315 @cindex C89
316 @cindex ANSI X3.159-1989
317 @cindex X3.159-1989
318 @cindex ISO C standard
319 @cindex ISO C
320 @cindex ISO C89
321 @cindex ISO C90
322 @cindex ISO/IEC 9899
323 @cindex ISO 9899
324 @cindex C90
325 @cindex ISO C94
326 @cindex C94
327 @cindex ISO C95
328 @cindex C95
329 @cindex ISO C99
330 @cindex C99
331 @cindex ISO C9X
332 @cindex C9X
333 @cindex Technical Corrigenda
334 @cindex TC1
335 @cindex Technical Corrigendum 1
336 @cindex TC2
337 @cindex Technical Corrigendum 2
338 @cindex AMD1
339 @cindex freestanding implementation
340 @cindex freestanding environment
341 @cindex hosted implementation
342 @cindex hosted environment
343 @findex __STDC_HOSTED__
344
345 For each language compiled by GCC for which there is a standard, GCC
346 attempts to follow one or more versions of that standard, possibly
347 with some exceptions, and possibly with some extensions.
348
349 GCC supports three versions of the C standard, although support for
350 the most recent version is not yet complete.
351
352 The original ANSI C standard (X3.159-1989) was ratified in 1989 and
353 published in 1990.  This standard was ratified as an ISO standard
354 (ISO/IEC 9899:1990) later in 1990.  There were no technical
355 differences between these publications, although the sections of the
356 ANSI standard were renumbered and became clauses in the ISO standard.
357 This standard, in both its forms, is commonly known as @dfn{C89}, or
358 occasionally as @dfn{C90}, from the dates of ratification.  The ANSI
359 standard, but not the ISO standard, also came with a Rationale
360 document.  To select this standard in GCC, use one of the options
361 @samp{-ansi}, @samp{-std=c89} or @samp{-std=iso9899:1990}; to obtain
362 all the diagnostics required by the standard, you should also specify
363 @samp{-pedantic} (or @samp{-pedantic-errors} if you want them to be
364 errors rather than warnings).  @xref{C Dialect Options,,Options
365 Controlling C Dialect}.
366
367 Errors in the 1990 ISO C standard were corrected in two Technical
368 Corrigenda published in 1994 and 1996.  GCC does not support the
369 uncorrected version.
370
371 An amendment to the 1990 standard was published in 1995.  This
372 amendment added digraphs and @code{__STDC_VERSION__} to the language,
373 but otherwise concerned the library.  This amendment is commonly known
374 as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
375 @dfn{C95}.  To select this standard in GCC, use the option
376 @samp{-std=iso9899:199409} (with, as for other standard versions,
377 @samp{-pedantic} to receive all required diagnostics).
378
379 A new edition of the ISO C standard was published in 1999 as ISO/IEC
380 9899:1999, and is commonly known as @dfn{C99}.  GCC has incomplete
381 support for this standard version; see
382 @uref{http://gcc.gnu.org/c99status.html} for details.  To select this
383 standard, use @samp{-std=c99} or @samp{-std=iso9899:1999}.  (While in
384 development, drafts of this standard version were referred to as
385 @dfn{C9X}.)
386
387 GCC also has some limited support for traditional (pre-ISO) C with the
388 @samp{-traditional} option.  This support may be of use for compiling
389 some very old programs that have not been updated to ISO C, but should
390 not be used for new programs.  It will not work with some modern C
391 libraries such as the GNU C library.
392
393 By default, GCC provides some extensions to the C language that on
394 rare occasions conflict with the C standard.  @xref{C
395 Extensions,,Extensions to the C Language Family}.  Use of the
396 @samp{-std} options listed above will disable these extensions where
397 they conflict with the C standard version selected.  You may also
398 select an extended version of the C language explicitly with
399 @samp{-std=gnu89} (for C89 with GNU extensions) or @samp{-std=gnu99}
400 (for C99 with GNU extensions).  The default, if no C language dialect
401 options are given, is @samp{-std=gnu89}; this will change to
402 @samp{-std=gnu99} in some future release when the C99 support is
403 complete.  Some features that are part of the C99 standard are
404 accepted as extensions in C89 mode.
405
406 The ISO C standard defines (in clause 4) two classes of conforming
407 implementation.  A @dfn{conforming hosted implementation} supports the
408 whole standard including all the library facilities; a @dfn{conforming
409 freestanding implementation} is only required to provide certain
410 library facilities: those in @code{<float.h>}, @code{<limits.h>},
411 @code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
412 @code{<iso646.h>}; and in C99, also those in @code{<stdbool.h>} and
413 @code{<stdint.h>}.  In addition, complex types, added in C99, are not
414 required for freestanding implementations.  The standard also defines
415 two environments for programs, a @dfn{freestanding environment},
416 required of all implementations and which may not have library
417 facilities beyond those required of freestanding implementations,
418 where the handling of program startup and termination are
419 implementation-defined, and a @dfn{hosted environment}, which is not
420 required, in which all the library facilities are provided and startup
421 is through a function @code{int main (void)} or @code{int main (int,
422 char *[])}.  An OS kernel would be a freestanding environment; a
423 program using the facilities of an operating system would normally be
424 in a hosted implementation.
425
426 GNU CC aims towards being usable as a conforming freestanding
427 implementation, or as the compiler for a conforming hosted
428 implementation.  By default, it will act as the compiler for a hosted
429 implementation, defining @code{__STDC_HOSTED__} as @code{1} and
430 presuming that when the names of ISO C functions are used, they have
431 the semantics defined in the standard.  To make it act as a conforming
432 freestanding implementation for a freestanding environment, use the
433 option @samp{-ffreestanding}; it will then define
434 @code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
435 meanings of function names from the standard library.  To build an OS
436 kernel, you may well still need to make your own arrangements for
437 linking and startup.  @xref{C Dialect Options,,Options Controlling C
438 Dialect}.
439
440 GNU CC does not provide the library facilities required only of hosted
441 implementations, nor yet all the facilities required by C99 of
442 freestanding implementations; to use the facilities of a hosted
443 environment, you will need to find them elsewhere (for example, in the
444 GNU C library).  @xref{Standard Libraries,,Standard Libraries}.
445
446 For references to Technical Corrigenda, Rationale documents and
447 information concerning the history of C that is available online, see
448 @uref{http://gcc.gnu.org/readings.html}
449
450 @c FIXME: details of C++ standard.
451 @c FIXME: definitions of Java and Objective C.
452
453 @xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
454 Fortran}, for details of the Fortran language supported by GCC.
455
456 @xref{References,,Language Definition References, chill, GNU Chill},
457 for details of the CHILL standard.
458
459 @include invoke.texi
460
461 @include install.texi
462
463 @include extend.texi
464
465 @include gcov.texi
466
467 @node Trouble
468 @chapter Known Causes of Trouble with GCC
469 @cindex bugs, known
470 @cindex installation trouble
471 @cindex known causes of trouble
472
473 This section describes known problems that affect users of GCC.  Most
474 of these are not GCC bugs per se---if they were, we would fix them.
475 But the result for a user may be like the result of a bug.
476
477 Some of these problems are due to bugs in other software, some are
478 missing features that are too much work to add, and some are places
479 where people's opinions differ as to what is best.
480
481 @menu
482 * Actual Bugs::               Bugs we will fix later.
483 * Installation Problems::     Problems that manifest when you install GCC.
484 * Cross-Compiler Problems::   Common problems of cross compiling with GCC.
485 * Interoperation::      Problems using GCC with other compilers,
486                            and with certain linkers, assemblers and debuggers.
487 * External Bugs::       Problems compiling certain programs.
488 * Incompatibilities::   GCC is incompatible with traditional C.
489 * Fixed Headers::       GNU C uses corrected versions of system header files.
490                            This is necessary, but doesn't always work smoothly.
491 * Standard Libraries::  GNU C uses the system C library, which might not be
492                            compliant with the ISO C standard.
493 * Disappointments::     Regrettable things we can't change, but not quite bugs.
494 * C++ Misunderstandings::     Common misunderstandings with GNU C++.
495 * Protoize Caveats::    Things to watch out for when using @code{protoize}.
496 * Non-bugs::            Things we think are right, but some others disagree.
497 * Warnings and Errors:: Which problems in your code get warnings,
498                          and which get errors.
499 @end menu
500
501 @node Actual Bugs
502 @section Actual Bugs We Haven't Fixed Yet
503
504 @itemize @bullet
505 @item
506 The @code{fixincludes} script interacts badly with automounters; if the
507 directory of system header files is automounted, it tends to be
508 unmounted while @code{fixincludes} is running.  This would seem to be a
509 bug in the automounter.  We don't know any good way to work around it.
510
511 @item
512 The @code{fixproto} script will sometimes add prototypes for the
513 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
514 @code{jmp_buf} type before that type is defined.  To work around this,
515 edit the offending file and place the typedef in front of the
516 prototypes.
517
518 @item
519 There are several obscure case of mis-using struct, union, and
520 enum tags that are not detected as errors by the compiler.
521
522 @item
523 When @samp{-pedantic-errors} is specified, GCC will incorrectly give
524 an error message when a function name is specified in an expression
525 involving the comma operator.
526
527 @item
528 Loop unrolling doesn't work properly for certain C++ programs.  This is
529 a bug in the C++ front end.  It sometimes emits incorrect debug info, and
530 the loop unrolling code is unable to recover from this error.
531 @end itemize
532
533 @node Installation Problems
534 @section Installation Problems
535
536 This is a list of problems (and some apparent problems which don't
537 really mean anything is wrong) that show up during installation of GNU
538 CC.
539
540 @itemize @bullet
541 @item
542 On certain systems, defining certain environment variables such as
543 @code{CC} can interfere with the functioning of @code{make}.
544
545 @item
546 If you encounter seemingly strange errors when trying to build the
547 compiler in a directory other than the source directory, it could be
548 because you have previously configured the compiler in the source
549 directory.  Make sure you have done all the necessary preparations.
550 @xref{Other Dir}.
551
552 @item
553 If you build GCC on a BSD system using a directory stored in a System
554 V file system, problems may occur in running @code{fixincludes} if the
555 System V file system doesn't support symbolic links.  These problems
556 result in a failure to fix the declaration of @code{size_t} in
557 @file{sys/types.h}.  If you find that @code{size_t} is a signed type and
558 that type mismatches occur, this could be the cause.
559
560 The solution is not to use such a directory for building GCC.
561
562 @item
563 In previous versions of GCC, the @code{gcc} driver program looked for
564 @code{as} and @code{ld} in various places; for example, in files
565 beginning with @file{/usr/local/lib/gcc-}.  GCC version 2 looks for
566 them in the directory
567 @file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}.
568
569 Thus, to use a version of @code{as} or @code{ld} that is not the system
570 default, for example @code{gas} or GNU @code{ld}, you must put them in
571 that directory (or make links to them from that directory).
572
573 @item
574 Some commands executed when making the compiler may fail (return a
575 non-zero status) and be ignored by @code{make}.  These failures, which
576 are often due to files that were not found, are expected, and can safely
577 be ignored.
578
579 @item
580 It is normal to have warnings in compiling certain files about
581 unreachable code and about enumeration type clashes.  These files' names
582 begin with @samp{insn-}.  Also, @file{real.c} may get some warnings that
583 you can ignore.
584
585 @item
586 Sometimes @code{make} recompiles parts of the compiler when installing
587 the compiler.  In one case, this was traced down to a bug in
588 @code{make}.  Either ignore the problem or switch to GNU Make.
589
590 @item
591 If you have installed a program known as purify, you may find that it
592 causes errors while linking @code{enquire}, which is part of building
593 GCC.  The fix is to get rid of the file @code{real-ld} which purify
594 installs---so that GCC won't try to use it.
595
596 @item
597 On GNU/Linux SLS 1.01, there is a problem with @file{libc.a}: it does not
598 contain the obstack functions.  However, GCC assumes that the obstack
599 functions are in @file{libc.a} when it is the GNU C library.  To work
600 around this problem, change the @code{__GNU_LIBRARY__} conditional
601 around line 31 to @samp{#if 1}.
602
603 @item
604 On some 386 systems, building the compiler never finishes because
605 @code{enquire} hangs due to a hardware problem in the motherboard---it
606 reports floating point exceptions to the kernel incorrectly.  You can
607 install GCC except for @file{float.h} by patching out the command to
608 run @code{enquire}.  You may also be able to fix the problem for real by
609 getting a replacement motherboard.  This problem was observed in
610 Revision E of the Micronics motherboard, and is fixed in Revision F.
611 It has also been observed in the MYLEX MXA-33 motherboard.
612
613 If you encounter this problem, you may also want to consider removing
614 the FPU from the socket during the compilation.  Alternatively, if you
615 are running SCO Unix, you can reboot and force the FPU to be ignored.
616 To do this, type @samp{hd(40)unix auto ignorefpu}.
617
618 @item
619 On some 386 systems, GCC crashes trying to compile @file{enquire.c}.
620 This happens on machines that don't have a 387 FPU chip.  On 386
621 machines, the system kernel is supposed to emulate the 387 when you
622 don't have one.  The crash is due to a bug in the emulator.
623
624 One of these systems is the Unix from Interactive Systems: 386/ix.
625 On this system, an alternate emulator is provided, and it does work.
626 To use it, execute this command as super-user:
627
628 @example
629 ln /etc/emulator.rel1 /etc/emulator
630 @end example
631
632 @noindent
633 and then reboot the system.  (The default emulator file remains present
634 under the name @file{emulator.dflt}.)
635
636 Try using @file{/etc/emulator.att}, if you have such a problem on the
637 SCO system.
638
639 Another system which has this problem is Esix.  We don't know whether it
640 has an alternate emulator that works.
641
642 On NetBSD 0.8, a similar problem manifests itself as these error messages:
643
644 @example
645 enquire.c: In function `fprop':
646 enquire.c:2328: floating overflow
647 @end example
648
649 @item
650 On SCO systems, when compiling GCC with the system's compiler,
651 do not use @samp{-O}.  Some versions of the system's compiler miscompile
652 GCC with @samp{-O}.
653
654 @cindex @code{genflags}, crash on Sun 4
655 @item
656 Sometimes on a Sun 4 you may observe a crash in the program
657 @code{genflags} or @code{genoutput} while building GCC.  This is said to
658 be due to a bug in @code{sh}.  You can probably get around it by running
659 @code{genflags} or @code{genoutput} manually and then retrying the
660 @code{make}.
661
662 @item
663 On Solaris 2, executables of GCC version 2.0.2 are commonly
664 available, but they have a bug that shows up when compiling current
665 versions of GCC: undefined symbol errors occur during assembly if you
666 use @samp{-g}.
667
668 The solution is to compile the current version of GCC without
669 @samp{-g}.  That makes a working compiler which you can use to recompile
670 with @samp{-g}.
671
672 @item
673 Solaris 2 comes with a number of optional OS packages.  Some of these
674 packages are needed to use GCC fully.  If you did not install all
675 optional packages when installing Solaris, you will need to verify that
676 the packages that GCC needs are installed.
677
678 To check whether an optional package is installed, use
679 the @code{pkginfo} command.  To add an optional package, use the
680 @code{pkgadd} command.  For further details, see the Solaris
681 documentation.
682
683 For Solaris 2.0 and 2.1, GCC needs six packages: @samp{SUNWarc},
684 @samp{SUNWbtool}, @samp{SUNWesu}, @samp{SUNWhea}, @samp{SUNWlibm}, and
685 @samp{SUNWtoo}.
686
687 For Solaris 2.2, GCC needs an additional seventh package: @samp{SUNWsprot}.
688
689 @item
690 On Solaris 2, trying to use the linker and other tools in
691 @file{/usr/ucb} to install GCC has been observed to cause trouble.
692 For example, the linker may hang indefinitely.  The fix is to remove
693 @file{/usr/ucb} from your @code{PATH}.
694
695 @item
696 If you use the 1.31 version of the MIPS assembler (such as was shipped
697 with Ultrix 3.1), you will need to use the -fno-delayed-branch switch
698 when optimizing floating point code.  Otherwise, the assembler will
699 complain when the GCC compiler fills a branch delay slot with a
700 floating point instruction, such as @code{add.d}.
701
702 @item
703 If on a MIPS system you get an error message saying ``does not have gp
704 sections for all it's [sic] sectons [sic]'', don't worry about it.  This
705 happens whenever you use GAS with the MIPS linker, but there is not
706 really anything wrong, and it is okay to use the output file.  You can
707 stop such warnings by installing the GNU linker.
708
709 It would be nice to extend GAS to produce the gp tables, but they are
710 optional, and there should not be a warning about their absence.
711
712 @item
713 In Ultrix 4.0 on the MIPS machine, @file{stdio.h} does not work with GNU
714 CC at all unless it has been fixed with @code{fixincludes}.  This causes
715 problems in building GCC.  Once GCC is installed, the problems go
716 away.
717
718 To work around this problem, when making the stage 1 compiler, specify
719 this option to Make:
720
721 @example
722 GCC_FOR_TARGET="./xgcc -B./ -I./include"
723 @end example
724
725 When making stage 2 and stage 3, specify this option:
726
727 @example
728 CFLAGS="-g -I./include"
729 @end example
730
731 @item
732 Users have reported some problems with version 2.0 of the MIPS
733 compiler tools that were shipped with Ultrix 4.1.  Version 2.10
734 which came with Ultrix 4.2 seems to work fine.
735
736 Users have also reported some problems with version 2.20 of the
737 MIPS compiler tools that were shipped with RISC/os 4.x.  The earlier
738 version 2.11 seems to work fine.
739
740 @item
741 Some versions of the MIPS linker will issue an assertion failure
742 when linking code that uses @code{alloca} against shared
743 libraries on RISC-OS 5.0, and DEC's OSF/1 systems.  This is a bug
744 in the linker, that is supposed to be fixed in future revisions.
745 To protect against this, GCC passes @samp{-non_shared} to the
746 linker unless you pass an explicit @samp{-shared} or
747 @samp{-call_shared} switch.
748
749 @item
750 On System V release 3, you may get this error message
751 while linking:
752
753 @smallexample
754 ld fatal: failed to write symbol name @var{something}
755  in strings table for file @var{whatever}
756 @end smallexample
757
758 This probably indicates that the disk is full or your ULIMIT won't allow
759 the file to be as large as it needs to be.
760
761 This problem can also result because the kernel parameter @code{MAXUMEM}
762 is too small.  If so, you must regenerate the kernel and make the value
763 much larger.  The default value is reported to be 1024; a value of 32768
764 is said to work.  Smaller values may also work.
765
766 @item
767 On System V, if you get an error like this,
768
769 @example
770 /usr/local/lib/bison.simple: In function `yyparse':
771 /usr/local/lib/bison.simple:625: virtual memory exhausted
772 @end example
773
774 @noindent
775 that too indicates a problem with disk space, ULIMIT, or @code{MAXUMEM}.
776
777 @item
778 Current GCC versions probably do not work on version 2 of the NeXT
779 operating system.
780
781 @item
782 On NeXTStep 3.0, the Objective C compiler does not work, due,
783 apparently, to a kernel bug that it happens to trigger.  This problem
784 does not happen on 3.1.
785
786 @item
787 On the Tower models 4@var{n}0 and 6@var{n}0, by default a process is not
788 allowed to have more than one megabyte of memory.  GCC cannot compile
789 itself (or many other programs) with @samp{-O} in that much memory.
790
791 To solve this problem, reconfigure the kernel adding the following line
792 to the configuration file:
793
794 @smallexample
795 MAXUMEM = 4096
796 @end smallexample
797
798 @item
799 On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a bug
800 in the assembler that must be fixed before GCC can be built.  This
801 bug manifests itself during the first stage of compilation, while
802 building @file{libgcc2.a}:
803
804 @smallexample
805 _floatdisf
806 cc1: warning: `-g' option not supported on this version of GCC
807 cc1: warning: `-g1' option not supported on this version of GCC
808 ./xgcc: Internal compiler error: program as got fatal signal 11
809 @end smallexample
810
811 A patched version of the assembler is available as the file
812 @uref{ftp://altdorf.ai.mit.edu/archive/cph/hpux-8.0-assembler}.  If you
813 have HP software support, the patch can also be obtained directly from
814 HP, as described in the following note:
815
816 @quotation
817 This is the patched assembler, to patch SR#1653-010439, where the
818 assembler aborts on floating point constants.
819
820 The bug is not really in the assembler, but in the shared library
821 version of the function ``cvtnum(3c)''.  The bug on ``cvtnum(3c)'' is
822 SR#4701-078451.  Anyway, the attached assembler uses the archive
823 library version of ``cvtnum(3c)'' and thus does not exhibit the bug.
824 @end quotation
825
826 This patch is also known as PHCO_4484.
827
828 @item
829 On HP-UX version 8.05, but not on 8.07 or more recent versions,
830 the @code{fixproto} shell script triggers a bug in the system shell.
831 If you encounter this problem, upgrade your operating system or
832 use BASH (the GNU shell) to run @code{fixproto}.
833
834 @item
835 Some versions of the Pyramid C compiler are reported to be unable to
836 compile GCC.  You must use an older version of GCC for
837 bootstrapping.  One indication of this problem is if you get a crash
838 when GCC compiles the function @code{muldi3} in file @file{libgcc2.c}.
839
840 You may be able to succeed by getting GCC version 1, installing it,
841 and using it to compile GCC version 2.  The bug in the Pyramid C
842 compiler does not seem to affect GCC version 1.
843
844 @item
845 There may be similar problems on System V Release 3.1 on 386 systems.
846
847 @item
848 On the Intel Paragon (an i860 machine), if you are using operating
849 system version 1.0, you will get warnings or errors about redefinition
850 of @code{va_arg} when you build GCC.
851
852 If this happens, then you need to link most programs with the library
853 @file{iclib.a}.  You must also modify @file{stdio.h} as follows: before
854 the lines
855
856 @example
857 #if     defined(__i860__) && !defined(_VA_LIST)
858 #include <va_list.h>
859 @end example
860
861 @noindent
862 insert the line
863
864 @example
865 #if __PGC__
866 @end example
867
868 @noindent
869 and after the lines
870
871 @example
872 extern int  vprintf(const char *, va_list );
873 extern int  vsprintf(char *, const char *, va_list );
874 #endif
875 @end example
876
877 @noindent
878 insert the line
879
880 @example
881 #endif /* __PGC__ */
882 @end example
883
884 These problems don't exist in operating system version 1.1.
885
886 @item
887 On the Altos 3068, programs compiled with GCC won't work unless you
888 fix a kernel bug.  This happens using system versions V.2.2 1.0gT1 and
889 V.2.2 1.0e and perhaps later versions as well.  See the file
890 @file{README.ALTOS}.
891
892 @item
893 You will get several sorts of compilation and linking errors on the
894 we32k if you don't follow the special instructions.  @xref{Configurations}.
895
896 @item
897 A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto
898 program to report an error of the form:
899
900 @example
901 ./fixproto: sh internal 1K buffer overflow
902 @end example
903
904 To fix this, change the first line of the fixproto script to look like:
905
906 @example
907 #!/bin/ksh
908 @end example
909 @end itemize
910
911 @node Cross-Compiler Problems
912 @section Cross-Compiler Problems
913
914 You may run into problems with cross compilation on certain machines,
915 for several reasons.
916
917 @itemize @bullet
918 @item
919 Cross compilation can run into trouble for certain machines because
920 some target machines' assemblers require floating point numbers to be
921 written as @emph{integer} constants in certain contexts.
922
923 The compiler writes these integer constants by examining the floating
924 point value as an integer and printing that integer, because this is
925 simple to write and independent of the details of the floating point
926 representation.  But this does not work if the compiler is running on
927 a different machine with an incompatible floating point format, or
928 even a different byte-ordering.
929
930 In addition, correct constant folding of floating point values
931 requires representing them in the target machine's format.
932 (The C standard does not quite require this, but in practice
933 it is the only way to win.)
934
935 It is now possible to overcome these problems by defining macros such
936 as @code{REAL_VALUE_TYPE}.  But doing so is a substantial amount of
937 work for each target machine.
938 @ifset INTERNALS
939 @xref{Cross-compilation}.
940 @end ifset
941 @ifclear INTERNALS
942 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
943 gcc.info, Using and Porting GCC}.
944 @end ifclear
945
946 @item
947 At present, the program @file{mips-tfile} which adds debug
948 support to object files on MIPS systems does not work in a cross
949 compile environment.
950 @end itemize
951
952 @node Interoperation
953 @section Interoperation
954
955 This section lists various difficulties encountered in using GNU C or
956 GNU C++ together with other compilers or with the assemblers, linkers,
957 libraries and debuggers on certain systems.
958
959 @itemize @bullet
960 @item
961 Objective C does not work on the RS/6000.
962
963 @item
964 GNU C++ does not do name mangling in the same way as other C++
965 compilers.  This means that object files compiled with one compiler
966 cannot be used with another.
967
968 This effect is intentional, to protect you from more subtle problems.
969 Compilers differ as to many internal details of C++ implementation,
970 including: how class instances are laid out, how multiple inheritance is
971 implemented, and how virtual function calls are handled.  If the name
972 encoding were made the same, your programs would link against libraries
973 provided from other compilers---but the programs would then crash when
974 run.  Incompatible libraries are then detected at link time, rather than
975 at run time.
976
977 @item
978 Older GDB versions sometimes fail to read the output of GCC version
979 2.  If you have trouble, get GDB version 4.4 or later.
980
981 @item
982 @cindex DBX
983 DBX rejects some files produced by GCC, though it accepts similar
984 constructs in output from PCC.  Until someone can supply a coherent
985 description of what is valid DBX input and what is not, there is
986 nothing I can do about these problems.  You are on your own.
987
988 @item
989 The GNU assembler (GAS) does not support PIC.  To generate PIC code, you
990 must use some other assembler, such as @file{/bin/as}.
991
992 @item
993 On some BSD systems, including some versions of Ultrix, use of profiling
994 causes static variable destructors (currently used only in C++) not to
995 be run.
996
997 @item
998 Use of @samp{-I/usr/include} may cause trouble.
999
1000 Many systems come with header files that won't work with GCC unless
1001 corrected by @code{fixincludes}.  The corrected header files go in a new
1002 directory; GCC searches this directory before @file{/usr/include}.
1003 If you use @samp{-I/usr/include}, this tells GCC to search
1004 @file{/usr/include} earlier on, before the corrected headers.  The
1005 result is that you get the uncorrected header files.
1006
1007 Instead, you should use these options (when compiling C programs):
1008
1009 @smallexample
1010 -I/usr/local/lib/gcc-lib/@var{target}/@var{version}/include -I/usr/include
1011 @end smallexample
1012
1013 For C++ programs, GCC also uses a special directory that defines C++
1014 interfaces to standard C subroutines.  This directory is meant to be
1015 searched @emph{before} other standard include directories, so that it
1016 takes precedence.  If you are compiling C++ programs and specifying
1017 include directories explicitly, use this option first, then the two
1018 options above:
1019
1020 @example
1021 -I/usr/local/lib/g++-include
1022 @end example
1023
1024 @ignore
1025 @cindex @code{vfork}, for the Sun-4
1026 @item
1027 There is a bug in @code{vfork} on the Sun-4 which causes the registers
1028 of the child process to clobber those of the parent.  Because of this,
1029 programs that call @code{vfork} are likely to lose when compiled
1030 optimized with GCC when the child code alters registers which contain
1031 C variables in the parent.  This affects variables which are live in the
1032 parent across the call to @code{vfork}.
1033
1034 If you encounter this, you can work around the problem by declaring
1035 variables @code{volatile} in the function that calls @code{vfork}, until
1036 the problem goes away, or by not declaring them @code{register} and not
1037 using @samp{-O} for those source files.
1038 @end ignore
1039
1040 @item
1041 On some SGI systems, when you use @samp{-lgl_s} as an option,
1042 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
1043 Naturally, this does not happen when you use GCC.
1044 You must specify all three options explicitly.
1045
1046 @item
1047 On a Sparc, GCC aligns all values of type @code{double} on an 8-byte
1048 boundary, and it expects every @code{double} to be so aligned.  The Sun
1049 compiler usually gives @code{double} values 8-byte alignment, with one
1050 exception: function arguments of type @code{double} may not be aligned.
1051
1052 As a result, if a function compiled with Sun CC takes the address of an
1053 argument of type @code{double} and passes this pointer of type
1054 @code{double *} to a function compiled with GCC, dereferencing the
1055 pointer may cause a fatal signal.
1056
1057 One way to solve this problem is to compile your entire program with GNU
1058 CC.  Another solution is to modify the function that is compiled with
1059 Sun CC to copy the argument into a local variable; local variables
1060 are always properly aligned.  A third solution is to modify the function
1061 that uses the pointer to dereference it via the following function
1062 @code{access_double} instead of directly with @samp{*}:
1063
1064 @smallexample
1065 inline double
1066 access_double (double *unaligned_ptr)
1067 @{
1068   union d2i @{ double d; int i[2]; @};
1069
1070   union d2i *p = (union d2i *) unaligned_ptr;
1071   union d2i u;
1072
1073   u.i[0] = p->i[0];
1074   u.i[1] = p->i[1];
1075
1076   return u.d;
1077 @}
1078 @end smallexample
1079
1080 @noindent
1081 Storing into the pointer can be done likewise with the same union.
1082
1083 @item
1084 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
1085 may allocate memory that is only 4 byte aligned.  Since GCC on the
1086 Sparc assumes that doubles are 8 byte aligned, this may result in a
1087 fatal signal if doubles are stored in memory allocated by the
1088 @file{libmalloc.a} library.
1089
1090 The solution is to not use the @file{libmalloc.a} library.  Use instead
1091 @code{malloc} and related functions from @file{libc.a}; they do not have
1092 this problem.
1093
1094 @item
1095 Sun forgot to include a static version of @file{libdl.a} with some
1096 versions of SunOS (mainly 4.1).  This results in undefined symbols when
1097 linking static binaries (that is, if you use @samp{-static}).  If you
1098 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
1099 when linking, compile and link against the file
1100 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
1101
1102 @item
1103 The 128-bit long double format that the Sparc port supports currently
1104 works by using the architecturally defined quad-word floating point
1105 instructions.  Since there is no hardware that supports these
1106 instructions they must be emulated by the operating system.  Long
1107 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
1108 kernel emulator uses an obsolete and incompatible format.  Long doubles
1109 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
1110 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
1111 does not enable them by default.  Long doubles appear to work in Sun OS
1112 5.x (Solaris 2.x).
1113
1114 @item
1115 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
1116 compile GCC correctly.  We do not yet know why.  However, GCC
1117 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
1118 compile itself properly on 9.01.
1119
1120 @item
1121 On the HP PA machine, ADB sometimes fails to work on functions compiled
1122 with GCC.  Specifically, it fails to work on functions that use
1123 @code{alloca} or variable-size arrays.  This is because GCC doesn't
1124 generate HP-UX unwind descriptors for such functions.  It may even be
1125 impossible to generate them.
1126
1127 @item
1128 Debugging (@samp{-g}) is not supported on the HP PA machine, unless you use
1129 the preliminary GNU tools (@pxref{Installation}).
1130
1131 @item
1132 Taking the address of a label may generate errors from the HP-UX
1133 PA assembler.  GAS for the PA does not have this problem.
1134
1135 @item
1136 Using floating point parameters for indirect calls to static functions
1137 will not work when using the HP assembler.  There simply is no way for GCC
1138 to specify what registers hold arguments for static functions when using
1139 the HP assembler.  GAS for the PA does not have this problem.
1140
1141 @item
1142 In extremely rare cases involving some very large functions you may
1143 receive errors from the HP linker complaining about an out of bounds
1144 unconditional branch offset.  This used to occur more often in previous
1145 versions of GCC, but is now exceptionally rare.  If you should run
1146 into it, you can work around by making your function smaller.
1147
1148 @item
1149 GCC compiled code sometimes emits warnings from the HP-UX assembler of
1150 the form:
1151
1152 @smallexample
1153 (warning) Use of GR3 when
1154   frame >= 8192 may cause conflict.
1155 @end smallexample
1156
1157 These warnings are harmless and can be safely ignored.
1158
1159 @item
1160 The current version of the assembler (@file{/bin/as}) for the RS/6000
1161 has certain problems that prevent the @samp{-g} option in GCC from
1162 working.  Note that @file{Makefile.in} uses @samp{-g} by default when
1163 compiling @file{libgcc2.c}.
1164
1165 IBM has produced a fixed version of the assembler.  The upgraded
1166 assembler unfortunately was not included in any of the AIX 3.2 update
1167 PTF releases (3.2.2, 3.2.3, or 3.2.3e).  Users of AIX 3.1 should request
1168 PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
1169 See the file @file{README.RS6000} for more details on these updates.
1170
1171 You can test for the presence of a fixed assembler by using the
1172 command
1173
1174 @smallexample
1175 as -u < /dev/null
1176 @end smallexample
1177
1178 @noindent
1179 If the command exits normally, the assembler fix already is installed.
1180 If the assembler complains that "-u" is an unknown flag, you need to
1181 order the fix.
1182
1183 @item
1184 On the IBM RS/6000, compiling code of the form
1185
1186 @smallexample
1187 extern int foo;
1188
1189 @dots{} foo @dots{}
1190
1191 static int foo;
1192 @end smallexample
1193
1194 @noindent
1195 will cause the linker to report an undefined symbol @code{foo}.
1196 Although this behavior differs from most other systems, it is not a
1197 bug because redefining an @code{extern} variable as @code{static}
1198 is undefined in ISO C.
1199
1200 @item
1201 AIX on the RS/6000 provides support (NLS) for environments outside of
1202 the United States.  Compilers and assemblers use NLS to support
1203 locale-specific representations of various objects including
1204 floating-point numbers ("." vs "," for separating decimal fractions).
1205 There have been problems reported where the library linked with GCC does
1206 not produce the same floating-point formats that the assembler accepts.
1207 If you have this problem, set the LANG environment variable to "C" or
1208 "En_US".
1209
1210 @item
1211 Even if you specify @samp{-fdollars-in-identifiers},
1212 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
1213 to a restriction in the IBM assembler.  GAS supports these
1214 identifiers.
1215
1216 @item
1217 On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}.  XLC
1218 version 1.3.0.1 or later fixes this problem.  You can obtain XLC-1.3.0.2
1219 by requesting PTF 421749 from IBM.
1220
1221 @item
1222 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
1223 occurs when the @samp{fldcr} instruction is used.  GCC uses
1224 @samp{fldcr} on the 88100 to serialize volatile memory references.  Use
1225 the option @samp{-mno-serialize-volatile} if your version of the
1226 assembler has this bug.
1227
1228 @item
1229 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
1230 messages from the linker.  These warning messages complain of mismatched
1231 psect attributes.  You can ignore them.  @xref{VMS Install}.
1232
1233 @item
1234 On NewsOS version 3, if you include both of the files @file{stddef.h}
1235 and @file{sys/types.h}, you get an error because there are two typedefs
1236 of @code{size_t}.  You should change @file{sys/types.h} by adding these
1237 lines around the definition of @code{size_t}:
1238
1239 @smallexample
1240 #ifndef _SIZE_T
1241 #define _SIZE_T
1242 @var{actual typedef here}
1243 #endif
1244 @end smallexample
1245
1246 @cindex Alliant
1247 @item
1248 On the Alliant, the system's own convention for returning structures
1249 and unions is unusual, and is not compatible with GCC no matter
1250 what options are used.
1251
1252 @cindex RT PC
1253 @cindex IBM RT PC
1254 @item
1255 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
1256 convention for structure and union returning.  Use the option
1257 @samp{-mhc-struct-return} to tell GCC to use a convention compatible
1258 with it.
1259
1260 @cindex Vax calling convention
1261 @cindex Ultrix calling convention
1262 @item
1263 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
1264 by function calls.  However, the C compiler uses conventions compatible
1265 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
1266
1267 GCC uses the same convention as the Ultrix C compiler.  You can use
1268 these options to produce code compatible with the Fortran compiler:
1269
1270 @smallexample
1271 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
1272 @end smallexample
1273
1274 @item
1275 On the WE32k, you may find that programs compiled with GCC do not
1276 work with the standard shared C library.  You may need to link with
1277 the ordinary C compiler.  If you do so, you must specify the following
1278 options:
1279
1280 @smallexample
1281 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
1282 @end smallexample
1283
1284 The first specifies where to find the library @file{libgcc.a}
1285 specified with the @samp{-lgcc} option.
1286
1287 GCC does linking by invoking @code{ld}, just as @code{cc} does, and
1288 there is no reason why it @emph{should} matter which compilation program
1289 you use to invoke @code{ld}.  If someone tracks this problem down,
1290 it can probably be fixed easily.
1291
1292 @item
1293 On the Alpha, you may get assembler errors about invalid syntax as a
1294 result of floating point constants.  This is due to a bug in the C
1295 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}.  Given valid
1296 floating point numbers, they sometimes print @samp{NaN}.
1297
1298 @item
1299 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
1300 sometimes reorders instructions incorrectly when optimization is turned
1301 on.  If you think this may be happening to you, try using the GNU
1302 assembler; GAS version 2.1 supports ECOFF on Irix.
1303
1304 Or use the @samp{-noasmopt} option when you compile GCC with itself,
1305 and then again when you compile your program.  (This is a temporary
1306 kludge to turn off assembler optimization on Irix.)  If this proves to
1307 be what you need, edit the assembler spec in the file @file{specs} so
1308 that it unconditionally passes @samp{-O0} to the assembler, and never
1309 passes @samp{-O2} or @samp{-O3}.
1310 @end itemize
1311
1312 @node External Bugs
1313 @section Problems Compiling Certain Programs
1314
1315 @c prevent bad page break with this line
1316 Certain programs have problems compiling.
1317
1318 @itemize @bullet
1319 @item
1320 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
1321 because of problems in DEC's versions of the X11 header files
1322 @file{X11/Xlib.h} and @file{X11/Xutil.h}.  People recommend adding
1323 @samp{-I/usr/include/mit} to use the MIT versions of the header files,
1324 using the @samp{-traditional} switch to turn off ISO C, or fixing the
1325 header files by adding this:
1326
1327 @example
1328 #ifdef __STDC__
1329 #define NeedFunctionPrototypes 0
1330 #endif
1331 @end example
1332
1333 @item
1334 On various 386 Unix systems derived from System V, including SCO, ISC,
1335 and ESIX, you may get error messages about running out of virtual memory
1336 while compiling certain programs.
1337
1338 You can prevent this problem by linking GCC with the GNU malloc
1339 (which thus replaces the malloc that comes with the system).  GNU malloc
1340 is available as a separate package, and also in the file
1341 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
1342
1343 If you have installed GNU malloc as a separate library package, use this
1344 option when you relink GCC:
1345
1346 @example
1347 MALLOC=/usr/local/lib/libgmalloc.a
1348 @end example
1349
1350 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
1351 the object file to @file{gmalloc.o} and use this option when you relink
1352 GCC:
1353
1354 @example
1355 MALLOC=gmalloc.o
1356 @end example
1357 @end itemize
1358
1359 @node Incompatibilities
1360 @section Incompatibilities of GCC
1361 @cindex incompatibilities of GCC
1362
1363 There are several noteworthy incompatibilities between GNU C and K&R 
1364 (non-ISO) versions of C.  The @samp{-traditional} option
1365 eliminates many of these incompatibilities, @emph{but not all}, by
1366 telling GNU C to behave like a K&R C compiler.
1367
1368 @itemize @bullet
1369 @cindex string constants
1370 @cindex read-only strings
1371 @cindex shared strings
1372 @item
1373 GCC normally makes string constants read-only.  If several
1374 identical-looking string constants are used, GCC stores only one
1375 copy of the string.
1376
1377 @cindex @code{mktemp}, and constant strings
1378 One consequence is that you cannot call @code{mktemp} with a string
1379 constant argument.  The function @code{mktemp} always alters the
1380 string its argument points to.
1381
1382 @cindex @code{sscanf}, and constant strings
1383 @cindex @code{fscanf}, and constant strings
1384 @cindex @code{scanf}, and constant strings
1385 Another consequence is that @code{sscanf} does not work on some systems
1386 when passed a string constant as its format control string or input.
1387 This is because @code{sscanf} incorrectly tries to write into the string
1388 constant.  Likewise @code{fscanf} and @code{scanf}.
1389
1390 The best solution to these problems is to change the program to use
1391 @code{char}-array variables with initialization strings for these
1392 purposes instead of string constants.  But if this is not possible,
1393 you can use the @samp{-fwritable-strings} flag, which directs GCC
1394 to handle string constants the same way most C compilers do.
1395 @samp{-traditional} also has this effect, among others.
1396
1397 @item
1398 @code{-2147483648} is positive.
1399
1400 This is because 2147483648 cannot fit in the type @code{int}, so
1401 (following the ISO C rules) its data type is @code{unsigned long int}.
1402 Negating this value yields 2147483648 again.
1403
1404 @item
1405 GCC does not substitute macro arguments when they appear inside of
1406 string constants.  For example, the following macro in GCC
1407
1408 @example
1409 #define foo(a) "a"
1410 @end example
1411
1412 @noindent
1413 will produce output @code{"a"} regardless of what the argument @var{a} is.
1414
1415 The @samp{-traditional} option directs GCC to handle such cases
1416 (among others) in the old-fashioned (non-ISO) fashion.
1417
1418 @cindex @code{setjmp} incompatibilities
1419 @cindex @code{longjmp} incompatibilities
1420 @item
1421 When you use @code{setjmp} and @code{longjmp}, the only automatic
1422 variables guaranteed to remain valid are those declared
1423 @code{volatile}.  This is a consequence of automatic register
1424 allocation.  Consider this function:
1425
1426 @example
1427 jmp_buf j;
1428
1429 foo ()
1430 @{
1431   int a, b;
1432
1433   a = fun1 ();
1434   if (setjmp (j))
1435     return a;
1436
1437   a = fun2 ();
1438   /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
1439   return a + fun3 ();
1440 @}
1441 @end example
1442
1443 Here @code{a} may or may not be restored to its first value when the
1444 @code{longjmp} occurs.  If @code{a} is allocated in a register, then
1445 its first value is restored; otherwise, it keeps the last value stored
1446 in it.
1447
1448 If you use the @samp{-W} option with the @samp{-O} option, you will
1449 get a warning when GCC thinks such a problem might be possible.
1450
1451 The @samp{-traditional} option directs GNU C to put variables in
1452 the stack by default, rather than in registers, in functions that
1453 call @code{setjmp}.  This results in the behavior found in
1454 traditional C compilers.
1455
1456 @item
1457 Programs that use preprocessing directives in the middle of macro
1458 arguments do not work with GCC.  For example, a program like this
1459 will not work:
1460
1461 @example
1462 foobar (
1463 #define luser
1464         hack)
1465 @end example
1466
1467 ISO C does not permit such a construct.  It would make sense to support
1468 it when @samp{-traditional} is used, but it is too much work to
1469 implement.
1470
1471 @item
1472 K&R compilers allow comments to cross over an inclusion boundary (i.e.
1473 started in an include file and ended in the including file).  I think
1474 this would be quite ugly and can't imagine it could be needed.
1475
1476 @cindex external declaration scope
1477 @cindex scope of external declarations
1478 @cindex declaration scope
1479 @item
1480 Declarations of external variables and functions within a block apply
1481 only to the block containing the declaration.  In other words, they
1482 have the same scope as any other declaration in the same place.
1483
1484 In some other C compilers, a @code{extern} declaration affects all the
1485 rest of the file even if it happens within a block.
1486
1487 The @samp{-traditional} option directs GNU C to treat all @code{extern}
1488 declarations as global, like traditional compilers.
1489
1490 @item
1491 In traditional C, you can combine @code{long}, etc., with a typedef name,
1492 as shown here:
1493
1494 @example
1495 typedef int foo;
1496 typedef long foo bar;
1497 @end example
1498
1499 In ISO C, this is not allowed: @code{long} and other type modifiers
1500 require an explicit @code{int}.  Because this criterion is expressed
1501 by Bison grammar rules rather than C code, the @samp{-traditional}
1502 flag cannot alter it.
1503
1504 @cindex typedef names as function parameters
1505 @item
1506 PCC allows typedef names to be used as function parameters.  The
1507 difficulty described immediately above applies here too.
1508
1509 @item
1510 When in @samp{-traditional} mode, GCC allows the following erroneous
1511 pair of declarations to appear together in a given scope:
1512
1513 @example
1514 typedef int foo;
1515 typedef foo foo;
1516 @end example
1517
1518 @item
1519 GCC treats all characters of identifiers as significant, even when in
1520 @samp{-traditional} mode.  According to K&R-1 (2.2), ``No more than the
1521 first eight characters are significant, although more may be used.''.
1522 Also according to K&R-1 (2.2), ``An identifier is a sequence of letters
1523 and digits; the first character must be a letter.  The underscore _
1524 counts as a letter.'', but GCC also allows dollar signs in identifiers.
1525
1526 @cindex whitespace
1527 @item
1528 PCC allows whitespace in the middle of compound assignment operators
1529 such as @samp{+=}.  GCC, following the ISO standard, does not
1530 allow this.  The difficulty described immediately above applies here
1531 too.
1532
1533 @cindex apostrophes
1534 @cindex '
1535 @item
1536 GCC complains about unterminated character constants inside of
1537 preprocessing conditionals that fail.  Some programs have English
1538 comments enclosed in conditionals that are guaranteed to fail; if these
1539 comments contain apostrophes, GCC will probably report an error.  For
1540 example, this code would produce an error:
1541
1542 @example
1543 #if 0
1544 You can't expect this to work.
1545 #endif
1546 @end example
1547
1548 The best solution to such a problem is to put the text into an actual
1549 C comment delimited by @samp{/*@dots{}*/}.  However,
1550 @samp{-traditional} suppresses these error messages.
1551
1552 @item
1553 Many user programs contain the declaration @samp{long time ();}.  In the
1554 past, the system header files on many systems did not actually declare
1555 @code{time}, so it did not matter what type your program declared it to
1556 return.  But in systems with ISO C headers, @code{time} is declared to
1557 return @code{time_t}, and if that is not the same as @code{long}, then
1558 @samp{long time ();} is erroneous.
1559
1560 The solution is to change your program to use appropriate system headers
1561 (@code{<time.h>} on systems with ISO C headers) and not to declare
1562 @code{time} if the system header files declare it, or failing that to
1563 use @code{time_t} as the return type of @code{time}.
1564
1565 @cindex @code{float} as function value type
1566 @item
1567 When compiling functions that return @code{float}, PCC converts it to
1568 a double.  GCC actually returns a @code{float}.  If you are concerned
1569 with PCC compatibility, you should declare your functions to return
1570 @code{double}; you might as well say what you mean.
1571
1572 @cindex structures
1573 @cindex unions
1574 @item
1575 When compiling functions that return structures or unions, GCC
1576 output code normally uses a method different from that used on most
1577 versions of Unix.  As a result, code compiled with GCC cannot call
1578 a structure-returning function compiled with PCC, and vice versa.
1579
1580 The method used by GCC is as follows: a structure or union which is
1581 1, 2, 4 or 8 bytes long is returned like a scalar.  A structure or union
1582 with any other size is stored into an address supplied by the caller
1583 (usually in a special, fixed register, but on some machines it is passed
1584 on the stack).  The machine-description macros @code{STRUCT_VALUE} and
1585 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
1586
1587 By contrast, PCC on most target machines returns structures and unions
1588 of any size by copying the data into an area of static storage, and then
1589 returning the address of that storage as if it were a pointer value.
1590 The caller must copy the data from that memory area to the place where
1591 the value is wanted.  GCC does not use this method because it is
1592 slower and nonreentrant.
1593
1594 On some newer machines, PCC uses a reentrant convention for all
1595 structure and union returning.  GCC on most of these machines uses a
1596 compatible convention when returning structures and unions in memory,
1597 but still returns small structures and unions in registers.
1598
1599 You can tell GCC to use a compatible convention for all structure and
1600 union returning with the option @samp{-fpcc-struct-return}.
1601
1602 @cindex preprocessing tokens
1603 @cindex preprocessing numbers
1604 @item
1605 GNU C complains about program fragments such as @samp{0x74ae-0x4000}
1606 which appear to be two hexadecimal constants separated by the minus
1607 operator.  Actually, this string is a single @dfn{preprocessing token}.
1608 Each such token must correspond to one token in C.  Since this does not,
1609 GNU C prints an error message.  Although it may appear obvious that what
1610 is meant is an operator and two values, the ISO C standard specifically
1611 requires that this be treated as erroneous.
1612
1613 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
1614 begins with a digit and is followed by letters, underscores, digits,
1615 periods and @samp{e+}, @samp{e-}, @samp{E+}, or @samp{E-} character
1616 sequences.
1617
1618 To make the above program fragment valid, place whitespace in front of
1619 the minus sign.  This whitespace will end the preprocessing number.
1620 @end itemize
1621
1622 @node Fixed Headers
1623 @section Fixed Header Files
1624
1625 GCC needs to install corrected versions of some system header files.
1626 This is because most target systems have some header files that won't
1627 work with GCC unless they are changed.  Some have bugs, some are
1628 incompatible with ISO C, and some depend on special features of other
1629 compilers.
1630
1631 Installing GCC automatically creates and installs the fixed header
1632 files, by running a program called @code{fixincludes} (or for certain
1633 targets an alternative such as @code{fixinc.svr4}).  Normally, you
1634 don't need to pay attention to this.  But there are cases where it
1635 doesn't do the right thing automatically.
1636
1637 @itemize @bullet
1638 @item
1639 If you update the system's header files, such as by installing a new
1640 system version, the fixed header files of GCC are not automatically
1641 updated.  The easiest way to update them is to reinstall GCC.  (If
1642 you want to be clever, look in the makefile and you can find a
1643 shortcut.)
1644
1645 @item
1646 On some systems, in particular SunOS 4, header file directories contain
1647 machine-specific symbolic links in certain places.  This makes it
1648 possible to share most of the header files among hosts running the
1649 same version of SunOS 4 on different machine models.
1650
1651 The programs that fix the header files do not understand this special
1652 way of using symbolic links; therefore, the directory of fixed header
1653 files is good only for the machine model used to build it.
1654
1655 In SunOS 4, only programs that look inside the kernel will notice the
1656 difference between machine models.  Therefore, for most purposes, you
1657 need not be concerned about this.
1658
1659 It is possible to make separate sets of fixed header files for the
1660 different machine models, and arrange a structure of symbolic links so
1661 as to use the proper set, but you'll have to do this by hand.
1662
1663 @item
1664 On Lynxos, GCC by default does not fix the header files.  This is
1665 because bugs in the shell cause the @code{fixincludes} script to fail.
1666
1667 This means you will encounter problems due to bugs in the system header
1668 files.  It may be no comfort that they aren't GCC's fault, but it
1669 does mean that there's nothing for us to do about them.
1670 @end itemize
1671
1672 @node Standard Libraries
1673 @section Standard Libraries
1674
1675 GCC by itself attempts to be a conforming freestanding implementation.
1676 @xref{Standards,,Language Standards Supported by GCC}, for details of
1677 what this means.  Beyond the library facilities required of such an
1678 implementation, the rest of the C library is supplied by the vendor of
1679 the operating system.  If that C library doesn't conform to the C
1680 standards, then your programs might get warnings (especially when using
1681 @samp{-Wall}) that you don't expect.
1682
1683 For example, the @code{sprintf} function on SunOS 4.1.3 returns
1684 @code{char *} while the C standard says that @code{sprintf} returns an
1685 @code{int}.  The @code{fixincludes} program could make the prototype for
1686 this function match the Standard, but that would be wrong, since the
1687 function will still return @code{char *}.
1688
1689 If you need a Standard compliant library, then you need to find one, as
1690 GCC does not provide one.  The GNU C library (called @code{glibc})
1691 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
1692 GNU/Linux and HURD-based GNU systems; no recent version of it supports
1693 other systems, though some very old versions did.  Version 2.2 of the
1694 GNU C library includes nearly complete C99 support.  You could also ask
1695 your operating system vendor if newer libraries are available.
1696
1697 @node Disappointments
1698 @section Disappointments and Misunderstandings
1699
1700 These problems are perhaps regrettable, but we don't know any practical
1701 way around them.
1702
1703 @itemize @bullet
1704 @item
1705 Certain local variables aren't recognized by debuggers when you compile
1706 with optimization.
1707
1708 This occurs because sometimes GCC optimizes the variable out of
1709 existence.  There is no way to tell the debugger how to compute the
1710 value such a variable ``would have had'', and it is not clear that would
1711 be desirable anyway.  So GCC simply does not mention the eliminated
1712 variable when it writes debugging information.
1713
1714 You have to expect a certain amount of disagreement between the
1715 executable and your source code, when you use optimization.
1716
1717 @cindex conflicting types
1718 @cindex scope of declaration
1719 @item
1720 Users often think it is a bug when GCC reports an error for code
1721 like this:
1722
1723 @example
1724 int foo (struct mumble *);
1725
1726 struct mumble @{ @dots{} @};
1727
1728 int foo (struct mumble *x)
1729 @{ @dots{} @}
1730 @end example
1731
1732 This code really is erroneous, because the scope of @code{struct
1733 mumble} in the prototype is limited to the argument list containing it.
1734 It does not refer to the @code{struct mumble} defined with file scope
1735 immediately below---they are two unrelated types with similar names in
1736 different scopes.
1737
1738 But in the definition of @code{foo}, the file-scope type is used
1739 because that is available to be inherited.  Thus, the definition and
1740 the prototype do not match, and you get an error.
1741
1742 This behavior may seem silly, but it's what the ISO standard specifies.
1743 It is easy enough for you to make your code work by moving the
1744 definition of @code{struct mumble} above the prototype.  It's not worth
1745 being incompatible with ISO C just to avoid an error for the example
1746 shown above.
1747
1748 @item
1749 Accesses to bitfields even in volatile objects works by accessing larger
1750 objects, such as a byte or a word.  You cannot rely on what size of
1751 object is accessed in order to read or write the bitfield; it may even
1752 vary for a given bitfield according to the precise usage.
1753
1754 If you care about controlling the amount of memory that is accessed, use
1755 volatile but do not use bitfields.
1756
1757 @item
1758 GCC comes with shell scripts to fix certain known problems in system
1759 header files.  They install corrected copies of various header files in
1760 a special directory where only GCC will normally look for them.  The
1761 scripts adapt to various systems by searching all the system header
1762 files for the problem cases that we know about.
1763
1764 If new system header files are installed, nothing automatically arranges
1765 to update the corrected header files.  You will have to reinstall GCC
1766 to fix the new header files.  More specifically, go to the build
1767 directory and delete the files @file{stmp-fixinc} and
1768 @file{stmp-headers}, and the subdirectory @code{include}; then do
1769 @samp{make install} again.
1770
1771 @item
1772 @cindex floating point precision
1773 On 68000 and x86 systems, for instance, you can get paradoxical results
1774 if you test the precise values of floating point numbers.  For example,
1775 you can find that a floating point value which is not a NaN is not equal
1776 to itself.  This results from the fact that the floating point registers
1777 hold a few more bits of precision than fit in a @code{double} in memory.
1778 Compiled code moves values between memory and floating point registers
1779 at its convenience, and moving them into memory truncates them.
1780
1781 You can partially avoid this problem by using the @samp{-ffloat-store}
1782 option (@pxref{Optimize Options}).
1783
1784 @item
1785 On the MIPS, variable argument functions using @file{varargs.h}
1786 cannot have a floating point value for the first argument.  The
1787 reason for this is that in the absence of a prototype in scope,
1788 if the first argument is a floating point, it is passed in a
1789 floating point register, rather than an integer register.
1790
1791 If the code is rewritten to use the ISO standard @file{stdarg.h}
1792 method of variable arguments, and the prototype is in scope at
1793 the time of the call, everything will work fine.
1794
1795 @item
1796 On the H8/300 and H8/300H, variable argument functions must be
1797 implemented using the ISO standard @file{stdarg.h} method of
1798 variable arguments.  Furthermore, calls to functions using @file{stdarg.h}
1799 variable arguments must have a prototype for the called function
1800 in scope at the time of the call.
1801 @end itemize
1802
1803 @node C++ Misunderstandings
1804 @section Common Misunderstandings with GNU C++
1805
1806 @cindex misunderstandings in C++
1807 @cindex surprises in C++
1808 @cindex C++ misunderstandings
1809 C++ is a complex language and an evolving one, and its standard
1810 definition (the ISO C++ standard) was only recently completed.  As a
1811 result, your C++ compiler may occasionally surprise you, even when its
1812 behavior is correct.  This section discusses some areas that frequently
1813 give rise to questions of this sort.
1814
1815 @menu
1816 * Static Definitions::  Static member declarations are not definitions
1817 * Temporaries::         Temporaries may vanish before you expect
1818 * Copy Assignment::     Copy Assignment operators copy virtual bases twice
1819 @end menu
1820
1821 @node Static Definitions
1822 @subsection Declare @emph{and} Define Static Members
1823
1824 @cindex C++ static data, declaring and defining
1825 @cindex static data in C++, declaring and defining
1826 @cindex declaring static data in C++
1827 @cindex defining static data in C++
1828 When a class has static data members, it is not enough to @emph{declare}
1829 the static member; you must also @emph{define} it.  For example:
1830
1831 @example
1832 class Foo
1833 @{
1834   @dots{}
1835   void method();
1836   static int bar;
1837 @};
1838 @end example
1839
1840 This declaration only establishes that the class @code{Foo} has an
1841 @code{int} named @code{Foo::bar}, and a member function named
1842 @code{Foo::method}.  But you still need to define @emph{both}
1843 @code{method} and @code{bar} elsewhere.  According to the ISO
1844 standard, you must supply an initializer in one (and only one) source
1845 file, such as:
1846
1847 @example
1848 int Foo::bar = 0;
1849 @end example
1850
1851 Other C++ compilers may not correctly implement the standard behavior.
1852 As a result, when you switch to @code{g++} from one of these compilers,
1853 you may discover that a program that appeared to work correctly in fact
1854 does not conform to the standard: @code{g++} reports as undefined
1855 symbols any static data members that lack definitions.
1856
1857 @node Temporaries
1858 @subsection Temporaries May Vanish Before You Expect
1859
1860 @cindex temporaries, lifetime of
1861 @cindex portions of temporary objects, pointers to
1862 It is dangerous to use pointers or references to @emph{portions} of a
1863 temporary object.  The compiler may very well delete the object before
1864 you expect it to, leaving a pointer to garbage.  The most common place
1865 where this problem crops up is in classes like string classes,
1866 especially ones that define a conversion function to type @code{char *}
1867 or @code{const char *} -- which is one reason why the standard
1868 @code{string} class requires you to call the @code{c_str} member
1869 function.  However, any class that returns a pointer to some internal
1870 structure is potentially subject to this problem.
1871
1872 For example, a program may use a function @code{strfunc} that returns
1873 @code{string} objects, and another function @code{charfunc} that
1874 operates on pointers to @code{char}:
1875
1876 @example
1877 string strfunc ();
1878 void charfunc (const char *);
1879
1880 void 
1881 f ()
1882 @{
1883   const char *p = strfunc().c_str();
1884   ...
1885   charfunc (p);
1886   ...
1887   charfunc (p);
1888 @}
1889 @end example
1890
1891 @noindent
1892 In this situation, it may seem reasonable to save a pointer to the C
1893 string returned by the @code{c_str} member function and use that rather
1894 than call @code{c_str} repeatedly.  However, the temporary string
1895 created by the call to @code{strfunc} is destroyed after @code{p} is
1896 initialized, at which point @code{p} is left pointing to freed memory.
1897
1898 Code like this may run successfully under some other compilers,
1899 particularly obsolete cfront-based compilers that delete temporaries
1900 along with normal local variables.  However, the GNU C++ behavior is
1901 standard-conforming, so if your program depends on late destruction of
1902 temporaries it is not portable.
1903
1904 The safe way to write such code is to give the temporary a name, which
1905 forces it to remain until the end of the scope of the name.  For
1906 example:
1907
1908 @example
1909 string& tmp = strfunc ();
1910 charfunc (tmp.c_str ());
1911 @end example
1912
1913 @node Copy Assignment
1914 @subsection Implicit Copy-Assignment for Virtual Bases
1915
1916 When a base class is virtual, only one subobject of the base class
1917 belongs to each full object. Also, the constructors and destructors are
1918 invoked only once, and called from the most-derived class. However, such
1919 objects behave unspecified when being assigned. For example:
1920
1921 @example
1922 struct Base@{
1923   char *name;
1924   Base(char *n) : name(strdup(n))@{@}
1925   Base& operator= (const Base& other)@{
1926    free (name);
1927    name = strdup (other.name);
1928   @}
1929 @};
1930
1931 struct A:virtual Base@{
1932   int val;
1933   A():Base("A")@{@}
1934 @};
1935
1936 struct B:virtual Base@{
1937   int bval;
1938   B():Base("B")@{@}
1939 @};
1940
1941 struct Derived:public A, public B@{
1942   Derived():Base("Derived")@{@}
1943 @};
1944
1945 void func(Derived &d1, Derived &d2)
1946 @{
1947   d1 = d2;
1948 @}
1949 @end example
1950
1951 The C++ standard specifies that @samp{Base::Base} is only called once
1952 when constructing or copy-constructing a Derived object. It is
1953 unspecified whether @samp{Base::operator=} is called more than once when
1954 the implicit copy-assignment for Derived objects is invoked (as it is
1955 inside @samp{func} in the example).
1956
1957 g++ implements the "intuitive" algorithm for copy-assignment: assign all
1958 direct bases, then assign all members. In that algorithm, the virtual
1959 base subobject can be encountered many times. In the example, copying
1960 proceeds in the following order: @samp{val}, @samp{name} (via
1961 @code{strdup}), @samp{bval}, and @samp{name} again.
1962
1963 If application code relies on copy-assignment, a user-defined
1964 copy-assignment operator removes any uncertainties. With such an
1965 operator, the application can define whether and how the virtual base
1966 subobject is assigned.
1967
1968 @node Protoize Caveats
1969 @section Caveats of using @code{protoize}
1970
1971 The conversion programs @code{protoize} and @code{unprotoize} can
1972 sometimes change a source file in a way that won't work unless you
1973 rearrange it.
1974
1975 @itemize @bullet
1976 @item
1977 @code{protoize} can insert references to a type name or type tag before
1978 the definition, or in a file where they are not defined.
1979
1980 If this happens, compiler error messages should show you where the new
1981 references are, so fixing the file by hand is straightforward.
1982
1983 @item
1984 There are some C constructs which @code{protoize} cannot figure out.
1985 For example, it can't determine argument types for declaring a
1986 pointer-to-function variable; this you must do by hand.  @code{protoize}
1987 inserts a comment containing @samp{???} each time it finds such a
1988 variable; so you can find all such variables by searching for this
1989 string.  ISO C does not require declaring the argument types of
1990 pointer-to-function types.
1991
1992 @item
1993 Using @code{unprotoize} can easily introduce bugs.  If the program
1994 relied on prototypes to bring about conversion of arguments, these
1995 conversions will not take place in the program without prototypes.
1996 One case in which you can be sure @code{unprotoize} is safe is when
1997 you are removing prototypes that were made with @code{protoize}; if
1998 the program worked before without any prototypes, it will work again
1999 without them.
2000
2001 You can find all the places where this problem might occur by compiling
2002 the program with the @samp{-Wconversion} option.  It prints a warning
2003 whenever an argument is converted.
2004
2005 @item
2006 Both conversion programs can be confused if there are macro calls in and
2007 around the text to be converted.  In other words, the standard syntax
2008 for a declaration or definition must not result from expanding a macro.
2009 This problem is inherent in the design of C and cannot be fixed.  If
2010 only a few functions have confusing macro calls, you can easily convert
2011 them manually.
2012
2013 @item
2014 @code{protoize} cannot get the argument types for a function whose
2015 definition was not actually compiled due to preprocessing conditionals.
2016 When this happens, @code{protoize} changes nothing in regard to such
2017 a function.  @code{protoize} tries to detect such instances and warn
2018 about them.
2019
2020 You can generally work around this problem by using @code{protoize} step
2021 by step, each time specifying a different set of @samp{-D} options for
2022 compilation, until all of the functions have been converted.  There is
2023 no automatic way to verify that you have got them all, however.
2024
2025 @item
2026 Confusion may result if there is an occasion to convert a function
2027 declaration or definition in a region of source code where there is more
2028 than one formal parameter list present.  Thus, attempts to convert code
2029 containing multiple (conditionally compiled) versions of a single
2030 function header (in the same vicinity) may not produce the desired (or
2031 expected) results.
2032
2033 If you plan on converting source files which contain such code, it is
2034 recommended that you first make sure that each conditionally compiled
2035 region of source code which contains an alternative function header also
2036 contains at least one additional follower token (past the final right
2037 parenthesis of the function header).  This should circumvent the
2038 problem.
2039
2040 @item
2041 @code{unprotoize} can become confused when trying to convert a function
2042 definition or declaration which contains a declaration for a
2043 pointer-to-function formal argument which has the same name as the
2044 function being defined or declared.  We recommend you avoid such choices
2045 of formal parameter names.
2046
2047 @item
2048 You might also want to correct some of the indentation by hand and break
2049 long lines.  (The conversion programs don't write lines longer than
2050 eighty characters in any case.)
2051 @end itemize
2052
2053 @node Non-bugs
2054 @section Certain Changes We Don't Want to Make
2055
2056 This section lists changes that people frequently request, but which
2057 we do not make because we think GCC is better without them.
2058
2059 @itemize @bullet
2060 @item
2061 Checking the number and type of arguments to a function which has an
2062 old-fashioned definition and no prototype.
2063
2064 Such a feature would work only occasionally---only for calls that appear
2065 in the same file as the called function, following the definition.  The
2066 only way to check all calls reliably is to add a prototype for the
2067 function.  But adding a prototype eliminates the motivation for this
2068 feature.  So the feature is not worthwhile.
2069
2070 @item
2071 Warning about using an expression whose type is signed as a shift count.
2072
2073 Shift count operands are probably signed more often than unsigned.
2074 Warning about this would cause far more annoyance than good.
2075
2076 @item
2077 Warning about assigning a signed value to an unsigned variable.
2078
2079 Such assignments must be very common; warning about them would cause
2080 more annoyance than good.
2081
2082 @item
2083 Warning when a non-void function value is ignored.
2084
2085 Coming as I do from a Lisp background, I balk at the idea that there is
2086 something dangerous about discarding a value.  There are functions that
2087 return values which some callers may find useful; it makes no sense to
2088 clutter the program with a cast to @code{void} whenever the value isn't
2089 useful.
2090
2091 @item
2092 Assuming (for optimization) that the address of an external symbol is
2093 never zero.
2094
2095 This assumption is false on certain systems when @samp{#pragma weak} is
2096 used.
2097
2098 @item
2099 Making @samp{-fshort-enums} the default.
2100
2101 This would cause storage layout to be incompatible with most other C
2102 compilers.  And it doesn't seem very important, given that you can get
2103 the same result in other ways.  The case where it matters most is when
2104 the enumeration-valued object is inside a structure, and in that case
2105 you can specify a field width explicitly.
2106
2107 @item
2108 Making bitfields unsigned by default on particular machines where ``the
2109 ABI standard'' says to do so.
2110
2111 The ISO C standard leaves it up to the implementation whether a bitfield
2112 declared plain @code{int} is signed or not.  This in effect creates two
2113 alternative dialects of C.
2114
2115 The GNU C compiler supports both dialects; you can specify the signed
2116 dialect with @samp{-fsigned-bitfields} and the unsigned dialect with
2117 @samp{-funsigned-bitfields}.  However, this leaves open the question of
2118 which dialect to use by default.
2119
2120 Currently, the preferred dialect makes plain bitfields signed, because
2121 this is simplest.  Since @code{int} is the same as @code{signed int} in
2122 every other context, it is cleanest for them to be the same in bitfields
2123 as well.
2124
2125 Some computer manufacturers have published Application Binary Interface
2126 standards which specify that plain bitfields should be unsigned.  It is
2127 a mistake, however, to say anything about this issue in an ABI.  This is
2128 because the handling of plain bitfields distinguishes two dialects of C.
2129 Both dialects are meaningful on every type of machine.  Whether a
2130 particular object file was compiled using signed bitfields or unsigned
2131 is of no concern to other object files, even if they access the same
2132 bitfields in the same data structures.
2133
2134 A given program is written in one or the other of these two dialects.
2135 The program stands a chance to work on most any machine if it is
2136 compiled with the proper dialect.  It is unlikely to work at all if
2137 compiled with the wrong dialect.
2138
2139 Many users appreciate the GNU C compiler because it provides an
2140 environment that is uniform across machines.  These users would be
2141 inconvenienced if the compiler treated plain bitfields differently on
2142 certain machines.
2143
2144 Occasionally users write programs intended only for a particular machine
2145 type.  On these occasions, the users would benefit if the GNU C compiler
2146 were to support by default the same dialect as the other compilers on
2147 that machine.  But such applications are rare.  And users writing a
2148 program to run on more than one type of machine cannot possibly benefit
2149 from this kind of compatibility.
2150
2151 This is why GCC does and will treat plain bitfields in the same
2152 fashion on all types of machines (by default).
2153
2154 There are some arguments for making bitfields unsigned by default on all
2155 machines.  If, for example, this becomes a universal de facto standard,
2156 it would make sense for GCC to go along with it.  This is something
2157 to be considered in the future.
2158
2159 (Of course, users strongly concerned about portability should indicate
2160 explicitly in each bitfield whether it is signed or not.  In this way,
2161 they write programs which have the same meaning in both C dialects.)
2162
2163 @item
2164 Undefining @code{__STDC__} when @samp{-ansi} is not used.
2165
2166 Currently, GCC defines @code{__STDC__} as long as you don't use
2167 @samp{-traditional}.  This provides good results in practice.
2168
2169 Programmers normally use conditionals on @code{__STDC__} to ask whether
2170 it is safe to use certain features of ISO C, such as function
2171 prototypes or ISO token concatenation.  Since plain @samp{gcc} supports
2172 all the features of ISO C, the correct answer to these questions is
2173 ``yes''.
2174
2175 Some users try to use @code{__STDC__} to check for the availability of
2176 certain library facilities.  This is actually incorrect usage in an ISO
2177 C program, because the ISO C standard says that a conforming
2178 freestanding implementation should define @code{__STDC__} even though it
2179 does not have the library facilities.  @samp{gcc -ansi -pedantic} is a
2180 conforming freestanding implementation, and it is therefore required to
2181 define @code{__STDC__}, even though it does not come with an ISO C
2182 library.
2183
2184 Sometimes people say that defining @code{__STDC__} in a compiler that
2185 does not completely conform to the ISO C standard somehow violates the
2186 standard.  This is illogical.  The standard is a standard for compilers
2187 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
2188 compilers such as plain @samp{gcc}.  Whatever the ISO C standard says
2189 is relevant to the design of plain @samp{gcc} without @samp{-ansi} only
2190 for pragmatic reasons, not as a requirement.
2191
2192 GCC normally defines @code{__STDC__} to be 1, and in addition
2193 defines @code{__STRICT_ANSI__} if you specify the @samp{-ansi} option.
2194 On some hosts, system include files use a different convention, where
2195 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
2196 conformance to the C Standard.  GCC follows the host convention when
2197 processing system include files, but when processing user files it follows
2198 the usual GNU C convention.
2199
2200 @item
2201 Undefining @code{__STDC__} in C++.
2202
2203 Programs written to compile with C++-to-C translators get the
2204 value of @code{__STDC__} that goes with the C compiler that is
2205 subsequently used.  These programs must test @code{__STDC__}
2206 to determine what kind of C preprocessor that compiler uses:
2207 whether they should concatenate tokens in the ISO C fashion
2208 or in the traditional fashion.
2209
2210 These programs work properly with GNU C++ if @code{__STDC__} is defined.
2211 They would not work otherwise.
2212
2213 In addition, many header files are written to provide prototypes in ISO
2214 C but not in traditional C.  Many of these header files can work without
2215 change in C++ provided @code{__STDC__} is defined.  If @code{__STDC__}
2216 is not defined, they will all fail, and will all need to be changed to
2217 test explicitly for C++ as well.
2218
2219 @item
2220 Deleting ``empty'' loops.
2221
2222 Historically, GCC has not deleted ``empty'' loops under the
2223 assumption that the most likely reason you would put one in a program is
2224 to have a delay, so deleting them will not make real programs run any
2225 faster.
2226
2227 However, the rationale here is that optimization of a nonempty loop
2228 cannot produce an empty one, which holds for C but is not always the
2229 case for C++.
2230
2231 Moreover, with @samp{-funroll-loops} small ``empty'' loops are already
2232 removed, so the current behavior is both sub-optimal and inconsistent
2233 and will change in the future.
2234
2235 @item
2236 Making side effects happen in the same order as in some other compiler.
2237
2238 @cindex side effects, order of evaluation
2239 @cindex order of evaluation, side effects
2240 It is never safe to depend on the order of evaluation of side effects.
2241 For example, a function call like this may very well behave differently
2242 from one compiler to another:
2243
2244 @example
2245 void func (int, int);
2246
2247 int i = 2;
2248 func (i++, i++);
2249 @end example
2250
2251 There is no guarantee (in either the C or the C++ standard language
2252 definitions) that the increments will be evaluated in any particular
2253 order.  Either increment might happen first.  @code{func} might get the
2254 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
2255
2256 @item
2257 Not allowing structures with volatile fields in registers.
2258
2259 Strictly speaking, there is no prohibition in the ISO C standard
2260 against allowing structures with volatile fields in registers, but
2261 it does not seem to make any sense and is probably not what you wanted
2262 to do.  So the compiler will give an error message in this case.
2263
2264 @item
2265 Making certain warnings into errors by default.
2266
2267 Some ISO C testsuites report failure when the compiler does not produce
2268 an error message for a certain program.
2269
2270 ISO C requires a ``diagnostic'' message for certain kinds of invalid
2271 programs, but a warning is defined by GCC to count as a diagnostic.  If
2272 GCC produces a warning but not an error, that is correct ISO C support.
2273 If test suites call this ``failure'', they should be run with the GCC
2274 option @samp{-pedantic-errors}, which will turn these warnings into
2275 errors.
2276
2277 @end itemize
2278
2279 @node Warnings and Errors
2280 @section Warning Messages and Error Messages
2281
2282 @cindex error messages
2283 @cindex warnings vs errors
2284 @cindex messages, warning and error
2285 The GNU compiler can produce two kinds of diagnostics: errors and
2286 warnings.  Each kind has a different purpose:
2287
2288 @itemize @w{}
2289 @item
2290 @emph{Errors} report problems that make it impossible to compile your
2291 program.  GCC reports errors with the source file name and line
2292 number where the problem is apparent.
2293
2294 @item
2295 @emph{Warnings} report other unusual conditions in your code that
2296 @emph{may} indicate a problem, although compilation can (and does)
2297 proceed.  Warning messages also report the source file name and line
2298 number, but include the text @samp{warning:} to distinguish them
2299 from error messages.
2300 @end itemize
2301
2302 Warnings may indicate danger points where you should check to make sure
2303 that your program really does what you intend; or the use of obsolete
2304 features; or the use of nonstandard features of GNU C or C++.  Many
2305 warnings are issued only if you ask for them, with one of the @samp{-W}
2306 options (for instance, @samp{-Wall} requests a variety of useful
2307 warnings).
2308
2309 GCC always tries to compile your program if possible; it never
2310 gratuitously rejects a program whose meaning is clear merely because
2311 (for instance) it fails to conform to a standard.  In some cases,
2312 however, the C and C++ standards specify that certain extensions are
2313 forbidden, and a diagnostic @emph{must} be issued by a conforming
2314 compiler.  The @samp{-pedantic} option tells GCC to issue warnings in
2315 such cases; @samp{-pedantic-errors} says to make them errors instead.
2316 This does not mean that @emph{all} non-ISO constructs get warnings
2317 or errors.
2318
2319 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
2320 more detail on these and related command-line options.
2321
2322 @node Bugs
2323 @chapter Reporting Bugs
2324 @cindex bugs
2325 @cindex reporting bugs
2326
2327 Your bug reports play an essential role in making GCC reliable.
2328
2329 When you encounter a problem, the first thing to do is to see if it is
2330 already known.  @xref{Trouble}.  If it isn't known, then you should
2331 report the problem.
2332
2333 Reporting a bug may help you by bringing a solution to your problem, or
2334 it may not.  (If it does not, look in the service directory; see
2335 @ref{Service}.)  In any case, the principal function of a bug report is
2336 to help the entire community by making the next version of GCC work
2337 better.  Bug reports are your contribution to the maintenance of GCC.
2338
2339 Since the maintainers are very overloaded, we cannot respond to every
2340 bug report.  However, if the bug has not been fixed, we are likely to
2341 send you a patch and ask you to tell us whether it works.
2342
2343 In order for a bug report to serve its purpose, you must include the
2344 information that makes for fixing the bug.
2345
2346 @menu
2347 * Criteria:  Bug Criteria.   Have you really found a bug?
2348 * Where: Bug Lists.          Where to send your bug report.
2349 * Reporting: Bug Reporting.  How to report a bug effectively.
2350 * GNATS: gccbug.             You can use a bug reporting tool.
2351 * Patches: Sending Patches.  How to send a patch for GCC.
2352 * Known: Trouble.            Known problems.
2353 * Help: Service.             Where to ask for help.
2354 @end menu
2355
2356 @node Bug Criteria,Bug Lists,,Bugs
2357 @section Have You Found a Bug?
2358 @cindex bug criteria
2359
2360 If you are not sure whether you have found a bug, here are some guidelines:
2361
2362 @itemize @bullet
2363 @cindex fatal signal
2364 @cindex core dump
2365 @item
2366 If the compiler gets a fatal signal, for any input whatever, that is a
2367 compiler bug.  Reliable compilers never crash.
2368
2369 @cindex invalid assembly code
2370 @cindex assembly code, invalid
2371 @item
2372 If the compiler produces invalid assembly code, for any input whatever
2373 (except an @code{asm} statement), that is a compiler bug, unless the
2374 compiler reports errors (not just warnings) which would ordinarily
2375 prevent the assembler from being run.
2376
2377 @cindex undefined behavior
2378 @cindex undefined function value
2379 @cindex increment operators
2380 @item
2381 If the compiler produces valid assembly code that does not correctly
2382 execute the input source code, that is a compiler bug.
2383
2384 However, you must double-check to make sure, because you may have run
2385 into an incompatibility between GNU C and traditional C
2386 (@pxref{Incompatibilities}).  These incompatibilities might be considered
2387 bugs, but they are inescapable consequences of valuable features.
2388
2389 Or you may have a program whose behavior is undefined, which happened
2390 by chance to give the desired results with another C or C++ compiler.
2391
2392 For example, in many nonoptimizing compilers, you can write @samp{x;}
2393 at the end of a function instead of @samp{return x;}, with the same
2394 results.  But the value of the function is undefined if @code{return}
2395 is omitted; it is not a bug when GCC produces different results.
2396
2397 Problems often result from expressions with two increment operators,
2398 as in @code{f (*p++, *p++)}.  Your previous compiler might have
2399 interpreted that expression the way you intended; GCC might
2400 interpret it another way.  Neither compiler is wrong.  The bug is
2401 in your code.
2402
2403 After you have localized the error to a single source line, it should
2404 be easy to check for these things.  If your program is correct and
2405 well defined, you have found a compiler bug.
2406
2407 @item
2408 If the compiler produces an error message for valid input, that is a
2409 compiler bug.
2410
2411 @cindex invalid input
2412 @item
2413 If the compiler does not produce an error message for invalid input,
2414 that is a compiler bug.  However, you should note that your idea of
2415 ``invalid input'' might be my idea of ``an extension'' or ``support
2416 for traditional practice''.
2417
2418 @item
2419 If you are an experienced user of one of the languages GCC supports, your 
2420 suggestions for improvement of GCC are welcome in any case.
2421 @end itemize
2422
2423 @node Bug Lists,Bug Reporting,Bug Criteria,Bugs
2424 @section Where to Report Bugs
2425 @cindex bug report mailing lists
2426 @kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
2427 Send bug reports for the GNU Compiler Collection to
2428 @email{gcc-bugs@@gcc.gnu.org}.  In accordance with the GNU-wide
2429 convention, in which bug reports for tool ``foo'' are sent
2430 to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
2431 may also be used; it will forward to the address given above.
2432
2433 Please read @uref{http://www.gnu.org/software/gcc/bugs.html} for
2434 bug reporting instructions before you post a bug report.
2435
2436 Often people think of posting bug reports to the newsgroup instead of
2437 mailing them.  This appears to work, but it has one problem which can be
2438 crucial: a newsgroup posting does not contain a mail path back to the
2439 sender.  Thus, if maintainers need more information, they may be unable
2440 to reach you.  For this reason, you should always send bug reports by
2441 mail to the proper mailing list.
2442
2443 As a last resort, send bug reports on paper to:
2444
2445 @example
2446 GNU Compiler Bugs
2447 Free Software Foundation
2448 59 Temple Place - Suite 330
2449 Boston, MA 02111-1307, USA
2450 @end example
2451
2452 @node Bug Reporting,gccbug,Bug Lists,Bugs
2453 @section How to Report Bugs
2454 @cindex compiler bugs, reporting
2455
2456 You may find additional and/or more up-to-date instructions at
2457 @uref{http://www.gnu.org/software/gcc/bugs.html}.
2458
2459 The fundamental principle of reporting bugs usefully is this:
2460 @strong{report all the facts}.  If you are not sure whether to state a
2461 fact or leave it out, state it!
2462
2463 Often people omit facts because they think they know what causes the
2464 problem and they conclude that some details don't matter.  Thus, you might
2465 assume that the name of the variable you use in an example does not matter.
2466 Well, probably it doesn't, but one cannot be sure.  Perhaps the bug is a
2467 stray memory reference which happens to fetch from the location where that
2468 name is stored in memory; perhaps, if the name were different, the contents
2469 of that location would fool the compiler into doing the right thing despite
2470 the bug.  Play it safe and give a specific, complete example.  That is the
2471 easiest thing for you to do, and the most helpful.
2472
2473 Keep in mind that the purpose of a bug report is to enable someone to
2474 fix the bug if it is not known.  It isn't very important what happens if
2475 the bug is already known.  Therefore, always write your bug reports on
2476 the assumption that the bug is not known.
2477
2478 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2479 bell?''  This cannot help us fix a bug, so it is basically useless.  We
2480 respond by asking for enough details to enable us to investigate.
2481 You might as well expedite matters by sending them to begin with.
2482
2483 Try to make your bug report self-contained.  If we have to ask you for
2484 more information, it is best if you include all the previous information
2485 in your response, as well as the information that was missing.
2486
2487 Please report each bug in a separate message.  This makes it easier for
2488 us to track which bugs have been fixed and to forward your bugs reports
2489 to the appropriate maintainer.
2490
2491 To enable someone to investigate the bug, you should include all these
2492 things:
2493
2494 @itemize @bullet
2495 @item
2496 The version of GCC.  You can get this by running it with the
2497 @samp{-v} option.
2498
2499 Without this, we won't know whether there is any point in looking for
2500 the bug in the current version of GCC.
2501
2502 @item
2503 A complete input file that will reproduce the bug.  If the bug is in the
2504 C preprocessor, send a source file and any header files that it
2505 requires.  If the bug is in the compiler proper (@file{cc1}), send the
2506 preprocessor output generated by adding @samp{-save-temps} to the
2507 compilation command (@pxref{Debugging Options}).  When you do this, use
2508 the same @samp{-I}, @samp{-D} or @samp{-U} options that you used in
2509 actual compilation. Then send the @var{input}.i or @var{input}.ii files
2510 generated.
2511
2512 A single statement is not enough of an example.  In order to compile it,
2513 it must be embedded in a complete file of compiler input; and the bug
2514 might depend on the details of how this is done.
2515
2516 Without a real example one can compile, all anyone can do about your bug
2517 report is wish you luck.  It would be futile to try to guess how to
2518 provoke the bug.  For example, bugs in register allocation and reloading
2519 frequently depend on every little detail of the function they happen in.
2520
2521 Even if the input file that fails comes from a GNU program, you should
2522 still send the complete test case.  Don't ask the GCC maintainers to
2523 do the extra work of obtaining the program in question---they are all
2524 overworked as it is.  Also, the problem may depend on what is in the
2525 header files on your system; it is unreliable for the GCC maintainers
2526 to try the problem with the header files available to them.  By sending
2527 CPP output, you can eliminate this source of uncertainty and save us
2528 a certain percentage of wild goose chases.
2529
2530 @item
2531 The command arguments you gave GCC to compile that example
2532 and observe the bug.  For example, did you use @samp{-O}?  To guarantee
2533 you won't omit something important, list all the options.
2534
2535 If we were to try to guess the arguments, we would probably guess wrong
2536 and then we would not encounter the bug.
2537
2538 @item
2539 The type of machine you are using, and the operating system name and
2540 version number.
2541
2542 @item
2543 The operands you gave to the @code{configure} command when you installed
2544 the compiler.
2545
2546 @item
2547 A complete list of any modifications you have made to the compiler
2548 source.  (We don't promise to investigate the bug unless it happens in
2549 an unmodified compiler.  But if you've made modifications and don't tell
2550 us, then you are sending us on a wild goose chase.)
2551
2552 Be precise about these changes.  A description in English is not
2553 enough---send a context diff for them.
2554
2555 Adding files of your own (such as a machine description for a machine we
2556 don't support) is a modification of the compiler source.
2557
2558 @item
2559 Details of any other deviations from the standard procedure for installing
2560 GCC.
2561
2562 @item
2563 A description of what behavior you observe that you believe is
2564 incorrect.  For example, ``The compiler gets a fatal signal,'' or,
2565 ``The assembler instruction at line 208 in the output is incorrect.''
2566
2567 Of course, if the bug is that the compiler gets a fatal signal, then one
2568 can't miss it.  But if the bug is incorrect output, the maintainer might
2569 not notice unless it is glaringly wrong.  None of us has time to study
2570 all the assembler code from a 50-line C program just on the chance that
2571 one instruction might be wrong.  We need @emph{you} to do this part!
2572
2573 Even if the problem you experience is a fatal signal, you should still
2574 say so explicitly.  Suppose something strange is going on, such as, your
2575 copy of the compiler is out of synch, or you have encountered a bug in
2576 the C library on your system.  (This has happened!)  Your copy might
2577 crash and the copy here would not.  If you @i{said} to expect a crash,
2578 then when the compiler here fails to crash, we would know that the bug
2579 was not happening.  If you don't say to expect a crash, then we would
2580 not know whether the bug was happening.  We would not be able to draw
2581 any conclusion from our observations.
2582
2583 If the problem is a diagnostic when compiling GCC with some other
2584 compiler, say whether it is a warning or an error.
2585
2586 Often the observed symptom is incorrect output when your program is run.
2587 Sad to say, this is not enough information unless the program is short
2588 and simple.  None of us has time to study a large program to figure out
2589 how it would work if compiled correctly, much less which line of it was
2590 compiled wrong.  So you will have to do that.  Tell us which source line
2591 it is, and what incorrect result happens when that line is executed.  A
2592 person who understands the program can find this as easily as finding a
2593 bug in the program itself.
2594
2595 @item
2596 If you send examples of assembler code output from GCC,
2597 please use @samp{-g} when you make them.  The debugging information
2598 includes source line numbers which are essential for correlating the
2599 output with the input.
2600
2601 @item
2602 If you wish to mention something in the GCC source, refer to it by
2603 context, not by line number.
2604
2605 The line numbers in the development sources don't match those in your
2606 sources.  Your line numbers would convey no useful information to the
2607 maintainers.
2608
2609 @item
2610 Additional information from a debugger might enable someone to find a
2611 problem on a machine which he does not have available.  However, you
2612 need to think when you collect this information if you want it to have
2613 any chance of being useful.
2614
2615 @cindex backtrace for bug reports
2616 For example, many people send just a backtrace, but that is never
2617 useful by itself.  A simple backtrace with arguments conveys little
2618 about GCC because the compiler is largely data-driven; the same
2619 functions are called over and over for different RTL insns, doing
2620 different things depending on the details of the insn.
2621
2622 Most of the arguments listed in the backtrace are useless because they
2623 are pointers to RTL list structure.  The numeric values of the
2624 pointers, which the debugger prints in the backtrace, have no
2625 significance whatever; all that matters is the contents of the objects
2626 they point to (and most of the contents are other such pointers).
2627
2628 In addition, most compiler passes consist of one or more loops that
2629 scan the RTL insn sequence.  The most vital piece of information about
2630 such a loop---which insn it has reached---is usually in a local variable,
2631 not in an argument.
2632
2633 @findex debug_rtx
2634 What you need to provide in addition to a backtrace are the values of
2635 the local variables for several stack frames up.  When a local
2636 variable or an argument is an RTX, first print its value and then use
2637 the GDB command @code{pr} to print the RTL expression that it points
2638 to.  (If GDB doesn't run on your machine, use your debugger to call
2639 the function @code{debug_rtx} with the RTX as an argument.)  In
2640 general, whenever a variable is a pointer, its value is no use
2641 without the data it points to.
2642 @end itemize
2643
2644 Here are some things that are not necessary:
2645
2646 @itemize @bullet
2647 @item
2648 A description of the envelope of the bug.
2649
2650 Often people who encounter a bug spend a lot of time investigating
2651 which changes to the input file will make the bug go away and which
2652 changes will not affect it.
2653
2654 This is often time consuming and not very useful, because the way we
2655 will find the bug is by running a single example under the debugger with
2656 breakpoints, not by pure deduction from a series of examples.  You might
2657 as well save your time for something else.
2658
2659 Of course, if you can find a simpler example to report @emph{instead} of
2660 the original one, that is a convenience.  Errors in the output will be
2661 easier to spot, running under the debugger will take less time, etc.
2662 Most GCC bugs involve just one function, so the most straightforward
2663 way to simplify an example is to delete all the function definitions
2664 except the one where the bug occurs.  Those earlier in the file may be
2665 replaced by external declarations if the crucial function depends on
2666 them.  (Exception: inline functions may affect compilation of functions
2667 defined later in the file.)
2668
2669 However, simplification is not vital; if you don't want to do this,
2670 report the bug anyway and send the entire test case you used.
2671
2672 @item
2673 In particular, some people insert conditionals @samp{#ifdef BUG} around
2674 a statement which, if removed, makes the bug not happen.  These are just
2675 clutter; we won't pay any attention to them anyway.  Besides, you should
2676 send us cpp output, and that can't have conditionals.
2677
2678 @item
2679 A patch for the bug.
2680
2681 A patch for the bug is useful if it is a good one.  But don't omit the
2682 necessary information, such as the test case, on the assumption that a
2683 patch is all we need.  We might see problems with your patch and decide
2684 to fix the problem another way, or we might not understand it at all.
2685
2686 Sometimes with a program as complicated as GCC it is very hard to
2687 construct an example that will make the program follow a certain path
2688 through the code.  If you don't send the example, we won't be able to
2689 construct one, so we won't be able to verify that the bug is fixed.
2690
2691 And if we can't understand what bug you are trying to fix, or why your
2692 patch should be an improvement, we won't install it.  A test case will
2693 help us to understand.
2694
2695 @xref{Sending Patches}, for guidelines on how to make it easy for us to
2696 understand and install your patches.
2697
2698 @item
2699 A guess about what the bug is or what it depends on.
2700
2701 Such guesses are usually wrong.  Even I can't guess right about such
2702 things without first using the debugger to find the facts.
2703
2704 @item
2705 A core dump file.
2706
2707 We have no way of examining a core dump for your type of machine
2708 unless we have an identical system---and if we do have one,
2709 we should be able to reproduce the crash ourselves.
2710 @end itemize
2711
2712 @node gccbug,Sending Patches, Bug Reporting, Bugs
2713 @section The gccbug script
2714 @cindex gccbug script
2715
2716 To simplify creation of bug reports, and to allow better tracking of
2717 reports, we use the GNATS bug tracking system. Part of that system is
2718 the @code{gccbug} script. This is a Unix shell script, so you need a
2719 shell to run it. It is normally installed in the same directory where
2720 @code{gcc} is installed.
2721
2722 The gccbug script is derived from send-pr, @pxref{using
2723 send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
2724 invoked, it starts a text editor so you can fill out the various fields
2725 of the report. When the you quit the editor, the report is automatically
2726 send to the bug reporting address.
2727
2728 A number of fields in this bug report form are specific to GCC, and are
2729 explained here.
2730
2731 @table @code
2732
2733 @cindex @code{Category} field
2734 @cindex @code{>Category:}
2735 @item >Category:
2736 The category of a GCC problem can be one of the following:
2737
2738 @table @code
2739 @item c
2740 A problem with the C compiler proper.
2741 driver.
2742
2743 @item c++
2744 A problem with the C++ compiler.
2745 driver.
2746
2747 @item fortran
2748 A problem with the Fortran 77.
2749
2750 @item java
2751 A problem with the Java compiler.
2752
2753 @item objc
2754 A problem with the Objective C compiler.
2755
2756 @item libstdc++
2757 A problem with the C++ standard library.
2758
2759 @item libf2c
2760 A problem with the Fortran 77 library.
2761
2762 @item libobjc
2763 A problem with the Objective C library.
2764
2765 @item optimization
2766 The problem occurs only when generating optimized code.
2767
2768 @item debug
2769 The problem occurs only when generating code for debugging.
2770
2771 @item target
2772 The problem is specific to the target architecture.
2773
2774 @item middle-end
2775 The problem is independent from target architecture and programming
2776 language.
2777
2778 @item other
2779 It is a problem in some other part of the GCC software.
2780
2781 @item web
2782 There is a problem with the GCC home page.
2783
2784 @end table
2785
2786 @cindex @code{Class} field
2787 @cindex @code{>Class:}
2788 @item >Class:
2789 The class of a problem can be one of the following:
2790
2791 @table @code
2792 @cindex @emph{doc-bug} class
2793 @item doc-bug
2794 A problem with the documentation.
2795
2796 @cindex @emph{accepts-illegal} class
2797 @item accepts-illegal
2798 GCC fails to reject erroneous code.
2799
2800 @cindex @emph{rejects-legal} class
2801 @item rejects-legal    
2802 GCC gives an error message for correct code.
2803
2804 @cindex @emph{wrong-code} class
2805 @item wrong-code       
2806 The machine code generated by gcc is incorrect.
2807
2808 @cindex @emph{ice-on-legal-code} class
2809 @item ice-on-legal-code   
2810 GCC gives an Internal Compiler Error (ICE) for correct code.
2811
2812 @cindex @emph{ice-on-illegal-code} class
2813 @item ice-on-illegal-code 
2814 GCC gives an ICE instead of reporting an error
2815
2816 @cindex @emph{pessimizes-code} class
2817 @item pessimizes-code     
2818 GCC misses an important optimization opportunity.
2819
2820 @cindex @emph{sw-bug} class
2821 @item sw-bug
2822 A general product problem.  (@samp{sw} stands for ``software''.)
2823
2824 @cindex @emph{change-request} class
2825 @item change-request
2826 A request for a change in behavior, etc.
2827
2828 @cindex @emph{support} class
2829 @item support
2830 A support problem or question.
2831
2832 @cindex @emph{duplicate} class
2833 @item duplicate (@var{pr-number})
2834 Duplicate PR.  @var{pr-number} should be the number of the original PR.
2835
2836 @noindent
2837 The default is @samp{sw-bug}.
2838 @sp 1
2839 @end table
2840
2841 @end table
2842
2843 @node Sending Patches,, gccbug, Bugs
2844 @section Sending Patches for GCC
2845
2846 If you would like to write bug fixes or improvements for the GNU C
2847 compiler, that is very helpful.  Send suggested fixes to the patches
2848 mailing list, @email{gcc-patches@@gcc.gnu.org}.
2849
2850 Please follow these guidelines so we can study your patches efficiently.
2851 If you don't follow these guidelines, your information might still be
2852 useful, but using it will take extra work.  Maintaining GNU C is a lot
2853 of work in the best of circumstances, and we can't keep up unless you do
2854 your best to help.
2855
2856 @itemize @bullet
2857 @item
2858 Send an explanation with your changes of what problem they fix or what
2859 improvement they bring about.  For a bug fix, just include a copy of the
2860 bug report, and explain why the change fixes the bug.
2861
2862 (Referring to a bug report is not as good as including it, because then
2863 we will have to look it up, and we have probably already deleted it if
2864 we've already fixed the bug.)
2865
2866 @item
2867 Always include a proper bug report for the problem you think you have
2868 fixed.  We need to convince ourselves that the change is right before
2869 installing it.  Even if it is right, we might have trouble judging it if
2870 we don't have a way to reproduce the problem.
2871
2872 @item
2873 Include all the comments that are appropriate to help people reading the
2874 source in the future understand why this change was needed.
2875
2876 @item
2877 Don't mix together changes made for different reasons.
2878 Send them @emph{individually}.
2879
2880 If you make two changes for separate reasons, then we might not want to
2881 install them both.  We might want to install just one.  If you send them
2882 all jumbled together in a single set of diffs, we have to do extra work
2883 to disentangle them---to figure out which parts of the change serve
2884 which purpose.  If we don't have time for this, we might have to ignore
2885 your changes entirely.
2886
2887 If you send each change as soon as you have written it, with its own
2888 explanation, then the two changes never get tangled up, and we can
2889 consider each one properly without any extra work to disentangle them.
2890
2891 Ideally, each change you send should be impossible to subdivide into
2892 parts that we might want to consider separately, because each of its
2893 parts gets its motivation from the other parts.
2894
2895 @item
2896 Send each change as soon as that change is finished.  Sometimes people
2897 think they are helping us by accumulating many changes to send them all
2898 together.  As explained above, this is absolutely the worst thing you
2899 could do.
2900
2901 Since you should send each change separately, you might as well send it
2902 right away.  That gives us the option of installing it immediately if it
2903 is important.
2904
2905 @item
2906 Use @samp{diff -c} to make your diffs.  Diffs without context are hard
2907 for us to install reliably.  More than that, they make it hard for us to
2908 study the diffs to decide whether we want to install them.  Unidiff
2909 format is better than contextless diffs, but not as easy to read as
2910 @samp{-c} format.
2911
2912 If you have GNU diff, use @samp{diff -cp}, which shows the name of the
2913 function that each change occurs in.
2914
2915 @item
2916 Write the change log entries for your changes.  We get lots of changes,
2917 and we don't have time to do all the change log writing ourselves.
2918
2919 Read the @file{ChangeLog} file to see what sorts of information to put
2920 in, and to learn the style that we use.  The purpose of the change log
2921 is to show people where to find what was changed.  So you need to be
2922 specific about what functions you changed; in large functions, it's
2923 often helpful to indicate where within the function the change was.
2924
2925 On the other hand, once you have shown people where to find the change,
2926 you need not explain its purpose.  Thus, if you add a new function, all
2927 you need to say about it is that it is new.  If you feel that the
2928 purpose needs explaining, it probably does---but the explanation will be
2929 much more useful if you put it in comments in the code.
2930
2931 If you would like your name to appear in the header line for who made
2932 the change, send us the header line.
2933
2934 @item
2935 When you write the fix, keep in mind that we can't install a change that
2936 would break other systems.
2937
2938 People often suggest fixing a problem by changing machine-independent
2939 files such as @file{toplev.c} to do something special that a particular
2940 system needs.  Sometimes it is totally obvious that such changes would
2941 break GCC for almost all users.  We can't possibly make a change like
2942 that.  At best it might tell us how to write another patch that would
2943 solve the problem acceptably.
2944
2945 Sometimes people send fixes that @emph{might} be an improvement in
2946 general---but it is hard to be sure of this.  It's hard to install
2947 such changes because we have to study them very carefully.  Of course,
2948 a good explanation of the reasoning by which you concluded the change
2949 was correct can help convince us.
2950
2951 The safest changes are changes to the configuration files for a
2952 particular machine.  These are safe because they can't create new bugs
2953 on other machines.
2954
2955 Please help us keep up with the workload by designing the patch in a
2956 form that is good to install.
2957 @end itemize
2958
2959 @node Service
2960 @chapter How To Get Help with GCC
2961
2962 If you need help installing, using or changing GCC, there are two
2963 ways to find it:
2964
2965 @itemize @bullet
2966 @item
2967 Send a message to a suitable network mailing list.  First try
2968 @email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
2969 that brings no response, try @email{gcc@@gcc.gnu.org}.  For help
2970 changing GCC, ask @email{gcc@@gcc.gnu.org}.  If you think you have found
2971 a bug in GCC, please report it following the instructions at
2972 @uref{http://gcc.gnu.org/bugs.html}.
2973
2974 @item
2975 Look in the service directory for someone who might help you for a fee.
2976 The service directory is found at
2977 @uref{http://www.gnu.org/prep/service.html}.
2978 @end itemize
2979
2980 @c For further information, see
2981 @c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}.
2982 @c FIXME: this URL may be too volatile, this FAQ entry needs to move to
2983 @c the regular web pages before we can uncomment the reference.
2984
2985 @node Contributing
2986 @chapter Contributing to GCC Development
2987
2988 If you would like to help pretest GCC releases to assure they work well,
2989 our current development sources are available by CVS (see
2990 @uref{http://gcc.gnu.org/cvs.html}).  Source and binary snapshots are
2991 also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
2992 Remember that snapshots of the current development sources may not be of
2993 production quality; if you find problems (whether compiler crashes,
2994 miscompiled code, poor optimization or any other problem), please report
2995 them following our bug reporting instructions at
2996 @uref{http://gcc.gnu.org/bugs.html}.
2997
2998 If you would like to work on improvements to GCC, please read
2999 @uref{http://gcc.gnu.org/contribute.html} and
3000 @uref{http://gcc.gnu.org/contributewhy.html} for information on how to
3001 make useful contributions and avoid duplication of effort.  Suggested
3002 projects are listed at @uref{http://gcc.gnu.org/projects/}.
3003
3004 @node VMS
3005 @chapter Using GCC on VMS
3006
3007 @c prevent bad page break with this line
3008 Here is how to use GCC on VMS.
3009
3010 @menu
3011 * Include Files and VMS::  Where the preprocessor looks for the include files.
3012 * Global Declarations::    How to do globaldef, globalref and globalvalue with
3013                            GCC.
3014 * VMS Misc::               Misc information.
3015 @end menu
3016
3017 @node Include Files and VMS
3018 @section Include Files and VMS
3019
3020 @cindex include files and VMS
3021 @cindex VMS and include files
3022 @cindex header files and VMS
3023 Due to the differences between the filesystems of Unix and VMS, GCC
3024 attempts to translate file names in @samp{#include} into names that VMS
3025 will understand.  The basic strategy is to prepend a prefix to the
3026 specification of the include file, convert the whole filename to a VMS
3027 filename, and then try to open the file.  GCC tries various prefixes
3028 one by one until one of them succeeds:
3029
3030 @enumerate
3031 @item
3032 The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
3033 where GNU C header files are traditionally stored.  If you wish to store
3034 header files in non-standard locations, then you can assign the logical
3035 @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
3036 list is suitable for use with a rooted logical.
3037
3038 @item
3039 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}.  This is where
3040 VAX-C header files are traditionally stored.
3041
3042 @item
3043 If the include file specification by itself is a valid VMS filename, the
3044 preprocessor then uses this name with no prefix in an attempt to open
3045 the include file.
3046
3047 @item
3048 If the file specification is not a valid VMS filename (i.e. does not
3049 contain a device or a directory specifier, and contains a @samp{/}
3050 character), the preprocessor tries to convert it from Unix syntax to
3051 VMS syntax.
3052
3053 Conversion works like this: the first directory name becomes a device,
3054 and the rest of the directories are converted into VMS-format directory
3055 names.  For example, the name @file{X11/foobar.h} is
3056 translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
3057 whichever one can be opened.  This strategy allows you to assign a
3058 logical name to point to the actual location of the header files.
3059
3060 @item
3061 If none of these strategies succeeds, the @samp{#include} fails.
3062 @end enumerate
3063
3064 Include directives of the form:
3065
3066 @example
3067 #include foobar
3068 @end example
3069
3070 @noindent
3071 are a common source of incompatibility between VAX-C and GCC.  VAX-C
3072 treats this much like a standard @code{#include <foobar.h>} directive.
3073 That is incompatible with the ISO C behavior implemented by GCC: to
3074 expand the name @code{foobar} as a macro.  Macro expansion should
3075 eventually yield one of the two standard formats for @code{#include}:
3076
3077 @example
3078 #include "@var{file}"
3079 #include <@var{file}>
3080 @end example
3081
3082 If you have this problem, the best solution is to modify the source to
3083 convert the @code{#include} directives to one of the two standard forms.
3084 That will work with either compiler.  If you want a quick and dirty fix,
3085 define the file names as macros with the proper expansion, like this:
3086
3087 @example
3088 #define stdio <stdio.h>
3089 @end example
3090
3091 @noindent
3092 This will work, as long as the name doesn't conflict with anything else
3093 in the program.
3094
3095 Another source of incompatibility is that VAX-C assumes that:
3096
3097 @example
3098 #include "foobar"
3099 @end example
3100
3101 @noindent
3102 is actually asking for the file @file{foobar.h}.  GCC does not
3103 make this assumption, and instead takes what you ask for literally;
3104 it tries to read the file @file{foobar}.  The best way to avoid this
3105 problem is to always specify the desired file extension in your include
3106 directives.
3107
3108 GCC for VMS is distributed with a set of include files that is
3109 sufficient to compile most general purpose programs.  Even though the
3110 GCC distribution does not contain header files to define constants
3111 and structures for some VMS system-specific functions, there is no
3112 reason why you cannot use GCC with any of these functions.  You first
3113 may have to generate or create header files, either by using the public
3114 domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
3115 extracting the relevant modules from one of the system macro libraries,
3116 and using an editor to construct a C header file.
3117
3118 A @code{#include} file name cannot contain a DECNET node name.  The
3119 preprocessor reports an I/O error if you attempt to use a node name,
3120 whether explicitly, or implicitly via a logical name.
3121
3122 @node Global Declarations
3123 @section Global Declarations and VMS
3124
3125 @findex GLOBALREF
3126 @findex GLOBALDEF
3127 @findex GLOBALVALUEDEF
3128 @findex GLOBALVALUEREF
3129 GCC does not provide the @code{globalref}, @code{globaldef} and
3130 @code{globalvalue} keywords of VAX-C.  You can get the same effect with
3131 an obscure feature of GAS, the GNU assembler.  (This requires GAS
3132 version 1.39 or later.)  The following macros allow you to use this
3133 feature in a fairly natural way:
3134
3135 @smallexample
3136 #ifdef __GNUC__
3137 #define GLOBALREF(TYPE,NAME)                      \
3138   TYPE NAME                                       \
3139   asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
3140 #define GLOBALDEF(TYPE,NAME,VALUE)                \
3141   TYPE NAME                                       \
3142   asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
3143     = VALUE
3144 #define GLOBALVALUEREF(TYPE,NAME)                 \
3145   const TYPE NAME[1]                              \
3146   asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
3147 #define GLOBALVALUEDEF(TYPE,NAME,VALUE)           \
3148   const TYPE NAME[1]                              \
3149   asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)  \
3150     = @{VALUE@}
3151 #else
3152 #define GLOBALREF(TYPE,NAME) \
3153   globalref TYPE NAME
3154 #define GLOBALDEF(TYPE,NAME,VALUE) \
3155   globaldef TYPE NAME = VALUE
3156 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
3157   globalvalue TYPE NAME = VALUE
3158 #define GLOBALVALUEREF(TYPE,NAME) \
3159   globalvalue TYPE NAME
3160 #endif
3161 @end smallexample
3162
3163 @noindent
3164 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
3165 name is removed by the assembler, after it has modified the attributes
3166 of the symbol).  These macros are provided in the VMS binaries
3167 distribution in a header file @file{GNU_HACKS.H}.  An example of the
3168 usage is:
3169
3170 @example
3171 GLOBALREF (int, ijk);
3172 GLOBALDEF (int, jkl, 0);
3173 @end example
3174
3175 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
3176 straightforwardly for arrays, since there is no way to insert the array
3177 dimension into the declaration at the right place.  However, you can
3178 declare an array with these macros if you first define a typedef for the
3179 array type, like this:
3180
3181 @example
3182 typedef int intvector[10];
3183 GLOBALREF (intvector, foo);
3184 @end example
3185
3186 Array and structure initializers will also break the macros; you can
3187 define the initializer to be a macro of its own, or you can expand the
3188 @code{GLOBALDEF} macro by hand.  You may find a case where you wish to
3189 use the @code{GLOBALDEF} macro with a large array, but you are not
3190 interested in explicitly initializing each element of the array.  In
3191 such cases you can use an initializer like: @code{@{0,@}}, which will
3192 initialize the entire array to @code{0}.
3193
3194 A shortcoming of this implementation is that a variable declared with
3195 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array.  For
3196 example, the declaration:
3197
3198 @example
3199 GLOBALVALUEREF(int, ijk);
3200 @end example
3201
3202 @noindent
3203 declares the variable @code{ijk} as an array of type @code{int [1]}.
3204 This is done because a globalvalue is actually a constant; its ``value''
3205 is what the linker would normally consider an address.  That is not how
3206 an integer value works in C, but it is how an array works.  So treating
3207 the symbol as an array name gives consistent results---with the
3208 exception that the value seems to have the wrong type.  @strong{Don't
3209 try to access an element of the array.}  It doesn't have any elements.
3210 The array ``address'' may not be the address of actual storage.
3211
3212 The fact that the symbol is an array may lead to warnings where the
3213 variable is used.  Insert type casts to avoid the warnings.  Here is an
3214 example; it takes advantage of the ISO C feature allowing macros that
3215 expand to use the same name as the macro itself.
3216
3217 @example
3218 GLOBALVALUEREF (int, ss$_normal);
3219 GLOBALVALUEDEF (int, xyzzy,123);
3220 #ifdef __GNUC__
3221 #define ss$_normal ((int) ss$_normal)
3222 #define xyzzy ((int) xyzzy)
3223 #endif
3224 @end example
3225
3226 Don't use @code{globaldef} or @code{globalref} with a variable whose
3227 type is an enumeration type; this is not implemented.  Instead, make the
3228 variable an integer, and use a @code{globalvaluedef} for each of the
3229 enumeration values.  An example of this would be:
3230
3231 @example
3232 #ifdef __GNUC__
3233 GLOBALDEF (int, color, 0);
3234 GLOBALVALUEDEF (int, RED, 0);
3235 GLOBALVALUEDEF (int, BLUE, 1);
3236 GLOBALVALUEDEF (int, GREEN, 3);
3237 #else
3238 enum globaldef color @{RED, BLUE, GREEN = 3@};
3239 #endif
3240 @end example
3241
3242 @node VMS Misc
3243 @section Other VMS Issues
3244
3245 @cindex exit status and VMS
3246 @cindex return value of @code{main}
3247 @cindex @code{main} and the exit status
3248 GCC automatically arranges for @code{main} to return 1 by default if
3249 you fail to specify an explicit return value.  This will be interpreted
3250 by VMS as a status code indicating a normal successful completion.
3251 Version 1 of GCC did not provide this default.
3252
3253 GCC on VMS works only with the GNU assembler, GAS.  You need version
3254 1.37 or later of GAS in order to produce value debugging information for
3255 the VMS debugger.  Use the ordinary VMS linker with the object files
3256 produced by GAS.
3257
3258 @cindex shared VMS run time system
3259 @cindex @file{VAXCRTL}
3260 Under previous versions of GCC, the generated code would occasionally
3261 give strange results when linked to the sharable @file{VAXCRTL} library.
3262 Now this should work.
3263
3264 A caveat for use of @code{const} global variables: the @code{const}
3265 modifier must be specified in every external declaration of the variable
3266 in all of the source files that use that variable.  Otherwise the linker
3267 will issue warnings about conflicting attributes for the variable.  Your
3268 program will still work despite the warnings, but the variable will be
3269 placed in writable storage.
3270
3271 @cindex name augmentation
3272 @cindex case sensitivity and VMS
3273 @cindex VMS and case sensitivity
3274 Although the VMS linker does distinguish between upper and lower case
3275 letters in global symbols, most VMS compilers convert all such symbols
3276 into upper case and most run-time library routines also have upper case
3277 names.  To be able to reliably call such routines, GCC (by means of
3278 the assembler GAS) converts global symbols into upper case like other
3279 VMS compilers.  However, since the usual practice in C is to distinguish
3280 case, GCC (via GAS) tries to preserve usual C behavior by augmenting
3281 each name that is not all lower case.  This means truncating the name
3282 to at most 23 characters and then adding more characters at the end
3283 which encode the case pattern of those 23.   Names which contain at
3284 least one dollar sign are an exception; they are converted directly into
3285 upper case without augmentation.
3286
3287 Name augmentation yields bad results for programs that use precompiled
3288 libraries (such as Xlib) which were generated by another compiler.  You
3289 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
3290 it makes external C functions and variables case-independent as is usual
3291 on VMS.  Alternatively, you could write all references to the functions
3292 and variables in such libraries using lower case; this will work on VMS,
3293 but is not portable to other systems.  The compiler option @samp{/NAMES}
3294 also provides control over global name handling.
3295
3296 Function and variable names are handled somewhat differently with GNU
3297 C++.  The GNU C++ compiler performs @dfn{name mangling} on function
3298 names, which means that it adds information to the function name to
3299 describe the data types of the arguments that the function takes.  One
3300 result of this is that the name of a function can become very long.
3301 Since the VMS linker only recognizes the first 31 characters in a name,
3302 special action is taken to ensure that each function and variable has a
3303 unique name that can be represented in 31 characters.
3304
3305 If the name (plus a name augmentation, if required) is less than 32
3306 characters in length, then no special action is performed.  If the name
3307 is longer than 31 characters, the assembler (GAS) will generate a
3308 hash string based upon the function name, truncate the function name to
3309 23 characters, and append the hash string to the truncated name.  If the
3310 @samp{/VERBOSE} compiler option is used, the assembler will print both
3311 the full and truncated names of each symbol that is truncated.
3312
3313 The @samp{/NOCASE_HACK} compiler option should not be used when you are
3314 compiling programs that use libg++.  libg++ has several instances of
3315 objects (i.e.  @code{Filebuf} and @code{filebuf}) which become
3316 indistinguishable in a case-insensitive environment.  This leads to
3317 cases where you need to inhibit augmentation selectively (if you were
3318 using libg++ and Xlib in the same program, for example).  There is no
3319 special feature for doing this, but you can get the result by defining a
3320 macro for each mixed case symbol for which you wish to inhibit
3321 augmentation.  The macro should expand into the lower case equivalent of
3322 itself.  For example:
3323
3324 @example
3325 #define StuDlyCapS studlycaps
3326 @end example
3327
3328 These macro definitions can be placed in a header file to minimize the
3329 number of changes to your source code.
3330 @end ifset
3331
3332 @ifset INTERNALS
3333 @node Portability
3334 @chapter GCC and Portability
3335 @cindex portability
3336 @cindex GCC and portability
3337
3338 The main goal of GCC was to make a good, fast compiler for machines in
3339 the class that the GNU system aims to run on: 32-bit machines that address
3340 8-bit bytes and have several general registers.  Elegance, theoretical
3341 power and simplicity are only secondary.
3342
3343 GCC gets most of the information about the target machine from a machine
3344 description which gives an algebraic formula for each of the machine's
3345 instructions.  This is a very clean way to describe the target.  But when
3346 the compiler needs information that is difficult to express in this
3347 fashion, I have not hesitated to define an ad-hoc parameter to the machine
3348 description.  The purpose of portability is to reduce the total work needed
3349 on the compiler; it was not of interest for its own sake.
3350
3351 @cindex endianness
3352 @cindex autoincrement addressing, availability
3353 @findex abort
3354 GCC does not contain machine dependent code, but it does contain code
3355 that depends on machine parameters such as endianness (whether the most
3356 significant byte has the highest or lowest address of the bytes in a word)
3357 and the availability of autoincrement addressing.  In the RTL-generation
3358 pass, it is often necessary to have multiple strategies for generating code
3359 for a particular kind of syntax tree, strategies that are usable for different
3360 combinations of parameters.  Often I have not tried to address all possible
3361 cases, but only the common ones or only the ones that I have encountered.
3362 As a result, a new target may require additional strategies.  You will know
3363 if this happens because the compiler will call @code{abort}.  Fortunately,
3364 the new strategies can be added in a machine-independent fashion, and will
3365 affect only the target machines that need them.
3366 @end ifset
3367
3368 @ifset INTERNALS
3369 @node Interface
3370 @chapter Interfacing to GCC Output
3371 @cindex interfacing to GCC output
3372 @cindex run-time conventions
3373 @cindex function call conventions
3374 @cindex conventions, run-time
3375
3376 GCC is normally configured to use the same function calling convention
3377 normally in use on the target system.  This is done with the
3378 machine-description macros described (@pxref{Target Macros}).
3379
3380 @cindex unions, returning
3381 @cindex structures, returning
3382 @cindex returning structures and unions
3383 However, returning of structure and union values is done differently on
3384 some target machines.  As a result, functions compiled with PCC
3385 returning such types cannot be called from code compiled with GCC,
3386 and vice versa.  This does not cause trouble often because few Unix
3387 library routines return structures or unions.
3388
3389 GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
3390 long in the same registers used for @code{int} or @code{double} return
3391 values.  (GCC typically allocates variables of such types in
3392 registers also.)  Structures and unions of other sizes are returned by
3393 storing them into an address passed by the caller (usually in a
3394 register).  The machine-description macros @code{STRUCT_VALUE} and
3395 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
3396
3397 By contrast, PCC on most target machines returns structures and unions
3398 of any size by copying the data into an area of static storage, and then
3399 returning the address of that storage as if it were a pointer value.
3400 The caller must copy the data from that memory area to the place where
3401 the value is wanted.  This is slower than the method used by GCC, and
3402 fails to be reentrant.
3403
3404 On some target machines, such as RISC machines and the 80386, the
3405 standard system convention is to pass to the subroutine the address of
3406 where to return the value.  On these machines, GCC has been
3407 configured to be compatible with the standard compiler, when this method
3408 is used.  It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3409
3410 @cindex argument passing
3411 @cindex passing arguments
3412 GCC uses the system's standard convention for passing arguments.  On
3413 some machines, the first few arguments are passed in registers; in
3414 others, all are passed on the stack.  It would be possible to use
3415 registers for argument passing on any machine, and this would probably
3416 result in a significant speedup.  But the result would be complete
3417 incompatibility with code that follows the standard convention.  So this
3418 change is practical only if you are switching to GCC as the sole C
3419 compiler for the system.  We may implement register argument passing on
3420 certain machines once we have a complete GNU system so that we can
3421 compile the libraries with GCC.
3422
3423 On some machines (particularly the Sparc), certain types of arguments
3424 are passed ``by invisible reference''.  This means that the value is
3425 stored in memory, and the address of the memory location is passed to
3426 the subroutine.
3427
3428 @cindex @code{longjmp} and automatic variables
3429 If you use @code{longjmp}, beware of automatic variables.  ISO C says that
3430 automatic variables that are not declared @code{volatile} have undefined
3431 values after a @code{longjmp}.  And this is all GCC promises to do,
3432 because it is very difficult to restore register variables correctly, and
3433 one of GCC's features is that it can put variables in registers without
3434 your asking it to.
3435
3436 If you want a variable to be unaltered by @code{longjmp}, and you don't
3437 want to write @code{volatile} because old C compilers don't accept it,
3438 just take the address of the variable.  If a variable's address is ever
3439 taken, even if just to compute it and ignore it, then the variable cannot
3440 go in a register:
3441
3442 @example
3443 @{
3444   int careful;
3445   &careful;
3446   @dots{}
3447 @}
3448 @end example
3449
3450 @cindex arithmetic libraries
3451 @cindex math libraries
3452 Code compiled with GCC may call certain library routines.  Most of
3453 them handle arithmetic for which there are no instructions.  This
3454 includes multiply and divide on some machines, and floating point
3455 operations on any machine for which floating point support is disabled
3456 with @samp{-msoft-float}.  Some standard parts of the C library, such as
3457 @code{bcopy} or @code{memcpy}, are also called automatically.  The usual
3458 function call interface is used for calling the library routines.
3459
3460 These library routines should be defined in the library @file{libgcc.a},
3461 which GCC automatically searches whenever it links a program.  On
3462 machines that have multiply and divide instructions, if hardware
3463 floating point is in use, normally @file{libgcc.a} is not needed, but it
3464 is searched just in case.
3465
3466 Each arithmetic function is defined in @file{libgcc1.c} to use the
3467 corresponding C arithmetic operator.  As long as the file is compiled
3468 with another C compiler, which supports all the C arithmetic operators,
3469 this file will work portably.  However, @file{libgcc1.c} does not work if
3470 compiled with GCC, because each arithmetic function would compile
3471 into a call to itself!
3472 @end ifset
3473
3474 @ifset INTERNALS
3475 @node Passes
3476 @chapter Passes and Files of the Compiler
3477 @cindex passes and files of the compiler
3478 @cindex files and passes of the compiler
3479 @cindex compiler passes and files
3480
3481 @cindex top level of compiler
3482 The overall control structure of the compiler is in @file{toplev.c}.  This
3483 file is responsible for initialization, decoding arguments, opening and
3484 closing files, and sequencing the passes.
3485
3486 @cindex parsing pass
3487 The parsing pass is invoked only once, to parse the entire input.  The RTL
3488 intermediate code for a function is generated as the function is parsed, a
3489 statement at a time.  Each statement is read in as a syntax tree and then
3490 converted to RTL; then the storage for the tree for the statement is
3491 reclaimed.  Storage for types (and the expressions for their sizes),
3492 declarations, and a representation of the binding contours and how they nest,
3493 remain until the function is finished being compiled; these are all needed
3494 to output the debugging information.
3495
3496 @findex rest_of_compilation
3497 @findex rest_of_decl_compilation
3498 Each time the parsing pass reads a complete function definition or
3499 top-level declaration, it calls either the function
3500 @code{rest_of_compilation}, or the function
3501 @code{rest_of_decl_compilation} in @file{toplev.c}, which are
3502 responsible for all further processing necessary, ending with output of
3503 the assembler language.  All other compiler passes run, in sequence,
3504 within @code{rest_of_compilation}.  When that function returns from
3505 compiling a function definition, the storage used for that function
3506 definition's compilation is entirely freed, unless it is an inline
3507 function
3508 @ifset USING
3509 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3510 @end ifset
3511 @ifclear USING
3512 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3513 @end ifclear
3514
3515 Here is a list of all the passes of the compiler and their source files.
3516 Also included is a description of where debugging dumps can be requested
3517 with @samp{-d} options.
3518
3519 @itemize @bullet
3520 @item
3521 Parsing.  This pass reads the entire text of a function definition,
3522 constructing partial syntax trees.  This and RTL generation are no longer
3523 truly separate passes (formerly they were), but it is easier to think
3524 of them as separate.
3525
3526 The tree representation does not entirely follow C syntax, because it is
3527 intended to support other languages as well.
3528
3529 Language-specific data type analysis is also done in this pass, and every
3530 tree node that represents an expression has a data type attached.
3531 Variables are represented as declaration nodes.
3532
3533 @cindex constant folding
3534 @cindex arithmetic simplifications
3535 @cindex simplifications, arithmetic
3536 Constant folding and some arithmetic simplifications are also done
3537 during this pass.
3538
3539 The language-independent source files for parsing are
3540 @file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}.
3541 There are also header files @file{tree.h} and @file{tree.def}
3542 which define the format of the tree representation.@refill
3543
3544 @c Avoiding overfull is tricky here.
3545 The source files to parse C are
3546 @file{c-parse.in},
3547 @file{c-decl.c},
3548 @file{c-typeck.c},
3549 @file{c-aux-info.c},
3550 @file{c-convert.c},
3551 and @file{c-lang.c}
3552 along with header files
3553 @file{c-lex.h}, and
3554 @file{c-tree.h}.
3555
3556 The source files for parsing C++ are in @file{cp/}.
3557 They are @file{parse.y},
3558 @file{class.c},@*
3559 @file{cvt.c}, @file{decl.c}, @file{decl2.c}, 
3560 @file{except.c},@*
3561 @file{expr.c}, @file{init.c}, @file{lex.c},
3562 @file{method.c}, @file{ptree.c},@*
3563 @file{search.c}, @file{tree.c}, 
3564 @file{typeck2.c}, and
3565 @file{typeck.c}, along with header files @file{cp-tree.def},
3566 @file{cp-tree.h}, and @file{decl.h}.
3567
3568 The special source files for parsing Objective C are in @file{objc/}.
3569 They are @file{objc-parse.y}, @file{objc-act.c}, @file{objc-tree.def}, and
3570 @file{objc-act.h}.  Certain C-specific files are used for this as
3571 well.
3572
3573 The file @file{c-common.c} is also used for all of the above languages.
3574
3575 @cindex RTL generation
3576 @item
3577 RTL generation.  This is the conversion of syntax tree into RTL code.
3578 It is actually done statement-by-statement during parsing, but for
3579 most purposes it can be thought of as a separate pass.
3580
3581 @cindex target-parameter-dependent code
3582 This is where the bulk of target-parameter-dependent code is found,
3583 since often it is necessary for strategies to apply only when certain
3584 standard kinds of instructions are available.  The purpose of named
3585 instruction patterns is to provide this information to the RTL
3586 generation pass.
3587
3588 @cindex tail recursion optimization
3589 Optimization is done in this pass for @code{if}-conditions that are
3590 comparisons, boolean operations or conditional expressions.  Tail
3591 recursion is detected at this time also.  Decisions are made about how
3592 best to arrange loops and how to output @code{switch} statements.
3593
3594 @c Avoiding overfull is tricky here.
3595 The source files for RTL generation include
3596 @file{stmt.c},
3597 @file{calls.c},
3598 @file{expr.c},
3599 @file{explow.c},
3600 @file{expmed.c},
3601 @file{function.c},
3602 @file{optabs.c}
3603 and @file{emit-rtl.c}.
3604 Also, the file
3605 @file{insn-emit.c}, generated from the machine description by the
3606 program @code{genemit}, is used in this pass.  The header file
3607 @file{expr.h} is used for communication within this pass.@refill
3608
3609 @findex genflags
3610 @findex gencodes
3611 The header files @file{insn-flags.h} and @file{insn-codes.h},
3612 generated from the machine description by the programs @code{genflags}
3613 and @code{gencodes}, tell this pass which standard names are available
3614 for use and which patterns correspond to them.@refill
3615
3616 Aside from debugging information output, none of the following passes
3617 refers to the tree structure representation of the function (only
3618 part of which is saved).
3619
3620 @cindex inline, automatic
3621 The decision of whether the function can and should be expanded inline
3622 in its subsequent callers is made at the end of rtl generation.  The
3623 function must meet certain criteria, currently related to the size of
3624 the function and the types and number of parameters it has.  Note that
3625 this function may contain loops, recursive calls to itself
3626 (tail-recursive functions can be inlined!), gotos, in short, all
3627 constructs supported by GCC.  The file @file{integrate.c} contains
3628 the code to save a function's rtl for later inlining and to inline that
3629 rtl when the function is called.  The header file @file{integrate.h}
3630 is also used for this purpose.
3631
3632 The option @samp{-dr} causes a debugging dump of the RTL code after
3633 this pass.  This dump file's name is made by appending @samp{.rtl} to
3634 the input file name.
3635
3636 @cindex jump optimization
3637 @cindex unreachable code
3638 @cindex dead code
3639 @item
3640 Jump optimization.  This pass simplifies jumps to the following
3641 instruction, jumps across jumps, and jumps to jumps.  It deletes
3642 unreferenced labels and unreachable code, except that unreachable code
3643 that contains a loop is not recognized as unreachable in this pass.
3644 (Such loops are deleted later in the basic block analysis.)  It also
3645 converts some code originally written with jumps into sequences of
3646 instructions that directly set values from the results of comparisons,
3647 if the machine has such instructions.
3648
3649 Jump optimization is performed two or three times.  The first time is
3650 immediately following RTL generation.  The second time is after CSE,
3651 but only if CSE says repeated jump optimization is needed.  The
3652 last time is right before the final pass.  That time, cross-jumping
3653 and deletion of no-op move instructions are done together with the
3654 optimizations described above.
3655
3656 The source file of this pass is @file{jump.c}.
3657
3658 The option @samp{-dj} causes a debugging dump of the RTL code after
3659 this pass is run for the first time.  This dump file's name is made by
3660 appending @samp{.jump} to the input file name.
3661
3662 @cindex register use analysis
3663 @item
3664 Register scan.  This pass finds the first and last use of each
3665 register, as a guide for common subexpression elimination.  Its source
3666 is in @file{regclass.c}.
3667
3668 @cindex jump threading
3669 @item
3670 Jump threading.  This pass detects a condition jump that branches to an
3671 identical or inverse test.  Such jumps can be @samp{threaded} through
3672 the second conditional test.  The source code for this pass is in
3673 @file{jump.c}.  This optimization is only performed if
3674 @samp{-fthread-jumps} is enabled.
3675
3676 @cindex common subexpression elimination
3677 @cindex constant propagation
3678 @item
3679 Common subexpression elimination.  This pass also does constant
3680 propagation.  Its source file is @file{cse.c}.  If constant
3681 propagation causes conditional jumps to become unconditional or to
3682 become no-ops, jump optimization is run again when CSE is finished.
3683
3684 The option @samp{-ds} causes a debugging dump of the RTL code after
3685 this pass.  This dump file's name is made by appending @samp{.cse} to
3686 the input file name.
3687
3688 @cindex global common subexpression elimination
3689 @cindex constant propagation
3690 @cindex copy propagation
3691 @item               
3692 Global common subexpression elimination.  This pass performs GCSE
3693 using Morel-Renvoise Partial Redundancy Elimination, with the exception
3694 that it does not try to move invariants out of loops - that is left to
3695 the loop optimization pass.  This pass also performs global constant
3696 and copy propagation.
3697
3698 The source file for this pass is gcse.c.
3699
3700 The option @samp{-dG} causes a debugging dump of the RTL code after
3701 this pass.  This dump file's name is made by appending @samp{.gcse} to
3702 the input file name.
3703
3704 @cindex loop optimization
3705 @cindex code motion
3706 @cindex strength-reduction
3707 @item
3708 Loop optimization.  This pass moves constant expressions out of loops,
3709 and optionally does strength-reduction and loop unrolling as well.
3710 Its source files are @file{loop.c} and @file{unroll.c}, plus the header
3711 @file{loop.h} used for communication between them.  Loop unrolling uses
3712 some functions in @file{integrate.c} and the header @file{integrate.h}.
3713
3714 The option @samp{-dL} causes a debugging dump of the RTL code after
3715 this pass.  This dump file's name is made by appending @samp{.loop} to
3716 the input file name.
3717
3718 @item
3719 If @samp{-frerun-cse-after-loop} was enabled, a second common
3720 subexpression elimination pass is performed after the loop optimization
3721 pass.  Jump threading is also done again at this time if it was specified.
3722
3723 The option @samp{-dt} causes a debugging dump of the RTL code after
3724 this pass.  This dump file's name is made by appending @samp{.cse2} to
3725 the input file name.
3726
3727 @cindex data flow analysis
3728 @cindex analysis, data flow
3729 @cindex basic blocks
3730 @item
3731 Data flow analysis (@file{flow.c}).  This pass divides the program
3732 into basic blocks (and in the process deletes unreachable loops); then
3733 it computes which pseudo-registers are live at each point in the
3734 program, and makes the first instruction that uses a value point at
3735 the instruction that computed the value.
3736
3737 @cindex autoincrement/decrement analysis
3738 This pass also deletes computations whose results are never used, and
3739 combines memory references with add or subtract instructions to make
3740 autoincrement or autodecrement addressing.
3741
3742 The option @samp{-df} causes a debugging dump of the RTL code after
3743 this pass.  This dump file's name is made by appending @samp{.flow} to
3744 the input file name.  If stupid register allocation is in use, this
3745 dump file reflects the full results of such allocation.
3746
3747 @cindex instruction combination
3748 @item
3749 Instruction combination (@file{combine.c}).  This pass attempts to
3750 combine groups of two or three instructions that are related by data
3751 flow into single instructions.  It combines the RTL expressions for
3752 the instructions by substitution, simplifies the result using algebra,
3753 and then attempts to match the result against the machine description.
3754
3755 The option @samp{-dc} causes a debugging dump of the RTL code after
3756 this pass.  This dump file's name is made by appending @samp{.combine}
3757 to the input file name.
3758
3759 @cindex register movement
3760 @item
3761 Register movement (@file{regmove.c}). This pass looks for cases where
3762 matching constraints would force an instruction to need a reload, and
3763 this reload would be a register to register move.  It then attempts
3764 to change the registers used by the instruction to avoid the move
3765 instruction.
3766
3767 The option @samp{-dN} causes a debugging dump of the RTL code after
3768 this pass.  This dump file's name is made by appending @samp{.regmove}
3769 to the input file name.
3770
3771 @cindex instruction scheduling
3772 @cindex scheduling, instruction
3773 @item
3774 Instruction scheduling (@file{sched.c}).  This pass looks for
3775 instructions whose output will not be available by the time that it is
3776 used in subsequent instructions.  (Memory loads and floating point
3777 instructions often have this behavior on RISC machines).  It re-orders
3778 instructions within a basic block to try to separate the definition and
3779 use of items that otherwise would cause pipeline stalls.
3780
3781 Instruction scheduling is performed twice.  The first time is immediately
3782 after instruction combination and the second is immediately after reload.
3783
3784 The option @samp{-dS} causes a debugging dump of the RTL code after this
3785 pass is run for the first time.  The dump file's name is made by
3786 appending @samp{.sched} to the input file name.
3787
3788 @cindex register class preference pass
3789 @item
3790 Register class preferencing.  The RTL code is scanned to find out
3791 which register class is best for each pseudo register.  The source
3792 file is @file{regclass.c}.
3793
3794 @cindex register allocation
3795 @cindex local register allocation
3796 @item
3797 Local register allocation (@file{local-alloc.c}).  This pass allocates
3798 hard registers to pseudo registers that are used only within one basic
3799 block.  Because the basic block is linear, it can use fast and
3800 powerful techniques to do a very good job.
3801
3802 The option @samp{-dl} causes a debugging dump of the RTL code after
3803 this pass.  This dump file's name is made by appending @samp{.lreg} to
3804 the input file name.
3805
3806 @cindex global register allocation
3807 @item
3808 Global register allocation (@file{global.c}).  This pass
3809 allocates hard registers for the remaining pseudo registers (those
3810 whose life spans are not contained in one basic block).
3811
3812 @cindex reloading
3813 @item
3814 Reloading.  This pass renumbers pseudo registers with the hardware
3815 registers numbers they were allocated.  Pseudo registers that did not
3816 get hard registers are replaced with stack slots.  Then it finds
3817 instructions that are invalid because a value has failed to end up in
3818 a register, or has ended up in a register of the wrong kind.  It fixes
3819 up these instructions by reloading the problematical values
3820 temporarily into registers.  Additional instructions are generated to
3821 do the copying.
3822
3823 The reload pass also optionally eliminates the frame pointer and inserts
3824 instructions to save and restore call-clobbered registers around calls.
3825
3826 Source files are @file{reload.c} and @file{reload1.c}, plus the header
3827 @file{reload.h} used for communication between them.
3828
3829 The option @samp{-dg} causes a debugging dump of the RTL code after
3830 this pass.  This dump file's name is made by appending @samp{.greg} to
3831 the input file name.
3832
3833 @cindex instruction scheduling
3834 @cindex scheduling, instruction
3835 @item
3836 Instruction scheduling is repeated here to try to avoid pipeline stalls
3837 due to memory loads generated for spilled pseudo registers.
3838
3839 The option @samp{-dR} causes a debugging dump of the RTL code after
3840 this pass.  This dump file's name is made by appending @samp{.sched2}
3841 to the input file name.
3842
3843 @cindex cross-jumping
3844 @cindex no-op move instructions
3845 @item
3846 Jump optimization is repeated, this time including cross-jumping
3847 and deletion of no-op move instructions.
3848
3849 The option @samp{-dJ} causes a debugging dump of the RTL code after
3850 this pass.  This dump file's name is made by appending @samp{.jump2}
3851 to the input file name.
3852
3853 @cindex delayed branch scheduling
3854 @cindex scheduling, delayed branch
3855 @item
3856 Delayed branch scheduling.  This optional pass attempts to find
3857 instructions that can go into the delay slots of other instructions,
3858 usually jumps and calls.  The source file name is @file{reorg.c}.
3859
3860 The option @samp{-dd} causes a debugging dump of the RTL code after
3861 this pass.  This dump file's name is made by appending @samp{.dbr}
3862 to the input file name.
3863
3864 @cindex branch shortening
3865 @item
3866 Branch shortening.  On many RISC machines, branch instructions have a
3867 limited range.  Thus, longer sequences of instructions must be used for 
3868 long branches.  In this pass, the compiler figures out what how far each
3869 instruction will be from each other instruction, and therefore whether
3870 the usual instructions, or the longer sequences, must be used for each
3871 branch. 
3872
3873 @cindex register-to-stack conversion
3874 @item
3875 Conversion from usage of some hard registers to usage of a register
3876 stack may be done at this point.  Currently, this is supported only
3877 for the floating-point registers of the Intel 80387 coprocessor.   The
3878 source file name is @file{reg-stack.c}.
3879
3880 The options @samp{-dk} causes a debugging dump of the RTL code after
3881 this pass.  This dump file's name is made by appending @samp{.stack}
3882 to the input file name.
3883
3884 @cindex final pass
3885 @cindex peephole optimization
3886 @item
3887 Final.  This pass outputs the assembler code for the function.  It is
3888 also responsible for identifying spurious test and compare
3889 instructions.  Machine-specific peephole optimizations are performed
3890 at the same time.  The function entry and exit sequences are generated
3891 directly as assembler code in this pass; they never exist as RTL.
3892
3893 The source files are @file{final.c} plus @file{insn-output.c}; the
3894 latter is generated automatically from the machine description by the
3895 tool @file{genoutput}.  The header file @file{conditions.h} is used
3896 for communication between these files.
3897
3898 @cindex debugging information generation
3899 @item
3900 Debugging information output.  This is run after final because it must
3901 output the stack slot offsets for pseudo registers that did not get
3902 hard registers.  Source files are @file{dbxout.c} for DBX symbol table
3903 format, @file{sdbout.c} for SDB symbol table format, and
3904 @file{dwarfout.c} for DWARF symbol table format.
3905 @end itemize
3906
3907 Some additional files are used by all or many passes:
3908
3909 @itemize @bullet
3910 @item
3911 Every pass uses @file{machmode.def} and @file{machmode.h} which define
3912 the machine modes.
3913
3914 @item
3915 Several passes use @file{real.h}, which defines the default
3916 representation of floating point constants and how to operate on them.
3917
3918 @item
3919 All the passes that work with RTL use the header files @file{rtl.h}
3920 and @file{rtl.def}, and subroutines in file @file{rtl.c}.  The tools
3921 @code{gen*} also use these files to read and work with the machine
3922 description RTL.
3923
3924 @findex genconfig
3925 @item
3926 Several passes refer to the header file @file{insn-config.h} which
3927 contains a few parameters (C macro definitions) generated
3928 automatically from the machine description RTL by the tool
3929 @code{genconfig}.
3930
3931 @cindex instruction recognizer
3932 @item
3933 Several passes use the instruction recognizer, which consists of
3934 @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
3935 and @file{insn-extract.c} that are generated automatically from the
3936 machine description by the tools @file{genrecog} and
3937 @file{genextract}.@refill
3938
3939 @item
3940 Several passes use the header files @file{regs.h} which defines the
3941 information recorded about pseudo register usage, and @file{basic-block.h}
3942 which defines the information recorded about basic blocks.
3943
3944 @item
3945 @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
3946 with a bit for each hard register, and some macros to manipulate it.
3947 This type is just @code{int} if the machine has few enough hard registers;
3948 otherwise it is an array of @code{int} and some of the macros expand
3949 into loops.
3950
3951 @item
3952 Several passes use instruction attributes.  A definition of the
3953 attributes defined for a particular machine is in file
3954 @file{insn-attr.h}, which is generated from the machine description by
3955 the program @file{genattr}.  The file @file{insn-attrtab.c} contains
3956 subroutines to obtain the attribute values for insns.  It is generated
3957 from the machine description by the program @file{genattrtab}.@refill
3958 @end itemize
3959 @end ifset
3960
3961 @ifset INTERNALS
3962 @include rtl.texi
3963 @include md.texi
3964 @include tm.texi
3965 @end ifset
3966
3967 @ifset INTERNALS
3968 @node Config
3969 @chapter The Configuration File
3970 @cindex configuration file
3971 @cindex @file{xm-@var{machine}.h}
3972
3973 The configuration file @file{xm-@var{machine}.h} contains macro
3974 definitions that describe the machine and system on which the compiler
3975 is running, unlike the definitions in @file{@var{machine}.h}, which
3976 describe the machine for which the compiler is producing output.  Most
3977 of the values in @file{xm-@var{machine}.h} are actually the same on all
3978 machines that GCC runs on, so large parts of all configuration files
3979 are identical.  But there are some macros that vary:
3980
3981 @table @code
3982 @findex USG
3983 @item USG
3984 Define this macro if the host system is System V.
3985
3986 @findex VMS
3987 @item VMS
3988 Define this macro if the host system is VMS.
3989
3990 @findex FATAL_EXIT_CODE
3991 @item FATAL_EXIT_CODE
3992 A C expression for the status code to be returned when the compiler
3993 exits after serious errors.
3994
3995 @findex SUCCESS_EXIT_CODE
3996 @item SUCCESS_EXIT_CODE
3997 A C expression for the status code to be returned when the compiler
3998 exits without serious errors.
3999
4000 @findex HOST_WORDS_BIG_ENDIAN
4001 @item HOST_WORDS_BIG_ENDIAN
4002 Defined if the host machine stores words of multi-word values in
4003 big-endian order.  (GCC does not depend on the host byte ordering
4004 within a word.)
4005
4006 @findex HOST_FLOAT_WORDS_BIG_ENDIAN
4007 @item HOST_FLOAT_WORDS_BIG_ENDIAN
4008 Define this macro to be 1 if the host machine stores @code{DFmode},
4009 @code{XFmode} or @code{TFmode} floating point numbers in memory with the
4010 word containing the sign bit at the lowest address; otherwise, define it
4011 to be zero.
4012
4013 This macro need not be defined if the ordering is the same as for
4014 multi-word integers.
4015
4016 @findex HOST_FLOAT_FORMAT
4017 @item HOST_FLOAT_FORMAT
4018 A numeric code distinguishing the floating point format for the host
4019 machine.  See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
4020 alternatives and default.
4021
4022 @findex HOST_BITS_PER_CHAR
4023 @item HOST_BITS_PER_CHAR
4024 A C expression for the number of bits in @code{char} on the host
4025 machine.
4026
4027 @findex HOST_BITS_PER_SHORT
4028 @item HOST_BITS_PER_SHORT
4029 A C expression for the number of bits in @code{short} on the host
4030 machine.
4031
4032 @findex HOST_BITS_PER_INT
4033 @item HOST_BITS_PER_INT
4034 A C expression for the number of bits in @code{int} on the host
4035 machine.
4036
4037 @findex HOST_BITS_PER_LONG
4038 @item HOST_BITS_PER_LONG
4039 A C expression for the number of bits in @code{long} on the host
4040 machine.
4041
4042 @findex ONLY_INT_FIELDS
4043 @item ONLY_INT_FIELDS
4044 Define this macro to indicate that the host compiler only supports
4045 @code{int} bit fields, rather than other integral types, including
4046 @code{enum}, as do most C compilers.
4047
4048 @findex OBSTACK_CHUNK_SIZE
4049 @item OBSTACK_CHUNK_SIZE
4050 A C expression for the size of ordinary obstack chunks.
4051 If you don't define this, a usually-reasonable default is used.
4052
4053 @findex OBSTACK_CHUNK_ALLOC
4054 @item OBSTACK_CHUNK_ALLOC
4055 The function used to allocate obstack chunks.
4056 If you don't define this, @code{xmalloc} is used.
4057
4058 @findex OBSTACK_CHUNK_FREE
4059 @item OBSTACK_CHUNK_FREE
4060 The function used to free obstack chunks.
4061 If you don't define this, @code{free} is used.
4062
4063 @findex USE_C_ALLOCA
4064 @item USE_C_ALLOCA
4065 Define this macro to indicate that the compiler is running with the
4066 @code{alloca} implemented in C.  This version of @code{alloca} can be
4067 found in the file @file{alloca.c}; to use it, you must also alter the
4068 @file{Makefile} variable @code{ALLOCA}.  (This is done automatically
4069 for the systems on which we know it is needed.)
4070
4071 If you do define this macro, you should probably do it as follows:
4072
4073 @example
4074 #ifndef __GNUC__
4075 #define USE_C_ALLOCA
4076 #else
4077 #define alloca __builtin_alloca
4078 #endif
4079 @end example
4080
4081 @noindent
4082 so that when the compiler is compiled with GCC it uses the more
4083 efficient built-in @code{alloca} function.
4084
4085 @item FUNCTION_CONVERSION_BUG
4086 @findex FUNCTION_CONVERSION_BUG
4087 Define this macro to indicate that the host compiler does not properly
4088 handle converting a function value to a pointer-to-function when it is
4089 used in an expression.
4090
4091 @findex MULTIBYTE_CHARS
4092 @item MULTIBYTE_CHARS
4093 Define this macro to enable support for multibyte characters in the
4094 input to GCC.  This requires that the host system support the ISO C
4095 library functions for converting multibyte characters to wide
4096 characters.
4097
4098 @findex POSIX
4099 @item POSIX
4100 Define this if your system is POSIX.1 compliant.
4101
4102 @findex USE_PROTOTYPES
4103 @item USE_PROTOTYPES
4104 Define this to be 1 if you know that the host compiler supports
4105 prototypes, even if it doesn't define __STDC__, or define
4106 it to be 0 if you do not want any prototypes used in compiling
4107 GCC.  If @samp{USE_PROTOTYPES} is not defined, it will be
4108 determined automatically whether your compiler supports
4109 prototypes by checking if @samp{__STDC__} is defined.
4110
4111 @findex PATH_SEPARATOR
4112 @item PATH_SEPARATOR
4113 Define this macro to be a C character constant representing the
4114 character used to separate components in paths.  The default value is
4115 the colon character
4116
4117 @findex DIR_SEPARATOR
4118 @item DIR_SEPARATOR
4119 If your system uses some character other than slash to separate
4120 directory names within a file specification, define this macro to be a C
4121 character constant specifying that character.  When GCC displays file
4122 names, the character you specify will be used.  GCC will test for
4123 both slash and the character you specify when parsing filenames.
4124
4125 @findex OBJECT_SUFFIX
4126 @item OBJECT_SUFFIX
4127 Define this macro to be a C string representing the suffix for object
4128 files on your machine.  If you do not define this macro, GCC will use
4129 @samp{.o} as the suffix for object files.
4130
4131 @findex EXECUTABLE_SUFFIX
4132 @item EXECUTABLE_SUFFIX
4133 Define this macro to be a C string representing the suffix for executable
4134 files on your machine.  If you do not define this macro, GCC will use
4135 the null string as the suffix for object files.
4136
4137 @findex HOST_BIT_BUCKET
4138 @item HOST_BIT_BUCKET
4139 The name of a file or file-like object on the host system which acts as
4140 a ``bit bucket''.  If you do not define this macro, GCC will use
4141 @samp{/dev/null} as the bit bucket.  If the target does not support a
4142 bit bucket, this should be defined to the null string, or some other
4143 illegal filename.  If the bit bucket is not writable, GCC will use a
4144 temporary file instead.
4145
4146 @findex COLLECT_EXPORT_LIST
4147 @item COLLECT_EXPORT_LIST
4148 If defined, @code{collect2} will scan the individual object files
4149 specified on its command line and create an export list for the linker.
4150 Define this macro for systems like AIX, where the linker discards
4151 object files that are not referenced from @code{main} and uses export
4152 lists.
4153
4154 @findex COLLECT2_HOST_INITIALIZATION
4155 @item COLLECT2_HOST_INITIALIZATION
4156 If defined, a C statement (sans semicolon) that performs host-dependent
4157 initialization when @code{collect2} is being initialized.
4158
4159 @findex GCC_DRIVER_HOST_INITIALIZATION
4160 @item GCC_DRIVER_HOST_INITIALIZATION
4161 If defined, a C statement (sans semicolon) that performs host-dependent
4162 initialization when a compilation driver is being initialized.
4163
4164 @findex UPDATE_PATH_HOST_CANONICALIZE
4165 @item UPDATE_PATH_HOST_CANONICALIZE (@var{path}, @var{key})
4166 If defined, a C statement (sans semicolon) that performs host-dependent
4167 canonicalization when a path used in a compilation driver or preprocessor is
4168 canonicalized. @var{path} is the path to be canonicalized, and @var{key} is
4169 a translation prefix when its value isn't @code{NULL}. If the C statement
4170 does canonicalize @var{path}, the new path should be returned.
4171 @end table
4172
4173 @findex bzero
4174 @findex bcmp
4175 In addition, configuration files for system V define @code{bcopy},
4176 @code{bzero} and @code{bcmp} as aliases.  Some files define @code{alloca}
4177 as a macro when compiled with GCC, in order to take advantage of the
4178 benefit of GCC's built-in @code{alloca}.
4179
4180 @node Fragments
4181 @chapter Makefile Fragments
4182 @cindex makefile fragment
4183
4184 When you configure GCC using the @file{configure} script
4185 (@pxref{Installation}), it will construct the file @file{Makefile} from
4186 the template file @file{Makefile.in}.  When it does this, it will
4187 incorporate makefile fragment files from the @file{config} directory,
4188 named @file{t-@var{target}} and @file{x-@var{host}}.  If these files do
4189 not exist, it means nothing needs to be added for a given target or
4190 host.
4191
4192 @menu
4193 * Target Fragment:: Writing the @file{t-@var{target}} file.
4194 * Host Fragment::   Writing the @file{x-@var{host}} file.
4195 @end menu
4196
4197 @node Target Fragment
4198 @section The Target Makefile Fragment
4199 @cindex target makefile fragment
4200 @cindex @file{t-@var{target}}
4201
4202 The target makefile fragment, @file{t-@var{target}}, defines special
4203 target dependent variables and targets used in the @file{Makefile}:
4204
4205 @table @code
4206 @findex LIBGCC1
4207 @item LIBGCC1
4208 The rule to use to build @file{libgcc1.a}.
4209 If your target does not need to use the functions in @file{libgcc1.a},
4210 set this to empty.
4211 @xref{Interface}.
4212
4213 @findex CROSS_LIBGCC1
4214 @item CROSS_LIBGCC1
4215 The rule to use to build @file{libgcc1.a} when building a cross
4216 compiler.  If your target does not need to use the functions in
4217 @file{libgcc1.a}, set this to empty.  @xref{Cross Runtime}.
4218
4219 @findex LIBGCC2_CFLAGS
4220 @item LIBGCC2_CFLAGS
4221 Compiler flags to use when compiling @file{libgcc2.c}.
4222
4223 @findex LIB2FUNCS_EXTRA
4224 @item LIB2FUNCS_EXTRA
4225 A list of source file names to be compiled or assembled and inserted
4226 into @file{libgcc.a}.
4227
4228 @findex Floating Point Emulation
4229 @item Floating Point Emulation
4230 To have GCC include software floating point libraries in @file{libgcc.a}
4231 define @code{FPBIT} and @code{DPBIT} along with a few rules as follows:
4232 @smallexample
4233 # We want fine grained libraries, so use the new code to build the
4234 # floating point emulation libraries.
4235 FPBIT = fp-bit.c
4236 DPBIT = dp-bit.c
4237
4238
4239 fp-bit.c: $(srcdir)/config/fp-bit.c
4240         echo '#define FLOAT' > fp-bit.c
4241         cat $(srcdir)/config/fp-bit.c >> fp-bit.c
4242
4243 dp-bit.c: $(srcdir)/config/fp-bit.c
4244         cat $(srcdir)/config/fp-bit.c > dp-bit.c
4245 @end smallexample
4246
4247 You may need to provide additional #defines at the beginning of @file{fp-bit.c}
4248 and @file{dp-bit.c} to control target endianness and other options.
4249
4250
4251 @findex CRTSTUFF_T_CFLAGS
4252 @item CRTSTUFF_T_CFLAGS
4253 Special flags used when compiling @file{crtstuff.c}.
4254 @xref{Initialization}.
4255
4256 @findex CRTSTUFF_T_CFLAGS_S
4257 @item CRTSTUFF_T_CFLAGS_S
4258 Special flags used when compiling @file{crtstuff.c} for shared
4259 linking.  Used if you use @file{crtbeginS.o} and @file{crtendS.o}
4260 in @code{EXTRA-PARTS}.
4261 @xref{Initialization}.
4262
4263 @findex MULTILIB_OPTIONS
4264 @item MULTILIB_OPTIONS
4265 For some targets, invoking GCC in different ways produces objects
4266 that can not be linked together.  For example, for some targets GCC
4267 produces both big and little endian code.  For these targets, you must
4268 arrange for multiple versions of @file{libgcc.a} to be compiled, one for
4269 each set of incompatible options.  When GCC invokes the linker, it
4270 arranges to link in the right version of @file{libgcc.a}, based on
4271 the command line options used.
4272
4273 The @code{MULTILIB_OPTIONS} macro lists the set of options for which
4274 special versions of @file{libgcc.a} must be built.  Write options that
4275 are mutually incompatible side by side, separated by a slash.  Write
4276 options that may be used together separated by a space.  The build
4277 procedure will build all combinations of compatible options.
4278
4279 For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
4280 msoft-float}, @file{Makefile} will build special versions of
4281 @file{libgcc.a} using the following sets of options:  @samp{-m68000},
4282 @samp{-m68020}, @samp{-msoft-float}, @samp{-m68000 -msoft-float}, and 
4283 @samp{-m68020 -msoft-float}.
4284
4285 @findex MULTILIB_DIRNAMES
4286 @item MULTILIB_DIRNAMES
4287 If @code{MULTILIB_OPTIONS} is used, this variable specifies the
4288 directory names that should be used to hold the various libraries.
4289 Write one element in @code{MULTILIB_DIRNAMES} for each element in
4290 @code{MULTILIB_OPTIONS}.  If @code{MULTILIB_DIRNAMES} is not used, the
4291 default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
4292 as spaces.
4293
4294 For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020
4295 msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
4296 @samp{m68000 m68020 msoft-float}.  You may specify a different value if
4297 you desire a different set of directory names.
4298
4299 @findex MULTILIB_MATCHES
4300 @item MULTILIB_MATCHES
4301 Sometimes the same option may be written in two different ways.  If an
4302 option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about
4303 any synonyms.  In that case, set @code{MULTILIB_MATCHES} to a list of
4304 items of the form @samp{option=option} to describe all relevant
4305 synonyms.  For example, @samp{m68000=mc68000 m68020=mc68020}.
4306
4307 @findex MULTILIB_EXCEPTIONS
4308 @item MULTILIB_EXCEPTIONS
4309 Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being
4310 specified, there are combinations that should not be built.  In that
4311 case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions
4312 in shell case syntax that should not be built.
4313
4314 For example, in the PowerPC embedded ABI support, it is not desirable
4315 to build libraries compiled with the @samp{-mcall-aix} option
4316 and either of the @samp{-fleading-underscore} or @samp{-mlittle} options
4317 at the same time.  Therefore @code{MULTILIB_EXCEPTIONS} is set to
4318 @code{*mcall-aix/*fleading-underscore* *mlittle/*mcall-aix*}.
4319
4320 @findex MULTILIB_EXTRA_OPTS
4321 @item MULTILIB_EXTRA_OPTS
4322 Sometimes it is desirable that when building multiple versions of
4323 @file{libgcc.a} certain options should always be passed on to the
4324 compiler.  In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list
4325 of options to be used for all builds.
4326 @end table
4327
4328 @node Host Fragment
4329 @section The Host Makefile Fragment
4330 @cindex host makefile fragment
4331 @cindex @file{x-@var{host}}
4332
4333 The host makefile fragment, @file{x-@var{host}}, defines special host
4334 dependent variables and targets used in the @file{Makefile}:
4335
4336 @table @code
4337 @findex CC
4338 @item CC
4339 The compiler to use when building the first stage.
4340
4341 @findex CLIB
4342 @item CLIB
4343 Additional host libraries to link with.
4344
4345 @findex OLDCC
4346 @item OLDCC
4347 The compiler to use when building @file{libgcc1.a} for a native
4348 compilation.
4349
4350 @findex OLDAR
4351 @item OLDAR
4352 The version of @code{ar} to use when building @file{libgcc1.a} for a native
4353 compilation.
4354
4355 @findex INSTALL
4356 @item INSTALL
4357 The install program&nbs