source: trunk/third/gcc/gcc.texi @ 11288

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