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