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